1. Project Vision: Towards a Symbiotic Game Engine

Khora was born from a critical observation: modern game engines, for all their power, are fundamentally rigid. They impose static pipelines, force developers into complex manual optimization, and adapt poorly to the ever-growing diversity of hardware—from high-end PCs to mobile devices and VR platforms.

Our vision is to build an engine that behaves not as a machine, but as a living organism. A symbiotic system where each component is aware of its environment and collaborates to achieve a common goal. Instead of following a fixed set of instructions, Khora observes, learns, and continuously adapts.

The Problem with Rigidity

• Static Resource Allocation: Fixed CPU/GPU budgets are ill-suited to the dynamic complexity of a game scene, leading to either underutilization or performance bottlenecks.
• Laborious Manual Optimization: Developers spend a disproportionate amount of time tuning settings for each target platform, a task that is both tedious and fragile.
• Lack of Contextual Awareness: A traditional engine cannot make intelligent trade-offs. It does not know if a performance dip in the audio system is more or less impactful to the player's experience than one in the renderer during a critical cinematic sequence.

The Khora Solution: The Symbiotic Adaptive Architecture (SAA)

Khora flips the paradigm. It replaces a rigid, top-down orchestrator with a council of intelligent, collaborating agents.

• Automated Self-Optimization: The engine autonomously detects performance bottlenecks and reallocates resources to resolve them.
• Strategic Flexibility: The rendering subsystem can dynamically switch from a fast, low-fidelity technique to a high-quality one based on system load and performance targets, without any direct developer intervention.
• Goal-Oriented Decision Making: All adaptations are driven by high-level goals, such as "maintain 90fps in VR," "prioritize visual quality during cinematics," or "conserve battery on mobile."

The ultimate goal is to empower creators to focus entirely on their artistic vision, trusting the engine to handle the complex technical challenge of delivering a smooth, optimal, and resilient experience on any platform.

2. Core Concepts: The Symbiotic Adaptive Architecture (SAA)

The Symbiotic Adaptive Architecture (SAA) is the philosophical and conceptual framework of Khora. It is built on seven key pillars that work in symbiosis to create a truly adaptive engine.

1. Dynamic Context Core (DCC) - The Central Nervous System

The DCC is the engine's center of awareness. It does not command subsystems directly; instead, it maintains a constantly updated situational model of the entire application state. It acts as a central hub, aggregating telemetry from across the engine to understand the "big picture":

• Hardware Load: Real-time utilization of CPU cores, GPU, VRAM, and memory bandwidth.
• Game State: Scene complexity, entity counts, light sources, physics interactions, network status.
• Performance Goals: The currently active objectives, such as target framerate, maximum input latency, or power consumption budget.

2. Intelligent Subsystem Agents (ISAs) - The Specialists

Every major engine subsystem (Rendering, Physics, Audio, AI, Assets) is designed as an Intelligent Subsystem Agent. An ISA is not a passive library; it is a semi-autonomous component with a deep understanding of its own domain.

• Self-Assessment: It constantly measures its own performance and resource consumption.
• Multi-Strategy: It possesses multiple algorithms to accomplish its task, each with different performance characteristics (e.g., a precise but slow physics solver vs. a fast but approximate one).
• Cost Estimation: It can accurately predict the resource cost (CPU time, memory) of each of its strategies under the current conditions.

3. Goal-Oriented Resource Negotiation (GORNA) - The Council Protocol

GORNA is the formal communication protocol used by the DCC and the ISAs to dynamically allocate resources. This negotiation process replaces static, pre-defined budgets.

1. Request: ISAs submit their desired resource needs to the DCC, often specifying the strategy they intend to use (e.g., "The Rendering Agent requests 8ms of GPU time to execute its High-Fidelity strategy").
2. Arbitration: The DCC analyzes all incoming requests, comparing them against its global situational model and the active performance goals.
3. Allocation: The DCC grants a final budget to each ISA. This budget may be less than what was requested.
4. Adaptation: An ISA that receives a reduced budget is responsible for adapting. It must select a less resource-intensive strategy to stay within its allocated budget.

4. Adaptive Game Data Flows (AGDF) - The Living Data

AGDF is the principle that not only algorithms but also the very structure of data should be dynamic. This advanced concept is realized through our custom ECS, the CRPECS. Instead of being static, an entity's data layout can be fundamentally altered by the SAA in response to the game's context. For example, the Control Plane can cheaply remove physics components from an entity that is far from the player, and add them back when it gets closer. The CRPECS's design makes these structural changes extremely low-cost, enabling a deeper level of self-optimization at the memory level.

5. Semantic Interfaces & Contracts - The Common Language

For intelligent negotiation to be possible, all ISAs must speak a common, unambiguous language. These are defined by a set of formal contracts (Rust traits) that specify an ISA's capabilities and requirements.

• Capabilities: What an ISA can do ("I can render scenes using Forward+ or a Simple Unlit pipeline").
• Requirements: What data it needs to function ("I require access to all entity positions and meshes").
• Guarantees: What it promises in return for a given budget ("With a 4ms CPU budget, I guarantee a stable physics simulation for up to 1000 active rigid bodies").

6. Observability & Traceability - The Glass Box

An intelligent system risks becoming an indecipherable "black box." To prevent this, Observability is a first-class principle in Khora. Every significant decision made by the DCC is meticulously logged with its complete context—the telemetry, the requests, and the final budget allocation. This allows developers to ask not just "what happened?" but "why did the engine make that choice?", which is crucial for debugging, tuning, and building trust in the adaptive system.

7. Developer Guidance & Control - A Partnership, Not an Autocracy

The engine's autonomy serves the developer, it does not replace them. Khora provides clear mechanisms for developers to guide and constrain the SAA.

• Constraints: Developers can define rules or physical volumes in the world to influence decision-making (e.g., "In this zone, physics accuracy is more important than graphical fidelity").
• Adaptation Modes: The DCC can be instructed to operate in different modes:
  • Learning: The default, fully dynamic mode where the engine explores strategies to meet its goals.
  • Stable: Uses heuristics learned from the Learning mode but avoids drastic changes. Ideal for profiling and shipping a predictable experience.
  • Manual: Disables the SAA entirely, allowing developers to lock in specific strategies for debugging or benchmarking.

3. The SAA-CLAD Symbiosis: From Philosophy to Practice

The Khora Engine is built on two core architectural concepts: the Symbiotic Adaptive Architecture (SAA) and the CLAD Pattern. It is crucial to understand that these are not two separate architectures; they are two sides of the same coin, representing the vision and its execution.

• SAA is the "Why": It is our philosophical blueprint. It describes what we want to achieve—a self-optimizing, adaptive engine where intelligent subsystems collaborate to meet high-level goals.
• CLAD is the "How": It is our concrete implementation strategy in Rust. It provides the strict rules, crate structure, and data flow patterns required to make the SAA vision a high-performance, maintainable reality.

Every abstract concept in the SAA has a direct, physical home within the CLAD structure. This explicit mapping ensures that our code is always a faithful implementation of our vision and provides a clear mental model for development.

The SAA-CLAD Mapping

This clear separation of concerns is the key to resolving the classic conflict between complexity and performance. It allows Khora to be highly intelligent and dynamic in its Control Plane (control, agents) while being uncompromisingly fast and predictable in its Data Plane (lanes, data).

4. Technical Architecture: The CLAD Pattern

The CLAD (Control-Lane-Agent-Data) pattern is the concrete Rust implementation of the SAA philosophy. It is an architectural style designed for extreme performance and maintainability by enforcing a strict separation of concerns.

Core Principle: The Hot/Cold Path Split

The entire engine is architected around isolating the Control Plane (Cold Path) from the Data Plane (Hot Path).

• Cold Path (Control Plane):

  • Purpose: Complex, stateful decision-making.
  • Components: khora-control, khora-agents.
  • Frequency: Ticks at a lower, non-critical rate (e.g., 10-60 Hz).
  • Characteristics: Permitted to use complex logic, perform memory allocations, write logs, and analyze data. Its execution time does not directly impact the rendering time of a single frame.

• Hot Path (Data Plane):

  • Purpose: Raw, deterministic work execution.
  • Components: khora-lanes, khora-data.
  • Frequency: Must execute within a strict frame budget (e.g., < 16.67ms for 60fps).
  • Characteristics: Optimized for raw speed. Aims for zero heap allocations, cache-friendly data access (SoA), SIMD operations, and minimal branching.

The CLAD Crates: Roles and Responsibilities

khora-core - The Foundation

The bedrock of the engine. It contains only abstract traits, universal data types (like math primitives), and interface contracts. It has zero dependencies on other khora-* crates and defines the universal "language" of the engine.

khora-data - The Data Layer ([D]ata)

The heart of Khora's data management strategy. This crate's primary responsibility is the implementation of our custom, high-performance CRPECS. It provides the concrete foundation for the AGDF concept, containing the specialized memory allocators, page structures, and the query engine that drives the entire Data Plane.

khora-lanes - The Hot Path ([L]ane)

This crate contains the performance-critical, "dumb" execution pipelines. A Lane is a specific implementation of an ISA's strategy (e.g., a rendering pass, a physics solver). They are optimized for linear data processing and contain no complex branching logic.

khora-agents - The Tactical Brains ([A]gent)

This crate is the home of the ISAs. Each agent is an intelligent wrapper around one or more Lanes. It is responsible for reporting its status to the Control Plane, estimating the cost of its strategies, and, upon receiving a budget, configuring and dispatching the appropriate Lane.

khora-control - The Strategic Brain ([C]ontrol)

The highest level of decision-making. This crate contains the DCC and the GORNA protocol implementation. It consumes telemetry, evaluates the overall situation against high-level goals, and orchestrates the Agents by allocating their resource budgets.

khora-telemetry - The Nervous System

A dedicated service for collecting, aggregating, and exposing engine-wide metrics. It gathers raw data from khora-infra (e.g., VRAM usage) and the Lanes (e.g., execution time) and provides it in a structured format to khora-control and debugging tools.

khora-infra - The Bridge to the World

This crate contains all concrete implementations that interact with external systems: GPU backends (WGPU), windowing (Winit), filesystem I/O, networking libraries, etc. It primarily implements the generic traits defined in khora-core.

khora-sdk - The Public Facade

A simple, stable API designed for game developers. It hides the complexity of the internal CLAD architecture and provides ergonomic, easy-to-use entry points for building an application with Khora.

5. Project and Crate Structure

The Khora project is organized as a Cargo workspace to enforce modularity, enable efficient compilation, and reflect our CLAD architecture. This document provides a high-level overview of the repository's layout.

Top-Level Directory Structure

• .github/: Contains GitHub-specific configurations like CI workflows and issue templates.
• crates/: The heart of the engine. Contains all the core khora-* source code, organized into modular crates.
• docs/: Contains all project documentation, including the source for this book.
• examples/: Engine usage examples and testbeds, with sandbox being our primary test application.
• resources/: Runtime configuration files, such as default profiles for the DCC.
• xtask/: A dedicated crate for build automation and scripting tasks (cargo-xtask).
• Cargo.toml: The root workspace definition, specifying members and compilation profiles.

Detailed Crate Layout

The following is a representative layout of the crates/ directory, illustrating the internal structure of our CLAD implementation.

crates/
├── khora-core/      # FOUNDATIONAL: Traits, core types, interface contracts.
│   └── src/
│       ├── math/
│       ├── platform/
│       ├── renderer/
│       └── ...
│
├── khora-control/   # [C]ONTROL: DCC and GORNA implementation.
│   └── src/
│
├── khora-data/      # [D]ATA: CRPECS, resources, and other data containers.
│   └── src/
│       ├── ecs/
│       └── ...
│
├── khora-lanes/     # [L]ANES: Hot-path execution pipelines (systems).
│   └── src/
│       ├── render_lane/
│       └── scene_lane/
│
├── khora-agents/    # [A]GENTS: Intelligent wrappers driving the Lanes.
│   └── src/
│       ├── render_agent/
│       └── ...
│
├── khora-telemetry/ # Central service for metrics and monitoring.
│   └── src/
│
├── khora-infra/     # Concrete implementations of external dependencies.
│   └── src/
│       ├── graphics/
│       └── platform/
│
├── khora-sdk/       # The stable, public-facing API for game developers.
│   └── src/
│
├── khora-editor/    # The engine's editor GUI.
│   └── src/
│
└── khora-plugins/   # Packaged strategies and extensions.
    └── src/

6. ECS Architecture: The CRPECS

This document details the architecture of Khora's custom Chunked Relational Page ECS (CRPECS). It was designed from the ground up to be the high-performance backbone of the SAA and to enable its most advanced concept: Adaptive Game Data Flows (AGDF).

Philosophy: Performance Through Intelligent Compromise

Modern ECS architectures typically force a difficult choice:

• Archetypal (e.g., bevy_ecs): Delivers extremely fast iteration speeds due to perfect data locality, but incurs a very high performance cost when an entity's component structure changes (an "archetype move").
• Sparse Set (e.g., specs): Offers very fast structural changes, but iteration can be slower for entities with many components due to increased pointer indirection and poorer data locality.

Khora's SAA vision requires the best of both worlds: fast, predictable iteration for the Data Plane (the Lanes), and cheap, frequent structural changes driven by the Control Plane (the Agents and Control crates). The CRPECS resolves this conflict by creating a new set of trade-offs perfectly aligned with our goals.

Its core principle is to completely dissociate an entity's logical identity from the physical storage location of its component data.

Core Principles

1. Component Pages: Semantic Data Grouping

Instead of storing components based on the entity's complete structure (its archetype), we group them by semantic domain into fixed-size memory blocks called Pages (e.g., 16KB).

• A PhysicsPage would store the contiguous Vecs for Position, Velocity, and Collider.
• A RenderPage would store the contiguous Vecs for MeshHandle, MaterialHandle, and Visibility.

Within each Page, component data is stored as a Structure of Arrays (SoA), guaranteeing optimal cache performance for any system iterating within that domain.

2. Entity Metadata: The Relational Hub

An entity's identity is maintained in a central table, completely separate from its component data. Each entry in this table is a small struct containing pointers that map the entity's ID to the physical location of its data across all relevant Pages.

#![allow(unused)]
fn main() {
// A logical pointer to a piece of component data.
struct PageIndex {
    page_id: u32,   // Which page holds the data?
    row_index: u32, // Which row within that page's SoA?
}

// The central "table of contents" for a single entity.
struct EntityMetadata {
    // A map from a component's semantic domain to its physical location.
    locations: HashMap<SemanticDomain, PageIndex>,
}
}

3. Data Dissociation: The Key to Flexibility

The data for a single entity is physically scattered across multiple Pages, but it is logically unified by its EntityMetadata. This is the architectural key that unlocks our required flexibility.

How Key Operations Work

Iteration (e.g., Query<(&mut Position, &Velocity)>)

• Performance: Near-Optimal.
• The query understands that Position and Velocity both belong to the Physics semantic domain. It therefore only needs to iterate through all active PhysicsPages, accessing their contiguous Vecs. This achieves performance nearly identical to a pure Archetypal ECS for domain-specific queries.

Adding/Removing Components (Structural Changes)

• Performance: Extremely High.
• To remove an entity's AI behavior, we simply remove an entry from the locations HashMap in its EntityMetadata. This is a near-instantaneous O(1) operation. The actual component data is now "orphaned" and will be cleaned up later by a low-priority garbage collection process.
• Adding a component only requires modifying the data within a single semantic domain, leaving all other component data for that entity completely untouched.

The Intelligent Compromise: Transversal Queries

The explicit trade-off for this flexibility is the performance cost of transversal queries—queries that access data from different semantic domains simultaneously (e.g., Query<(&Position, &MeshHandle)>).

• Mechanism: Such a query cannot iterate linearly over a single set of Pages. It must perform a "join," typically by iterating over the pages of one domain (e.g., PhysicsPages) and using each entity's ID to look up its EntityMetadata, which then points to the location of its data in the other domain (e.g., RenderPages).
• Cost: This lookup process introduces pointer chasing and potential cache misses. A transversal query can be significantly slower than a native, domain-specific query.
• Architectural Benefit: This is a deliberate design choice. It creates a strong "architectural gravity" that encourages developers to write clean, decoupled systems. The physics engine should operate on physics data, and the rendering engine on rendering data. We make the common, well-designed case extremely fast, at the expense of the rare, coupled case.

Integration with CLAD and SAA

The CRPECS is the cornerstone of the khora-data crate and the ultimate implementation of the [D]ata in CLAD.

• It provides the perfect foundation for AGDF, as the SAA's Control Plane can cheaply and frequently alter data layouts by modifying EntityMetadata.
• The garbage collection and page compaction processes can themselves be implemented as Intelligent Subsystem Agents (ISAs), operating on a low-priority thread when the system has spare resources, making the ECS itself a living, self-optimizing part of the SAA.

07 - Asset Architecture: The Virtual File System (VFS)

The Problem: Assets as a Strategic Resource

In a traditional engine, an asset system is a simple loader: you ask for a file path, it gives you back data. This is insufficient for the Symbiotic Adaptive Architecture (SAA). To make intelligent decisions, the AssetAgent ISA needs to understand assets not as files on disk, but as strategic resources with costs, dependencies, and alternatives.

Khora's solution is the Virtual File System (VFS). It is not a filesystem in the OS sense; it's an intelligent database that abstracts the physical storage of assets and enriches them with metadata, turning them into a queryable resource for the entire engine.

Core Concepts

1. Logical Identification: AssetUUID and AssetHandle

The engine logic never references a physical file path. Instead, it uses two central types:

• AssetUUID: A unique and stable identifier that represents the "idea" of an asset, regardless of its location or filename. In our production pipeline, it is generated deterministically from the asset's source path.
• AssetHandle<T>: A lightweight, cloneable smart pointer (Arc<T>). This is the type that engine systems manipulate. This indirection is critical: it allows the AssetAgent to manage the asset's lifecycle in the background without ever affecting the game logic that holds the handle.

2. The Abstract Data Source: The AssetSource Enum

To support both development and production workflows, we need an abstraction over where asset data comes from. The AssetSource enum fulfills this role in a type-safe manner:

• AssetSource::Path(PathBuf): Used by the editor (future). Indicates that the asset is a loose file on disk.
• AssetSource::Packed { offset, size }: Used by the runtime. Indicates the exact location of the asset's data within a data.pack file.

3. Rich Metadata and a Hybrid Indexing Strategy

The core intelligence of the VFS lies in the AssetMetadata. To create and use this metadata, Khora employs a hybrid strategy:

• For Production (What we just built): Packfiles

  • A build tool (xtask) runs the assets pack command.
  • This tool scans source directories (defined in Assets.toml), generates a stable AssetUUID for each asset, and produces two files:
    1. index.bin: A binary file containing a list of all AssetMetadata.
    2. data.pack: A binary file containing the raw, contiguous data of all assets for optimal I/O.
  • Goal: Maximum loading performance in release builds.

• For Development (Future Issue #175): The Real-Time Asset Database

  • A service integrated into the editor will watch the asset directories.
  • Changes will trigger an incremental update to an on-disk database, which will contain the same AssetMetadata but with AssetSource::Path variants.
  • Goal: A seamless and iterative development experience.

The Lifecycle of an Asset Request (Runtime Mode)

This diagram illustrates how the CLAD components we built interact to load an asset from packfiles:

sequenceDiagram
    participant GameLogic as "Game Logic"
    participant AssetAgent as "AssetAgent (Control Plane)"
    participant VFS as "VirtualFileSystem (Data)"
    participant PackLane as "PackLoadingLane (Data Plane)"
    participant Loader as "AssetLoader (e.g., PngLoader)"

    GameLogic->>+AssetAgent: load::<Texture>(texture_uuid)
    AssetAgent->>+VFS: get_metadata(&texture_uuid)
    VFS-->>-AssetAgent: Return AssetMetadata
    Note right of AssetAgent: Decision: Use "default" variant.<br/>Source: AssetSource::Packed { offset, size }
    AssetAgent->>+PackLane: load_asset_bytes(source)
    PackLane-->>-AssetAgent: Return Result<Vec<u8>>
    Note right of AssetAgent: Finds correct loader ("png")<br/>in its LoaderRegistry.
    AssetAgent->>+Loader: load(&bytes)
    Loader-->>-AssetAgent: Return Result<Texture>
    AssetAgent->>AssetAgent: Create AssetHandle<Texture>
    AssetAgent-->>-GameLogic: Return Result<AssetHandle<Texture>>

Conclusion: Why This Architecture is Essential for SAA

This VFS architecture is a critical foundation for the SAA philosophy. It elevates the AssetAgent from a simple file loader to a true Intelligent Subsystem Agent. By providing it with rich metadata via the VFS, we give the agent the context it needs to make meaningful, strategic decisions—such as choosing a lower-quality asset variant to stay within a VRAM budget—that align with the engine's global performance goals.

08 - Roadmap & Issue Tracker

This document outlines the phased development plan for Khora. It integrates all open and proposed tasks into a structured series of milestones.

Phase 1: Foundational Architecture

Goal: Establish the complete, decoupled CLAD crate structure and render a basic scene through the SDK. (Complete)

With the successful abstraction of command recording and submission, the core architectural goals for the foundational phase are now met. The engine is fully decoupled from the rendering backend.

Phase 2: Scene, Assets & Basic Capabilities

Goal: Build out the necessary features to represent and interact with a game world, starting with the implementation of our revolutionary ECS.

[Scene Representation, Assets & Data Focus]

• #42 [Feature] Implement Texture Loading & Management (Depends on #174)
• #43 [Feature] Implement Mesh Loading & Management (Depends on #174)
• #44 [Task] Render Loaded Static Model with Basic Materials (Depends on #40, #42, #43)
• #157 [Task] Implement Component Removal & Basic Garbage Collection (CRPECS v1)
• #45 [Feature] Implement Basic Scene Serialization
• #99 [Feature] Implement Basic Audio System (Playback & Management)
• #126 [Task] Integrate CPU/GPU Timers with Core Metrics System

[Rendering Capabilities, Physics, Animation, AI & Strategy Exploration]

• #159 [Feature] Implement SimpleUnlit RenderLane
• #46 [Feature] Implement Camera System & Uniforms
• #47 [Feature] Implement Material System
• #48 [Feature] Implement Basic Lighting Models (Track shader complexity/perf)
• #160 [Feature] Implement Forward+ Lighting RenderLane
• #49 [Feature] Implement Depth Buffering
• #50 [Research] Explore Alternative Rendering Paths/Strategies (e.g., Forward vs Deferred concept)
• #100 [Feature] Implement Basic Physics System (Integration & Collision Detection) (Depends on #40)
• #161 [Feature] Define and Implement Core PhysicsLanes (Broadphase, Solver)
• #101 [Feature] Implement Skeletal Animation System
• #158 [Feature] Implement Transversal Queries (CRPECS v1)
• #162 [Feature] Implement SkinnedMesh ComputeLane
• #104 [Feature] Implement Basic AI System (Placeholder Behaviors, e.g., Simple State Machine)

Phase 3: The Adaptive Core

Goal: Implement the "magic" of Khora: the DCC, ISAs, and GORNA, proving the SAA concept.

[Dynamic Context Core (DCC) v1 - Awareness]

• #71 [Feature] Design DCC Architecture
• #72 [Feature] Implement DCC Core Service
• #73 [Feature] Integrate Performance/Resource Metrics Collection into DCC
• #74 [Feature] Implement Game State Monitoring Hook into DCC
• #75 [Feature] Design Initial ISA Interface Contract v0.1
• #76 [Task] Refactor one Subsystem to partially implement ISA v0.1
• #116 [Research/Refactor] Evaluate Abstraction for Windowing/Platform System
• #128 [Feature] DCC v1 Integration with Core Metrics System
• #163 [Feature] Make CRPECS Garbage Collector an ISA

[Intelligent Subsystem Agents (ISA) v1 & Basic Adaptation]

• #176 [Feature] Evolve AssetAgent into a full ISA (Depends on #174)
• #78 [Feature] Implement Multiple Strategies for one key ISA
• #79 [Feature] Refine ISA Interface Contract
• #80 [Feature] Implement DCC Heuristics Engine v1
• #81 [Feature] Implement DCC Command System to trigger ISA Strategy Switches
• #82 [Task] Demonstrate Automatic Renderer Strategy Switching
• #83 [Task] Refactor a Second Subsystem as ISA v0.1

[Goal-Oriented Resource Negotiation (GORNA) v1]

• #84 [Research] Design GORNA Protocol
• #85 [Feature] Implement Resource Budgeting in DCC
• #86 [Feature] Enhance ISAs to Estimate Resource Needs per Strategy
• #87 [Feature] Implement Basic GORNA between DCC and 2-3 ISAs
• #88 [Task] Demonstrate Dynamic Resource Re-allocation under Load

Phase 4: Tooling, Usability & Scripting

Goal: Make the engine usable and debuggable by humans. Build the editor, provide observability tools, and integrate a scripting language.

[Editor GUI, Observability & UI]

• #52 [Feature] Choose & Integrate GUI Library
• #53 [Feature] Create Editor Layout
• #54 [Feature] Implement Render Viewport
• #55 [Feature] Implement Scene Hierarchy Panel
• #56 [Feature] Implement Inspector Panel (Basic Components)
• #57 [Feature] Implement Performance/Context Visualization Panel
• #58 [Feature] Implement Basic Play/Stop Mode
• #77 [Feature] Visualize Full Context Model in Editor Debug Panel
• #102 [Feature] Implement In-Engine UI System
• #164 [Feature] Implement UiRenderLane
• #165 [Feature] Implement a "Decision Tracer" for DCC/GORNA in the editor
• #166 [Feature] Implement a Timeline Scrubber for the Context Visualization Panel

[Editor Polish, Networking & Manual Control]

• #175 [Feature] Implement Real-time Asset Database for Editor (Depends on #41)
• #66 [Feature] Implement Asset Browser (Depends on #175)
• #67 [Feature] Implement Material Editor
• #68 [Feature] Implement Gizmos
• #167 [Feature] Implement EditorGizmo RenderLane
• #69 [Feature] Implement Undo/Redo Functionality
• #70 [Feature] Implement Editor Panels for Fine-Grained System Control
• #103 [Feature] Implement Basic Networking System

[Scripting v1]

• #168 [Research] Evaluate and choose a scripting language
• #169 [Feature] Implement Scripting Backend and Bindings
• #170 [Feature] Make the Scripting VM an ISA (ScriptingAgent)

[Maturation, Optimization & Packaging]

• #94 [Task] Extensive Performance Profiling & Optimization
• #95 [Task] Documentation Overhaul (Including SAA concepts)
• #96 [Task] Build & Packaging for Target Platforms

[Milestone: API Ergonomics & DX (Developer Experience)]

• #173 [Feature] Implement a Fluent API for Entity Creation

Phase 5: Advanced Intelligence & Future Capabilities

Goal: Build upon the stable SAA foundation to explore next-generation features and specializations.

[Advanced Adaptivity & Specialization (AGDF, Contracts)]

• #89 [Research] Design Semantic Interfaces & Contracts v1
• #90 [Research] Investigate Adaptive Game Data Flow (AGDF) Feasibility & Design
• #91 [Prototype] Implement basic AGDF for a specific component type
• #92 [Research] Explore using Specialized Hardware (ML cores?)
• #129 [Feature] Metrics System - Advanced Features (Labels, Histograms, Export)

[DCC v2 - Developer Guidance & Control]

• #93 [Feature] Implement more Sophisticated DCC Heuristics / potentially ML-based Decision Model
• #171 [Feature] Implement Engine Adaptation Modes (Learning, Stable, Manual)
• #172 [Feature] Implement Developer Hints and Constraints System (PriorityVolume)

[Core XR Integration & Context]

• #59 [Feature] Integrate OpenXR SDK & Bindings
• #60 [Feature] Implement XR Instance/Session/Space Management
• #61 [Feature] Integrate Graphics API with XR
• #62 [Feature] Implement Stereo Rendering Path
• #63 [Feature] Implement Head/Controller Tracking
• #64 [Feature] Integrate XR Performance Metrics
• #65 [Task] Display Basic Scene in VR with Performance Overlay

Closed Issues (Historical Reference)

[Core Foundation & Basic Window]

• #1 [Feature] Setup Project Structure & Cargo Workspace
• #2 [Feature] Implement Core Math Library (Vec3, Mat4, Quat) - Design for DOD/Potential ADF
• #3 [Feature] Choose and Integrate Windowing Library
• #4 [Feature] Implement Basic Input System (Feed events into core)
• #5 [Feature] Create Main Application Loop Structure
• #6 [Task] Display Empty Window & Basic Stats (FPS, Mem)
• #7 [Task] Setup Basic Logging & Event System
• #8 [Task] Define Project Coding Standards & Formatting
• #18 [Feature] Design Core Engine Interfaces & Message Passing (Thinking about ISAs & DCC)
• #19 [Feature] Implement Foundational Performance Monitoring Hooks (CPU Timers)
• #20 [Feature] Implement Basic Memory Allocation Tracking

[Core Foundation & Context Hooks]

• #21 [Feature] Setup Project Structure & Cargo Workspace
• #22 [Feature] Implement Core Math Library (Vec3, Mat4, Quat) - Design for DOD/Potential AGDF
• #23 [Feature] Design Core Engine Interfaces & Message Passing (Thinking about ISAs & DCC)
• #24 [Feature] Implement Basic Logging & Event System
• #25 [Feature] Implement Foundational Performance Monitoring Hooks (CPU Timers)
• #26 [Feature] Implement Basic Memory Allocation Tracking
• #27 [Feature] Choose and Integrate Windowing Library
• #28 [Feature] Implement Basic Input System (Feed events into core)
• #29 [Feature] Create Main Loop Structure (placeholder for future DCC control)
• #30 [Task] Display Empty Window & Basic Stats (FPS, Mem)

[Rendering Primitives & ISA Scaffolding]

• #31 [Feature] Choose & Integrate Graphics API Wrapper
• #32 [Feature] Design Rendering Interface as potential ISA (Clear inputs, outputs, potential strategies)
• #33 [Feature] Implement Graphics Device Abstraction
• #34 [Feature] Implement Swapchain Management
• #35 [Feature] Implement Basic Shader System
• #36 [Feature] Implement Basic Buffer/Texture Management (Track VRAM usage)
• #37 [Feature] Implement GPU Performance Monitoring Hooks (Timestamps)
• #110 [Feature] Implement Robust Graphics Backend Selection (Vulkan/DX12/GL Fallback)
• #118 [Feature] Implement Basic Render Pipeline System
• #121 [Feature] Develop Custom Bitflags Macro for Internal Engine Use
• #123 [Feature] Implement Core Metrics System Backend v1 (In-Memory)
• #124 [Task] Integrate VRAM Tracking into Core Metrics System
• #125 [Task] Integrate System RAM Tracking into Core Metrics System
• #38 [Task] Render a Single Triangle/Quad with Performance Timings
• #135 [Enhancement] Advanced GPU Performance & Resize Heuristics
• #140 [Feature] Implement Basic Command Recording & Submission

[Scene Representation, Assets & Data Focus]

• #39 [Research & Design] Define Khora's ECS Architecture
• #154 [Task] Implement Core ECS Data Structures (CRPECS v1)
• #155 [Task] Implement Basic Entity Lifecycle (CRPECS v1)
• #156 [Task] Implement Native Queries (CRPECS v1)
• #40 [Feature] Implement Scene Hierarchy & Transform System (Depends on #156)
• #41 [Design] Design Asset System with VFS & Define Core Structs
• #174 [Feature] Implement VFS Packfile Builder & Runtime (Depends on #41)

Complete Crate Reference