# CLAUDE.md

Инструкции для Claude Code по работе с этим репозиторием.

## Проект

G-WORLD — **2D-симулятор убежища с видом сбоку** (референс Fallout Shelter):
порода, вырытые шахты, комнаты на сетке, жители, время/погода/климат.

Godot **4.7**, GDScript, рендер Forward+, целевая платформа — Windows.

Игра двумерная. Если в задаче или в коде появляется 3D-нода (`Node3D`,
`CharacterBody3D`, `Camera3D`) — это ошибка, а не задумка: уточнить у
пользователя, прежде чем продолжать.

## Где что лежит

- `src/main/` — точка входа.
- `src/autoload/` — синглтоны. Новую автозагрузку регистрировать через настройки
  проекта и описывать в `docs/ARCHITECTURE.md`.
- `src/core/` — утилиты и типы без знания о геймплее.
- `src/data/resources/` — схемы контента (наследники `Resource`),
  `src/data/tables/` — сами `.tres`.
- `src/systems/` — симуляция (время, климат, погода, экономика).
- `src/world/` — сетка убежища, порода, комнаты, камера, фон.
- `src/entities/` — жители, предметы.
- `src/ui/` — `screens/`, `components/`, `theme/`.
- `src/debug/` — дев-консоль и оверлеи.
- `assets/` — только сырьё (арт, звук, шрифты, шейдеры), кода там нет.
- `tests/unit/` — логика без сцены, `tests/integration/` — на собранных сценах.

Правила зависимостей между слоями — в `docs/ARCHITECTURE.md`. Перед тем как
класть новый файл, свериться с таблицей слоёв; не заводить новую папку верхнего
уровня, не обсудив это с пользователем.

## Стиль кода

- Файлы и папки — `snake_case`, ноды и `class_name` — `PascalCase`.
- Сцена и её скрипт лежат рядом и называются одинаково.
- Типизировать всё: параметры, возвраты (`-> void` тоже), поля.
- Приватное — с `_`. Константы — `SCREAMING_SNAKE_CASE`.
- Сигналы именовать прошедшим временем факта: `weather_changed`, `day_started`.
- `@onready var` вместо поиска нод по строкам в `_process`.
- Комментарии — по-русски, объясняют «почему», а не пересказывают код.
  Комментировать только неочевидное.

## Архитектурные правила, которые легко нарушить

1. **Симуляция отделена от рендера.** Классы из `systems/` обязаны работать без
   дерева сцены. Ноды в них не хранить.
2. **UI не меняет мир напрямую** — шлёт намерение, изменение делает система.
3. **Контент — данными.** Новая комната/предмет — это `.tres`, а не `if` в коде.
4. **`EventBus` — не свалка.** Туда только события для нескольких несвязанных
   слоёв; локальную связь делать обычными сигналами.

## Работа с редактором через MCP (`godot-ai`)

Godot-редактор, скорее всего, открыт, и он владеет `project.godot`, `.tscn`,
`.tres` и `.import`.

- **Не редактировать вручную** `project.godot` и `*.tscn`/`*.tres`: редактор
  перезапишет изменения. Использовать MCP-инструменты (`scene_manage`,
  `node_create`, `node_set_property`, `script_attach`, `autoload_manage`,
  `project_manage`, `resource_manage`) — они работают через живой редактор.
- `.gd`-файлы править обычными Edit/Write — это нормально, редактор их
  перечитает.
- Проверять результат: `project_run` + `logs_read` (ошибки парсера и рантайма),
  `editor_screenshot` — чтобы увидеть сцену глазами.
- `addons/` — вендорный код плагина, его не трогаем.

## Чего не делать

- Не коммитить и не пушить без явной просьбы.
- Не добавлять C#: в `project.godot` есть секция `[dotnet]`, но проект на
  GDScript. Не заводить `.cs`, не обсудив.
- Не класть тяжёлое сырьё в `assets/` — для него есть игнорируемые `kits/` и
  `ai-input/`.
- Не удалять `.gitkeep` из ещё пустых папок — они держат структуру в git.
- Не менять `.gitattributes`/`.gitignore` мимоходом.