# Changelog — Mars · hexo documentation

Журнал изменений документации. Каждое значимое изменение дизайна или архитектуры — запись здесь.

Формат основан на [Keep a Changelog](https://keepachangelog.com/).

---

## Unreleased — prototype iterations (2026-04-15)

Пока не отдельная версия документации (v0.1 остаётся базой), но прототип в `prototype/index.html` прошёл несколько итераций на основе фидбека:

- **v3 визуал**: wheeled Curiosity-style rover (вместо гибких ног), isometric pseudo-3D здания (Solar/Drill/Dome)
- **Adjacency rules**: Drill работает только если Solar в радиусе 1 гекса (visible cables между ними)
- **Townscaper merge**: tunnels между соседними застроенными тайлами + платформы под постройками
- **Big world**: карта 60×40 ≈ 2400 гексов (было 24×16)
- **12 wonders** с реальными именами вместо 6 (Olympus Mons, Jezero, Hellas, Valles Marineris, Tharsis Montes ×3, Polar Caps ×2, Gale, Nili Fossae, Meridiani)
- **No "game over"** — persistent progression, бесконечное исследование
- **Zoom**: hybrid camera (follow rover at 1x, lock to map center at planet view), `Z` toggle
- **1 building per tile** + dismantle (X key) с 50% refund
- **PDA terminal**: STALKER-style зелёный фосфорный overlay с реальной инфой про чудеса Марса (overview/specs/history)
- **Badges system**: 10 достижений (corners, all wonders, first-of-each-building, tile count milestones)

Новые идеи из прототипа — перемещены в `v0.1/08-open-questions.md` разделы 18-25.

## v0.1 — 2026-04-15

**Статус**: draft · **Фаза**: pre-code design

Первая версия проектной документации. Собрана из диалога с владельцем проекта и трёх параллельных глубоких ресёрчей (open-source persistent MMO, реальные Mars data, визуальные стили).

### Added

#### Концепция и позиционирование
- Проект назван **Mars** (продукт), первая версия — **hexo** (кодовое имя)
- Позиционирование: персистентный mass-multiplayer Telegram Mini App для Mars IT School
- Жёсткие философские запреты: no combat, no destruction, no griefing, no pay-to-win
- Референс-игры: Polytopia, Dorfromantik, Townscaper, Hexarchy, Terra Nil, OGame, Surviving Mars

#### Геймдизайн
- Центральная механика — **роботы** (Scout, Worker, Drill, Hauler, Terraformer)
- Именованные роботы как вектор институциональной памяти школы
- 4 фазы прогрессии в сезоне: Высадка → Добыча → Колония → Терраформ
- Ресурсы: metal, ice, regolith, energy, science, biomass (поздняя игра)
- Вакуум войны заполнен: метрики, кооперация, природные вызовы, глобальная цель

#### Марсианское время (ключевое решение)
- База игрового времени — **сол** (24h 39m 35s)
- Сезон = 1 **Darian-месяц** (27-28 солов ≈ 28.77 земных дней)
- Использование дэрианского календаря (24 месяца, имена: Sagittarius, Dhanus, ...)
- Mars Year counter (MY 38 на момент v0.1)
- Гибрид таймзон: AMT для глобальных событий, local TZ для персональных
- Реальные марсианские сезонные события (пылевые бури, CO₂ циклы)

#### Мир и данные
- Карта — **реальный Марс** (HRSC+MOLA blended DEM 200m/px, 6.7 GB)
- Гекс-сетка на сфере через **DGGRID + ISEA3H resolution 9** (~22 000 гексов, ~50 km edge)
- 12 неизбежных pentagon tiles как "Wonders of Mars"
- Именованные объекты из USGS Gazetteer (~2 200 features)
- Ресурсы из Odyssey GRS (H, Fe) и CRISM (clays, sulfates)
- Лицензирование: public domain + CC-BY-SA, полностью использовать можно
- Pipeline: bake once в Python → JSON → seed migration

#### Техническая архитектура
- **Frontend**: React 18 + Vite + TypeScript + @telegram-apps/sdk-react + PixiJS v8 + Honeycomb.js
- **Backend**: Node 22 + Fastify + Knex + Postgres 16 + BullMQ (Redis)
- **Lazy-eval** как ключевая архитектурная гарантия масштабирования
- Database schema v0.1 (players, tiles, colonies, robots, buildings, build_queue, seasons, events)
- `pg_advisory_xact_lock` для concurrency
- Telegram initData HMAC validation — server authoritative
- Deploy на Fly.io (web + worker + Managed Postgres)
- Интеграция с существующей инфрой: Mars ID SSO, Caddy wildcard, GlitchTip, Pulse

#### Визуальный стиль
- Референс вайба: Townscaper + Dorfromantik + Polytopia
- Техника: pre-baked low-poly 3D → 2D sprites + palette-swap shader
- Starter assets: Kenney Hexagon Pack (CC0)
- Terraform прогрессия через palette shader (5 стадий от Raw Mars до Lush)
- Budget: $500-800 на hero tiles от indie-артиста

#### Roadmap
- 6-недельный MVP план
- Ожидаемые фазы: MVP → художник → пилот 50 детей → все филиалы → legacy mode → v0.2
- Метрики успеха для MVP

### Open questions (v0.1)
- Mars ID интеграция: A/B/C варианты
- MAX_OFFLINE_SOLS политика
- Первый пилот: филиал, возраст, дата
- Имя и стартовый цикл первого сезона
- Домен (hexo.marshub.uz vs альтернативы)
- Фракции филиалов
- Название "команд" учеников
- Inspo папка (блокирована macOS Sandbox)
- Монетизация (отложено)
- См. полный список в `v0.1/08-open-questions.md`

### Research sources
Все ссылки исходного ресёрча сохранены в соответствующих design docs.

Ключевые open-source референсы:
- [OGameX](https://github.com/lanedirt/OGameX) — lazy-eval pattern, schema
- [Solaris](https://github.com/solaris-games/solaris) — mutex, services architecture
- [Unciv](https://github.com/yairm210/Unciv) — hex math, production formulas
- [Telegram-Mini-Apps/reactjs-template](https://github.com/Telegram-Mini-Apps/reactjs-template) — boilerplate
- [Honeycomb.js](https://github.com/flauwekeul/honeycomb) — hex coordinates
- [Red Blob Games: Hexagonal Grids](https://www.redblobgames.com/grids/hexagons/) — reference
- [DGGRID](https://github.com/sahrk/DGGRID) — sphere hex generation

Данные Марса:
- [HRSC+MOLA blended DEM](https://astrogeology.usgs.gov/search/map/Mars/Topography/HRSC_MOLA_Blend/Mars_HRSC_MOLA_BlendDEM_Global_200mp_v2)
- [USGS Gazetteer Mars](https://planetarynames.wr.usgs.gov/Page/MARS/target)
- [Odyssey GRS](https://pds-geosciences.wustl.edu/missions/odyssey/grs.html)
- [OpenPlanetaryMap](https://www.openplanetary.org/opm)
- [NASA Mars24 / Allison-McEwen алгоритм](https://www.giss.nasa.gov/tools/mars24/help/algorithm.html)

---

## Шаблон для будущих версий

```markdown
## vX.Y — YYYY-MM-DD

**Статус**: draft | active | archived  
**Фаза**: описание

### Added
- Что добавлено

### Changed
- Что поменялось по сравнению с предыдущей версией

### Deprecated
- Что больше не актуально (но остаётся для истории)

### Removed
- Что удалено

### Fixed
- Исправления в документации (противоречия, опечатки)

### Resolved questions
- Вопрос из open-questions → решение → ссылка на документ
```