monkey_dust

🏆 SDL_GPU Exclusive — стан після FIX-8

🚀 Швидкий старт

git clone --recurse-submodules https://github.com/rdga1bot/monkey_dust.git
cd monkey_dust

# Основна збірка:
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DUSE_SDL3=ON
ninja -C build monkey_dust          # гра       → build/game/monkey_dust
ninja -C build monkey_dust_editor   # редактор  → build/tools/monkey_dust_editor
ninja -C build md_flare_demo        # viewer    → build/tools/md_flare_demo
ninja -C build md_flare_convert     # конвертер → build/tools/md_flare_convert

# З wicked-style editor в грі:
cmake -S . -B build -G Ninja -DUSE_SDL3=ON -DMONKEY_DUST_EDITOR=ON
ninja -C build monkey_dust

# Запустити 131 GTests:
ninja -C build md_tests && build/tests/md_tests

# Перекомпілювати SPIR-V після зміни .vert/.frag/.comp:
bash scripts/compile_shaders.sh

./build/game/monkey_dust
./build/tools/md_flare_demo
./build/tools/monkey_dust_editor

📁 Monorepo структура (M46 + AI-Ext-1–20 + BT VM + IMP-1–9)

⚙️ Збірка

CMake варіанти

# Стандартна збірка (USE_SDL3=ON — єдиний активний шлях):
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DUSE_SDL3=ON

# З wicked-style in-game editor:
cmake -S . -B build -G Ninja -DUSE_SDL3=ON -DMONKEY_DUST_EDITOR=ON

# Debug (ImGui overlay, DEBUG defines):
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DUSE_SDL3=ON

Compile definitions per target

🗺️ Flare Rendering Pipeline

TileMapRenderer — 3D ізометричний (game runtime)

goblin_camp.txt
  └─[LoadFlareMap]──► FlareMap { layers[], meta(TileMetaRegistry), spawns[] }
                           │
                    [ParseTilesetDefFile]
                           │ img= (ПЕРШИЙ рядок → atlas[0]; наступні → atlas[1..3])
                           ▼
               TileMetaRegistry { 229 entries, atlas_idx, offset_y, anim }
                           │
              [TileMapRenderer::Render()]
                   PASS 1: CollectLayer (bg + fringe + object → vbuf[MAX_TILES])
                   PASS 2: qsort depth=(col+row)*3+prio + x_off sub-tile corr
                   PASS 3: UV v=1−y/H → ibuf[stride=36]; tile anim frames
                   PASS 4: batch draw per atlas_idx (≤4 draw calls)
                           │
               glBufferSubData → glDrawArraysInstanced → tile_map.vert/frag

TileMap2DRenderer — 2D (SDL_GPU demo / standalone editor)

[TileMap2DRenderer::Init()]
  ├── GpuDevice::IsReady() == true  →  SDL_GPU path (Vulkan pipeline + GpuVertexBuffer)
  └── GpuDevice::IsReady() == false →  OpenGL fallback (VAO/VBO + GLSL shaders)

Stride = 44 bytes: a_corner(vec2) · a_screen_tl(vec2) · a_screen_size(vec2)
                   a_uv_rect(vec4) · a_atlas_idx(float)

📐 UV Convention — КРИТИЧНО

MdLoadTexturePixelArt — фільтрація (НЕ СПРОЩУВАТИ)

🖼️ Atlas Selection Rule

# tileset_grassland.txt:
[tileset]
img=images/tilesets/tileset_grassland.png        ← atlas[0]
tile=16,1061,2698,192,96,96,48
...
img=images/tilesets/tileset_grassland_water.png  ← atlas[1]
tile=301,...

🏔️ Tile Classification: Flat / Billboard

float y_top = (float)tm->offset_y / 96.0f * tile_world_size;
float y_bot = -(float)(tm->h - tm->offset_y) / 96.0f * tile_world_size;
// Flat sentinel: y_bot = y_top = 0.0f

// Horizontal offset (M7.27):
float x_off = (float)(tm->w/2 - tm->offset_x) * tile_world_size / 192.0f;

// FRINGE depth:
int prio = (layer.type == LT::FRINGE) ? 1 : (layer.type == LT::OBJECT) ? 2 : 0;
// depth = (col + row) * 3 + prio

✨ Шейдер tile_map (3D renderer)

Per-instance layout (stride = 36 bytes, TINST_STRIDE)

⚡ GPU HAL

Абстракція поверх SDL_GPU. Після FIX-8 — тільки SDL_GPU шлях у HAL impl файлах. Весь OpenGL fallback code видалено з game/engine (залишається тільки у standalone editor через if(dev==null) guards).

🔺 SPIR-V шейдери

bash scripts/compile_shaders.sh
# glslc --target-env=vulkan1.1 -DSPIRV_COMPILE=1 -o shaders/spirv/X.spv shaders/X.glsl

🎨 Rendering Stack

Кадр SDL_GPU (порядок pass)

GpuProfiler::BeginFrame()
  │
  ├── [Upload] GpuProfiler::BeginPass("Upload")
  │    AnimationSoA::UploadSDLGPU()   // AnimNpcState → SSBO 5
  │    TransformSoA::UploadSDL()      // xzyr → SSBO 0
  │    GpuProfiler::EndPass()
  │
  ├── [Skinning compute] GpuProfiler::BeginPass("Skinning")
  │    AnimationSoA::DispatchSkinning()  // skinning.comp → FinalBones SSBO 4
  │    GpuProfiler::EndPass()
  │
  ├── [Shadow CSM] GpuProfiler::BeginPass("ShadowCSM")
  │    shadow_cull.comp → shadow_visible[] SSBO 6
  │    ShadowSystem::RenderShadowPass()  // depth-only pass × 3 cascades
  │    GpuProfiler::EndPass()
  │
  ├── [Cull] cull.comp → visible_indices[] SSBO 1 + draw_cmd SSBO 2
  │
  ├── [Scene] GpuProfiler::BeginPass("Scene")
  │    NPC instanced draw (animated.vert + npc_instanced.frag)
  │    Flare billboards (BillboardRenderer)
  │    GpuProfiler::EndPass()
  │
  ├── [Deferred lights] Point volumes → additive blend (SSBO 1+2 reused)
  │
  ├── [SSAO] ssao.comp → half-res R8_UNORM
  │
  └── [SMAA] 3-pass fullscreen: edge → blend weight → final blend

Deferred Lighting (M29–M31)

GPU Profiler (M41)

// engine/include/monkey_dust/render/gpu_profiler.h
md::GpuProfiler::Get().BeginFrame();
md::GpuProfiler::Get().BeginPass("Skinning");
AnimationSoA::Get().DispatchSkinning(...);
md::GpuProfiler::Get().EndPass();
// → EditorGpuProfilerPanel показує budget bars у ms

🧠 AI — BehaviorTree + LOD

Stackless VM, 24-byte ноди (cache-friendly). Data-driven через BTLoader JSON. 3-tier LOD: HIGH (повний BT), LOW (спрощений), FROZEN (тільки позиція).

// Загальний flow:
RegisterAllBTBindings();           // ОБОВ'ЯЗКОВО перед LoadFromFile
BTLoader::Get().LoadFromFile("data/ai/bt_templates.json");
// ...
// У game loop:
AISystem::Get().Tick(reg, dt);     // 10 TPS
ScheduleSystem::Get().Tick(reg, game_time);  // day/night switch

BT Node Types (behavior_tree.h)

🎭 Director / FlowGraph / Sense (M18–M25)

DirectorSystem (M20)

// engine/include/monkey_dust/ai/director_system.h
DirectorSystem::Get().Tick(reg, dt);  // збільшує/зменшує menace
float m = DirectorSystem::Get().menace();  // [0..1]
DirectorStage s = DirectorSystem::Get().stage();  // CALM/TENSE/ALERT/CRISIS

// DirectorProfile з JSON (data/ai/director_profile.json):
// { "gauge_fill_rate": 0.05, "gauge_decay_rate": 0.025, ... }

AgentState (M18 + AI patterns C1,C4,C5,C6,C8)

// engine/include/monkey_dust/components/agent_state.h
// C5: 26 named timer slots
enum class AgentTimerSlot : uint8_t {
    SuspectTargetResponse=0, HeightenedSenses=1, ThreatAwareTimeout=2,
    VocalResponseDelay=3, AlertResponseDelay=4, GiveUpSearchDelay=5,
    HuntFailSafeTimeout=6, StalkTimeout=7, AmbushDelay=8,
    RepeatedPathfindFail=24, Generic=25
};
static constexpr int MAX_AGENT_TIMERS = 26;

// C4: 40 named bit indices
namespace lcf {
    static constexpr uint8_t DONE_BREAKOUT=0, SHOULD_RESET=1,
        SHOULD_ATTACK=10, SHOULD_BREAKOUT=9, HAS_PATH_FAIL=39;
    // ... (40 total)
}
struct LogicCharacterFlags {
    uint64_t bits = 0;
    bool test(uint8_t idx) const noexcept;
    void set(uint8_t idx) noexcept;
    void clear(uint8_t idx) noexcept;
};

// C6: Gauge system
enum class GaugeType : uint8_t { Retreat=0, StunDamage=1, COUNT };
struct AgentGauges { float val[2] = {}; /* get/set/add */ };

// C8: EntityState 23-flag bitmask
enum class EntityStateFlag : uint32_t {
    None=0, Activate=0x1, Spawn=0x2, Enable=0x80, Frozen=0x400000, /* ... */
};
inline bool esf_test(uint32_t state, EntityStateFlag f);

// C1: 14-value motivation
enum class MotivationType : uint8_t {
    None=0, Idle=1, Stalk=2, Attack=3, ThreatAware=4, Search=5,
    Flee=6, Script=7, Despawn=8, Suspicious=9, BackstageStalk=10,
    Ambush=11, Breakout=12, PlayerHiding=13, COUNT
};

struct AgentState {
    uint64_t          timers[MAX_AGENT_TIMERS]; // C5: 26 named slots (ms)
    LogicCharacterFlags lcflags;                 // C4: uint64 + 40 named bits
    uint32_t          entity_state;              // C8: EntityStateFlag bitmask
    AgentGauges       gauges;                    // C6: retreat + stun
    MotivationType    motivation;                // C1: active motivation
    uint8_t           _pad[3];
    int               bb_count;
    BlackboardEntry   bb[MAX_BB_ENTRIES];        // [24] FNV-1a keyed
};

FlowGraph (M23 + M45)

// engine/include/monkey_dust/scripting/flow_graph.h
// FNV-1a uint32 для node IDs; MAX 64 nodes + 128 conns; MAX_PENDING=32
FlowGraph::Get().TriggerNode(fnv1a("on_player_enter"));
FlowGraph::Get().Tick(game_time_s);

// FlowVar typed union (M45):
FlowGraph::Get().SetVarFloat("menace_threshold", 0.7f);
FlowGraph::Get().SetVarBool("boss_alive", true);
bool alive = FlowGraph::Get().GetVarBool("boss_alive");

SenseComponent (M19)

// ViewConeSet: Close (3m/120°) / Focused (10m/30°) / Normal (6m/90°) / Peripheral (8m/180°)
// SenseActivation[2]: time_since_detected_s + activation_level [0..1]
SenseRegistry::Get().LoadViewConeSets("data/ai/view_cone_sets.json");
// Tick: FlareAnimSystem + DirectorSystem berechnen activation

NpcConfig (M22 + C9)

// engine/include/monkey_dust/ai/npc_config.h
struct NpcConfig {
    char name[32];
    char parent[32];           // $inherit — один рівень
    char cone_set[24];         // SenseRegistry key
    char director_profile[24];
    char bt_day[32];
    char bt_night[32];
    char bt_stage[4][32];      // C9: per-DirectorStage override (Unaware/Suspicious/Hunting/Intense)
                               //     empty string = fall back to bt_day/bt_night
    int   max_health;
    float move_speed;
    float wander_radius;
};

// JSON (data/ai/npcs/guard.json):
{ "id": "guard", "$inherit": "humanoid_base",
  "health": 120, "speed": 3.5, "bt_day": "guard_patrol",
  "bt_stage_2": "guard_hunting" }   // Hunting stage override

🧠 Extended AI Patterns (C1–C20)

C1–C10 (базові структури)

C11–C20 (розширені AI примітиви)

C1 — MotivationGate BT патерн

// BuildMotivationGateBT (ai_goal.h) — Priority-selector з 4 motivation-gated branches:
// DirectorSystem/FlowGraph пише motivation; BT читає через MotivationCheck — нуль coupling.
uint16_t rep = bt.addRepeat(0);
uint16_t sel = bt.addSelector();
uint16_t seq_atk  = bt.addSequence();
bt.addChild(seq_atk, bt.addMotivationCheck(MotivationType::Attack));
bt.addChild(seq_atk, bt.addSetMotivation(MotivationType::Idle));  // споживає мотивацію
bt.addChild(seq_atk, bt.addAction(actChaseTarget));
bt.addChild(sel, seq_atk);
// ... (Flee, Search, Idle wander branches)
bt.setRoot(rep);

C13 — frame_flags (один-тік сигнали)

// BTSystem::Tick() — фаза 1: скидаємо frame_flags ПЕРЕД BT::tick()
as.frame_flags = 0;  // C13 invariant — per-frame signals reset

// Встановити сигнал (напр. з SenseSystem або FlowGraph):
as.frame_flags |= (1ULL << lcf::HAS_RECEIVED_DOT);

// BT читає через FrameFlagCheck (зникне автоматично наступного тіку):
bt.addFrameFlagCheck(lcf::HAS_RECEIVED_DOT, true);

C18 — RoleSystem (координація NPC)

// RoleRegistry: один SearchLead на всю сцену
// BT-дерево першого NPC що може стати SearchLead:
uint16_t seq = bt.addSequence();
bt.addChild(seq, bt.addRoleCheck(NpcRole::SearchLead, /*could_perform=*/true));
bt.addChild(seq, bt.addRoleClaim(NpcRole::SearchLead, query_id));
bt.addChild(seq, bt.addAction(actSystematicSearch));

// Другий NPC перевіряє чи він вже виконує роль:
bt.addRoleCheck(NpcRole::SearchLead, /*could_perform=*/false); // is_performing

// Звільнення при виході з ролі:
bt.addRoleRelease(NpcRole::SearchLead);

C4 — LogicCharacterFlags (bit-index, не bitmask)

// ПРАВИЛЬНО — передаємо bit-index (0..39):
bt.addFlagCheck(lcf::SHOULD_ATTACK, true);   // перевірити що bit 10 = 1
bt.addFlagSet  (lcf::SHOULD_ATTACK, false);  // скинути bit 10

as.lcflags.set  (lcf::HAS_PATH_FAIL);       // bit 39
as.lcflags.test (lcf::SHOULD_ATTACK);       // → bool

// НЕПРАВИЛЬНО: bt.addFlagCheck(0x400) ← bitmask більше не підтримується

C7 — Hierarchical FNV IDs

constexpr uint32_t K_AI_NPC_HUNT   = fnv_path("ai", "npc",   "hunt");
uint32_t node_id = fnv_combine(fnv1a_rt(zone_name), fnv1a("on_enter"));

🤖 BT VM — BTNodePool · BTSystem · BTJsonLoader

BTNodePool — flat 32KB arena

// engine/include/monkey_dust/ai/bt_node_pool.h
// sizeof(BehaviorTree) = 4616 bytes > BLOCK_SIZE=4096 → single flat bump ptr
BTNodePool pool;                          // 8 блоки × 4096 = 32 KB BSS
BehaviorTree* tpl = pool.AllocTree();     // placement-new у арені, O(1)
// ... будуємо tpl ...
pool.TreeCount();    // → кількість живих BT
pool.BytesUsed();    // → байти використано
pool.Reset();        // ~BehaviorTree() на всіх, offset=0 (не free())

BTSystem — ECS driver (3 фази)

// engine/include/monkey_dust/ai/bt_system.h
BTSystem bt_sys;
BTSystem::ConnectRegistry(reg);  // підключаємо on_destroy listener

// У logic tick (10 TPS):
bt_sys.Tick(ctx, reg, nowMs);
// Фаза 1: clear frame_flags + expire stale DirectorHints (>MAX_PENDING_TICKS=10)
// Фаза 2: clear frame_flags для entity без DirectorHintComponent
// Фаза 3: tick всіх enabled BehaviorTreeComponent

// Якщо entity має owning=true BT — BTSystem::OnComponentDestroy() звільняє дерево

BTJsonLoader — strstr recursive parser

// engine/include/monkey_dust/ai/bt_json_loader.h
// JSON format:
{
  "name": "systematic_search",
  "root": {
    "type": "SelectorLinear",
    "children": [
      { "type": "DecoratorBranch", "branch_type": "Dead",
        "condition": "condIsDead", "shutdown_speed": "Critical",
        "children": [{ "type": "ActionNode", "action": "actDead" }] },
      { "type": "SequenceLinear", "children": [
          { "type": "MotivationCheck", "motivation": "Search" },
          { "type": "AwarenessCheck",  "state": "SearchingArea" },
          { "type": "TimerStart", "timer_slot": "SearchTimeout",
            "duration_ms": 30000, "only_increase": false },
          { "type": "RoleCheck", "role": "SearchLead", "mode": "could_perform" },
          { "type": "RoleClaim", "role": "SearchLead", "query_id": 1 },
          { "type": "ActionNode", "action": "actSystematicSearch" }
      ]}
    ]
  }
}

// Завантаження:
md::BTActionRegistry::Get().Clear();
md::BTActionRegistry::Get().RegisterAction("actSystematicSearch", actSystematicSearch);
md::BTActionRegistry::Get().RegisterCondition("condIsDead", condIsDead);

BehaviorTree bt;
BTJsonLoader::LoadFromFile(bt, "data/bt/systematic_search.bt.json");
// Unregistered actions/conditions → MD_LOG_WARNING + s_act_failure / s_cond_false
// (дерево завантажується навіть якщо не всі функції зареєстровано)

Підтримувані типи вузлів BTJsonLoader

🔬 9 Multi-Engine Improvements

IMP-1: ACES tonemapping (pbr.frag)

// Замінює Reinhard: color/(color+1)
// ACES filmic:
color = clamp((color*(2.51*color+0.03))/(color*(2.43*color+0.59)+0.14), 0.0, 1.0);
color = pow(color, vec3(1.0 / 2.2));  // gamma correction

IMP-2: Live BT Reload

// game/src/ai/bt_loader.h
BTLoader::Get().WatchFile("data/ai/bt_templates.json");  // реєструємо у HotReload

// logic_tick.cpp — щотіку (main thread):
BTLoader::Get().PollReload();  // if (needs_reload_) { RegisterAllBTBindings(); LoadFromFile(); }

// BTLoader::OnReloadCallback (background thread) — тільки ставить volatile flag:
static void OnReloadCallback(const char*) { Get().needs_reload_ = true; }

IMP-3: NpcMemoryComponent

// engine/include/monkey_dust/components/npc_memory.h
NpcMemoryComponent* mem = reg.try_get<NpcMemoryComponent>(e);
if (mem) {
    mem->AddSpatial(wx, wz, now_ms, 200);  // LRU: evicts oldest if full
    mem->AddEvent(fnv1a("heard_footstep")); // ring overwrite if full
    bool heard = mem->HasEvent(fnv1a("heard_footstep"));
    mem->ExpireOlderThan(now_ms, 30000);   // 30s lifetime
}

// BT JSON:
{ "type": "MemoryCheck", "mode": "has_spatial" }  // або "has_event"
{ "type": "MemoryForget" }                         // ClearAll()

IMP-8: UtilityScorer

// engine/include/monkey_dust/ai/utility_scorer.h
// Замінює жорстко прошиту priority-selector для вибору мотивації:
MotivationType next = UtilityScorer::SelectMotivation(as, now_ms);
if (next != as.motivation) {
    as.motivation = next;
    // MotivationCheck у BT підхопить на наступному тіку
}

// Внутрішньо:
// FillCandidates: AwarenessState::Aware → Attack score 80; Alert → Search 60; ...
// Bias(as.motivation, 10) → +10 до поточної мотивації (інерція)
// BestFrom → max score, при рівності — менший enum index

📜 Lua Sandbox (M15 + FIX-2/3)

// LuaSystem::Init() (engine/src/scripting/lua_system.cpp):
lua_mem_used_ = 0;
L_ = lua_newstate(lua_alloc, &lua_mem_used_);  // 8 MB custom allocator
luaL_openlibs(L_);

static const char* blocked[] = { "io", "os", "package", "debug", nullptr };
for (int i = 0; blocked[i]; ++i) { lua_pushnil(L_); lua_setglobal(L_, blocked[i]); }
static const char* blocked_fns[] = { "dofile", "loadfile", "load", "loadstring", nullptr };
for (int i = 0; blocked_fns[i]; ++i) { lua_pushnil(L_); lua_setglobal(L_, blocked_fns[i]); }

lua_sethook(L_, hook, LUA_MASKCOUNT, 10000);

LuaEventBus (M15)

// engine/include/monkey_dust/scripting/lua_event_bus.h
// MAX_HANDLERS=64 BSS — не збільшувати без профайлінгу
LuaEventBus::Get().Register("player_died", handler_fn);
LuaEventBus::Get().Fire("player_died", L);

Lua C API (lua_game_api.h)

🗺️ Standalone Editor (monkey_dust_editor)

Standalone JSON + tile map editor. SDL3 + imgui_impl_sdl3/opengl3. Запускати з кореня репо: ./build/tools/monkey_dust_editor

Вікно: 85% висоти монітора, 16:9 (мін 854×480). Конфіг шрифтів: data/editor_config.json.

Вкладки редактора

Гарячі клавіші (Map tab)

Viewport Map — керування мишею

Palette — вкладки

Layer visibility

Eye-toggles для кожного з 6 шарів; активний шар підсвічено зеленим. Тільки видимі шари рендеряться у viewport. LayerMask() передається до TileMap2DRenderer.

Undo/Redo архітектура

// PaintOp: записує до 25 комірок (5×5 brush) або index до FloodSnap
// FloodSnap: full-layer before/after snapshot (8 × 2 × 64KB BSS)
// Undo/Redo stack: кільцевий буфер до 256 ops
// Flood fill займає 1 undo slot (FloodSnap у snap_pool_)

File меню (menu bar)

🖥️ Wicked-style Editor (M34 + M38–M41 + Extension Panels, MONKEY_DUST_EDITOR=ON)

Компілюється у monkey_dust з -DMONKEY_DUST_EDITOR=ON. Toggle: F3. Physics пауза активна за замовчуванням при відкритті.

Клавіатурні скорочення

Gizmo — snapping

Камера редактора

Toolbar кнопки

Меню Bar

Command Palette (Ctrl+P)

Fuzzy-search по всіх командах редактора. ↑↓ = навігація, Enter або подвійний клік = виконати, Esc = закрити.

Scoring (без heap allocation, без зовнішньої бібліотеки): +1 за кожен match символу; +4 за consecutive run; +2 за початок слова або після :/пробілу. Результати сортуються за score (insertion sort, max 32 видимих).

// Доступні команди з hint:
Gizmo: Translate    [W]        Gizmo: Rotate         [E]
Gizmo: Scale        [R]        Gizmo: Toggle World/Local [G]
Camera: Focus       [F]        Select All            [Ctrl+A]
Delete Selected     [Del]      Edit: Undo            [Ctrl+Z]
Edit: Redo          [Ctrl+Y]   Scene: Rebuild NavMesh
Scene: Save Game    [F5]       Scene: Load Game      [F9]
Spawn: NPC Bandit              Debug: Toggle Overlay [F1]
Panel: ViewCone Inspector      Panel: FlowGraph      ...

Panels (14 штук)

FlareBrowser (Editor panel)

Відображає завантажений FlareMap: tile thumbnails по atlas_idx, meta (offset_y, anim frames), шар-фільтр. Корисний для перевірки що тайлсет завантажений коректно та для вибору tile_id для скриптів.

▶️ md_flare_demo

Standalone SDL_GPU Vulkan Flare map viewer. Без OpenGL context, без Raylib.

./build/tools/md_flare_demo [mods_root] [mod_name] [map_name]
# defaults: third_party/flare-game/mods  empyrean_campaign  maps/goblin_camp.txt

Plain SDL_Window → SDL_ClaimWindowForGPUDevice → Vulkan swapchain → TileMap2DRenderer SDL_GPU path → SPIR-V tile_map_2d.vert/frag.

Керування (md_flare_demo)

WorldPlacer (Debug build, F4)

In-game об'єктний редактор у DEBUG build. Активується F4. Коли активний — Tab не перемикає тип будівлі, а тип маркера.

// Формат export:
{ "markers": [
    { "type": "TREE", "x": 12.5, "y": 0.0, "z": -8.3 },
    { "type": "SPAWN_BANDIT", "x": 5.0, "y": 0.0, "z": 3.1 }
  ]
}

🧪 Test Suite (M43–M58 + AI-Ext-1–20 + BT VM + Batch 3–27)

ninja -C build md_tests && build/tests/md_tests
# [==========] 1252 tests from 180 test suites ran. (all PASSED)

🔄 Game Loop

// game/src/main.cpp — спрощена схема:
while (running) {
    // ── Logic: 10 TPS (LOGIC_TICK_S = 0.1f) ──────────────────────────
    while (logic_lag >= LOGIC_TICK_S) {
        ProcessInput();
        LogicTick(reg, gs, 0.1f);   // AI + Nav + Combat + Director + Projectiles
        logic_lag -= LOGIC_TICK_S;
    }

    // ── Render: 60 FPS ───────────────────────────────────────────────
    SDL_GPUCommandBuffer* cmd = GpuDevice::Get().AcquireCommandBuffer();
    AnimationSoA::Get().Advance(frame_dt);
    AnimationSoA::Get().UploadSDLGPU(cmd);
    TransformSoA::Get().UploadSDL();
    AnimationSoA::Get().DispatchSkinning(skin_bindings);
    ShadowSystem::Get().RenderShadowPass(...);
    // ... cull compute → NPC draw → lights → SSAO → SMAA ...
    HudRenderer::Draw(reg, gs, camera);
    GpuDevice::Get().Submit(cmd);

    AnimationSoA::Get().AdvanceFrame();
}

🧩 ECS (EnTT 3.16)

// Registry singleton:
auto& reg = Registry::Get();

// Спавн NPC:
auto e = reg.create();
reg.emplace<WorldTransform>(e, x, 0.f, z);
reg.emplace<Health>(e, 100);
reg.emplace<AIAgent>(e);
reg.emplace<NavAgent>(e);
reg.emplace<AgentState>(e);  // M18: timers+flags+blackboard

// Collect → Apply патерн (НЕ мутувати registry під час view.each):
std::vector<entt::entity> to_destroy;
reg.view<Health>().each([&](auto e, auto& hp) {
    if (hp.current <= 0) to_destroy.push_back(e);
});
for (auto e : to_destroy) reg.destroy(e);

Компоненти (engine/include/monkey_dust/components/)

🧭 NavMesh + PathCache

// PathCache — LRU 64, TTL 5s, spinlock + _mm_pause (FIX-7):
uint32_t ks = PathCache::PosKey(start_x, start_z);
uint32_t ke = PathCache::PosKey(end_x, end_z);
float verts[MAX_PATH_LEN * 3]; int len;
if (!PathCache::Get().Get(ks, ke, now_s, verts, len)) {
    NavSystem::Get().QueryPath(sx, sz, ex, ez, verts, len);
    PathCache::Get().Put(ks, ke, now_s, verts, len);
}
// Waypoint path: path[i*3], path[i*3+1], path[i*3+2] — НЕ path[i]

⚔️ Combat + Powers (M4 + M33–M35)

Base Combat System

// 6 hit zones (HEAD/CHEST/ABDOMEN/LEFT_ARM/RIGHT_ARM/LEGS)
// 3 damage types: BLUNT / CUT / PIERCE
// armor_resistance[3] per zone

DamageCalc::Apply(attacker, target, reg);  // collect → apply

PowerSlotManager (M35)

// 4 slots per entity; cooldowns; no heap alloc
PowerSlotManager::Get().AssignPower(entity, slot=0, power_id="fireball");
PowerSlotManager::Get().UsePower(entity, slot=0, reg);
float cd = PowerSlotManager::Get().GetCooldown(entity, slot=0);

// Lua:
// md_assign_power(entity, slot, "fireball")
// md_use_power(entity, slot)
// md_get_power_cooldown(entity, slot) → float

ProjectileSystem (M34)

// Collect → apply; MAX_PROJECTILES фіксований масив
// ProjectileComponent: vel(vec3) + dmg + max_range + ttl + owner_entity
ProjectileSystem::Get().Tick(reg, dt);  // move → hit check → expire

🏗️ Building System

// BuildSystem: 200×200 grid snap; 9 building types
BuildSystem::Get().Place(def_id, wx, wz, reg);
BuildSystem::Get().Demolish(entity, reg);  // async NavMesh rebuild
BuildSystem::WorldToGrid(wx, wz, gx, gz);
BuildSystem::SnapToGrid(wx, wz);  // ref args

// ProductionChain: resource_in → ticks_per_cycle → resource_out
// Inventory: 16 слотів, resource costs для будівництва

💾 Save / Load (v8 + CRC32)

// SaveHeader (world_serializer.h):
struct SaveHeader {
    uint32_t magic;         // 0x4D445356 "MDSV"
    uint32_t version;       // 8
    uint32_t crc32;         // CRC32 всього файлу (це поле = 0 при обчисленні)
    uint32_t data_size;     // повний розмір файлу в байтах
    uint64_t timestamp_ms;
    float    player_x, player_z, game_time_hours;
    uint32_t npc_count, building_count;
};

// Atomic save: записати у .tmp → rename
// Async save: SaveSystem::SaveAsync(path) → char[256] async_path_ (FIX-9)

// SetCallbacks (НЕ SetContext):
SaveSystem::Get().SetCallbacks(WorldSerializer::Serialize,
                               WorldSerializer::Deserialize, nullptr);

NpcRecord layout (v7/v8)

struct NpcRecord {
    float x, z, y;          // позиція
    uint32_t faction;
    int8_t  personal_relation;
    uint8_t bt_template_id;
    uint8_t has_agent_state; // _pad[0] = AgentState inline flag (M36)
    uint8_t _reserved;
    // AgentState tail (якщо has_agent_state):
    float   timers[8];
    uint32_t flags;
    uint32_t bb_keys[24]; float bb_vals[24]; uint8_t bb_used;
};

📜 Quest System

// QuestSystem (game/src/systems/quest_system.h)
// Types: KILL / BUILD / COLLECT
// bitmask: completed_quests[4] (128 quests max)
// Chains: prerequisite_quest + next_quest + faction_reward

// JSON (data/quests/quest_001.json):
{ "id": 1, "type": "KILL", "target_faction": 2, "count": 5,
  "next_quest": 2, "faction_reward": { "faction": 0, "delta": 10 } }

🔒 Security & Integrity (FIX-1–10)

Performance: AVX2 (M46)

// engine/include/monkey_dust/platform/md_hints.h:
#ifdef __AVX2__
// BulkComputeDistSq: 8 floats/iter з _mm256_fmadd_ps
__m256 dx = _mm256_sub_ps(_mm256_load_ps(px + i), cx8);
__m256 dz = _mm256_sub_ps(_mm256_load_ps(pz + i), cz8);
_mm256_store_ps(dist_sq + i, _mm256_fmadd_ps(dx, dx, _mm256_mul_ps(dz, dz)));
#endif

// alignas(64) на всіх 5 SoA масивах → vmovaps замість vmovups
// MD_HOT на BulkComputeDistSq/BulkComputeLOD → __attribute__((hot))

🚫 Що НЕ робити

💡 Канонічні патерни

Collect → Apply (мутація ECS)

static std::vector<entt::entity> to_kill;  // BSS, не heap
to_kill.clear();
reg.view<Health>().each([&](auto e, auto& hp){
    if (hp.current <= 0) to_kill.push_back(e);
});
for (auto e : to_kill) reg.destroy(e);

SaveSystem setup

// game/src/main.cpp — ДО першого Save/Load:
SaveSystem::Get().SetCallbacks(
    WorldSerializer::Serialize,    // SaveWriteCallback
    WorldSerializer::Deserialize,  // SaveReadCallback
    nullptr                        // userdata
);
// НЕ SetContext (видалено)

BTActionFunc signature

// Листові функції BT:
BTStatus myAction(md::EngineContext& ctx, entt::entity e) {
    auto& gs = static_cast<GameState&>(ctx);
    // ...
    return BTStatus::SUCCESS;
}
// Реєстрація:
RegisterBTAction("myAction", myAction);

GPU compute dispatch

GpuComputePipeline::Desc d;
d.glsl_path                     = "shaders/my.comp";
d.num_readonly_storage_buffers  = 1;
d.num_readwrite_storage_buffers = 1;
pipeline.Create(d);

// SDL_GPU dispatch:
GpuComputePass pass;
pass.Begin(&pipeline, bindings);  // bindings.cmd != nullptr
pass.Dispatch(groups_x, 1u, 1u);
pass.End();

md_hints.h usage

#include <monkey_dust/platform/md_hints.h>

MD_HOT void MyHotFunction() { ... }

if (MD_UNLIKELY(error_condition)) { MD_LOG_WARNING(...); return; }
if (MD_LIKELY(common_path)) { ... }

MotivationGate: написати motivation з зовнішньої системи

// DirectorSystem або FlowGraph пише; BT читає через MotivationCheck
// Нульова пов'язаність — BT не знає хто і коли поставив motivation.

// FlowGraph node action (при срацюванні тригера):
if (AgentState* as = reg.try_get<AgentState>(npc))
    as->motivation = MotivationType::Attack;

// BT автоматично підхопить на наступному тику через MotivationCheck вузол

fnv_path для ієрархічних ключів

#include <monkey_dust/ai/fnv.h>

// Compile-time ієрархічний ключ:
constexpr uint32_t K_ZONE_A_ENTER = fnv_path("zone_a", "on_enter");
constexpr uint32_t K_AI_PATROL    = fnv_path("ai", "npc",   "patrol");

// Blackboard key combination:
uint32_t k = fnv_combine(fnv1a_rt(npc_name), fnv1a("speed"));
bb_set_float(state, k, 3.5f);

LogicTickContext: захист від re-entrant тіків

// game/src/logic_tick.h — перед кожним RunLogicTick:
extern LogicTickContext g_logic_ctx;
if (g_logic_ctx.active) { MD_LOG_WARNING("re-entrant tick!"); return; }
g_logic_ctx.begin(dt);
RunLogicTick(now_s, fps, player, ...);
g_logic_ctx.end();

// frame_index доступний для per-frame дебагу:
MD_LOG_INFO("frame %llu dt=%.3f", g_logic_ctx.frame_index, g_logic_ctx.dt);

⚠️ Відомі pitfalls

🗓️ Roadmap — стан на 2026-05-16

Завершено (M0–M58 + FIX-1–10 + AI-Ext-1–20 + BT VM + IMP-1–9 + Batch 3–27)

🔗 SSBO / Texture Bindings

SSBO bindings (SDL_GPU set=1 / OpenGL binding=N)

Texture units

SDL_GPU descriptor sets (SPIRV_COMPILE path)

© Ліцензія

Сторонні компоненти (дозвільні ліцензії)

Субмодуль third_party/flare-game/ — виключно для розробки та тестування, не розповсюджується (GPL-2.0).