Mainframe Engine — Documentation

Design documentation for Mainframe Engine. The current-state docs describe the engine exactly as it exists in the code today (including its known bugs). The future docs are design proposals for work that has not started yet. milestones.md ties the two together.

Status: M0–M10 complete (v1.0.0 line, 2026-10-05); M11–M13 are proposals. When code changes, update the matching doc and its Known issues section in the same commit.

Start here

Doc	What it covers
Milestones	Roadmap: what is done ✅, what is next, links to every design doc
Architecture overview	Layers, assemblies, dependencies, who owns what
Engine lifecycle	Startup, the per-frame loop, shutdown

Current-state design docs

Area	Doc
Build & release	Build & platforms · Release & versioning · Distribution via NuGet (the MainframeEngine package) · Future: mobile (M12) · Future: consoles
Core	Engine lifecycle · Scene graph & nodes · Scene serialization · Physics · Localization · Demo
Games & editor	Projects & GameHost (project.mfproj, GameHost, editor link, code reload, mfgame template) · Editor · Future: editor
Rendering	Vulkan renderer · 2D canvas · GPU resources · Materials & meshes · Asset pipeline · Color pipeline · Post-processing · Shadow system · Lighting · Sky · Spine · Scene grid · Cameras & input · Shaders · Coordinate conventions
UI	Game UI (RmlUi) · Native libraries
Tooling	Developer overlay & gizmos · Testing · Docs site (just docs, GitHub Pages)
Audio	Audio
Online	Networking · Steamworks

Future design proposals

Located in design/future/. Each one has: Problem · Goals / Non-goals · Proposed design · Diagram · Task list · Open questions. See milestones.md for order.

Proposal	Milestone
Editor, after M10: remote scene tree, simulate mode, box selection, docking	after M10
Rendering backend abstraction (D3D12, WebGPU)	M11
Mobile core (Android + iOS): platform layer, lifecycle and safe areas, TBDR rendering and quality tiers, touch/gestures/virtual controls, ASTC/KTX2 asset cooking, AOT and size budgets, editor deploy and live preview, store pipeline	M12
Mobile platform services: IAP, achievements/leaderboards/cloud saves, consent + ads, notifications, analytics/crash reporting via mfplatform shims	M13
Consoles (PS5 + Xbox Series): public readiness (M11 shaped for D3D12 and a console API, NativeAOT, platform seams, console-ready checklist), private ports after program access	—
Terrain: Terrain3D, Faceted and Realistic profiles, Terrain dock, MultiMesh scatter	G8a
Procedural trees: Ez Tree port, LowPoly and Realistic styles, wind, impostors	G8b
Water: ponds and lakes, River3D streams, WaterMaterial3D	G8c
Forest showcase: Examples/Forest, a first-person forest walk, and the rendering it needs	G8d
Forest visual quality: the Unreal look in eight phases (probe GI, shadows, volumetrics, post, Ez Tree foliage, water, art, upscaling)	G8e
2D skeletal animation: engine-owned Spine-style rigs and clips, compute skinning, Spine JSON import · Skeleton editor · Animation graph	G17

Conventions

• One topic per file. Cross-link instead of duplicating.
• Diagrams: Mermaid for graphs embedded in markdown (sequence, class, flow, gantt). SVG in images/ for detailed graphics (memory layouts, descriptor tables, timelines, coordinate spaces). SVGs carry an opaque light background so they read on dark themes too. In a sequenceDiagram, write #59; for a ; in message text (a bare ; ends the statement).
• Source links are relative (../../MainframeEngine/Src/...) so they work on GitHub and in IDEs; the docs site rewrites them to GitHub URLs.
• Known issues cite file:line at the snapshot commit. Issues found by reading code but not reproduced at runtime are marked (inferred).
• Status legend (milestones): ✅ done · 🚧 in progress · ⬜ planned.