rock-mod 0.20.0 → 0.21.0

package/dist/client/game/ccmp/keys/CCMPKeysManager.d.ts

@@ -0,0 +1,41 @@
+import { type IKeysManager } from "../../common/keys/IKeysManager";
+type KeyHandler = () => void;
+/**
+ * Реализация `IKeysManager` поверх нативных CCMP-событий `keyDown`/`keyUp`.
+ *
+ * Контрактные тонкости (зеркало RageMP `mp.keys.bind`):
+ *  - `keyHold = false` → handler срабатывает на **нажатие** (`keyDown`).
+ *  - `keyHold = true`  → handler срабатывает на **отпускание** (`keyUp`).
+ *    Несмотря на название параметра, это НЕ "только когда зажато",
+ *    это "при отпускании после нажатия". См. RageMP wiki.
+ *
+ * Архитектура:
+ *  - Делаем **одну** глобальную подписку на `ccmp.on('keyDown')` и одну
+ *    на `keyUp` в конструкторе. Дальше сами роутим по `key`-коду через
+ *    `Map<key, { down: Set, up: Set }>`. Это намного эффективнее, чем
+ *    регистрировать новый `ccmp.on` на каждый `bind`, и убирает проблему
+ *    отсутствующего у CCMP `ccmp.off` (наш dispatcher остаётся в силе,
+ *    меняется только содержимое внутреннего реестра).
+ *  - Параллельно ведём `_pressedKeys: Set<number>` — текущее состояние,
+ *    чтобы `isDown`/`isUp` отвечали синхронно (у CCMP нет API запроса
+ *    состояния клавиши).
+ *
+ * Auto-repeat: если CCMP-клиент эмитит `keyDown` повторно при удержании
+ * (как WM_KEYDOWN auto-repeat), то и наши `down`-handler'ы будут срабатывать
+ * повторно — это зеркало RageMP-поведения. Не маскируем намеренно: gamemod-
+ * консьюмеры писались под такую семантику.
+ *
+ * Snapshot при диспатче (`[...binding.down]`) защищает от модификации Set
+ * из handler'а — `bind`/`unbind` внутри callback'а не ломают текущую итерацию.
+ */
+export declare class CCMPKeysManager implements IKeysManager {
+    private readonly _pressedKeys;
+    private readonly _bindings;
+    constructor();
+    isDown(key: number): boolean;
+    isUp(key: number): boolean;
+    bind(key: number, keyHold: boolean, handler: KeyHandler): void;
+    unbind(key: number, keyHold: boolean, handler?: KeyHandler): void;
+    private _dispatch;
+}
+export {};

package/dist/client/game/ccmp/keys/CCMPKeysManager.js

@@ -0,0 +1,94 @@
+/// <reference types="@classic-mp/types/client" />
+/**
+ * Реализация `IKeysManager` поверх нативных CCMP-событий `keyDown`/`keyUp`.
+ *
+ * Контрактные тонкости (зеркало RageMP `mp.keys.bind`):
+ *  - `keyHold = false` → handler срабатывает на **нажатие** (`keyDown`).
+ *  - `keyHold = true`  → handler срабатывает на **отпускание** (`keyUp`).
+ *    Несмотря на название параметра, это НЕ "только когда зажато",
+ *    это "при отпускании после нажатия". См. RageMP wiki.
+ *
+ * Архитектура:
+ *  - Делаем **одну** глобальную подписку на `ccmp.on('keyDown')` и одну
+ *    на `keyUp` в конструкторе. Дальше сами роутим по `key`-коду через
+ *    `Map<key, { down: Set, up: Set }>`. Это намного эффективнее, чем
+ *    регистрировать новый `ccmp.on` на каждый `bind`, и убирает проблему
+ *    отсутствующего у CCMP `ccmp.off` (наш dispatcher остаётся в силе,
+ *    меняется только содержимое внутреннего реестра).
+ *  - Параллельно ведём `_pressedKeys: Set<number>` — текущее состояние,
+ *    чтобы `isDown`/`isUp` отвечали синхронно (у CCMP нет API запроса
+ *    состояния клавиши).
+ *
+ * Auto-repeat: если CCMP-клиент эмитит `keyDown` повторно при удержании
+ * (как WM_KEYDOWN auto-repeat), то и наши `down`-handler'ы будут срабатывать
+ * повторно — это зеркало RageMP-поведения. Не маскируем намеренно: gamemod-
+ * консьюмеры писались под такую семантику.
+ *
+ * Snapshot при диспатче (`[...binding.down]`) защищает от модификации Set
+ * из handler'а — `bind`/`unbind` внутри callback'а не ломают текущую итерацию.
+ */
+export class CCMPKeysManager {
+    constructor() {
+        this._pressedKeys = new Set();
+        this._bindings = new Map();
+        ccmp.on("keyDown", (key) => {
+            this._pressedKeys.add(key);
+            this._dispatch(key, "down");
+        });
+        ccmp.on("keyUp", (key) => {
+            this._pressedKeys.delete(key);
+            this._dispatch(key, "up");
+        });
+    }
+    isDown(key) {
+        return this._pressedKeys.has(key);
+    }
+    isUp(key) {
+        return !this._pressedKeys.has(key);
+    }
+    bind(key, keyHold, handler) {
+        let binding = this._bindings.get(key);
+        if (!binding) {
+            binding = { down: new Set(), up: new Set() };
+            this._bindings.set(key, binding);
+        }
+        (keyHold ? binding.up : binding.down).add(handler);
+    }
+    unbind(key, keyHold, handler) {
+        const binding = this._bindings.get(key);
+        if (!binding) {
+            return;
+        }
+        const set = keyHold ? binding.up : binding.down;
+        if (handler === undefined) {
+            // RageMP-семантика: без handler — удаляем все подписки на (key, keyHold).
+            set.clear();
+        }
+        else {
+            set.delete(handler);
+        }
+        if (binding.down.size === 0 && binding.up.size === 0) {
+            this._bindings.delete(key);
+        }
+    }
+    _dispatch(key, phase) {
+        const binding = this._bindings.get(key);
+        if (!binding) {
+            return;
+        }
+        const handlers = phase === "down" ? binding.down : binding.up;
+        if (handlers.size === 0) {
+            return;
+        }
+        // Snapshot: handler может вызвать bind/unbind, мы не должны ломать
+        // итерацию по Set.
+        for (const handler of [...handlers]) {
+            try {
+                handler();
+            }
+            catch (error) {
+                console.error(`[CCMPKeysManager] ${phase}-handler for key ${key} threw:`, error);
+            }
+        }
+    }
+}

package/dist/client/game/ccmp/nametags/CCMPNametagsManager.d.ts

@@ -0,0 +1,4 @@
+import { type INametagsManager } from "../../common/nametags/INametagsManager";
+export declare class CCMPNametagsManager implements INametagsManager {
+    setEnabled(enabled: boolean): void;
+}

package/dist/client/game/ccmp/nametags/CCMPNametagsManager.js

@@ -0,0 +1,6 @@
+/// <reference types="@classic-mp/types/client" />
+export class CCMPNametagsManager {
+    setEnabled(enabled) {
+        ccmp.nametags.setEnabled(enabled);
+    }
+}

package/dist/client/game/ccmp/native/CCMPNativeCallerManager.d.ts

@@ -0,0 +1,74 @@
+import { type INativeCallerManager } from "../../common/native/INativeCallerManager";
+/**
+ * Реализация `INativeCallerManager` под CCMP — полноценный generic dispatch
+ * GTA V-нативов по hex-хэшу.
+ *
+ * ### Архитектура
+ *
+ * **Таблица hash→method** генерируется на build-time скриптом
+ * `scripts/generate-native-dispatch.mjs` из alloc8or-format nativedb
+ * (`scripts/data/natives.json`, ~6649 натов). Output:
+ * `_generated/nativeDispatch.ts`. Каждая запись — `{ns: "<ccmp-namespace>",
+ * methods: ["<camelMethod1>", "<camelMethod2-fallback>"]}`, где `methods[]`
+ * содержит канонический имя натива + все `old_names` алиасы (нужно потому
+ * что CCMP-биндинги могут использовать либо новое каноническое, либо
+ * легаси-имя в зависимости от момента генерации `@classic-mp/types`).
+ *
+ * **Runtime resolve**: при первом вызове `callNative(hash, ...args)`:
+ *  1. Lookup в `NATIVE_DISPATCH[hash.toLowerCase()]` → `{ns, methods[]}`.
+ *  2. `ccmp.natives[ns]` — берём namespace-объект.
+ *  3. Перебираем `methods[]` в порядке: для первой существующей функции —
+ *     биндим `[nsObj, fn]` в `_resolved` кэш.
+ *  4. Зовём с args через `fn.apply(nsObj, args)`.
+ *  5. Адаптируем return-shape (см. ниже).
+ *
+ * Lookup-кэш `_resolved` — Map с hash-ключом, чтобы не дёргать
+ * `NATIVE_DISPATCH[]` + `_resolve()` на каждый вызов (multiple natives
+ * вызываются на каждый render-tick).
+ *
+ * ### Адаптация return-shape (CCMP → RageMP-конвенция)
+ *
+ * CCMP-нативы для multi-return значений возвращают **объект** с именованными
+ * полями (например, `getGameplayCamCoord()` → `{x, y, z}`). Геймод (написанный
+ * под RageMP-конвенцию) ожидает **массив-кортеж** (`[x, y, z]`).
+ *
+ * Generic `_adaptResult`:
+ *  - `boolean` (top-level) → `0` или `1` (RageMP'шный native-bool протокол:
+ *    `mp.game.invoke(boolNative)` возвращает число).
+ *  - Object с string-keys → `Object.values(obj)` (порядок гарантирован ES2015
+ *    insertion-order для non-integer keys; CCMP-типы декларируют поля в
+ *    каноническом порядке).
+ *  - Nested object внутри tuple → рекурсивно тоже `Object.values()`
+ *    (для нативов вроде `getShapeTestResult` с nested `endcoords: {x,y,z}`).
+ *  - Bool **внутри** объекта/tuple → не конвертим (нужен для tuple-полей
+ *    типа `[bool, x, y]` где геймод-тип честно ожидает boolean).
+ *  - Primitives / arrays / null → passthrough.
+ *
+ * ### Hot path
+ *
+ * `callNative` вызывается из render-tick consumer'ов: `HudController`
+ * (drawBlip), `CameraIdleController.onInterval`, `VehicleIndicatorService`,
+ * `PolygonZoneRenderer`, `ScriptedMarker`, `ConeDebugRenderer`. После прогрева
+ * `_resolved`-кэша — один Map.get + `fn.apply` + adapt-проход. Адапт — линейный
+ * по числу полей возврата (обычно ≤ 5), стоимость незначительная.
+ *
+ * ### Ошибки
+ *
+ * - **Hash не в DB**: натив отсутствует в nativedb. Throws с подсказкой
+ *   "обновите scripts/data/natives.json" — обычно случается для свежих
+ *   build-specific натов, не вошедших в last-snapshot базы.
+ * - **Namespace не в `ccmp.natives`**: CCMP-runtime версия не имеет такого
+ *   namespace'а. Throws с указанием ns.
+ * - **Все method-кандидаты отсутствуют в namespace'е**: CCMP-биндинг не
+ *   экспонирует ни одного из known-имён. Throws с перечислением кандидатов.
+ */
+export declare class CCMPNativeCallerManager implements INativeCallerManager {
+    private readonly _resolved;
+    callNative(hash: string, ...args: unknown[]): unknown;
+    private _resolve;
+    /**
+     * Конвертация CCMP object-return → RageMP tuple-return.
+     * См. block-комментарий класса (Адаптация return-shape).
+     */
+    private static _adaptResult;
+}

package/dist/client/game/ccmp/native/CCMPNativeCallerManager.js

@@ -0,0 +1,129 @@
+/// <reference types="@classic-mp/types/client" />
+import { NATIVE_DISPATCH } from "./_generated/nativeDispatch";
+/**
+ * Реализация `INativeCallerManager` под CCMP — полноценный generic dispatch
+ * GTA V-нативов по hex-хэшу.
+ *
+ * ### Архитектура
+ *
+ * **Таблица hash→method** генерируется на build-time скриптом
+ * `scripts/generate-native-dispatch.mjs` из alloc8or-format nativedb
+ * (`scripts/data/natives.json`, ~6649 натов). Output:
+ * `_generated/nativeDispatch.ts`. Каждая запись — `{ns: "<ccmp-namespace>",
+ * methods: ["<camelMethod1>", "<camelMethod2-fallback>"]}`, где `methods[]`
+ * содержит канонический имя натива + все `old_names` алиасы (нужно потому
+ * что CCMP-биндинги могут использовать либо новое каноническое, либо
+ * легаси-имя в зависимости от момента генерации `@classic-mp/types`).
+ *
+ * **Runtime resolve**: при первом вызове `callNative(hash, ...args)`:
+ *  1. Lookup в `NATIVE_DISPATCH[hash.toLowerCase()]` → `{ns, methods[]}`.
+ *  2. `ccmp.natives[ns]` — берём namespace-объект.
+ *  3. Перебираем `methods[]` в порядке: для первой существующей функции —
+ *     биндим `[nsObj, fn]` в `_resolved` кэш.
+ *  4. Зовём с args через `fn.apply(nsObj, args)`.
+ *  5. Адаптируем return-shape (см. ниже).
+ *
+ * Lookup-кэш `_resolved` — Map с hash-ключом, чтобы не дёргать
+ * `NATIVE_DISPATCH[]` + `_resolve()` на каждый вызов (multiple natives
+ * вызываются на каждый render-tick).
+ *
+ * ### Адаптация return-shape (CCMP → RageMP-конвенция)
+ *
+ * CCMP-нативы для multi-return значений возвращают **объект** с именованными
+ * полями (например, `getGameplayCamCoord()` → `{x, y, z}`). Геймод (написанный
+ * под RageMP-конвенцию) ожидает **массив-кортеж** (`[x, y, z]`).
+ *
+ * Generic `_adaptResult`:
+ *  - `boolean` (top-level) → `0` или `1` (RageMP'шный native-bool протокол:
+ *    `mp.game.invoke(boolNative)` возвращает число).
+ *  - Object с string-keys → `Object.values(obj)` (порядок гарантирован ES2015
+ *    insertion-order для non-integer keys; CCMP-типы декларируют поля в
+ *    каноническом порядке).
+ *  - Nested object внутри tuple → рекурсивно тоже `Object.values()`
+ *    (для нативов вроде `getShapeTestResult` с nested `endcoords: {x,y,z}`).
+ *  - Bool **внутри** объекта/tuple → не конвертим (нужен для tuple-полей
+ *    типа `[bool, x, y]` где геймод-тип честно ожидает boolean).
+ *  - Primitives / arrays / null → passthrough.
+ *
+ * ### Hot path
+ *
+ * `callNative` вызывается из render-tick consumer'ов: `HudController`
+ * (drawBlip), `CameraIdleController.onInterval`, `VehicleIndicatorService`,
+ * `PolygonZoneRenderer`, `ScriptedMarker`, `ConeDebugRenderer`. После прогрева
+ * `_resolved`-кэша — один Map.get + `fn.apply` + adapt-проход. Адапт — линейный
+ * по числу полей возврата (обычно ≤ 5), стоимость незначительная.
+ *
+ * ### Ошибки
+ *
+ * - **Hash не в DB**: натив отсутствует в nativedb. Throws с подсказкой
+ *   "обновите scripts/data/natives.json" — обычно случается для свежих
+ *   build-specific натов, не вошедших в last-snapshot базы.
+ * - **Namespace не в `ccmp.natives`**: CCMP-runtime версия не имеет такого
+ *   namespace'а. Throws с указанием ns.
+ * - **Все method-кандидаты отсутствуют в namespace'е**: CCMP-биндинг не
+ *   экспонирует ни одного из known-имён. Throws с перечислением кандидатов.
+ */
+export class CCMPNativeCallerManager {
+    constructor() {
+        this._resolved = new Map();
+    }
+    callNative(hash, ...args) {
+        const key = hash.toLowerCase();
+        let resolved = this._resolved.get(key);
+        if (!resolved) {
+            resolved = this._resolve(key, hash);
+            this._resolved.set(key, resolved);
+        }
+        const [nsObj, fn] = resolved;
+        const result = fn.apply(nsObj, args);
+        return CCMPNativeCallerManager._adaptResult(result);
+    }
+    _resolve(key, originalHash) {
+        const entry = NATIVE_DISPATCH[key];
+        if (!entry) {
+            throw new Error(`CCMPNativeCallerManager.callNative: native hash "${originalHash}" не найден ` +
+                "в nativedb (scripts/data/natives.json). Если натив был добавлен недавно " +
+                "— обновите snapshot из CCMP-проекта и перезапустите " +
+                "`node scripts/generate-native-dispatch.mjs`.");
+        }
+        const natives = ccmp.natives;
+        const nsObj = natives[entry.ns];
+        if (!nsObj) {
+            throw new Error(`CCMPNativeCallerManager.callNative: native hash "${originalHash}" — namespace ` +
+                `"ccmp.natives.${entry.ns}" отсутствует в runtime. Возможно, версия CCMP ` +
+                "не соответствует версии nativedb.");
+        }
+        for (const method of entry.methods) {
+            const fn = nsObj[method];
+            if (typeof fn === "function") {
+                return [nsObj, fn];
+            }
+        }
+        throw new Error(`CCMPNativeCallerManager.callNative: native hash "${originalHash}" — ни один ` +
+            `из method-кандидатов [${entry.methods.join(", ")}] не существует в ` +
+            `ccmp.natives.${entry.ns}. CCMP-биндинг не экспонирует этот натив; ` +
+            "при необходимости — пропатчить @classic-mp/types или маппинг в nativedb.");
+    }
+    /**
+     * Конвертация CCMP object-return → RageMP tuple-return.
+     * См. block-комментарий класса (Адаптация return-shape).
+     */
+    static _adaptResult(r) {
+        if (typeof r === "boolean") {
+            // Top-level boolean → RageMP-конвенция 0/1.
+            return r ? 1 : 0;
+        }
+        if (r === null || typeof r !== "object" || Array.isArray(r)) {
+            return r;
+        }
+        // Object: flatten в tuple через Object.values, recursively для nested objects.
+        // Booleans внутри объекта НЕ конвертим — геймод-типы могут честно ожидать bool
+        // в multi-return tuple-полях.
+        return Object.values(r).map((v) => {
+            if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+                return Object.values(v);
+            }
+            return v;
+        });
+    }
+}

package/dist/client/game/ccmp/native/_generated/nativeDispatch.d.ts

@@ -0,0 +1,5 @@
+export interface NativeDispatchEntry {
+    readonly ns: string;
+    readonly methods: readonly string[];
+}
+export declare const NATIVE_DISPATCH: Readonly<Record<string, NativeDispatchEntry>>;