alt:V: установка сервера и особенности C#/JS модов

MAATRIX GAMES

Ставишь alt:V впервые — и почти сразу упираешься в вопрос, который на FiveM или RAGE:MP так остро не стоит: на чём вообще писать ресурсы, на JavaScript/TypeScript или на C#. От этого решения зависит структура сервера, набор модулей в конфиге и то, сколько библиотек придётся тащить с собой при деплое. Разберём установку с нуля и покажем разницу между рантаймами на практике, чтобы не пришлось потом переделывать half проекта.

Чем alt:V отличается от FiveM и RAGE:MP

alt:V — отдельная мультиплеерная платформа для GTA V, написанная с нуля, а не форк старых наработок вроде SA-MP-совместимых решений. Ключевое отличие для админа: alt:V изначально поддерживает несколько языков разработки ресурсов одновременно — сервер может грузить и JS/TS-ресурсы, и C#-ресурсы в рамках одного процесса, через отдельные модули. У FiveM это Lua (плюс C#/JS как надстройка через свои механизмы), у RAGE:MP — в основном JavaScript. alt:V же с самого начала строился как мультиязычная платформа, и это определяет всю структуру установки — сервер сам по себе не умеет исполнять ни один из языков, пока вы не подключите соответствующий модуль.

Второе отличие — сетевой протокол и порт. По умолчанию alt:V слушает 7788 (TCP и UDP), а не 30120 как FiveM. Если мигрируете с другой платформы, не забудьте пробросить именно этот порт на файрволе и роутере хостинга. О выборе платформы для RP в принципе — SA-MP, FiveM или RAGE:MP — мы разбирали отдельно, если alt:V для вас пока не финальный выбор, взгляните на сравнение платформ для RP-сервера.

Скачивание сервера и структура каталога

Официальная точка входа — сайт документации alt:V (docs.altv.mp) и CDN-раздачи под конкретную ОС и архитектуру. Дальше — общая логика:

1. Скачайте бинарник сервера под свою платформу: altv-server.exe для Windows или altv-server для Linux x64.
2. Скачайте нужные модули языков отдельными файлами — js-module (для JS/TS) и/или csharp-module (для C#). Модули не входят в основной бинарник, это осознанное архитектурное решение: не тянуть лишний рантайм, если он не нужен.
3. Скачайте служебные data-файлы (метаданные транспорта, педов и т.д.) — без них часть игровых систем работает некорректно.
4. Разложите всё по единой структуре каталога сервера.

Типичная структура выглядит так:

altv-server/
├── altv-server            # или altv-server.exe на Windows
├── server.toml
├── modules/
│   ├── libjs-module.so    # или js-module.dll
│   └── libcsharp-module.so
├── data/
│   ├── vehmodels.bin
│   └── vehmods.bin
└── resources/
    ├── freeroam-js/
    └── core-cs/

На Linux не забудьте chmod +x altv-server и выдать сервису права на запись в свою же папку (логи, кэш ресурсов) — иначе получите молчаливый выход сразу после старта без внятной ошибки в консоли.

server.toml: минимальный рабочий конфиг

Конфиг сервера — TOML-файл в корне, там же, где лежит бинарник. Минимальный рабочий вариант:

name: '>> Мой alt:V RP-сервер <<'
host: 0.0.0.0
port: 7788
players: 128
password: ''
announce: true
gamemode: 'Roleplay'
website: 'https://example.com'
language: 'ru'
description: 'RP-сервер на alt:V'
tags: ['roleplay', 'ru']

resources: [
    'freeroam-js'
]

modules: [
    'js-module',
    # 'csharp-module',
]

Что важно проверить перед первым запуском:

• host — 0.0.0.0, чтобы сервер слушал все интерфейсы, а не только loopback. Частая ошибка новичков — оставить 127.0.0.1 и потом полчаса гадать, почему сервер не виден снаружи.
• port — держите 7788, если нет причин менять. При смене порта не забудьте продублировать её на файрволе.
• announce — true, если хотите, чтобы сервер появился в публичном браузере серверов alt:V. Для закрытого теста ставьте false.
• modules — сюда добавляются только те рантаймы, которые реально используются. Лишний модуль в списке — это лишняя память и лишняя поверхность для багов при старте.
• resources — список папок из resources/, которые сервер должен загрузить при старте, в порядке загрузки (это важно, если один ресурс зависит от экспортов другого).

Ресурсы на JavaScript/TypeScript: altv-server-js

Если включили js-module, каждый JS/TS-ресурс — это папка в resources/ с файлом resource.toml внутри:

type: 'js'
main: 'server.js'
client-main: 'client.js'
client-files: ['client.js']

Минимальный server.js:

import alt from 'alt-server';

alt.on('resourceStart', () => {
    alt.log('Ресурс freeroam-js запущен');
});

alt.on('playerConnect', (player) => {
    player.spawn(0, 0, 72, 0);
    alt.log(`${player.name} подключился`);
});

Важный нюанс, который путает тех, кто пришёл с Node.js: JS-рантайм alt:V выполняется в собственной V8-изоляции, а не в полноценном Node — часть стандартных модулей Node (fs, net и т.п.) недоступна напрямую, доступ к системным ресурсам идёт через API alt-server. Если планируете писать на TypeScript, ставьте типы @altv/types и компилируйте в обычный JS через tsc или сборщик вроде esbuild/webpack — сервер выполняет только готовый JS, TS-файлы напрямую не понимает.

Плюс JS/TS-подхода — горячая перезагрузка: большинство изменений в ресурсе подхватывается через alt.on('resourceStart', ...) и рестарт конкретного ресурса командой в консоли сервера, без остановки всего процесса. Для итеративной разработки RP-механик это ощутимо экономит время. Если раньше ставили кастомные скрипты на FiveM, логика похожая — почитайте про установку кастомных скриптов на FiveM для сравнения подхода к структуре ресурсов.

Ресурсы на C#: altv-server-csharp

C#-ресурсы собираются через пакет AltV.Net (NuGet) и .NET SDK. Для сборки понадобится dotnet build на машине разработки — сервер получает уже скомпилированную сборку (.dll), исходники C# ему не нужны.

resource.toml для C#-ресурса:

type: 'cs'
main: 'bin/Release/net8.0/CoreResource.dll'

Минимальный класс ресурса:

using AltV.Net;
using AltV.Net.Elements.Entities;

public class CoreResource : Resource
{
    public override void OnStart()
    {
        Alt.Log("Ресурс core-cs запущен");
        Alt.OnPlayerConnect += (player, reason) =>
        {
            player.Spawn(new Position(0, 0, 72));
        };
    }

    public override void OnStop() { }
}

Разница с JS-подходом ощутимая: C#-ресурсы требуют полноценной пересборки при каждом изменении, горячей перезагрузки в том же смысле, что у JS, тут нет — рестарт ресурса подхватывает новую сборку, но сначала её нужно скомпилировать и заменить файл на сервере. Зато вы получаете статическую типизацию, привычный .NET-тулинг (отладчик, unit-тесты) и производительность, которая на CPU-тяжёлых системах (сложная экономика, античит-логика, симуляции) обычно выигрывает у динамического JS — хотя точные цифры сильно зависят от конкретной задачи и профилирования, и без замеров на своём коде верить голым обещаниям не стоит.

csharp-module тяжелее по объёму, чем js-module, — под капотом тянется CoreCLR-рантайм, так что и место на диске, и потребление памяти на старте будут выше. Для небольшого RP-сервера на старте это не критично, но при выборе тарифа стоит закладывать запас.

JS/TS или C#: что выбрать под свой сервер

На практике многие RP-проекты не выбирают что-то одно — alt:V позволяет держать оба модуля включёнными одновременно и грузить и JS-, и C#-ресурсы в одном инстансе. Типичная схема: быстрые, часто меняющиеся геймплейные фичи и UI — на JS/TS, а тяжёлое ядро (экономика, синхронизация состояния, интеграции с базой) — на C#. Взаимодействие между ресурсами разных языков идёт не напрямую, а через события (alt.emit/alt.on) и экспортируемые функции — прямых ссылок на объекты между рантаймами нет, и это стоит учитывать при проектировании архитектуры с первого дня, а не после того как половина логики уже написана. Если сравниваете подход к фреймворкам вообще, полезно посмотреть на сравнение ESX и QBCore для FiveM — сама логика выбора между «готовым фреймворком» и «своим ядром» переносится и на alt:V.

Частые вопросы