# Типы scripting API (`.d.ts` для Monaco)

Это **не** TypeScript-типы движка студии. Это TypeScript-декларации **API доступного скриптам пользователей** (`game.player`, `game.scene`, ...) — чтобы Monaco Editor в студии давал автодополнение и подсказки сигнатур.

## Файлы

| Файл | Что описывает |
|---|---|
| `audio.d.ts` | `game.audio.*` — проигрывание звуков |
| `common.d.ts` | общие типы (Vector3, Color, и т.п.) |
| `economy.d.ts` | `game.economy.*` — игровая валюта, покупки |
| `fx.d.ts` | `game.fx.*` — эффекты, частицы, трейсеры |
| `index.d.ts` | главный файл, сводит всё вместе |
| `input.d.ts` | `game.onKey`, `game.onKeyUp`, `game.onClick` |
| `misc.d.ts` | разное (math утилиты, time) |
| `multiplayer.d.ts` | `game.broadcast`, `game.onMessage` |
| `npcs.d.ts` | `game.npc.*` — спавн и управление NPC |
| `physics.d.ts` | `game.physics.*` — gravity, velocity, applyForce |
| `player.d.ts` | `game.player.*` — damage, heal, kill, position |
| `save.d.ts` | `game.save.*` — сохранение состояния игры |
| `scene.d.ts` | `game.scene.*` — spawn, delete, paint, move объектов |
| `self.d.ts` | особый случай: API доступное только владельцу скрипта |
| `tools.d.ts` | `game.tools.*` — рандом, JSON, утилиты |
| `tweens.d.ts` | `game.tween.*` — анимация значений |
| `ui.d.ts` | `game.ui.*` — HUD, текст, кнопки |

## Как это работает в студии

1. Юзер пишет скрипт в Monaco-редакторе.
2. Студия подгружает `bundle.js` (склейку всех `.d.ts` в один файл) и регистрирует через `monaco.languages.typescript.javascriptDefaults.addExtraLib(bundle, 'game.d.ts')`.
3. Monaco видит `game.player.dam`, предлагает `damage(amount: number): void`.
4. Юзер пишет правильный код.

## `_build_bundle.py` и `bundle.js`

`_build_bundle.py` склеивает все `*.d.ts` в один `bundle.js`-файл (фактически просто конкатенация с обёрткой `export default \`...\`;`). Запускать руками после изменения деклараций:

```bash
cd src/editor/engine/types
python _build_bundle.py
```

`bundle.js` коммитится в репо — Monaco грузит его при запуске редактора.

## Реальная реализация API

Реализация — в `ScriptSandbox.js` (главный поток) и `ScriptSandboxWorker.js` (Worker, где исполняется код юзера). Они проксируют вызовы `game.*` через `postMessage` к соответствующим менеджерам сцены.

См. [TUTORIAL_ADD_SCRIPT_API.md](../../../../docs/TUTORIAL_ADD_SCRIPT_API.md) — пошаговое руководство как добавить новое API.

## Согласованность

Если ты добавляешь новое API:
1. Реализуй в `ScriptSandbox.js` и (если нужно) в `ScriptSandboxWorker.js`.
2. Опиши в правильном `*.d.ts` (по тематике).
3. Запусти `python _build_bundle.py`.
4. Закоммить **оба** файла (`.d.ts` + новый `bundle.js`).
5. Тест в студии: autocomplete показывает новую функцию + работает в runtime.

**Несогласованность d.ts ↔ реальной реализации** — фрустрирующий баг для пользователей. Они видят что-то в подсказках, а в runtime получают `undefined`.
