# G-WORLD

2D-симулятор убежища с видом сбоку: игрок роет шахты в породе, строит комнаты
на сетке и следит за жителями. Визуальный референс — Fallout Shelter.

| | |
| --- | --- |
| Движок | Godot **4.7**, рендер Mobile (игра двумерная, Forward+ не нужен) |
| Язык | GDScript (типизированный) |
| Платформа | Windows (desktop), рендер-драйвер D3D12 |

## Быстрый старт

1. Установить Godot 4.7.
2. Открыть папку проекта из Project Manager (`project.godot` в корне).
3. `F5` — запуск. Главная сцена: `src/main/main.tscn`.

Плагин `addons/godot_ai` (MCP-мост для агентов) включается в
*Project → Project Settings → Plugins*.

## Структура репозитория

```
assets/            # Сырьё: то, что рисуется и звучит. Кода нет.
  art/backgrounds/ #   фоны и слои параллакса (небо, облака)
  art/sprites/     #   спрайты и атласы сущностей
  art/tilesets/    #   тайлсеты породы, стен, полов
  art/ui/          #   графика интерфейса: рамки, иконки, курсоры
  audio/music/     #   музыкальные треки
  audio/sfx/       #   короткие звуковые эффекты
  fonts/           #   шрифты
  shaders/         #   .gdshader, переиспользуемые между сценами

src/               # Весь код и сцены. Сцена лежит рядом со своим скриптом.
  main/            #   точка входа: main.tscn (Main → World, UI) и её скрипт
  autoload/        #   синглтоны: event_bus.gd, дальше SaveManager, GameState
  core/            #   инфраструктура без знания о геймплее: утилиты, типы
  data/resources/  #   схемы данных — наследники Resource (RoomDef, ItemDef)
  data/tables/     #   экземпляры схем — .tres-«база данных» контента
  systems/         #   симуляция: время, климат, погода, экономика
  world/           #   убежище: сетка, порода, комнаты, камера, фон
  entities/        #   жители, предметы и прочие «живые» объекты
  ui/screens/      #   экраны и HUD целиком
  ui/components/   #   переиспользуемые контролы
  ui/theme/        #   Theme-ресурсы и стили
  debug/           #   дев-консоль, оверлеи, читы

tests/unit/        # Тесты чистой логики (без дерева сцены)
tests/integration/ # Тесты на собранных сценах

docs/              # Проектная документация
  ARCHITECTURE.md  #   слои, правила зависимостей, поток данных
  adr/             #   ADR: почему приняли то или иное решение
```

Правила зависимостей между слоями описаны в [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## Соглашения

- **Файлы и папки** — `snake_case`: `game_clock.gd`, `vault_grid.tscn`.
- **Ноды в сцене и `class_name`** — `PascalCase`: `class_name GameClock`.
- **Скрипт и сцена одного объекта** лежат рядом и называются одинаково:
  `src/world/vault_grid.tscn` + `src/world/vault_grid.gd`.
- **Типизация обязательна**: `var speed: float = 1.0`, `func tick(delta: float) -> void:`.
- **Приватное** — с подчёркиванием: `_rebuild_cache()`, `var _cells: Array`.
- **Константы** — `SCREAMING_SNAKE_CASE`, магические числа выносим в константы.
- Переводы строк — LF (см. `.gitattributes`), кодировка — UTF-8.

## Работа с ассетами

Тяжёлое сырьё (скачанные наборы, черновики генерации) в репозиторий не попадает:
папки `kits/` и `ai-input/` игнорируются. В `assets/` кладём только то, что
реально используется в сборке.

Графика — пиксель-арт, поэтому фильтрация текстур в проекте выставлена в
**Nearest** (`rendering/textures/canvas_textures/default_texture_filter=0`).
С Linear пиксели мылятся на любом зуме, так что менять не нужно; отдельным
нодам фильтр переопределяется в `CanvasItem → Texture → Filter`.

В `kits/` лежит `.gdignore`, чтобы редактор не импортировал склад и не забивал
кеш: нужное оттуда переносится в `assets/`, а Godot видит только `assets/`.
Происхождение и лицензия перенесённого фиксируются в README рядом с файлами —
например [assets/art/backgrounds/sky/README.md](assets/art/backgrounds/sky/README.md).