# rufl/kookie architecture

> Architecture diagram of the GitHub repository rufl/kookie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rufl/kookie
- Repository: https://github.com/rufl/kookie

## Overview

KOOKIE is an experimental 3D shooter engine and game built around Kof, with authoritative multiplayer, a bounded content pipeline, persistence, and native platform adapters. The principal workflow runs player commands through client prediction and server authority, which resolves gameplay and returns snapshots and feedback; authored assets are validated and cooked into packages for runtime use. The README documents these boundaries and relationships, but most Kof implementation files were not sampled, so the graph uses documented relationships and directory paths for unsampled subsystems.

Main entry points: [`src/session/authoritative_session.kf`](https://github.com/rufl/kookie/blob/main/src/session/authoritative_session.kf) (Server authority), [`src/session/remote_endpoint.kf`](https://github.com/rufl/kookie/blob/main/src/session/remote_endpoint.kf) (Client session), [`src/world/g1_arena.kf`](https://github.com/rufl/kookie/blob/main/src/world/g1_arena.kf) (Arena world), [`src/content/cooker.kf`](https://github.com/rufl/kookie/blob/main/src/content/cooker.kf) (Asset intake and cooker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Game runtime"]
  node_main["Runtime entry<br/>[main.kf]"]
  node_client["Client session<br/>[remote_endpoint.kf]"]
  node_server["Server authority"]
  node_presentation["Game presentation<br/>[game_shell.kf]"]
end

subgraph group_gameplay["Gameplay systems"]
  node_world["Arena world<br/>[g1_arena.kf]"]
  node_combat["Combat and rewards<br/>[combat.kf]"]
  node_inventory["Items and progression<br/>[item_inventory.kf]"]
  node_movement["Movement and collision<br/>[movement.kf]"]
end

subgraph group_content["Content and creator tools"]
  node_cooker["Asset intake and cooker<br/>[cooker.kf]"]
  node_canonical["Canonical packages<br/>[package.kf]"]
  node_creator["Creator workspace"]
end

subgraph group_state["Persistence and replay"]
  node_save["Save and migration<br/>[save_file.kf]"]
  node_replay["Replay records<br/>[replay_file.kf]"]
end

subgraph group_platform["Native boundaries"]
  node_transport["UDP transport<br/>[kookie_transport.c]"]
  node_sdl["SDL presentation"]
  node_font["Pixel font"]
  node_durable["Durable publication"]
  node_simd["SIMD dispatch"]
  node_windows["Windows shell"]
end

node_player(("Player"))
node_author(("Asset authors"))

node_player -->|"sends input"| node_client
node_client -->|"sends commands"| node_server
node_server -->|"returns snapshots"| node_client
node_server -->|"resolves world"| node_world
node_server -->|"resolves combat"| node_combat
node_server -->|"awards progression"| node_inventory
node_client -->|"predicts movement"| node_movement
node_server -->|"reconciles movement"| node_movement
node_client -->|"exchanges commands"| node_transport
node_server -->|"exchanges snapshots"| node_transport
node_player -->|"starts runtime"| node_main
node_main -->|"runs game UI"| node_presentation
node_presentation -->|"renders and plays audio"| node_sdl
node_sdl -->|"uses glyph data"| node_font
node_author -->|"submits assets"| node_cooker
node_creator -->|"edits and cooks"| node_cooker
node_cooker -->|"emits products"| node_canonical
node_canonical -->|"loads runtime content"| node_world
node_server -->|"persists state"| node_save
node_save -->|"publishes save"| node_durable
node_server -->|"records replay"| node_replay
node_world -->|"uses measured dispatch"| node_simd
node_player -.->|"uses native shell"| node_windows

click node_main "https://github.com/rufl/kookie/blob/main/src/main.kf"
click node_client "https://github.com/rufl/kookie/blob/main/src/session/remote_endpoint.kf"
click node_server "https://github.com/rufl/kookie/blob/main/src/session/authoritative_session.kf"
click node_transport "https://github.com/rufl/kookie/blob/main/native/kookie_transport.c"
click node_world "https://github.com/rufl/kookie/blob/main/src/world/g1_arena.kf"
click node_combat "https://github.com/rufl/kookie/blob/main/src/core/combat.kf"
click node_inventory "https://github.com/rufl/kookie/blob/main/src/core/item_inventory.kf"
click node_movement "https://github.com/rufl/kookie/blob/main/src/core/movement.kf"
click node_presentation "https://github.com/rufl/kookie/blob/main/src/ui/game_shell.kf"
click node_sdl "https://github.com/rufl/kookie/blob/main/native/kookie_sdl_adapter.c"
click node_font "https://github.com/rufl/kookie/blob/main/native/kookie_pixel_font.h"
click node_cooker "https://github.com/rufl/kookie/blob/main/src/content/cooker.kf"
click node_canonical "https://github.com/rufl/kookie/blob/main/src/content/package.kf"
click node_creator "https://github.com/rufl/kookie/blob/main/src/ui/creator_workspace.kf"
click node_save "https://github.com/rufl/kookie/blob/main/src/core/save_file.kf"
click node_durable "https://github.com/rufl/kookie/blob/main/native/kookie_persistence_adapter.c"
click node_replay "https://github.com/rufl/kookie/blob/main/src/core/replay_file.kf"
click node_simd "https://github.com/rufl/kookie/blob/main/native/kookie_simd_dispatch.c"
click node_windows "https://github.com/rufl/kookie/blob/main/scripts/kookie_windows_shell.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_client,node_server,node_presentation toneBlue
class node_world,node_combat,node_inventory,node_movement toneAmber
class node_cooker,node_canonical,node_creator toneMint
class node_save,node_replay toneRose
class node_transport,node_sdl,node_font,node_durable,node_simd,node_windows,node_player,node_author toneIndigo
```

## Components

### Game runtime

- [Runtime entry](https://github.com/rufl/kookie/blob/main/src/main.kf): `src/main.kf`
- [Client session](https://github.com/rufl/kookie/blob/main/src/session/remote_endpoint.kf): `src/session/remote_endpoint.kf`
- [Server authority](https://github.com/rufl/kookie/blob/main/src/session/authoritative_session.kf): `src/session/authoritative_session.kf`
- [Game presentation](https://github.com/rufl/kookie/blob/main/src/ui/game_shell.kf): `src/ui/game_shell.kf`

### Gameplay systems

- [Arena world](https://github.com/rufl/kookie/blob/main/src/world/g1_arena.kf): `src/world/g1_arena.kf`
- [Combat and rewards](https://github.com/rufl/kookie/blob/main/src/core/combat.kf): `src/core/combat.kf`
- [Items and progression](https://github.com/rufl/kookie/blob/main/src/core/item_inventory.kf): `src/core/item_inventory.kf`
- [Movement and collision](https://github.com/rufl/kookie/blob/main/src/core/movement.kf): `src/core/movement.kf`

### Content and creator tools

- [Asset intake and cooker](https://github.com/rufl/kookie/blob/main/src/content/cooker.kf): `src/content/cooker.kf`
- [Canonical packages](https://github.com/rufl/kookie/blob/main/src/content/package.kf): `src/content/package.kf`
- [Creator workspace](https://github.com/rufl/kookie/blob/main/src/ui/creator_workspace.kf): `src/ui/creator_workspace.kf`

### Persistence and replay

- [Save and migration](https://github.com/rufl/kookie/blob/main/src/core/save_file.kf): `src/core/save_file.kf`
- [Replay records](https://github.com/rufl/kookie/blob/main/src/core/replay_file.kf): `src/core/replay_file.kf`

### Native boundaries

- [UDP transport](https://github.com/rufl/kookie/blob/main/native/kookie_transport.c): `native/kookie_transport.c`
- [SDL presentation](https://github.com/rufl/kookie/blob/main/native/kookie_sdl_adapter.c): `native/kookie_sdl_adapter.c`
- [Pixel font](https://github.com/rufl/kookie/blob/main/native/kookie_pixel_font.h): `native/kookie_pixel_font.h`
- [Durable publication](https://github.com/rufl/kookie/blob/main/native/kookie_persistence_adapter.c): `native/kookie_persistence_adapter.c`
- [SIMD dispatch](https://github.com/rufl/kookie/blob/main/native/kookie_simd_dispatch.c): `native/kookie_simd_dispatch.c`
- [Windows shell](https://github.com/rufl/kookie/blob/main/scripts/kookie_windows_shell.c): `scripts/kookie_windows_shell.c`

### Other components

- **Player**
- **Asset authors**

## Connections

- Player → Client session: sends input (evidence: `README.md`)
- Client session → Server authority: sends commands (evidence: `README.md`)
- Server authority → Client session: returns snapshots (evidence: `README.md`)
- Server authority → Arena world: resolves world (evidence: `README.md`)
- Server authority → Combat and rewards: resolves combat (evidence: `README.md`)
- Server authority → Items and progression: awards progression (evidence: `README.md`)
- Client session → Movement and collision: predicts movement (evidence: `README.md`)
- Server authority → Movement and collision: reconciles movement (evidence: `README.md`)
- Client session → UDP transport: exchanges commands (evidence: `README.md`)
- Server authority → UDP transport: exchanges snapshots (evidence: `README.md`)
- Player → Runtime entry: starts runtime (evidence: `README.md`)
- Runtime entry → Game presentation: runs game UI (evidence: `README.md`)
- Game presentation → SDL presentation: renders and plays audio (evidence: `README.md`)
- SDL presentation → Pixel font: uses glyph data (evidence: `native/kookie_sdl_adapter.c`)
- Asset authors → Asset intake and cooker: submits assets (evidence: `README.md`)
- Creator workspace → Asset intake and cooker: edits and cooks (evidence: `README.md`)
- Asset intake and cooker → Canonical packages: emits products (evidence: `README.md`)
- Canonical packages → Arena world: loads runtime content (evidence: `README.md`)
- Server authority → Save and migration: persists state (evidence: `README.md`)
- Save and migration → Durable publication: publishes save (evidence: `README.md`)
- Server authority → Replay records: records replay (evidence: `README.md`)
- Arena world → SIMD dispatch: uses measured dispatch (evidence: `README.md`)
- Player → Windows shell: uses native shell (evidence: `README.md`)