Client GTA natives

Client JavaScript может импортировать GTA native declarations из @varion/natives. Client runtime переписывает эти imports в injected native bridge. Этот bridge доступен scripts как globalThis.__varionNative.

Import forms

import * as native from '@varion/natives';

native.setEntityVisible(varion.Player.local.scriptID, true, false);

Named imports тоже переписываются:

import { playerPedId, getEntityCoords } from '@varion/natives';

const ped = playerPedId();
const pos = getEntityCoords(ped, true);

Generic invoke

Generated native typings expose generic helpers:

import { invoke, invokeFloat, invokeString, invokeVector3 } from '@varion/natives';

// ВНИМАНИЕ: синхронный invoke НЕ возвращает реальное значение игры. Он отправляет
// вызов в bridge и сразу возвращает placeholder (здесь 0).
const health = invoke('GET_ENTITY_HEALTH', varion.Player.local.scriptID); // => 0, не здоровье

Async-хелперы возвращают Promise с реальным значением:

const coords = await native.invokeAsync('GET_ENTITY_COORDS', varion.Player.local.scriptID, true);

Возвращаемые значения: sync и async

Синхронный вызов native — invoke('X', ...), invokeFloat / invokeString / invokeVector3 или native.someNative(...) — НЕ возвращает реальное значение игры. Он отправляет вызов в injected bridge и сразу возвращает placeholder:

Тип результата	Placeholder
число	0
имя начинается с is / has / can / does	false
строка	""
vector3	{ x: 0, y: 0, z: 0 }

Поэтому пример const health = invoke('GET_ENTITY_HEALTH', ...) вернёт 0, а не здоровье. Чтобы получить реальное значение, используйте async-хелперы — они возвращают Promise:

const health = await native.invokeFloatAsync('GET_ENTITY_HEALTH', ped);
const coords = await native.invokeVector3Async('GET_ENTITY_COORDS', ped, true);
const name   = await native.invokeStringAsync('GET_PLAYER_NAME', playerId);
const value  = await native.invokeAsync('SOME_NATIVE', arg1, arg2);

Доступны invokeAsync, invokeFloatAsync, invokeStringAsync и invokeVector3Async.

Единственное исключение — sync-чтение remote entity

Для REMOTE streamed entities client-снапшот является авторитетным, поэтому восемь natives возвращают реальное значение синхронно, когда первым аргументом идёт scriptID удалённого streamed entity:

GET_ENTITY_COORDS, GET_ENTITY_MODEL, GET_ENTITY_SPEED, IS_ENTITY_DEAD, IS_PED_DEAD_OR_DYING, DOES_ENTITY_EXIST, IS_ENTITY_VISIBLE, GET_ENTITY_ALPHA.

Для локального игрока, world state и natives, вызванных по hash, это не действует — нужен async-хелпер.

Game-thread чтения через gameBridge

Часть чтений на game thread (worldToScreen, чтение stats, entity-запросы) идёт через отдельный Promise-путь gameBridge, а не через native invoke:

const screen = await varion.worldToScreenAsync(x, y, z);
const world  = await varion.screenToWorldAsync(screenX, screenY);
const dead   = await entity.isDeadAsync();
const speed  = await entity.getSpeedAsync();
const exists = await entity.existsAsync();

Покрытие natives

Из 6673 зарегистрированных natives 6379 доступны для вызова («supported»); 294 заблокированы из-за неподдерживаемой сигнатуры (вход Vector3 по значению, struct / неизвестные аргументы). Кроме того, под GTA build 3788 около 191 «supported» native не имеют live-hash mapping и в runtime возвращают «unresolved».

Native catalog

Public native reference генерируется из current client SDK typings:

• Native overview
• Full catalog
• NETWORK
• VEHICLE
• PED

Source backing

Страница основана на client/src/scripting/CClientScriptRuntime.cpp, client/src/scripting/CNativeInvoker.cpp, client/src/scripting/CNativeRegistry.generated.cpp и sdk/Varion.Client/types/@varion/natives/index.d.ts.