Ludus documentation¶
These Markdown files are the sources rendered by Ludus Wiki. Open this directory in VS Code, Obsidian, another Markdown reader or a text editor. Relative links and local images work without internet access.
Choose a task¶
- Install and launch the editor
- Build the engine: native, headless, container and macOS
- Create your first game
- Use the CLI and shared SDKs
- Explore current capabilities
- Find the architecture owner
- Read or package documentation offline
Document roles¶
Guides describe supported workflows. Module pages contain usage examples. Designs can contain proposed extensions; read their status and evidence. Reviews record consulted sources, plans record intended work, and validation records name the tested revision and environment. Historical baselines retain earlier decisions and boundaries. Their statements apply to that scope.
The inventory below covers every authored page, grouped by its role.
It is generated by python scripts/check-docs --fix-index; edit linked pages
for content changes. Module/sample/tool READMEs link to these owners.
Start and orientation¶
- Build understanding. Then build your game.
- Content and audio
- Contribute to Ludus
- Create your first project
- Current capabilities
- Engine architecture map
- Foundation and jobs
- Glossary
- How Ludus fits together
- Install and launch
- Platform and rendering
- Public SDK API reference
- Reference reading paths
- Runtime and editor
- Startup and shutdown
- Terrain and generation
- Worlds and frame updates
Guides and workflows¶
- Benchmark scenes and system test suites
- Best-effort scene import (pbrt-v4, glTF 2.0, OBJ)
- Browser editor
- Browser smoke packaging and itch.io upload
- Build Profiling
- Build, run and debug
- Building Ludus
- Building the browser editor
- Checked drag and radial contact kernels
- Choose and use containers
- Code editor
- Continuous integration
- Filesystem measurements
- Game release setup, packaging and publishing
- Generated public SDK reference
- Hash bytes without confusing identity
- Independent Ludus game projects and shared SDKs — user guide
- LTC table fitting and accuracy
- Ludus Wiki: development and publication
- ludus-tools
- Memory Phase 0: Trace Prerequisites and Baselines
- Memory Phase 1: Domain Counters, Registry and Gauges
- Mobile support implementation plan
- Native debugging with RAD on Linux
- Native diagnostics and assertion policies
- Native editor workspace and troubleshooting
- Native game release packages
- Native gameplay live editing
- Own text and bind names
- Platform targets and compatibility
- Port Ludus to a new platform
- Public rendering: fullscreen and portable raster
- Read and publish files through the filesystem
- Runtime profiling
- Save, validate and build render graphs
- Troubleshooting
- Use deterministic randomness
- Use high-resolution time
- Vulkan and Wayland
Module usage¶
- FoundationIdentity
- FoundationLogging
- FoundationParsing
- FoundationProfiling
- FoundationThreading
- Gameplay world storage
- Graphics RHI
- Localization: catalogs, release cooking and formatting
- Ludus::FoundationGeometry
- Ludus::FoundationMath
- ShaderLanguage: the LUSL front end
- Unicode: pinned ICU4C host service
- World restore (two-pass)
Examples and probes¶
- Associative container benchmark
- Audio content sample
- Cook and capture staircase2
- Game world reference
- Ludus smoke application
- Packaged browser CI tests
- Shader feasibility probe
- W0 WebGPU feasibility probe
- W1 browser FoundationBase probe
- Your first rendered scene: Cornell box
Architecture and design¶
- Audio authoring and game integration
- Browser access to Ludus
- Camera systems architecture
- Code editor architecture: shaders, scripts and project text
- Container systems
- Content resources and loading
- CPU shallow-water field
- Curves and surfaces architecture
- Developer tools: RAD Debugger, code editors, and future scripting
- Drift game engine integration
- Engine configuration
- Engineering quality and CI architecture
- Entities and component storage
- Filesystem architecture
- Foundational Headers, Include Strategy, and the Ludus Core Vocabulary
- Frame and tick updates
- Game world architecture
- Gameplay foundation architecture
- Gameplay languages and visual authoring architecture
- Geometry content: authoring, cooking and loading
- Graphics debugging architecture and implementation plan
- High-resolution time
- Level data and loading
- Loading projects and editing games during play
- Low-level renderer systems architecture
- Ludus assertion subsystem design
- Ludus Core Containers — Static and Dynamic Array Design
- Ludus editor architecture
- Ludus editor interaction design
- Ludus game packaging and itch.io publishing
- Ludus game projects and shared engine SDKs
- Ludus Localization Architecture
- Ludus Memory Management Architecture
- Ludus Memory Profiling Architecture
- Ludus Parsing Architecture
- Ludus product and art direction
- Ludus Randomness Architecture
- Ludus RHI and Graphics Device Interface Architecture
- Ludus scene source format (
.luscene.json) - Ludus Shading Language (LUSL)
- Ludus Strings Architecture
- macOS Platform backend
- Module startup and shutdown architecture
- Multiplatform editor GUI systems
- Networking architecture
- Object handles and persistent UUID architecture
- Physics and fluid simulation for Drift
- Physics systems architecture
- Platform detection
- Primitive types and numeric boundaries
- Procedural content generation architecture
- Profiling Subsystem — Final Architecture (Reconciled)
- Reflection and serialization
- Render graph authoring, shader builds and pipeline management
- Render graph frame capture
- Resource manager architecture
- Runtime UI architecture
- S2: dependency cook, source debugging and transactional replacement
- S3: a visual encounter authoring workflow
- S4: installed native/Luau behavior provider and project cooking
- S5: Editor authoring, behavior debugging and GameHost generations
- S6: Behavior safety and platform qualification
- S7 reference performance and release acceptance
- Sequencer, cinematics and controlled image sequences
- Shared scene, material and lighting shader contract
- Skeletal animation architecture
- Smart pointer architecture
- Terrain generation architecture
- Terrain systems architecture
- Threading architecture
- Windows and Direct3D 12 backend
Decisions¶
- ADR 0001: CMake, Ninja, and Conan 2
- ADR 0002: Static Libraries as the Internal Default
- ADR 0003: C++ Standard Library and C Runtime Usage Policy
- ADR 0004: Type-Erase std::format at the Logging ABI Boundary
- ADR 0005: Build-Time Budgets Instead of Include-Hygiene Linting
- ADR 0006: Resumable Development Assertions (Continue Once)
- ADR 0007: The Foundational
core.hHeader and Include Boundary - ADR 0008: Explicit Memory Ownership with Measured Backend Selection
- ADR 0009: Browser WebGPU toolchain and feasibility probe
- ADR 0010: Bounded Slang shader-toolchain feasibility
- ADR 0010: FoundationMath Module Conventions and Contracts
- ADR 0011: bounded public fullscreen rendering
- ADR 0012: Separate GameHost and explicit gameplay replacement
- ADR 0013: Browser GLSL ES 3.00 shader toolchain (WebGL 2 backend artifact)
- ADR 0014: WebGL 2 backend and WebGPU -> WebGL 2 Auto startup fallback
- ADR 0015: Native primitive types and checked numeric boundaries
- ADR 0016: Target detection and runtime capability ownership
- ADR 0017: Shared monotonic time and explicit timer values
- ADR 0018: FoundationFilesystem and revision-bound reads
- ADR 0019: Bounded renderer-independent runtime UI core
- ADR 0020: Bounded CPU task graphs with an explicit serial executor
- ADR 0021: Bounded networking core and transport boundary
- ADR 0022: Bounded parsing foundation and JSON extraction
- ADR 0023: Editor presentation and portable document core
- ADR 0024: Curves and surfaces domains, statuses and numeric guarantees
- ADR 0025: Pin the native reference toolchain to LLVM 23
- ADR 0026: Adopt tree-sitter for code-editor syntax structure
- ADR 0027: Ludus Shading Language as a front end that emits Slang
Research and reviews¶
- Assertion adversarial review
- Camera systems reference review
- Configuration literature review
- CPU fluid field reference review
- Critical review: Squeezing More Out of Assert
- Curves and surfaces: Gems and research review
- Editor design reference review
- Editor GUI systems: design and reference review
- Engineering quality reference review
- Game world: Gems article review
- Gameplay foundation Gems review
- Historical profiling references: critical literature review
- Keyboard input: research and decision record
- Low-level renderer systems: reference review and research plan
- Ludus audio research and decisions
- Ludus editor reference reading guide
- Ludus Editor workspace research and design decisions
- Ludus Localization Literature Review
- Ludus logging: architectural review and engineering design
- Ludus math research and decisions
- Ludus Parsing Literature Review
- Ludus Randomness: Gems Review and Design Revisions
- Ludus Strings Literature Review
- Many-area-light resampling estimator review
- Memory Management: Independent Adversarial Design Review
- Memory Profiling: Game Development Reference Review
- Module lifecycle reference review
- Networking reference review
- Object handle and UUID reference review
- Physics and fluid simulation reference review
- Physics systems Gems and research review
- Procedural content generation Gems and research review
- Project live editing research and design revision
- Reflection and serialization: Game Development Gems review
- Resource manager reference review
- RHI and Graphics Device Interface Reference Review
- Scripting architecture Gems review
- Skeletal animation Gems review
- Smart pointer design and reference review
- Terrain Gems and research review
- Text/font rendering research and decisions
Plans and handoffs¶
- Assertion subsystem: repository reconciliation and implementation plan
- Audio content implementation milestones
- Codex handoff for audio content
- Fullscreen SDK handoff for Ludus-Sandbox
- Interactive development assertions: implementation plan and Kiro prompts
- Kiro handoff for independent Ludus game projects
- Kiro handoff for Ludus audio
- Kiro handoff for Ludus Editor workspace
- Kiro handoff for Ludus math
- Kiro handoff: build keyboard input
- Kiro handoff: build text and font rendering
- Kiro handoff: build the code editor
- Kiro handoff: project loading and editing during play
- Kiro handoff: revise and implement Ludus logging
- Shader-toolchain spike handoff
- WebGL 2 fallback and Drift handoff
- WebGL 2 fallback implementation handoff
- WebGPU browser export implementation plan
Validation and evidence¶
- Assertion startup / report-delivery — validation record
- Assertion subsystem: M0 + M1 implementation evidence
- Audio content implementation evidence
- Code editor decision log
- Curves and surfaces evidence (G0-G4)
- Evidence for the September 23, 2026 logging review
- First container-system increment: evidence
- FoundationMath evidence ledger
- FoundationTime validation
- Game packaging and publishing implementation evidence
- Game world validation
- Hosted acceptance and support record
- Keyboard input: implementation decision log
- Keyboard input: performance evidence
- L0: localization schemas, message profile and ICU backend probe
- Ludus audio decision log
- Ludus Editor workspace (E0) — implementation evidence ledger
- Memory Phase 0A: Aliased Array Resize
- Project live reload evidence
- Project SDK Workflow — Implementation Evidence Ledger
- Runtime UI validation
- S0: private Luau interpreter feasibility
- S1: generated native/Luau interaction
- Text/font rendering — audit findings (T01–T16 / F0–F6)
- Text/font rendering — F0–F2 native CPU results and environment report
- Text/font rendering — verified dependency and asset manifest (F0)
- Threading kernel validation and performance evidence
- W0 probe evidence and handoff
- W1 FoundationBase browser evidence
- W2 browser logging and profiling evidence
- W3 browser canvas and input evidence
- W4 RHI lifecycle evidence
- W5: WebGPU frames and rendering proof
- W6: Integrated browser smoke application
- W7: Reproducible browser smoke package
Historical baselines¶
- Milestone 0 Architecture
- Milestone 1 Architecture
- Milestone 2 Architecture
- Profiling Subsystem — Baseline Architecture & Design