Server JavaScript API

Полный справочник глобального объекта varion, доступного в серверном main.js каждого JS-ресурса. Каждый метод и сигнатура здесь сверены с typings-контрактом @varion/server (VarionServerApi) и Node-host.

Ресурс с type = "js" и заданным main запускается платформой автоматически — дополнительных modules не требуется. См. Server scripting и resource.toml.

Модель ресурса

varion — единственный глобальный вход. Импортов нет; объект доступен сразу в области модуля.
Регистрация обработчиков (on, onClient, onRpc), создание таймеров, new VoiceChannel, blip/marker/checkpoint/colshape и entity-фабрики должны вызываться в контексте ресурса — то есть при загрузке модуля или внутри callback этого же ресурса. Вызов вне контекста бросает исключение.
Всё, что создаёт ресурс (обработчики, таймеры, world-хендлы, сущности, voice channels), принадлежит ему и автоматически освобождается при stop/restart. Ручная очистка при выгрузке не нужна.

javascript

varion.log('resource loaded');

varion.on('playerReady', (player) => {
  player.spawn({ x: 215.76, y: -810.12, z: 30.73 }, 157, 0x705E61F2);
});

События (локальные и lifecycle)

Метод	Сигнатура	Назначение
`varion.on`	`on(name, handler)`	Подписка на встроенное или локальное событие. Разрешено несколько обработчиков на имя
`varion.off`	`off(name, handler?)`	Отписка. Без `handler` снимаются обработчики текущего ресурса для этого события
`varion.emit`	`emit(name, ...args)`	Локальное in-process событие. Доставляется `on`-обработчикам на этом же сервере, но не клиентам

Полный список из 41 встроенного server-события с точными аргументами приведён в События и RPC — здесь он не дублируется.

weaponDamage выполняется синхронно перед изменением authoritative health; его обработчик обязан быть синхронным (false отменяет hit, число заменяет damage, undefined принимает исходный). Все прочие события могут быть async.

javascript

varion.on('playerDeath', (player, killer, weaponHash) => {
  varion.log(player.name, 'killed by', killer ? killer.name : 'world');
});

Клиентские события и RPC

Метод	Сигнатура	Назначение
`varion.onClient`	`onClient(name, (player, ...args) => void \| Promise)`	Событие client -> server. Первый аргумент — proxy `Player`, а не числовой id. Разрешено несколько обработчиков
`varion.offClient`	`offClient(name, handler?)`	Отписка от клиентского события
`varion.onRpc`	`onRpc(name, (player, ...args) => result \| Promise)`	RPC client -> server. Ровно один обработчик на имя (повторная регистрация заменяет предыдущий). Только client-initiated. Async поддерживается
`varion.offRpc`	`offRpc(name, handler?)`	Снять RPC-обработчик

Первым аргументом onClient и onRpc всегда приходит Player. Возврат RPC (значение или resolved Promise) отправляется клиенту как результат; брошенное исключение или rejected Promise доходит как RPC-ошибка.

javascript

varion.onClient('chat:message', (player, message) => {
  varion.emitAllClients('chat:addMessage', player.name, String(message));
});

varion.onRpc('inventory:get', async (player) => ({ owner: player.id, slots: 40 }));

Отправка событий клиентам

Метод	Сигнатура	Назначение
`varion.emitClient`	`emitClient(playerId, name, ...args)`	Событие одному игроку. Первый аргумент — числовой id игрока
`varion.emitAllClients`	`emitAllClients(name, ...args)`	Событие всем подключённым игрокам
`player.emit`	`player.emit(name, ...args)`	Тот же адресный вызов через proxy `Player`

emitClient ожидает именно числовой id. Если под рукой объект Player, используйте player.emit(...) или varion.emitClient(player.id, ...).

javascript

varion.emitClient(player.id, 'hud:show', true);
varion.emitAllClients('announce', 'server restarting');

Логирование

varion.log(...parts), varion.logWarning(...parts), varion.logError(...parts) — аргументы приводятся к строке, объединяются пробелом и помечаются именем ресурса в выводе сервера.

Игроки

Метод	Возврат	Назначение
`varion.getPlayer(id)`	`Player`	Proxy игрока по id. Всегда возвращает объект
`varion.getPlayers()`	`Player[]`	Все подключённые игроки
`varion.getPlayerCount()`	`number`	Число подключённых игроков

Объект Player: read-only id, type, valid, name, ip, ping; читаемые и записываемые health, armour, model, dimension, pos (запись сразу применяется к игроку); методы spawn(pos, heading?, model?), kick(reason?), giveWeapon(weaponHash, ammo?), removeAllWeapons(), emit(name, ...args) и семейство metadata (см. ниже). Подробнее — Сущности.

Мир: время и погода

varion.setTime(hour, minute) — установить игровое время.
varion.setWeather(weatherId) — установить погоду по id.

World-визуалы

Все фабрики возвращают хендл { id, type, valid, destroy() }, принадлежащий ресурсу. Опции-объекты — это набор полей визуала (позиция, цвет и т.д.).

Метод	Сигнатура
`varion.createBlip`	`createBlip(options)`
`varion.createRadiusBlip`	`createRadiusBlip(x, y, z, radius, color?, dimension?)`
`varion.createAreaBlip`	`createAreaBlip(x, y, z, width, height, color?, dimension?)`
`varion.createMarker`	`createMarker(options)`
`varion.createCheckpoint`	`createCheckpoint(options)`
`varion.createTextLabel`	`createTextLabel(options)`

javascript

const blip = varion.createRadiusBlip(215, -810, 30, 50, 5);
// ...позже
blip.destroy();

Colshapes

Семь фабрик; каждая возвращает Colshape ({ id, type: 'colshape', valid, destroy() }). Вход/выход поднимают события entityEnterColshape / entityLeaveColshape (и player-варианты) — см. События и RPC.

Метод	Сигнатура
`varion.createColshape`	`createColshape(options)`
`varion.createColshapeSphere`	`createColshapeSphere(x, y, z, radius, dimension?)`
`varion.createColshapeBox`	`createColshapeBox(x, y, z, halfX, halfY, halfZ, dimension?)`
`varion.createColshapeCylinder`	`createColshapeCylinder(x, y, z, radius, height, dimension?)`
`varion.createColshapeCircle`	`createColshapeCircle(x, y, radius, dimension?)`
`varion.createColshapeRectangle`	`createColshapeRectangle(x, y, halfX, halfY, dimension?)`
`varion.createColshapePolygon`	`createColshapePolygon(points, minZ, maxZ, dimension?)`

points для полигона — плоский массив чисел [x0, y0, x1, y1, ...].

Сущности (async)

Метод	Возврат
`varion.createVehicle(model, pos, rot?)`	`Promise<Vehicle>`
`varion.createPed(model, pos, rot?)`	`Promise<Ped>`
`varion.createObject(model, pos, rot?)`	`Promise<ObjectEntity>`

Все три асинхронны: сетевой id выделяет сервер, поэтому дождитесь Promise, чтобы получить proxy сущности. Proxy: id, type, valid, netOwner, destroy() и семейство metadata.

javascript

const car = await varion.createVehicle(varion.hash('adder'),
  { x: 220, y: -805, z: 30 }, { x: 0, y: 0, z: 0 });
car.setStreamSyncedMeta('plate', 'VARION');

Голосовые каналы

varion.createVoiceChannel(spatial, maxDistance?) возвращает VoiceChannel (эквивалент new varion.VoiceChannel(spatial, maxDistance)).

Экземпляр VoiceChannel:

Свойства: id, type, valid, isSpatial, maxDistance, players, playerCount (read-only); priority, filter (read/write).
Методы: addPlayer(player), removePlayer(player), hasPlayer(player), isPlayerInChannel(player), isPlayerMuted(player), mutePlayer(player, muted?) (по умолчанию true), unmutePlayer(player), setFilter(filterHash), destroy().
Статические: VoiceChannel.all (все валидные каналы), VoiceChannel.getByID(id).

Аргумент player принимает proxy Player или числовой id.

javascript

const channel = varion.createVoiceChannel(true, 20);
channel.addPlayer(player);
channel.mutePlayer(player.id);

Metadata

Есть два уровня хранилищ.

Уровень сущности/игрока (методы на proxy Player или Entity):

Метод	Область репликации	Событие
`setMeta(key, value)` / `setMeta(obj)`	Только сервер, не реплицируется	`metaChange`
`setSyncedMeta(...)`	Всем клиентам	`syncedMetaChange`
`setStreamSyncedMeta(...)`	Клиентам, которые сейчас стримят сущность	`streamSyncedMetaChange`

Для каждого набора есть парные get*, has*, delete* и get*Keys.

Глобальный уровень (методы на varion):

Метод	Область репликации	Событие
`varion.setMeta(...)`	Только сервер, не реплицируется	`globalMetaChange`
`varion.setSyncedMeta(...)`	Всем клиентам	`globalSyncedMetaChange`
`varion.setGlobalMeta(...)`	Всем клиентам	`globalSyncedMetaChange`

varion.setSyncedMeta и varion.setGlobalMeta пишут в одно и то же реплицируемое хранилище и оба поднимают globalSyncedMetaChange — это синонимы. Отдельное хранилище только у varion.setMeta (серверный, не реплицируется). Парные get*/has*/delete*/get*Keys есть для всех трёх семейств (...Meta, ...SyncedMeta, ...GlobalMeta). Подробнее — Metadata.

Утилиты

varion.getNetTime() — Promise<number>, миллисекунды с момента старта сервера (асинхронный запрос к платформе).
varion.hash(value) — number, JOAAT-хеш строки (вход приводится к нижнему регистру). Удобно для model- и weapon-хешей.

javascript

const now = await varion.getNetTime();
const model = varion.hash('adder');

Управление ресурсами

Метод	Возврат	Назначение
`varion.getResourceConfig(name?)`	`object`	Таблица `[config]` из `resource.toml`. Синхронно. Без `name` — текущий ресурс (или единственный)
`varion.hasResource(name)`	`boolean`	Известен ли ресурс
`varion.getAllResources()`	`ResourceInfo[]`	Все ресурсы: `{ name, path, valid, started, config }`
`varion.startResource(name)`	`void`	Поставить запуск в очередь (fire-and-forget)
`varion.stopResource(name)`	`void`	Поставить остановку в очередь
`varion.restartResource(name)`	`void`	Поставить перезапуск в очередь
`varion.Resource.current`	`ResourceInfo \| null`	Текущий ресурс
`varion.Resource.get(name)`	`ResourceInfo \| null`	Ресурс по имени
`varion.Resource.all`	`ResourceInfo[]`	Все ресурсы

getResourceConfig синхронный — не используйте await.

javascript

const cfg = varion.getResourceConfig();
if (cfg.debug) varion.log('debug mode');

Таймеры

Таймеры привязаны к ресурсу и автоматически очищаются при его stop/restart. Глобальные setTimeout/setInterval/setImmediate в host тоже обёрнуты и ведут себя так же.

Метод	Назначение
`varion.setTimeout(callback, delay?, ...args)`	Однократный таймер, возвращает хендл
`varion.setInterval(callback, delay?, ...args)`	Периодический таймер, возвращает хендл
`varion.clearTimeout(handle)`	Отменить таймер
`varion.clearInterval(handle)`	Отменить интервал
`varion.nextTick(callback, ...args)`	Выполнить на следующем тике (setImmediate)
`varion.everyTick(callback)`	Выполнять каждый тик (~16 мс)
`varion.clearEveryTick(handle)`	Остановить `everyTick`

Классы

varion.Vector3 — new Vector3(x?, y?, z?) или new Vector3(vectorLike); свойство length; метод distanceTo(other).
varion.RGBA — new RGBA(r = 255, g = 255, b = 255, a = 255).
varion.VoiceChannel — конструктор new VoiceChannel(isSpatial, maxDistance?); см. раздел «Голосовые каналы».

javascript

const a = new varion.Vector3(0, 0, 72);
const b = new varion.Vector3({ x: 10, y: 0, z: 72 });
const d = a.distanceTo(b);
const red = new varion.RGBA(255, 0, 0, 255);

Source backing

Страница сверена с sdk/Varion.Server/npm/@varion/server/index.d.ts (интерфейс VarionServerApi) и рантаймом Node-host server/host/varion-host.cjs. Список встроенных событий — События и RPC.

Server JavaScript API ​

Модель ресурса ​

События (локальные и lifecycle) ​

Клиентские события и RPC ​

Отправка событий клиентам ​

Логирование ​

Игроки ​

Мир: время и погода ​

World-визуалы ​

Colshapes ​

Сущности (async) ​

Голосовые каналы ​

Metadata ​

Утилиты ​

Управление ресурсами ​

Таймеры ​

Классы ​

Source backing ​

Server JavaScript API

Модель ресурса

События (локальные и lifecycle)

Клиентские события и RPC

Отправка событий клиентам

Логирование

Игроки

Мир: время и погода

World-визуалы

Colshapes

Сущности (async)

Голосовые каналы

Metadata

Утилиты

Управление ресурсами

Таймеры

Классы

Source backing