vimp-engine 0.1.0

package/README.md

@@ -0,0 +1,9 @@
+# vimp-engine
+
+VIMP — движок-приложение: мастер (лобби, WebRTC-сигналинг), P2P-транспорт,
+Worker-хост, мета-модули матча, MVC-каркас клиента. Игровые правила
+(например, `@vimp/tanks`) подключаются динамически через
+[plugin-api](https://github.com/lgick/vimp/blob/main/docs/en/plugin-api.md)
+— этот пакет их не содержит.
+
+Документация: https://github.com/lgick/vimp/tree/main/docs/en

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "vimp-engine",
+  "version": "0.1.0",
+  "description": "VIMP — движок-приложение (мастер, P2P-транспорт, Worker-хост, мета, MVC-каркас клиента)",
+  "type": "module",
+  "exports": {
+    "./lib/*": "./src/lib/*",
+    "./config/*": "./src/config/*",
+    "./host/*": "./src/host/*"
+  },
+  "files": [
+    "src/lib",
+    "src/config",
+    "src/host"
+  ],
+  "scripts": {
+    "dev": "NODE_ENV=development nodemon src/master/main.js -w src/master -w src/lib -w src/config",
+    "start": "NODE_ENV=production node --env-file ../../.env src/master/main.js",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "express": "^5.1.0",
+    "uuid": "^13.0.0",
+    "vite-express": "^0.21.1",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "howler": "^2.2.4",
+    "nodemon": "^3.1.10",
+    "pixi.js": "^8.14.0",
+    "vite": "^7.1.11",
+    "vite-plugin-pug": "^0.4.1"
+  }
+}

package/src/config/authClient.js

@@ -0,0 +1,47 @@
+// Конфиг клиентского логина лобби (Этап B2). Бандлится в клиентскую сборку,
+// как config/lobby.js — auth-сервис живёт на отдельном домене/порте, поэтому
+// serviceUrl должен быть подставлен под конкретный деплой перед сборкой прода
+// (см. docs/en/auth.md).
+export default {
+  // базовый URL центрального auth-сервиса (packages/auth). Дефолт — dev-порт
+  // из packages/auth/src/config/auth.js
+  serviceUrl: 'http://localhost:3010',
+
+  // включённые провайдеры (должны совпадать с packages/auth config.oauth)
+  providers: ['github'],
+
+  // ключ localStorage для identity JWT
+  tokenStorageKey: 'vimpAuthToken',
+
+  // issuer, которым central auth-сервис подписывает identity-токен (Этап B3);
+  // должен совпадать с packages/auth/src/config/auth.js: jwt.issuer — хост
+  // сверяет claim iss токена с этим значением при проверке подписи по /jwks
+  issuer: 'vimp-auth',
+
+  // имя query-параметров, которыми auth-сервис возвращает управление
+  // (redirect на returnUrl после /oauth/:provider/callback)
+  queryParams: {
+    token: 'token',
+    pendingToken: 'pendingToken',
+    error: 'authError',
+  },
+
+  // DOM-элементы экрана логина/ника (views/includes/lobbyAuth.pug) и бейджа
+  // пользователя в лобби (views/includes/lobby.pug)
+  elems: {
+    containerId: 'lobby-auth',
+    loginSectionId: 'lobby-auth-login',
+    loginErrorId: 'lobby-auth-login-error',
+    nickSectionId: 'lobby-auth-nick',
+    nickInputId: 'lobby-auth-nick-input',
+    nickErrorId: 'lobby-auth-nick-error',
+    nickSubmitId: 'lobby-auth-nick-submit',
+    lobbyId: 'lobby',
+    userId: 'lobby-user',
+    userNickId: 'lobby-user-nick',
+    userLogoutId: 'lobby-user-logout',
+  },
+
+  // CSS-класс кнопок провайдеров в lobbyAuth.pug (data-provider на каждой)
+  providerButtonClass: 'lobby-auth-provider',
+};

package/src/config/clientDefaults.js

@@ -0,0 +1,113 @@
+// Движковые дефолты клиентского CONFIG_DATA (порт 0): интерполяция,
+// режимы/служебные клавиши, DOM-структуры движковых модулей, технические
+// сообщения. Игровая половина бывшего config/client.js — src/config/client.js
+// в репозитории игры (например vimp-tanks); merge выполняет buildClientConfig
+// через HostPlugin.buildClientGameConfig.
+export default {
+  // ***** interpolation ***** //
+  // snapshot-интерполяция: мир рендерится в прошлом (serverNow − delay)
+  interpolation: {
+    delay: 100, // мс; ~3 кадра при 30 пакетах/сек
+    maxFrameAge: 1000, // мс; страховочная очистка старых кадров буфера
+  },
+
+  // ***** modules ***** //
+  modules: {
+    canvasManager: {
+      dynamicCamera: {
+        // сила смещения камеры вперед (чем больше, тем дальше смотрит)
+        lookAheadFactor: 30,
+
+        // чувствительность зума (0 - 1)
+        // 0.1 - мягкое отдаление
+        // 0.5 - агрессивное отдаление
+        // 1.0 - экстремально сильная реакция на скорость
+        zoomOutFactor: 0.5,
+
+        // максимально возможное отдаление (от базового масштаба)
+        maxZoomOut: 0.6,
+
+        // плавность изменений позиции камеры (0 - 1)
+        smoothnessPosition: 0.008,
+
+        // плавность изменений зума камеры (0 - 1)
+        smoothnessZoom: 0.005,
+
+        // плавность входящей скорости (0 - 1)
+        // (игнорирует мелкие рывки сети, но реагирует на разгон)
+        smoothnessVelocity: 0.15,
+      },
+    },
+
+    controls: {
+      modes: {
+        67: 'chat', // чат (c)
+        77: 'vote', // опрос (m)
+        9: 'stat', // статистика (tab)
+      },
+      cmds: {
+        27: 'escape', // отмена (escape)
+        13: 'enter', // ввод (enter)
+      },
+    },
+
+    chat: {
+      elems: {
+        chatBox: 'chat-box',
+        cmd: 'cmd',
+      },
+      params: {
+        listLimit: 5,
+        lineTime: 15000,
+        cacheMin: 200,
+        cacheMax: 300,
+      },
+    },
+
+    panel: {
+      // контейнер панели; ячейки генерирует PanelView по схеме игры (fields)
+      containerId: 'panel',
+    },
+
+    stat: {
+      elems: {
+        stat: 'stat',
+      },
+    },
+
+    vote: {
+      elems: {
+        voteId: 'vote',
+        titleClass: 'vote-title',
+        listClass: 'vote-list',
+        navClass: 'vote-nav',
+        navActiveClass: 'active',
+      },
+    },
+  },
+
+  // game information
+  gameInform: {
+    id: 'game-informer',
+  },
+
+  // technical information
+  techInformList: [
+    `Server is full! Please wait or try again later.
+     Max players: {0}
+     You are #{1} in the queue.
+    `,
+
+    'Connection closed due to a new login from another device!',
+
+    'Loading...',
+
+    'Kicked for inactivity.',
+
+    'Connection terminated due to high network latency.',
+
+    'Connection terminated due to missed network pings.',
+
+    'Room is full! Max players: {0}. Try again later.',
+  ],
+};

package/src/config/hostDefaults.js

@@ -0,0 +1,79 @@
+// Движковые дефолты хоста: лимиты комнаты, таймеры, RTT/idle-кики,
+// спектаторский keyset (наблюдение — механизм движка). Игровая половина
+// бывшего config/game.js — src/config/game.js в репозитории игры (например
+// vimp-tanks); merge выполняет host.worker.js через HostPlugin.gameConfig.
+export default {
+  isDevMode: false, // флаг режима разработки
+
+  maxPlayers: 30,
+
+  // максимальная длина сообщения чата (авторитетно на сервере).
+  // должно совпадать с maxlength у input#cmd в client/views/includes/chat.pug
+  chatMaxLength: 60,
+
+  // таймеры (ms)
+  timers: {
+    // время обновления серверного кадра ~120 Гц
+    timeStep: 1000 / 120,
+
+    // частота отправки данных на клиент
+    // каждый 2-ой тик - будет 60 пакетов/сек,
+    // каждый 4-ый тик - будет 30 пакетов/сек (экономно)
+    networkSendRate: 4,
+
+    // время раунда (2 минуты)
+    roundTime: 120000,
+
+    // время карты (10 минут)
+    mapTime: 600000,
+
+    // границы пользовательских roundTime/mapTime комнаты (клампы в
+    // host.worker.js; зеркально min/max в lobby.pug, там в секундах)
+    roomTimeMin: 10000,
+    roomTimeMax: 3600000,
+
+    // время голосования (10 секунд)
+    voteTime: 10000,
+
+    // время ожидания для запуска нового голосования (30 секунд)
+    timeBlockedVote: 30000,
+
+    // время возможности сменить команду в начале раунда (10 секунд)
+    teamChangeGracePeriod: 10000,
+
+    // время ожидания запуска нового раунда после завершения текущего (5 секунд)
+    roundRestartDelay: 5000,
+
+    // время ожидания смены карты после голосования (2 секунды)
+    mapChangeDelay: 2000,
+
+    // интервал обновления RTT (round trip time)
+    rttPingInterval: 3000,
+
+    // периодичность проверки на бездействие (30 секунд)
+    idleCheckInterval: 30000,
+  },
+
+  rtt: {
+    maxMissedPings: 5, // количество пропусков ответа клиента перед киком
+
+    // сглаженная (EMA) задержка ответа для кика (1 секунда).
+    // Порог рассчитан на P2P-хостинг с домашних каналов: реальный RTT
+    // 200-300 мс + спайки на смене карты/старте раунда (клиент занят
+    // перестройкой полотна) — норма, кикать за это нельзя
+    maxLatency: 1000,
+  },
+
+  // порог допустимого бездействия перед киком
+  // если null — кик отключен
+  idleKickTimeout: {
+    player: 120000, // для игрока (2 минуты)
+    spectator: null, // для наблюдателя
+  },
+
+  // конфигурация клавиш наблюдателя и неактивного игрока
+  spectatorKeys: {
+    nextPlayer: 'nextPlayer', // next player (n)
+    prevPlayer: 'prevPlayer', // prev player (p)
+  },
+};

package/src/config/lobby.js

@@ -0,0 +1,104 @@
+// Конфиг лобби (список серверов + умный пинг). Клиент проходит лобби ДО
+// подключения к хосту, поэтому эти параметры бандлятся в сборку, а не приходят
+// от хоста в CONFIG_DATA (как остальной клиентский конфиг).
+export default {
+  // REST-эндпоинт мастера со списком серверов (GET /servers)
+  serversUrl: '/servers',
+
+  // каталог игр мастера (Этап 6.3, GameCatalog): roomDefaults формы создания
+  // комнаты и ClientPlugin берутся отсюда вместо статической композиции
+  gamesManifestUrl: '/games/manifest.json',
+
+  // каталог карт мастера, per-game (Этап 6.4): комната хоста стартует на
+  // актуальных картах активной игры, недоступность каталога — fallback на
+  // карты из бандла
+  maps: {
+    manifestUrl: gameId => `/games/${gameId}/maps/manifest.json`,
+    baseUrl: gameId => `/games/${gameId}/maps`,
+  },
+
+  // манифест конкретной игры (Этап 6.5): эстафета Worker'ов перечитывает его
+  // перед свопом — новый Worker должен получить свежий entries.host/wasm
+  // (деплой игры мог обновиться независимо от деплоя движка)
+  game: {
+    manifestUrl: gameId => `/games/${gameId}/manifest.json`,
+  },
+
+  // манифест worker-бандла мастера (Этап 5.2): Worker комнаты создаётся по
+  // url из манифеста, расхождение codeVersion при re-register — эстафета
+  // Worker'ов; недоступность манифеста — бандловый URL без обновлений кода
+  worker: {
+    manifestUrl: '/worker/manifest.json',
+  },
+
+  // JWKS central auth-сервиса, проксируемый мастером (Этап B3): Worker хоста
+  // фетчит его сам (тот же origin, что и сам Worker) и проверяет подпись
+  // identity-токена, не доверяя auth-сервису напрямую из недоверенного хоста
+  auth: {
+    jwksUrl: '/auth/jwks',
+
+    // rank/state central auth-сервиса, проксируемые мастером (Этап B4):
+    // хост запрашивает их на join своим identity-токеном и синхронизирует
+    // обратно по границам раунда/карты (RoundManager)
+    rankUrl: '/auth/rank',
+    stateUrl: '/auth/state',
+  },
+
+  // переподключение сигнального WS хоста (комната без него выпадает из
+  // выдачи мастера): экспоненциальный бэкофф от baseDelay до maxDelay (мс)
+  reconnect: {
+    baseDelay: 1000,
+    maxDelay: 30000,
+  },
+
+  // размер страницы для «Загрузить ещё» (offset/limit к мастеру)
+  pageSize: 10,
+
+  // минимальный интервал повторного пинга одного сервера (мс):
+  // защита от спама ping_host при перерисовке/скролле списка
+  pingInterval: 5000,
+
+  // DOM-элементы лобби (из lobby.pug)
+  elems: {
+    lobbyId: 'lobby',
+    listId: 'lobby-list',
+    searchId: 'lobby-search',
+    moreId: 'lobby-more',
+    emptyId: 'lobby-empty',
+    nameId: 'lobby-name',
+    hostBtnId: 'lobby-host',
+    // селектор игры: скрыт, пока в каталоге мастера одна игра (§6, PLAN.md)
+    gameId: 'lobby-game',
+    // контейнер полей комнаты: генерируются по ключам roomDefaults
+    // манифеста активной игры (Д7) — движок не знает игровых полей
+    fieldsId: 'lobby-fields',
+  },
+
+  // движковые подсказки генератору формы комнаты (только движковые ключи
+  // roomDefaults; игровые поля выводятся из типа значения)
+  form: {
+    // тайм-ключи движка: в roomDefaults хранятся в мс, в форме — секунды
+    secondsKeys: ['roundTime', 'mapTime'],
+    // атрибуты числовых полей (в единицах формы)
+    attrs: {
+      maxPlayers: { min: 1 },
+      roundTime: { min: 10, max: 3600 },
+      mapTime: { min: 10, max: 3600 },
+    },
+  },
+
+  // создание комнаты (хост в этой же вкладке); лимит игроков/время
+  // раунда-карты/огонь по своим/карта по умолчанию — из roomDefaults
+  // манифеста активной игры (Этап 6.3), не бандлятся здесь
+  create: {
+    defaultName: 'My Server',
+
+    // период heartbeat/актуализации комнаты у мастера (мс); должен быть
+    // меньше master.host.heartbeatTimeout (30 c), иначе комнату выметет
+    heartbeatInterval: 10000,
+
+    // socketId loopback-соединения хоста-игрока: по нему Worker исключает
+    // хоста из kick-политик (его отключение = смерть комнаты для всех)
+    hostSocketId: 'local',
+  },
+};

package/src/config/master.js

@@ -0,0 +1,103 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// корень репозитория — якорь от расположения файла, не от cwd
+const rootDir = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..', '..', '..');
+
+export default {
+  name: 'VIMP Master Server',
+  protocol: 'https:',
+  domain: 'localhost',
+  // 3000 — игровой сервер, 3001 — Vite HMR (vite.config.js)
+  port: 3002,
+
+  // сертификаты для локальной разработки — в .certs корня репозитория
+  // (в продакшене обычный HTTP за Nginx)
+  httpsOptions: {
+    key: path.join(rootDir, '.certs', 'key.pem'),
+    cert: path.join(rootDir, '.certs', 'cert.pem'),
+  },
+
+  // список игр-плагинов, подключаемых к мастеру (Этап A2 плана разделения):
+  // `package` — имя npm-пакета игры, резолвится через node_modules; пакет
+  // объявлен зависимостью в корневом package.json репозитория (деплой-уровень),
+  // не в packages/engine — vimp-engine остаётся game-agnostic и не тянет
+  // конкретную игру за собой (кодревью Этапов A, находка F1). `version` не
+  // используется GameCatalog напрямую, это опорная точка для проверки версии
+  // при деплое (Этап A4). В проде переопределяется переменной окружения
+  // GAMES_MATRIX (JSON), см. master/main.js
+  games: [{ id: 'tanks', package: '@vimp/tanks', version: '0.1.0' }],
+
+  // список серверов (GET /servers)
+  servers: {
+    // если всего комнат <= порога — региональный фильтр
+    // и пагинация отключаются, отдаётся весь список
+    regionThreshold: 15,
+    defaultLimit: 10, // размер страницы по умолчанию
+    maxLimit: 50, // максимальный размер страницы
+  },
+
+  // ограничения регистрируемых комнат
+  host: {
+    maxNameLength: 30, // длина имени комнаты
+    maxPlayersLimit: 8, // целевой размер комнаты (рамка P2P-плана)
+    heartbeatTimeout: 30000, // нет heartbeat дольше — комната удаляется
+    sweepInterval: 10000, // период проверки протухших комнат
+  },
+
+  // рейтинг хостера комнаты (server-rating этап 2, plan/server-rating/
+  // stage_2.md): /like·/unlike гостей комнаты вместо соц-модерации /ban.
+  // Дефолт движка для всех игр; auth-сервис хранит и клампит рейтинг
+  // персистентно и глобально (нужно и для аннулирования rank/skills, этап 4) —
+  // это значение зеркалируется в packages/auth/src/config/auth.js:rating,
+  // фактический кламп/blocked считает auth, не мастер
+  rating: {
+    min: -10,
+    max: 10,
+    blockAt: -10,
+    // период опроса auth за актуальным рейтингом активных хостеров (этап 3,
+    // stage_3.md) — держит кэш GET /servers свежим (счёт мог измениться на
+    // другом мастере), голос/регистрация на этом мастере обновляют кэш сразу
+    refreshInterval: 30000,
+  },
+
+  // заголовки безопасности (гигиена среды, Этап 5.4). CSP на статику/.wasm в
+  // проде ставит Nginx (см. docs/deployment.md) — здесь single source of truth
+  // политики; мастер применяет её к своим ответам только в проде (в dev CSP
+  // сломала бы Vite HMR). WASM требует 'wasm-unsafe-eval', Worker — 'blob:';
+  // connect-src data: — PixiJS фетчит тестовый data:-URL для проверки ImageBitmap.
+  // authServiceUrl (Этап B2) — домен central auth-сервиса (packages/auth):
+  // лобби делает туда прямой fetch (POST /nick), поэтому connect-src должен
+  // его разрешать; сам OAuth-редирект (location.href на auth-сервис/провайдера)
+  // CSP не ограничивает — это навигация верхнего уровня, не fetch/XHR
+  security: {
+    authServiceUrl: 'http://localhost:3010',
+    csp: authServiceUrl =>
+      [
+        "default-src 'self'",
+        "script-src 'self' 'wasm-unsafe-eval'",
+        "worker-src 'self' blob:",
+        `connect-src 'self' wss: data: ${authServiceUrl}`,
+        "img-src 'self' data: blob:",
+        "style-src 'self' 'unsafe-inline'",
+        "object-src 'none'",
+        "base-uri 'self'",
+        "frame-ancestors 'none'",
+      ].join('; '),
+    referrerPolicy: 'no-referrer',
+  },
+
+  // заголовок с регионом хоста от Nginx/CDN (например, CF-IPCountry);
+  // выбран вместо geoip-lite — бесплатнее по памяти
+  regionHeader: 'x-region',
+
+  // лимит сигнальных ping-запросов с одного IP (защита от DDOS)
+  pingRateLimit: {
+    limit: 10,
+    windowMs: 1000,
+  },
+
+  // ICE-конфигурация для установки P2P-соединений:
+  // STUN обязателен; TURN — опциональный релей по итогам Этапа 0
+  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
+};

package/src/config/opcodes.js

@@ -0,0 +1,29 @@
+// Разметка бинарного snapshot-протокола (порт SHOT_DATA).
+// Единый источник для хоста (упаковка) и клиента (распаковка) — обе стороны
+// живут в Rust-ядре: packages/engine/core/src/snapshot.rs (pack) и packages/engine/core/src/client/unpack.rs.
+
+// версия контракта движок ↔ игра-плагин (GameManifest, HostPlugin,
+// ClientPlugin, Wasm Host ABI — docs/{en,ru}/plugin-api.md);
+// проверяется при загрузке плагинов; ломающие изменения контрактов → +1.
+// Пока номинальная: код движка и игры ещё монолитен (см. PLAN.md)
+export const ENGINE_API_VERSION = 1;
+
+// версия формата кадра: первый байт после порта;
+// увеличивать при любом изменении байтовой раскладки в ядре
+// v2: per-user player-блок (gameId, inputSeq, состояние своего танка) — Фаза 5b
+// v3: id автора в событиях оружия (tracers +shooterId, bombs +ownerId) — Фаза 5c
+export const SNAPSHOT_FORMAT_VERSION = 3;
+
+// Реестр ключей снапшота (SNAPSHOT_KEYS) — игровая схема: живёт в
+// gameConfig.snapshot игры (например src/config/snapshot.js в vimp-tanks),
+// движок передаёт её ядру (lib/coreConfig.js) и клиенту в CONFIG_DATA
+// (lib/buildClientConfig.js), не зная раскладки.
+
+// флаги hot-буфера рендер-тика клиентского ядра
+// (зеркало core/src/client/mod.rs в репозитории игры, например vimp-tanks)
+export const HOT_FLAGS = {
+  GAME: 1,
+  CAMERA: 2,
+  PREDICTED: 4,
+  FRAMES: 8,
+};

package/src/config/wsports.js

@@ -0,0 +1,35 @@
+export default {
+  // порты получения данные от сервера
+  server: {
+    CONFIG_DATA: 0,
+    AUTH_DATA: 1,
+    AUTH_RESULT: 2,
+    MAP_DATA: 3,
+    FIRST_SHOT_DATA: 4,
+    SHOT_DATA: 5,
+    SOUND_DATA: 6,
+    GAME_INFORM_DATA: 7,
+    TECH_INFORM_DATA: 8,
+    MISC: 9,
+    PING: 10,
+    CLEAR: 11,
+    CONSOLE: 12,
+    PANEL_DATA: 13,
+    STAT_DATA: 14,
+    CHAT_DATA: 15,
+    VOTE_DATA: 16,
+    KEYSET_DATA: 17,
+  },
+  // порты получения данных от клиента
+  client: {
+    CONFIG_READY: 0,
+    AUTH_RESPONSE: 1,
+    MODULES_READY: 2,
+    MAP_READY: 3,
+    FIRST_SHOT_READY: 4,
+    KEYS_DATA: 5,
+    CHAT_DATA: 6,
+    VOTE_DATA: 7,
+    PONG: 8,
+  },
+};