M1 «Вертикальный срез» — план реализации
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Первая играбельная партия в браузере: новая игра → карта → движение → основание города → обработка клеток → производство → конец хода → простой ИИ → сохранение/загрузка.
Architecture: Чистое детерминированное ядро @territory/core (состояние — JSON, изменения — команды, случайность — сид в состоянии). Данные правил — @territory/content (типы из core). ИИ — @territory/ai отдаёт команды тем же путём. @territory/sim гоняет партии ИИ без интерфейса. Клиент — Vite + PixiJS (карта) + DOM-панели, ИИ в Web Worker.
Tech Stack: TypeScript 6, Vitest 5, Vite, PixiJS 8.
Spec: docs/specs/2026-11-17-territory-design.md (разделы 6, 7, 10) и правила docs/game/{map,terrain,units,cities,production,turn}.md.
Global Constraints
- Ядро и пакеты: без DOM, без
Math.random, без таймеров и системного времени. - Состояние партии сериализуется
JSON.stringifyбез потерь; полеversion: 1. - Все числа правил — в
@territory/content, ядро их только читает. - Одинаковые сид + команды → одинаковое состояние (проверяется «золотой» партией).
- Тексты интерфейса — английский, через таблицу строк клиента (
apps/client/src/i18n.ts). - Временная графика рисуется кодом; финальные спрайты Codex (T-0004) подключаются позже по
docs/game/art-style.md.
Review Focus
- Команда для юнита не своей фракции или не в свой ход → ошибка, состояние не меняется.
- Город на воде, рядом с другим городом или основателем, у которого нет очков хода → ошибка с понятной причиной.
- Сохранение → загрузка → продолжение даёт то же состояние, что и без сохранения (сравнение JSON).
- Голод в городе размера 1 не уводит размер в 0 и запас ниже 0.
- ИИ не зацикливается: за ход отдаёт конечное число команд и всегда завершает ход.
Task 1: Ядро — типы, сид-генератор, ruleset, создание партии и карта
Files: packages/core/src/{types,rng,grid,mapgen,newgame,index}.ts + тесты рядом; packages/content/src/{ruleset,index}.ts + тест.
Interfaces (Produces):
rng.ts:nextFloat(s: { rng: number }): number([0,1), меняетs.rng, mulberry32);nextInt(s, n): number.types.ts:TerrainId,UnitTypeId,BuildingId,GuildId(строки);Ruleset { terrains, units, buildings, guilds, rules };GameState { version: 1; seed; rng; turn; current; width; height; terrain: TerrainId[]; factions: Faction[]; units: Unit[]; cities: City[]; nextId; log: GameEvent[] };Faction { id; name; guild; color; leader; human; influence; eliminated; fog: number[] /* 0 unknown, 1 explored, 2 visible */ };Unit { id; owner; type; x; y; mp; fortified; path: [number, number][] };City { id; owner; name; x; y; size; food; stored; order: Order | null; buildings: BuildingId[]; worked: number[]; manual: number[] };Order = { kind: "unit"; id: UnitTypeId } | { kind: "building"; id: BuildingId };Effect = { kind: "yieldPercent" | "yieldFlat"; resource: "food" | "industry" | "influence"; value: number } | { kind: "growthKeep"; value: number }.grid.ts:idx(state, x, y),inBounds,chebyshev(ax, ay, bx, by),neighbors8.mapgen.ts:generateTerrain(s: { rng: number }, width, height, rules): TerrainId[].newgame.ts:newGame(rules: Ruleset, opts: { seed: number; size: "small" | "medium" | "large"; factions: { guild: GuildId; leaderIndex: number; human: boolean }[] }): GameState— стартовые позиции на суше на расстоянии ≥ 8, у каждой фракции основатель + воин + разведчик.- content:
defaultRuleset: Rulesetс числами изdocs/game/*.md; две гильдииhollow-crown,iron-concordс лидерами и именами юнитов (раздел 20 спецификации отличий).
Тесты: одинаковый сид → одинаковые terrain; разные сиды → разные; края — deep; доля суши 35–55% на трёх сидах; newGame даёт стартовые позиции на суше, попарно ≥ 8; JSON.parse(JSON.stringify(state)) равно state; ruleset проходит проверку ссылок (все id в гильдиях существуют).
Task 2: Ядро — видимость, движение, путь, команды юнитов
Files: packages/core/src/{fog,movement,path,commands}.ts + тесты.
Interfaces:
fog.ts:updateFog(state, rules, factionId): void(visible → explored, затем обзор юнитов и городов).path.ts:findPath(state, rules, unit: Unit, tx, ty): [number, number][] | null— A* по клеткам, известным фракции, цена = шаг местности.commands.ts:Command(объединение:move{unitId,dx,dy},goto{unitId,x,y},skip{unitId},fortify{unitId},foundCity{unitId,name?},setOrder{cityId,order},toggleTile{cityId,tile},endTurn);applyCommand(state, rules, cmd): { ok: true; state: GameState; events: GameEvent[] } | { ok: false; error: string }— работает на копии, исходное состояние не меняется.
Тесты: шаг по лугу тратит 1 очко; шаг в лес с полным запасом 1 очко разрешён; повторный — нет; вода и чужой юнит — ошибка; чужой юнит / не свой ход — ошибка и состояние не изменилось; goto идёт по пути в пределах очков и сохраняет остаток пути; путь обходит воду; fortify/skip; обзор разведчика 2.
Task 3: Ядро — города, производство, фаза мира, сохранение
Files: packages/core/src/{cities,economy,turn,save}.ts + тесты.
Interfaces:
cities.ts:foundCity(через команду): правила основания;cityArea(state, rules, city): number[];assignWorkers(state, rules, city): void;cityYield(state, rules, city): { food; industry; influence; foodUpkeep }.economy.ts:growthThreshold(rules, size),turnsToGrow(state, rules, city): number | null(прогноз для интерфейса),turnsToComplete(...).turn.ts:endTurn— передача очереди, фаза мира поdocs/game/turn.md, выбывание фракций.save.ts:serialize(state): string,deserialize(text): GameState(проверкаversion, понятная ошибка).
Тесты: основание на воде / ближе 3 / без очков — ошибка; новый город размер 1, центр с «очагом»; рост на пороге 15 + 6×size, Кладовая сохраняет 40%; голод в размере 1 — размер 1, запас 0; Мастерская +25% вниз; основатель ждёт размер 2 и забирает жителя; излишек промысла переносится; второе кольцо с размера 5; «золотая» мини-партия: 10 ходов из фиксированного сида с фиксированными командами → тот же хэш состояния при повторе и после сохранения/загрузки.
Task 4: ИИ и симуляция
Files: packages/ai/src/{index,ai}.ts + тест; packages/sim/src/{index,run}.ts + тест.
Interfaces: nextAiCommand(state, rules, factionId): Command (детерминированно; всегда в итоге endTurn); runSimulation(rules, opts: { seed; size; factions: number; turns }): GameState.
Тесты: ИИ за ход отдаёт ≤ 500 команд и заканчивает ход; за 60 ходов на малой карте у каждой фракции ≥ 3 городов; симуляция детерминирована (одинаковый хэш); ИИ никогда не получает ошибку от applyCommand.
Task 5: Клиент — запуск в браузере
Files: apps/client/{index.html,vite.config.ts}, apps/client/src/{main,i18n,game,save,input}.ts, apps/client/src/render/{map,sprites}.ts, apps/client/src/ui/{hud,city,newgame}.ts, apps/client/src/ai.worker.ts, apps/client/src/style.css.
- Скрипт
pnpm devв корне → Vite наapps/client;pnpm buildсобирает статический сайт. - Экран новой игры: размер карты, гильдия, лидер, число соперников (1–3), сид.
- Карта: PixiJS, временные спрайты кодом (цвет местности + узор, юнит — силуэт роли в цвете фракции, город — значок с размером), туман войны, выделение клетки, путь «идти к» с числом ходов. Панорама перетаскиванием (мышь и палец), масштаб колесом и щипком.
- Верхняя полоса: фракция, ход, эпоха, влияние; нижняя — выбранный юнит и кнопки приказов с клавишами (стрелки/цифровой блок, F — основать, Space — пропустить, G — идти к, B — укрепиться, Enter — конец хода).
- Экран города: размер, запас еды и прогноз роста, выход по ресурсам с пояснением, клетки области (клик — снять/поставить жителя), заказ и прогноз ходов, выбор заказа.
- Ходы ИИ — в Web Worker; интерфейс не замирает.
- Автосохранение в
localStorageкаждый ход + «Сохранить в файл» / «Загрузить из файла».
Проверка: pnpm --filter @territory/client build без ошибок; ручной прогон в браузере 20+ ходов: основать 2 города, построить воина и основателя, ИИ основывает города, сохранение/загрузка.
Task 6: Документы и статусы
- Обновить статусы в
docs/game/*.md(prototyped/playable),pnpm status, README: как запустить игру. - Задачи T-0001…T-0003 →
doneпри слиянии; новые задачи M1 с итогами.