Personal project / Engine architecture

Tessera Engine

A C++20/Direct3D 12 game engine in which every boundary has a verification mechanism and every decision is accompanied by evidence.

Tessera is the Windows game engine and editor I am developing as a personal project. I write the ECS, job system, asset pipeline and renderer. For tech leads and project leaders, this page explains each system’s responsibilities, the trade-offs I choose and the criteria I use to accept an implementation.

The documented survey dated October 12, 2026 records 819 C++ files, about 270,000 lines outside ThirdParty and 47 shaders. Two solutions in four configurations produce eight local builds with warnings treated as errors. These figures describe the project’s scale; the measurements below belong to the recorded scenarios, on this machine and in the documented builds. The repository is private.

  • C++20
  • Windows
  • Direct3D 12
  • ECS
  • DXR
  • Dear ImGui
  • Sharpmake
Editor overview with docking, viewport, hierarchy, inspector and Content Browser; this capture shows a scene with no cooked meshes loaded.

Overview

Small pieces, enforceable boundaries

Tessera takes its name from a piece of a mosaic. Each layer has one responsibility and a defined dependency direction. Simulation does not depend on rendering; the renderer builds a plan; the graphics backend translates that plan into GPU work. The editor consumes the same engine that it inspects.

The engine is a static library; the executable exports the Agility SDK’s D3D12SDKVersion and D3D12SDKPath. Simulation, planning and execution are separated by three complementary checks: a single ECS handoff to RenderScene, a render graph testable without a GPU and an entire solution without D3D12. The boundaries therefore have checks beyond folder conventions.

Architecture contracts

Patterns, alternatives and evidence

These patterns connect a decision to its implementation and to a check that can disprove it. Each name links to the detailed section; results describe documented tests, not guarantees for any scene or hardware.

The same policy guides simulation, GPU work and authoring: declare access, centralize derived values and make lifetimes explicit. I prefer a dependency the compiler can check to a rule that requires remembering every consumer.

PatternWhere it livesAlternative avoidedEvidence in the measured scenario
The renderer plans; the backend executesRender/RenderGraph / RHI/D3D12/DxRenderGraphExecutorA graph that records commands242 plan checks without a device.
A single ECS/render handoffRenderExtractionSystem to RenderSceneRenderer reading the live WorldAdding 100,000 entities without a mesh preserves instance counts and upload bytes.
Null backend as a build solutionTessera.NoD3D12.slnIsolation supported only by #ifdef or text searchesZero Dx*.obj objects in all four configurations of the solution without D3D12.
Generational handlesRHI/Handles.hA pointer or ComPtr in a componentNine handle tags; a PSO retired by hot reload causes a skipped draw, without a dangling reference.
Declared access and a hazard DAGSystemDescriptor, AccessAuditorLocks inside the ECSZero mutexes in ECS/; 32 systems: 0.68 µs at 10,000 entities and 0.86 µs at one million.
Deferred structural changesCommandBuffer, PlaybackCommandsMutating components during iterationIn the test, 1,000 entities produce one archetype transition.
Versions for dirty state; hashes for restorationTransformState, WorldSnapshotBoolean flags as the sole validity sourceIn the measured stationary frame, GPU Scene receives 0 upload bytes.
One producer per derived valueCanonicalCookedKey, ComputeSceneRectRecomputing identity or rectangles in each consumerA shared canonical key; a recomputed key caused a magenta scene in the recorded diagnostic.
Composition with explicit contextsDxFramePassContextA god class or inheritance-based extension85/85 virtual functions preserved across 12 verified module extractions.
Defaults preserve behaviorQualitySettings, EffectToggleApplying a quality profile without a requestWithout a flag, the acceptance comparison has 0 differing pixels out of 1,440,000.
Provenance and identity inside the dataPROV, IDNTAn external manifest or path-based identity102 ms scan versus 316 s recook in the measured project; UUID preserved in IDNT.
Instrument before accepting--*-probeTrusting a green build aloneA post-build verifier checks runtime DLLs and shaders; probes exercise individual features.
Current simulation-to-backend flow: single extraction, a plan without a GPU and Direct3D 12 execution. Conceptual diagram in English, without scene-specific pass counts.

Dependencies

Layered architecture

Responsibilities, interfaces and verifiable dependencies define the boundaries. SDL3 appears only under Platform/ and UI/; Direct3D headers stay in RHI/D3D12/. Render/ decides what to draw and produces the plan without recording GPU commands. ECS and Jobs include neither Render/ nor RHI/: source scans record zero includes of those layers. Scene registers rendering components and includes their headers, so it does not carry the same isolation claim.

Import and compression libraries belong exclusively to Tools/TesseraCooker. The runtime consumes cooked data without authoring dependencies. Tessera.NoD3D12.sln builds the engine and editor with a null backend and an SDL_Renderer interface. A D3D12 type crossing the boundary breaks that build; Debug, Development, Profile and Shipping produce zero Dx*.obj objects in the documented survey.

Engine dependency layers and the isolated Direct3D 12 boundary.

Simulation

A custom ECS built for scheduling

I studied EnTT and Flecs, then built an ECS around three requirements: declared read/write access, deferred deterministic structural changes, and world snapshots. An Entity is an eight-byte index and generation; the generation detects stale references. Disk persistence uses a UUID, StableEntityId, rather than a runtime handle.

Entities with the same component set live in archetypes, stored as contiguous SoA columns in 64 KiB chunks. At two million entities, 64 KiB required 1,482 pages versus 5,955 at 16 KiB, with the same bandwidth. Sparse sets hold rare components without multiplying archetypes. Shared-component tables keep one value per distinct configuration, referenced by the chunk.

Each SystemDescriptor declares reads and writes. The scheduler derives a dependency DAG and runs non-conflicting systems together. With 32 systems, measured scheduling overhead was 0.68 µs per frame over 10,000 entities and 0.86 µs over 1,000,000: this cost follows systems, not entity count.

Fixed frame phases define when input, simulation, physics, events, structural playback, transforms and render extraction occur. Creation, destruction and component changes go through CommandBuffer, applied at one deterministic point. A development access auditor detects undeclared writes and is compiled out in Shipping. Typed events, observers and a dedicated hierarchy store complete the model; versioned transform propagation avoids recalculating stationary nodes.

The rendering handoff is RenderExtractionSystem to RenderScene: the renderer consumes extracted data without consulting the live World for each draw. In the recorded probe, adding 100,000 entities without a mesh preserves instance counts and uploaded bytes. Structural changes are also batched: 1,000 entities produce one archetype transition in the playback test. A stationary frame uploads 0 bytes to GPU Scene; TransformState versions track changes and the WorldSnapshot hash checks restoration.

Snapshot replay reproduced 120 identical audit records over 120 frames on the same machine and build. That is the verified scope of determinism, and the foundation for editor Play/Stop; cross-platform determinism is not promised.

struct Entity
{
    uint32_t Index = InvalidEntityIndex;
    uint32_t Generation = 0;
};
static_assert(sizeof(Entity) == 8,
    "Entity is a chunk column; its size is layout.");
Archetype storage split into chunks with contiguous component columns.
ECS data structure: entity handles, archetypes and SoA storage.
ECS Diagnostics panel exposing the world and scheduling data.

Concurrency

Work stealing without blocking the frame

Each worker owns a Chase-Lev deque: it pushes and pops without a lock while idle workers steal from the other end. A worker waiting for a job executes other work on its current stack. The single-worker test checks that dependencies still progress. Threads outside the pool wait passively; allowing them to help would create two producers for a single-producer deque.

Jobs have AnyWorker, LongRunning or MainThread affinity. Separate counters track frame work and long-running work, so shader compilation cannot extend the frame wait. In the recorded comparison, the slowest frame during recompilation dropped from 803 ms to 18.75 ms. Per-worker FrameArena storage supports temporary allocation; ParallelFor over 1,048,576 elements produced the serial result with zero heap allocations.

A watchdog names the stalled stage, including runs with the editor window visible. Per-item stealing places the cost of finding work on the idle thread. In the recorded wide graph of real work, worker occupancy was 94.7%; the timeline connects that measurement to dependencies and the work actually executed.

The cooker uses the same system: compressing one 2048² texture took 311.8 s with one thread and 9.7 s with 24. Tracy and an editor timeline expose CPU/GPU activity and work per worker. These are specific project measurements, not general throughput guarantees.

Profiling timeline showing jobs by worker.
Editor profiling view with frame and timing information.

Persistence

One container, many chunks

Importing a source model means cooking it. A Tessera project stores engine formats and references the original through a named source root; it never copies the original into the project and rejects absolute source paths. This separates portable project data from the authoring files needed for a reimport.

The binary formats share a 64-byte header with magic, version, XXH3-128 content hash and chunk-table location. FourCC entries locate chunks aligned to 256 bytes. The runtime reads only the mip or LOD it needs. PROV records the source path and hash, cooker version and options; an unchanged-project scan took 102 ms versus 316 s for recooking. IDNT preserves the UUID across reimports.

A .tmesh contains an entire asset with internal submeshes: the buggy example turns 109 meshes into one file with 236 submeshes. SXFM stores per-piece transforms, allowing one wheel to be stored once and placed four times. In the measured collection, storage fell from 39.9 MB to 31.0 MB and draws from 342 to 229.

Optional chunks have defined absence behavior: without SXFM, the transform is identity. The compatibility policy allows adding PROV without changing the container version; SXFM requires a mesh version that still opens and renders older files. Evolving the format means explicitly deciding which readers and data must remain compatible.

Asset lifetime includes GPU release. CookedAssetLibrary::Clear calls DestroyMesh while the handles still identify the meshes, then ReleaseCookedTextures, before clearing local tables. CanonicalCookedKey centralizes derived asset identity; consumers reuse that key instead of producing variants that fail to find the same material.

FormatResponsibility
.tmeshMesh asset, submeshes and LODs
.ttexBC-compressed textures and mips; BC6H for HDRI
.tmatOpenPBR material
.tscn / .tpfb / .tcellLevel, prefab and streaming cell
.tprojJSON project descriptor, outside the binary container
Cooked mesh layout and the planned meshlet extension.
Cooked asset container: header, chunk table and payloads.
Asset Properties showing a cooked asset and its chunk structure.
Asset import interface and progress reporting.
Content Browser for engine-format assets.

Planned extension

Preparing the path to mesh shaders

Mesh shaders are not implemented in the renderer. The existing pipeline deliberately leaves the path open: canonical root-signature slots are visible to all stages, pipeline creation uses the pipeline state stream, DXC recognizes ms and as at Shader Model 6.5 or later, and capability detection queries GPU support.

A test successfully created a mesh-shader pipeline against the canonical root signature. That checks compatibility, not a shipping rendering path. meshoptimizer is selected but not integrated. The plan is for the cooker to generate meshlets into a new .tmesh chunk; older files will retain the traditional vertex path when that chunk is absent. The container and pipeline contracts are what make that extension possible.

GPU boundary

The renderer plans; the backend executes

IRenderBackend exposes no Direct3D types. Resources use generation-checked handles such as Handle<TextureTag> and Handle<MeshTag> to detect references to released objects. Render/ builds a GPU-independent plan; RHI/D3D12/ executes it. This makes planning testable without a device.

Nine handle tags separate resource categories, and generations validate lifetime. When hot reload retires a PSO, a draw still referencing it is skipped. A component does not need a pointer or ComPtr to a backend object; resource identity stays distinct from its Direct3D representation.

The backend defaults to Enhanced Barriers with a legacy fallback, and uses bindless Shader Model 6.6 with descriptor-table fallback. Its root signature occupies 13 of 64 DWORDs. A separate copy queue handles uploads; VRAM-budgeted streaming falls back to smaller mips under pressure, instead of dropping the scene. Shader hot reload rebuilds affected pipelines.

Multithreaded recording is selected where the workload justifies it. At 23,099 draws, measured CPU frame time dropped from 207–229 ms to 82–91 ms, a 2.3–2.8× improvement. The ordinary small frame deliberately keeps a single command list. Extra scheduling and recording machinery should earn its cost.

The render plan crosses an abstract interface before the D3D12 backend executes it.

Frame compilation

A render graph that produces a plan

A pass declares resource reads and writes, access types and GPU stages. The graph sees the whole frame and derives ordering and barriers from those declarations. It never records commands. The D3D12 executor reads the execution order and per-pass barriers, then records the corresponding work.

Compilation builds dependencies against the preceding last writer, rejects cycles with an empty plan, removes unused producers, selects queues, computes transient lifetimes and generates barriers where resource roles change. Exported resources and declared side effects preserve required work; simply importing a resource does not protect its producer from removal.

Use order and lifetime are distinct with optional compute: positions in the plan do not describe overlapping execution. The graph provides lifetime intervals; the heap owner chooses aliasing and requests aliasing barriers. My allocator packs by lifetime, the requirement that led me to reject the evaluated size-based D3D12 Memory Allocator approach. Eight deliberately staggered resources used 2,688 KB instead of 10,752 KB, a 4.00× reduction and the minimum for that test.

The supplied forward graph was exported from Sample.tscn on October 6, 2026. In that recorded configuration, 20 passes produce 15 barriers. Six disabled occlusion/ray-tracing passes only open empty scopes: a pass with no writes is not an unused producer and is not automatically removed. The highlighted SceneColor transition before ToneMapPass is inferred from its change from render target to shader read. Counts vary with the shading path and enabled effects.

Reset() clears frame data while retaining vector capacity; graph resource handles expire with it. Graphviz export and the editor panel expose the plan, while --rendergraph-self-test runs 242 checks without a GPU.

  1. Declare

    Import existing resources with their incoming state; create undefined transients; use AddPass to declare Read, Write or ReadWrite.

  2. Compile

    Export required end states, including present for the backbuffer. Compile() derives a dependency order, resource lifetimes and synchronization.

  3. Execute

    The backend consumes GetExecutionOrder() and GetBarriers() and emits GPU work. Planning remains independent of Direct3D 12.

Forward frame graph exported from Sample.tscn on October 6, 2026; the highlighted SceneColor transition is inferred by the graph.
Render Graph panel displaying passes and resource connections.

Rendering

Lighting with a reference for comparison

The renderer implements OpenPBR coat, anisotropy and fuzz, checked with a furnace test; image-based lighting, procedural sky and HDRI; cascaded shadows and clustered light culling. In the recorded culling test, 125× more lights cost 1.39×. Forward and deferred paths are interchangeable, with SSAO, bloom, histogram auto-exposure and transparency.

Inline DXR RayQuery provides soft shadows, ambient occlusion and traced reflections, with reflections limited to deferred rendering. A spatial-temporal denoiser and adaptive Low/High/Ultra budgets control the real-time effects. A reference path tracer measures their error. The captures show the sample scene and diagnostics; their visible counters describe those captures rather than a benchmark for every scene.

Motion vectors, jitter and reprojection in Render/TemporalReprojection.* already provide the temporal groundwork; TAA, motion blur and temporal upscaling remain planned extensions. QualitySettings and EffectToggle preserve default behavior without implicitly applying a profile. In the acceptance comparison without a flag, 0 of 1,440,000 pixels differ. Async compute is implemented and disabled by default: its roughly 2% gain in the recorded scenario is below the chosen 5% activation threshold.

Sponza sample scene rendered inside the Tessera editor.
Sample scene with the Ultra ray-tracing profile visible in the lighting panel.
Ray-tracing debug visualization in the editor.
Lighting controls and diagnostic values in the captured configuration.

Authoring

The editor uses the systems it exposes

Dear ImGui docking keeps the editor in C++, in the engine process. The Lobby opens a project without launching another application. The Content Browser has rendered thumbnails, a self-invalidating disk cache and background imports. Mesh/prefab windows provide GPU previews; the texture editor isolates channels and packs ORM. Asset properties expose the binary chunks directly.

Hierarchy, Inspector, ImGuizmo transforms, undo/redo, prefabs, tags and asset colours support scene work. The Material Graph is a read-only view derived from .tmat; its wiring is not editable. The graph widgets come from ImGuizmo’s GraphEditor.

Play, Pause, Stop and Simulate share the snapshot mechanism: Stop restores the captured world and verifies that its hash is identical. Authoring scenes use JSON for readable Git diffs and are cooked to binary for runtime. Profiling, Render Graph, ECS Diagnostics and Console make the running systems inspectable from the editor.

Asset editor with a GPU-rendered 3D preview.
Project Lobby at the editor entry point.
A second Content Browser view of the asset workflow.
Read-only Material Graph derived from material data.
Texture Editor with channel inspection controls.

Tradeoffs

Dependencies with a defined role

I write the engine-specific policies and use libraries for bounded problems. SDL3 access is restricted to Platform/ and UI/; IPlatformBackend bounds platform services. DirectXMath supplies SIMD mathematics across the engine; DXC compiles Shader Model 6.x HLSL. Dear ImGui and ImGuizmo supply interface primitives rather than a second managed editor stack.

cgltf, ufbx and my OBJ importer remain inside the cooker. I chose open-source ufbx over the FBX SDK for its triangulation; mikktspace matches tangent conventions used by art tools. Among the evaluated compressors, AMD Compressonator gave the preferred BC7 quality. stb_image and tinyexr decode images/HDRI; xxHash identifies cooked content; nlohmann/json preserves key order for stable text diffs.

Tracy supplies CPU/GPU timelines, and WinPixEventRuntime names GPU passes in PIX. vcpkg pins dependency versions by manifest baseline. Before adding a dependency I review its component licence at the official source, with a preference for open source.

Backend organization

Modules with explicit lifetimes

Backend features have three parts: resources that live for the device lifetime, a FrameState aggregate reset by a single declaration and free functions receiving (Feature, FrameState, Context). Persistent and transient state have distinct owners; resetting a frame does not depend on a list of flags scattered through the backend.

Initialization contexts are specific to each feature. For pass recording, DxFramePassContext supplies resources borrowed from the frame. Free functions do not name DxRenderBackend: they can reach only what their arguments expose. ComputeSceneRect centralizes rectangle computation, distinguishing output from rasterization; each pass uses the resolved value to keep viewport, picking and composition consistent.

Acceptance combines a preserved interface, self-tests and visual comparison. The record of 12 module extractions preserves all 85 interface virtual functions, self-test results and 0 differing pixels in the comparison scene. The documented survey records 11,116 lines in DxRenderBackend.cpp. These results support the isolation method; they do not claim that every execution is defect-free.

  1. Device

    The feature owns persistent resources and receives its own initialization context.

  2. Frame

    FrameState aggregates transient state and resets it in one operation.

  3. Execution

    Free functions receive feature, state and context; the signature bounds their access.

Backend feature composition: device-lifetime resources, frame state and free functions with context-bounded access. Conceptual diagram in English.

Validation

Builds and comparisons as design constraints

Sharpmake defines IDE and command-line builds through the same generator. Together with the vcpkg manifest baseline, it produces two solutions in Debug, Development, Profile and Shipping: eight local builds, all treating warnings as errors. Post-build verifiers check runtime DLLs and mirrored shader trees, because compilation and linking do not prove that required resources will be present at runtime.

Headless subsystem tests include 4,883 ECS checks, 242 render-graph checks and 837 cooker checks. Command-line probes exercise individual features; a benchmark harness compares timings and counters against a baseline. Image diffs against the preceding version require zero different scene pixels for the refactor acceptance checks described here.

Those numbers come from the project records used for this case study. They document the validation method and measured scenarios, not a fresh execution of the private repository by this website. Together, the alternate build, replay audits and image comparisons check different failure modes that a successful normal build alone would miss.

Next steps

Implementation direction and current limits

Meshlets and mesh shaders are the next rendering steps. The plan is to generate meshlets in the cooker and store them in an optional .tmesh chunk, preserving the traditional path for assets without it. The pipeline compatibility test exists; the mesh-shader rendering path is not implemented yet.

I intend to use the existing motion vectors, jitter and reprojection as groundwork for TAA, motion blur and temporal upscaling. Global illumination remains planned. Async compute is already optional, with activation conditional on measured benefit; its default configuration stays disabled.

Jolt Physics, miniaudio, GameNetworkingSockets and Recast & Detour are selected dependencies, not integrated systems. An authoritative server for 16 players is a goal; replication-scoped snapshots and the precision measurement for worlds up to 200 km² are design groundwork, not evidence of working networking. Windows is the only supported platform. Determinism was verified on the same machine and build; CI and cross-platform determinism remain outside the validated scope.

Contact

Québec City, QC, Canada / Available for opportunities

I'm open to opportunities in software development, tools programming and gameplay programming, as well as junior 3D artist roles. If my experience could be a good fit for your team, I'd be happy to connect through my social profiles.