Перейти к содержимому
OIYNUP Wiki

ADR-0003: Матричная orthogonal архитектура mech × biome × subject

  • Status: Accepted
  • Deciders: Jean, Ирлен (implicit через архитектурный dev handoff)
  • Date: 2026-04-19
  • Related SOT slice: Matrix architecture / Unity code contract

Context

Заголовок раздела «Context»

12 механик × 6 биомов × 6 предметов = 432 уникальных конфигурации MVP. Если каждую hard-код’ить как отдельную сцену или скрипт — это тысячи файлов, невозможно поддерживать, и любая правка механики требует обновления во всех биомах. Также hard-coding блокирует разноклассный multiplayer (1-классник и 4-классник в одном матче) и future expansion (Valiant-планета, новые биомы).

Нужен архитектурный контракт, который позволит комбинаторно собирать matches без переписывания.

Decision

Заголовок раздела «Decision»

Три ортогональных оси:

  1. Mechanic — абстрактная геймплей-логика с ролями (correct_platform, wrong_platform, checkpoint, и т.д.). Один MechanicController на каждую из 12.
  2. Biome — визуальный скин + локальная физика. BiomeTheme ScriptableObject маппирует роли на конкретные prefab’ы / анимации / SFX / physics-параметры. Один SO на каждый из 6 биомов.
  3. Subject — контент-pool per-player через API (question bank).

Контракт:

  • Mechanic code не знает про biome. Не импортирует biome-специфичные типы.
  • Biome code не знает про mechanic. Не импортирует mechanic-специфичные типы.
  • Глобальный «правильный слот» server-authoritative; персональные числа per-player (anti-cheat + adaptive difficulty).

Море-биом — special case: dual-state (над водой + под водой). Реализуется как два BiomeTheme SO или один SO с двумя режимами, переключается через water-level триггер.

Consequences

Заголовок раздела «Consequences»
  • Plus: 18 артефактов (12 MechanicControllers + 6 BiomeTheme) покрывают 432 комбинации.
  • Plus: добавление биома — создание одного SO, zero изменений в механиках.
  • Plus: добавление механики — один контроллер на role-contract, zero изменений в биомах.
  • Plus: разноклассный multi работает естественно — adaptive content-pool per-player.
  • Minus: требует дисциплины — violations орфогональности легко появляются случайно.
  • Minus: Addressables должны быть настроены (сейчас НЕ установлены — gap).
  • Minus: ScriptableObject data layer ещё не существует в коде (gap — нужна T4 сессия в плане).
  • Следующие шаги:
    1. Ирлен реализует MechanicController + BiomeTheme + SubjectPool.
    2. S1-b mechanics catalog validates orthogonal принцип для каждой карточки.
    3. При любом предложении «mechanic требует biome-специфики» — flag, wait ADR.

Alternatives considered

Заголовок раздела «Alternatives considered»
  • A1: Hard-coded scenes per-combination — отклонено, 432 сцен = unmaintainable.
  • A2: Mechanic-as-scene + biome-decorator prefab — отклонено, всё ещё слишком жёсткая связка; не поддерживает matrix composition.
  • A3: ECS (Entity Component System) — отклонено на MVP, overhead для команды 2 разработчиков; может быть future consideration.
Заголовок раздела «Related»
  • SOT: SOURCE_OF_TRUTH.md §Matrix architecture
  • ADRs: ADR-0001 (world-design), ADR-0002 (12 mechanics)
  • Canon: projects/oinap/docs/Архитектура_для_разработчика.md
  • Developer handoff: projects/oinap/handoff/2026-04-19-developer-handoff/
  • Codebase gap: memory project_oinap_codebase_map.md (matrix arch не реализована)