rock-mod 0.20.0 → 0.22.0

package/dist/client/net/ccmp/CCMPConsoleForwarder.js

@@ -0,0 +1,153 @@
+/// <reference types="@classic-mp/types/client" />
+/**
+ * Имя приватного rock-mod события для зеркалирования клиентских `console.*`
+ * вызовов в серверный stdout.
+ *
+ * Серверная сторона (`src/server/net/ccmp/CCMPNetManager.ts`) ловит это
+ * событие и печатает payload через свой `console.log`/`error`/`warn`. Это
+ * критически важно для отладки CCMP: на клиенте `console.log` идёт в игровую
+ * консоль (F8), и разработчик в серверном терминале не видит ничего.
+ */
+const CLIENT_LOG_EVENT = "rm::clientLog";
+const FORWARDED_LEVELS = ["log", "info", "warn", "error", "debug"];
+function safeJsonStringify(value) {
+    try {
+        return JSON.stringify(value, Object.getOwnPropertyNames(value));
+    }
+    catch (_a) {
+        return "[unjsonable]";
+    }
+}
+function safeToString(value) {
+    try {
+        const s = String(value);
+        return s === "[object Object]" ? safeJsonStringify(value) : s;
+    }
+    catch (_a) {
+        return "[unstringifiable]";
+    }
+}
+function safeReadString(value, key) {
+    try {
+        const v = value[key];
+        return typeof v === "string" ? v : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+function looksLikeError(value) {
+    if (value instanceof Error) {
+        return true;
+    }
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const v = value;
+    // Структурные признаки. Хотя бы один из: stack (V8 ставит на ошибки),
+    // или name+message (классический duck-type).
+    return typeof v["stack"] === "string" || (typeof v["name"] === "string" && typeof v["message"] === "string");
+}
+/**
+ * Превращает аргумент в JSON-сериализуемое значение.
+ *
+ * Проблема: `JSON.stringify(new Error("..."))` возвращает `"{}"` — у Error
+ * свойства `message`/`stack` не enumerable. Плюс под deno_core встречаются
+ * "ошибки" не наследующие `Error.prototype` (cross-realm, ops_throw,
+ * NotImplementedProxy через Proxy traps), для которых `instanceof Error`
+ * возвращает false, но визуально они ошибки.
+ *
+ * Стратегия:
+ *  1. Скаляры — как есть.
+ *  2. Если есть `.message`/`.stack` / похожее на Error — пакуем в
+ *     `__error`-обёртку с явно перечисленными полями.
+ *  3. Объекты — пробуем `JSON.stringify`. Если пусто (`{}`/`[]`) или падает
+ *     — добавляем `__toString` с `String(value)`.
+ *  4. Худший случай — голая строка `String(value)`.
+ */
+function serializeArg(value) {
+    var _a, _b;
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const type = typeof value;
+    if (type === "string" || type === "number" || type === "boolean") {
+        return value;
+    }
+    if (looksLikeError(value)) {
+        return {
+            __error: true,
+            name: (_a = safeReadString(value, "name")) !== null && _a !== void 0 ? _a : "Error",
+            message: (_b = safeReadString(value, "message")) !== null && _b !== void 0 ? _b : safeToString(value),
+            stack: safeReadString(value, "stack"),
+            toString: safeToString(value),
+        };
+    }
+    try {
+        const json = JSON.stringify(value);
+        if (json && json !== "{}" && json !== "[]") {
+            return value;
+        }
+        // Пустой JSON для непустого объекта — non-enumerable props. Дублируем
+        // через String(...) чтобы на сервере хоть что-то прочиталось.
+        return {
+            __toString: safeToString(value),
+            __raw: value,
+        };
+    }
+    catch (_c) {
+        return {
+            __toString: safeToString(value),
+        };
+    }
+}
+/**
+ * Создаёт обёртку для конкретного level. Извлечено в именованную функцию,
+ * чтобы избежать `no-loop-func` (захват `ccmp` в замыкании внутри `for`).
+ */
+function createForwardingMethod(level, original) {
+    return (...args) => {
+        try {
+            original(...args);
+        }
+        catch (_a) {
+            // Локальный консоль-вывод не должен ломать форвард.
+        }
+        try {
+            const payload = {
+                level,
+                args: args.map(serializeArg),
+            };
+            ccmp.emitServer(CLIENT_LOG_EVENT, payload);
+        }
+        catch (_b) {
+            // Если сервер недоступен (раннее в boot до handshake) — молча.
+        }
+    };
+}
+/**
+ * Оборачивает `globalThis.console` так, чтобы каждый вызов
+ * `console.log/info/warn/error/debug` дополнительно отправлялся на сервер.
+ * Оригинальное поведение (вывод в локальный игровой лог) сохраняется.
+ *
+ * Идемпотентно: повторный `install()` ничего не делает.
+ */
+export class CCMPConsoleForwarder {
+    constructor() {
+        this._installed = false;
+    }
+    install() {
+        var _a;
+        if (this._installed) {
+            return;
+        }
+        this._installed = true;
+        for (const level of FORWARDED_LEVELS) {
+            const original = (_a = console[level]) === null || _a === void 0 ? void 0 : _a.bind(console);
+            if (!original) {
+                continue;
+            }
+            console[level] = createForwardingMethod(level, original);
+        }
+    }
+}

package/dist/client/net/ccmp/CCMPNetManager.d.ts

@@ -0,0 +1,23 @@
+import { type INetManager } from "../common/INetManager";
+import { CCMPDataHandler } from "./dataHandler/CCMPDataHandler";
+import { CCMPEventsManager } from "./events/CCMPEventsManager";
+import { CCMPRPCManager } from "./rpc/CCMPRPCManager";
+/**
+ * Корневой сетевой менеджер CCMP-клиента.
+ *
+ * Симметричен `RageNetManager` (`src/client/net/ragemp/RageNetManager.ts`), но
+ * без `IEntityPoolRouter` — CCMP entity pool ещё не реализован, а events+RPC
+ * milestone от него не зависит.
+ */
+export declare class CCMPNetManager implements INetManager {
+    private readonly _eventsManager;
+    private readonly _rpcManager;
+    private readonly _dataHandler;
+    private readonly _bridge;
+    private readonly _renderTicker;
+    private readonly _consoleForwarder;
+    get events(): CCMPEventsManager;
+    get rpc(): CCMPRPCManager;
+    get dataHandler(): CCMPDataHandler;
+    constructor();
+}

package/dist/client/net/ccmp/CCMPNetManager.js

@@ -0,0 +1,55 @@
+import { CCMPConsoleForwarder } from "./CCMPConsoleForwarder";
+import { CCMPDataHandler } from "./dataHandler/CCMPDataHandler";
+import { CCMPEventsBridge } from "./events/CCMPEventsBridge";
+import { CCMPEventsManager } from "./events/CCMPEventsManager";
+import { CCMPRenderTicker } from "./events/CCMPRenderTicker";
+import { CCMPRPCManager } from "./rpc/CCMPRPCManager";
+/**
+ * Корневой сетевой менеджер CCMP-клиента.
+ *
+ * Симметричен `RageNetManager` (`src/client/net/ragemp/RageNetManager.ts`), но
+ * без `IEntityPoolRouter` — CCMP entity pool ещё не реализован, а events+RPC
+ * milestone от него не зависит.
+ */
+export class CCMPNetManager {
+    get events() {
+        return this._eventsManager;
+    }
+    get rpc() {
+        return this._rpcManager;
+    }
+    get dataHandler() {
+        return this._dataHandler;
+    }
+    constructor() {
+        // Прямой ping на сервер — не зависит от console-обёртки и других
+        // менеджеров. Серверная сторона (`CCMPNetManager`) логирует через
+        // `rm::clientLog` handler с уровнем info. Если в серверном stdout не
+        // видно "[client:<id>] [rock-mod] CCMP client net manager constructed" —
+        // значит client-бандл не загрузился / не дошёл до этого места.
+        try {
+            ccmp.emitServer("rm::clientLog", {
+                level: "info",
+                args: ["[rock-mod] CCMP client net manager constructed"],
+            });
+        }
+        catch (_a) {
+            // Если сетевой канал не готов, эта диагностическая строка теряется.
+        }
+        // Console forwarder ставим первым: чтобы любые `console.*` из
+        // конструкторов других менеджеров/модулей уже зеркалились на сервер.
+        this._consoleForwarder = new CCMPConsoleForwarder();
+        this._consoleForwarder.install();
+        this._eventsManager = new CCMPEventsManager();
+        this._rpcManager = new CCMPRPCManager();
+        // DataHandler сначала, чтобы он успел подписаться на internal-bus до
+        // первых эмиссий `rm::syncedMetaChange` от `CCMPSyncedMetaBridge`
+        // (registers later, when all stream-synced base-object managers are ready).
+        this._dataHandler = new CCMPDataHandler(this._eventsManager);
+        this._bridge = new CCMPEventsBridge(this._eventsManager);
+        this._renderTicker = new CCMPRenderTicker();
+        this._bridge.registerRawEvents();
+        this._bridge.registerServerEvents();
+        this._renderTicker.start(this._eventsManager);
+    }
+}

package/dist/client/net/ccmp/dataHandler/CCMPDataHandler.d.ts

@@ -0,0 +1,23 @@
+import { type IBaseObject } from "../../../entities";
+import { type IDataHandler } from "../../common/dataHandler/IDataHandler";
+import { type CCMPEventsManager } from "../events/CCMPEventsManager";
+type DataHandlerCallback = (object: IBaseObject, value: unknown, oldValue?: unknown) => void;
+/**
+ * Реализация `IDataHandler` под CCMP поверх `rm::syncedMetaChange`.
+ *
+ * `CCMPSyncedMetaBridge` переводит нативное событие
+ * `ccmp.on('streamSyncedMetaChange')` в internal-bus
+ * `rm::syncedMetaChange(entity, key, value, oldValue)`. Этот класс
+ * держит per-key реестр колбэков и диспатчит на них пришедшие изменения.
+ *
+ * Снапшот всех ключей сущности (отправляется CCMP'ом сразу после
+ * `StreamIn`) тоже проходит через это событие — поэтому первое появление
+ * сущности у клиента триггерит колбэк на каждый уже выставленный сервером
+ * ключ (с `oldValue === undefined`).
+ */
+export declare class CCMPDataHandler implements IDataHandler {
+    private readonly _handlers;
+    constructor(events: CCMPEventsManager);
+    addDataHandler(key: string, callback: DataHandlerCallback): void;
+}
+export {};

package/dist/client/net/ccmp/dataHandler/CCMPDataHandler.js

@@ -0,0 +1,43 @@
+import { ClientInternalEventName } from "../../common/events/types";
+/**
+ * Реализация `IDataHandler` под CCMP поверх `rm::syncedMetaChange`.
+ *
+ * `CCMPSyncedMetaBridge` переводит нативное событие
+ * `ccmp.on('streamSyncedMetaChange')` в internal-bus
+ * `rm::syncedMetaChange(entity, key, value, oldValue)`. Этот класс
+ * держит per-key реестр колбэков и диспатчит на них пришедшие изменения.
+ *
+ * Снапшот всех ключей сущности (отправляется CCMP'ом сразу после
+ * `StreamIn`) тоже проходит через это событие — поэтому первое появление
+ * сущности у клиента триггерит колбэк на каждый уже выставленный сервером
+ * ключ (с `oldValue === undefined`).
+ */
+export class CCMPDataHandler {
+    constructor(events) {
+        this._handlers = new Map();
+        events.onInternal({
+            [ClientInternalEventName.SyncedMetaChange]: (object, key, value, oldValue) => {
+                const callbacks = this._handlers.get(key);
+                if (!callbacks || callbacks.length === 0) {
+                    return;
+                }
+                for (const callback of [...callbacks]) {
+                    try {
+                        callback(object, value, oldValue);
+                    }
+                    catch (error) {
+                        console.error(`[CCMPDataHandler] callback for key "${key}" failed:`, error);
+                    }
+                }
+            },
+        });
+    }
+    addDataHandler(key, callback) {
+        let bucket = this._handlers.get(key);
+        if (!bucket) {
+            bucket = [];
+            this._handlers.set(key, bucket);
+        }
+        bucket.push(callback);
+    }
+}

package/dist/client/net/ccmp/events/CCMPEventsBridge.d.ts

@@ -0,0 +1,14 @@
+import { type IEventsBridge } from "../../common/events/IEventsBridge";
+import { type CCMPEventsManager } from "./CCMPEventsManager";
+/**
+ * Legacy bridge slot for CCMP raw events.
+ *
+ * Player lifecycle and stream events are handled by `CCMPPlayersManager`,
+ * because it can resolve every native `ccmp.players.Player` into the stable
+ * Rock-Mod `CCMPPlayer` instance before emitting internal `rm::*` events.
+ */
+export declare class CCMPEventsBridge implements IEventsBridge {
+    constructor(events: CCMPEventsManager);
+    registerRawEvents(): void;
+    registerServerEvents(): void;
+}

package/dist/client/net/ccmp/events/CCMPEventsBridge.js

@@ -0,0 +1,19 @@
+/**
+ * Legacy bridge slot for CCMP raw events.
+ *
+ * Player lifecycle and stream events are handled by `CCMPPlayersManager`,
+ * because it can resolve every native `ccmp.players.Player` into the stable
+ * Rock-Mod `CCMPPlayer` instance before emitting internal `rm::*` events.
+ */
+export class CCMPEventsBridge {
+    constructor(events) {
+        void events;
+    }
+    registerRawEvents() {
+        // Intentionally empty. See class comment.
+    }
+    registerServerEvents() {
+        // No-op: ранее тут жил handler для cooperation `rm::clientReady`-ответа.
+        // Теперь это responsibility `CCMPPlayersManager`.
+    }
+}

package/dist/client/net/ccmp/events/CCMPEventsManager.d.ts

@@ -0,0 +1,72 @@
+import { type IEventsManager } from "../../common/events/IEventsManager";
+import { type IClientInternalEvents } from "../../common/events/types";
+import { type IClientToServerEvents, type IServerToClientEvents } from "../../../../shared/net/common/events/types";
+/**
+ * Реализация `IEventsManager` поверх нативного CCMP клиента.
+ *
+ * Важные особенности CCMP, продиктовавшие дизайн:
+ *
+ * 1. У `ccmp.on(name, cb)` **нет** парного `ccmp.off`. Поэтому unsubscribe
+ *    реализован через собственный реестр: на каждое имя регистрируется ровно
+ *    один диспетчер в `ccmp`, который проходит по нашему `Set` подписчиков.
+ *    `off` лишь удаляет колбэк из `Set`, диспетчер на стороне CCMP остаётся
+ *    висеть (становится no-op).
+ *
+ * 2. `ccmp.emitServer(event, data)` принимает **одно** значение `data`. Наш
+ *    контракт `emitServer(name, ...args)` — variadic. Чтобы не терять
+ *    позиционные аргументы, всегда отправляем `args` массивом, а на приёме
+ *    разворачиваем обратно. Это совпадает с тем, как сервер уже шлёт клиенту
+ *    (`ccmpPlayer.emit(name, args)` в `CCMPEventsManager` на сервере).
+ *
+ * 3. Локальной in-process шины событий (аналог `mp.events.call`) у CCMP нет —
+ *    под `emitInternal` подкладываем `CCMPInProcessEmitter`. Однако `onInternal`
+ *    дополнительно подписывает handler ещё и на нативный `ccmp.on(name, ...)`,
+ *    потому что геймод использует `events.onInternal` как канал для UI-ingress
+ *    (см. `rock-mod-event-emitter.adapter.ts:61-66` в геймоде: `registerUI()`
+ *    делегирует в `events.onInternal`). Под RageMP такого дубля не нужно,
+ *    потому что `mp.events.add` естественно ловит и `mp.events.call`, и
+ *    CEF-выпуски `mp.trigger`. Побочный эффект: server/system события с тем
+ *    же именем тоже долетят до internal-handler'а — на практике конфликтов
+ *    нет, потому что namespace'ы геймода различаются (`rm::*` server,
+ *    `api:*` UI, `player:*`/`vehicle:*`/etc. internal).
+ *
+ * 4. `IClientEvents` (для `onRaw`/`offRaw`) — RageMP-specific глобальный
+ *    тип. Под CCMP осмысленно регистрировать `ccmp.on('playerConnected', ...)`
+ *    и другие билтины, но строго типизировать их через `IClientEvents` нельзя
+ *    — используем `@ts-expect-error` по аналогии с серверным `CCMPEventsManager`.
+ */
+export declare class CCMPEventsManager implements IEventsManager {
+    /** Реестр всех серверных/raw/generic подписчиков. */
+    private readonly _externalListeners;
+    /** Имена, для которых уже зарегистрирован диспетчер в нативном `ccmp`. */
+    private readonly _dispatched;
+    /** Локальная in-process шина — питает `onInternal`/`emitInternal`. */
+    private readonly _internalEmitter;
+    onRaw(events: Partial<IClientEvents>): void;
+    offRaw<K extends keyof IClientEvents>(eventName: K, listener?: IClientEvents[K]): void;
+    onInternal(events: Partial<IClientInternalEvents>): void;
+    offInternal<K extends keyof IClientInternalEvents>(eventName: K, listener?: IClientInternalEvents[K]): void;
+    emitInternal<K extends keyof IClientInternalEvents>(eventName: K, ...args: Parameters<IClientInternalEvents[K]>): void;
+    /**
+     * Sticky-вариант `emitInternal`. Кэширует последнее значение, чтобы поздние
+     * подписчики (`onInternal`) получили его сразу при подписке. Использовать
+     * для one-shot lifecycle-событий (`rm::playerReady` и т.п.), где гонка между
+     * "событие случилось" и "подписчик зарегистрирован" критична.
+     *
+     * См. `CCMPInProcessEmitter.emitSticky` для подробностей семантики.
+     */
+    emitInternalSticky<K extends keyof IClientInternalEvents>(eventName: K, ...args: Parameters<IClientInternalEvents[K]>): void;
+    /**
+     * Очищает sticky-кэш для конкретного internal-события. Использовать на
+     * disconnect/reset чтобы новые подписчики не получали устаревший local-
+     * player-stub после реконнекта.
+     */
+    clearInternalSticky<K extends keyof IClientInternalEvents>(eventName: K): void;
+    onServer(events: Partial<IServerToClientEvents>): void;
+    offServer<K extends keyof IServerToClientEvents>(eventName: K, listener?: IServerToClientEvents[K]): void;
+    emitServer<K extends keyof IClientToServerEvents>(eventName: K, ...args: Parameters<IClientToServerEvents[K]>): void;
+    register(event: string, listener: (...args: unknown[]) => void): void;
+    unregister(event: string): void;
+    private _registerExternal;
+    private _unregisterExternal;
+}

package/dist/client/net/ccmp/events/CCMPEventsManager.js

@@ -0,0 +1,177 @@
+import { CCMPInProcessEmitter } from "./CCMPInProcessEmitter";
+/**
+ * Реализация `IEventsManager` поверх нативного CCMP клиента.
+ *
+ * Важные особенности CCMP, продиктовавшие дизайн:
+ *
+ * 1. У `ccmp.on(name, cb)` **нет** парного `ccmp.off`. Поэтому unsubscribe
+ *    реализован через собственный реестр: на каждое имя регистрируется ровно
+ *    один диспетчер в `ccmp`, который проходит по нашему `Set` подписчиков.
+ *    `off` лишь удаляет колбэк из `Set`, диспетчер на стороне CCMP остаётся
+ *    висеть (становится no-op).
+ *
+ * 2. `ccmp.emitServer(event, data)` принимает **одно** значение `data`. Наш
+ *    контракт `emitServer(name, ...args)` — variadic. Чтобы не терять
+ *    позиционные аргументы, всегда отправляем `args` массивом, а на приёме
+ *    разворачиваем обратно. Это совпадает с тем, как сервер уже шлёт клиенту
+ *    (`ccmpPlayer.emit(name, args)` в `CCMPEventsManager` на сервере).
+ *
+ * 3. Локальной in-process шины событий (аналог `mp.events.call`) у CCMP нет —
+ *    под `emitInternal` подкладываем `CCMPInProcessEmitter`. Однако `onInternal`
+ *    дополнительно подписывает handler ещё и на нативный `ccmp.on(name, ...)`,
+ *    потому что геймод использует `events.onInternal` как канал для UI-ingress
+ *    (см. `rock-mod-event-emitter.adapter.ts:61-66` в геймоде: `registerUI()`
+ *    делегирует в `events.onInternal`). Под RageMP такого дубля не нужно,
+ *    потому что `mp.events.add` естественно ловит и `mp.events.call`, и
+ *    CEF-выпуски `mp.trigger`. Побочный эффект: server/system события с тем
+ *    же именем тоже долетят до internal-handler'а — на практике конфликтов
+ *    нет, потому что namespace'ы геймода различаются (`rm::*` server,
+ *    `api:*` UI, `player:*`/`vehicle:*`/etc. internal).
+ *
+ * 4. `IClientEvents` (для `onRaw`/`offRaw`) — RageMP-specific глобальный
+ *    тип. Под CCMP осмысленно регистрировать `ccmp.on('playerConnected', ...)`
+ *    и другие билтины, но строго типизировать их через `IClientEvents` нельзя
+ *    — используем `@ts-expect-error` по аналогии с серверным `CCMPEventsManager`.
+ */
+export class CCMPEventsManager {
+    constructor() {
+        /** Реестр всех серверных/raw/generic подписчиков. */
+        this._externalListeners = new Map();
+        /** Имена, для которых уже зарегистрирован диспетчер в нативном `ccmp`. */
+        this._dispatched = new Set();
+        /** Локальная in-process шина — питает `onInternal`/`emitInternal`. */
+        this._internalEmitter = new CCMPInProcessEmitter();
+    }
+    // -- Raw (CCMP builtin) ---------------------------------------------------
+    onRaw(events) {
+        // IClientEvents is RageMP-specific; под CCMP принимаем тот же call-shape,
+        // но привязываем через свой реестр диспетчеров.
+        for (const eventName of Object.keys(events)) {
+            const handler = events[eventName];
+            if (!handler) {
+                continue;
+            }
+            this._registerExternal(eventName, handler);
+        }
+    }
+    offRaw(eventName, listener) {
+        this._unregisterExternal(eventName, listener);
+    }
+    // -- Internal (in-process) ------------------------------------------------
+    onInternal(events) {
+        for (const eventName of Object.keys(events)) {
+            const handler = events[eventName];
+            if (!handler) {
+                continue;
+            }
+            // 1) Локальная in-process шина — питает `emitInternal` от client-кода.
+            this._internalEmitter.on(eventName, handler);
+            // 2) UI ingress. Геймод-адаптер `registerUI()` маппит UI-events через
+            //    `events.onInternal`. Под CCMP UI шлёт `window.ccmp.emitClient(name, payload)`,
+            //    которое приходит на клиент через `ccmp.on(name, handler)`. Подписываем
+            //    тот же handler на нативный канал через общий `_registerExternal`-реестр
+            //    (он управляет single-dispatcher'ом и Array.isArray-unwrap'ом).
+            this._registerExternal(eventName, handler);
+        }
+    }
+    offInternal(eventName, listener) {
+        this._internalEmitter.off(eventName, listener);
+        this._unregisterExternal(eventName, listener);
+    }
+    emitInternal(eventName, ...args) {
+        this._internalEmitter.emit(eventName, ...args);
+    }
+    /**
+     * Sticky-вариант `emitInternal`. Кэширует последнее значение, чтобы поздние
+     * подписчики (`onInternal`) получили его сразу при подписке. Использовать
+     * для one-shot lifecycle-событий (`rm::playerReady` и т.п.), где гонка между
+     * "событие случилось" и "подписчик зарегистрирован" критична.
+     *
+     * См. `CCMPInProcessEmitter.emitSticky` для подробностей семантики.
+     */
+    emitInternalSticky(eventName, ...args) {
+        this._internalEmitter.emitSticky(eventName, ...args);
+    }
+    /**
+     * Очищает sticky-кэш для конкретного internal-события. Использовать на
+     * disconnect/reset чтобы новые подписчики не получали устаревший local-
+     * player-stub после реконнекта.
+     */
+    clearInternalSticky(eventName) {
+        this._internalEmitter.clearSticky(eventName);
+    }
+    // -- Server <-> Client ----------------------------------------------------
+    onServer(events) {
+        for (const eventName of Object.keys(events)) {
+            const handler = events[eventName];
+            if (!handler) {
+                continue;
+            }
+            this._registerExternal(eventName, handler);
+        }
+    }
+    offServer(eventName, listener) {
+        this._unregisterExternal(eventName, listener);
+    }
+    emitServer(eventName, ...args) {
+        // Заворачиваем variadic args в массив — соответствует контракту приёма
+        // на сервере (`CCMPEventsManager.onClient` разворачивает обратно).
+        ccmp.emitServer(eventName, args);
+    }
+    // -- Generic escape hatch -------------------------------------------------
+    register(event, listener) {
+        this._internalEmitter.on(event, listener);
+        this._registerExternal(event, listener);
+    }
+    unregister(event) {
+        this._internalEmitter.off(event);
+        this._unregisterExternal(event);
+    }
+    // -- Implementation details -----------------------------------------------
+    _registerExternal(event, listener) {
+        let bucket = this._externalListeners.get(event);
+        if (!bucket) {
+            bucket = new Set();
+            this._externalListeners.set(event, bucket);
+        }
+        bucket.add(listener);
+        if (!this._dispatched.has(event)) {
+            this._dispatched.add(event);
+            ccmp.on(event, (payload) => {
+                const handlers = this._externalListeners.get(event);
+                if (!handlers || handlers.size === 0) {
+                    return;
+                }
+                // Сервер заворачивает variadic args в массив через
+                // `ccmpPlayer.emit(name, args)`. Однопараметрические/нативные события
+                // (билтины CCMP типа `playerConnected`) приходят как один объект —
+                // их прокидываем как единственный аргумент.
+                const args = Array.isArray(payload) ? payload : [payload];
+                for (const handler of [...handlers]) {
+                    try {
+                        handler(...args);
+                    }
+                    catch (error) {
+                        console.error(`[CCMPEventsManager] handler "${event}" failed:`, error);
+                    }
+                }
+            });
+        }
+    }
+    _unregisterExternal(event, listener) {
+        const bucket = this._externalListeners.get(event);
+        if (!bucket) {
+            return;
+        }
+        if (listener) {
+            bucket.delete(listener);
+            if (bucket.size === 0) {
+                this._externalListeners.delete(event);
+            }
+            return;
+        }
+        this._externalListeners.delete(event);
+        // Нативный `ccmp.on`-диспетчер остаётся висеть — у CCMP нет `off`.
+        // Когда в реестре пусто, он просто ничего не делает.
+    }
+}

package/dist/client/net/ccmp/events/CCMPInProcessEmitter.d.ts

@@ -0,0 +1,45 @@
+type Listener = (...args: unknown[]) => void;
+/**
+ * Тонкий внутренний event bus.
+ *
+ * RageMP даёт `mp.events.call(name, ...args)` для локальной шины поверх своего
+ * движка событий. У CCMP нативной внутренней шины нет — её роль выполняет этот
+ * класс. Используется только из `CCMPEventsManager` для `onInternal` /
+ * `offInternal` / `emitInternal` и из `CCMPEventsBridge` для синтезированных
+ * `rm::*` событий.
+ *
+ * Поддерживает "sticky" events (см. `emitSticky`) для one-shot lifecycle-
+ * сигналов (например `rm::playerReady`), которые могут эмититься до того,
+ * как поздние подписчики из DI-цепочки геймода успели зарегистрироваться.
+ * Sticky-кэш гарантирует, что любой `on()`-вызов после `emitSticky` получит
+ * последнее значение synchronously.
+ */
+export declare class CCMPInProcessEmitter {
+    private readonly _listeners;
+    /** Кэш аргументов для sticky-events. См. `emitSticky` / `on`. */
+    private readonly _stickyCache;
+    on(event: string, listener: Listener): void;
+    off(event: string, listener?: Listener): void;
+    emit(event: string, ...args: unknown[]): void;
+    /**
+     * Как `emit`, но дополнительно кэширует args, чтобы любой будущий
+     * `on(event, listener)` сразу получил воспроизведение последнего значения.
+     *
+     * Использовать только для one-shot lifecycle-событий (`rm::playerReady` и
+     * т.п.), где "позднее" подписавшийся обработчик всё равно должен получить
+     * сигнал. Для регулярных событий (`rm::playerConnected` на каждого нового
+     * игрока) sticky-кэш приведёт к нежелательному поведению — используйте
+     * обычный `emit`.
+     *
+     * Кэш переписывается на каждый последующий вызов с тем же event'ом, так
+     * что подписчики получат последнее значение, не цепочку историй.
+     */
+    emitSticky(event: string, ...args: unknown[]): void;
+    /**
+     * Удаляет sticky-кэш для события. Полезно на disconnect/reset, чтобы
+     * новые подписчики не получили устаревший local-player-stub.
+     */
+    clearSticky(event: string): void;
+    private _callListener;
+}
+export {};