# Движок плеера Рублокса

Это движок, который **запускает** игры созданные в [студии](https://studio.rublox.pro). В отличие от студии, плеер **только проигрывает** — не редактирует.

## Чем плеер отличается от студии

Обе используют **общий код движка** (BlockManager, PhysicsWorld, ScriptSandbox и т.д.) — это исторически наследие, движок был выделен в студию когда плеер уже существовал. Сейчас репозитории отдельные, но движок один и тот же на 90%.

**Что есть в плеере и нет в студии:**
- `PlayerAuth` через ticket-flow (см. `src/auth/`)
- Polling статуса игры (опубликована / в премодерации / заблокирована)
- Heartbeat для метрик `/kubikon3d/play/heartbeat`
- Чат внутри игры
- Лидерборд по очкам
- Кнопка «Сообщить о баге» (`/kubikon3d/bug-reports`)
- Кнопка «Пожаловаться» (`/kubikon3d/reports`)

**Что есть в студии и нет в плеере:**
- Редактирование сцены (gizmo, кисти, инспектор)
- Сохранение `PUT /projects/<id>`
- Загрузка моделей юзера
- Скрипт-редактор Monaco
- CAD-редактор моделей
- Геймдиз-инструменты (Geometry Dash sub-app)

## Файлы

| Файл | Что |
|---|---|
| `BabylonScene.js` | Главный класс — Engine + Scene + Camera. Тот же что в студии но без gizmo и SelectionManager. |
| `BlockManager.js` | Блоки 1×1×1 на InstancedMesh. **Read-only режим** — не позволяет ставить новые блоки в runtime (только скрипты через `game.scene.spawn`). |
| `PrimitiveManager.js` | Сферы/кубы/цилиндры. Так же read-only. |
| `ModelManager.js` | GLB-модели (мечи, машины, NPC-скины). |
| `PhysicsWorld.js` | AABB-физика. **Всегда включена** в плеере (в студии — только в Play-режиме). |
| `PlayerController.js` | Управление игроком, WASD + Space + мышь. |
| `ScriptSandbox.js` + `ScriptSandboxWorker.js` | Песочница скриптов юзера. |
| `GameRuntime.js` | Оркестратор игрового режима (см. студию). |
| `MultiplayerSync.js` | Colyseus state-sync для онлайн-игр. |
| `AccessoryManager.js` | Шляпы, очки, аксессуары на R15-скелете. |
| `EmoteGlbParser.js` | Парсер GLB-анимаций (танцы, эмоушены). |

## Поток загрузки игры

```
1. Юзер открывает https://player.rublox.pro/<game_id>
   ↓
2. PlayerAuth проверяет JWT (или redeem ticket из #ticket=)
   ↓
3. fetch GET /kubikon3d/projects/<game_id>
   → возвращает project_data JSON ~100КБ-5МБ
   ↓
4. BabylonScene создаёт сцену
   BlockManager.loadFromProject(data.blocks)
   PrimitiveManager.loadFromProject(data.primitives)
   ModelManager.loadFromProject(data.models)
   ...
   ↓
5. ScriptSandbox.startAll() — запускает все скрипты юзера
   ↓
6. GameRuntime.start() — включает физику, ввод
   ↓
7. Игрок играет
   ↓
8. Каждые 30с: POST /kubikon3d/play/heartbeat { game_id, play_time_ms }
```

## Что НЕ трогать (опасные оптимизации)

Те же грабли что в студии:

- `scene.blockMaterialDirtyMechanism = true` — ломает новые меши (трейсеры, debris)
- `scene.createOrUpdateSelectionOctree()` в hot path — O(N²) лагает
- `game.ui.set()` в `onTick` без throttle — React setState 60Hz убивает FPS
- `findOne` на старте скрипта — sceneSnapshot приходит через rAF, ref будет null

Подробнее: [docs/TUTORIAL_DEBUG_BABYLON.md](../../docs/TUTORIAL_DEBUG_BABYLON.md)

## AdminPreview/

Папка `src/AdminPreview/` — каталоги ассетов (gdSkins, gdPortals, gdSfx, gdMusic и т.д.). Используются движком при загрузке игр GD-формата (`GdLevelManager`). Контрибьюторам обычно трогать не нужно.

## Производительность — ориентиры

Те же что в студии:

| Объект | Норм | Лагать начинает |
|---|---|---|
| Блоки | 50К | 200К+ |
| Примитивы | 500 | 2000+ |
| GLB-модели | 200 | 500+ (зависит от вершин) |
| NPC | 50 | 100+ |
| Активные скрипты | 30 | 100+ |
| Частицы | 5К | 20К+ |

**FPS-цель плеера выше чем у студии** — игроки чувствительнее к лагам чем создатели:
- 60 FPS на средних ноутбуках 2020+
- 30 FPS на школьных машинках 2015+
- 60 FPS на мобиле (отдельная задача — мобильная оптимизация)

## Связанные доки

- [../../docs/TUTORIAL_FIRST_PR.md](../../docs/TUTORIAL_FIRST_PR.md) — первый PR
- [../../docs/TUTORIAL_DEBUG_BABYLON.md](../../docs/TUTORIAL_DEBUG_BABYLON.md) — отладка
- [../../API_USAGE.md](../../API_USAGE.md) — какие эндпоинты плеер дёргает
- В студии: [studio/src/editor/engine/README.md](https://git.rublox.pro/rublox/studio/src/branch/main/src/editor/engine/README.md) — полное описание движка

## Вопросы

Канал `#разработка` на https://team.rublox.pro
