Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

24.7 KB
Raw Blame

Estella Architecture

This document describes the architecture and design decisions of the Estella game engine. It is descriptive of the current code. For the target architecture, the root-cause rationale behind the current design, and the forward roadmap, see the architecture-of-record companions:

  • REARCHITECTURE.md — root-cause re-architecture: RC1–RC5 (correctness), F1–F4 (foundation), RC6 (assets), RC11 (networking).
  • REARCH_2D_PARITY.md — 2D feature-parity / modernization roadmap (local, gitignored).
  • REARCH_WGSL.md — WGSL / WebGPU backend campaign (local, gitignored).

Overview

Estella is a game engine with a TypeScript SDK driven by a C++ core. Its world is three-dimensional — Transform is a vec3 position, a quaternion and a vec3 scale, and a flat game is the corner of that space where z is 0 and the camera is orthographic. It ships through two hosts built from the same core:

  • wasm (Emscripten) for the web, WeChat MiniGames and single-file playable ads, rendering through WebGL2 or WebGPU.
  • native (native/) for desktop, Android and iOS — the same C++ compiled ahead of time against an embedded Dawn (Metal / Vulkan), with the same SDK bundle driving it on QuickJS. Not a WebView.

The visual editor is a separate, private product, mounted at desktop/ as an optional submodule. Nothing in this repository requires it to exist: the engine builds, tests, gates and verifies its own renderer without a checkout.

The architecture rests on two non-negotiable principles (see REARCHITECTURE.md):

  1. Single source of truth — a given fact (memory layout, type id, enum value) is defined once. Cross-boundary layout is generated by EHT and enforced with compile-time static_assert + a runtime ABI-hash handshake; drift is a build or startup failure, never silent corruption.
  2. One channel per abstraction — GfxDevice for the GPU, a single SparseSet for component storage, WasmBridge for the WASM boundary, per-App resources for subsystem state. Bypassing an abstraction should fail to compile or fail a CI guard.
┌──────────────────────────────────────────────────────────────────────┐
│  TypeScript SDK  (sdk/src)                                            │
│  App · World · Schedule · Plugins · Query/Commands/Res/Events         │
│  render submit · physics(2D) · physics3d · ai/nav · skeletal ·        │
│  tilemap · ui · audio · scene · prefab · net · postprocess · video    │
└───────────────┬──────────────────────────────────────────────────────┘
                │  one boundary, one generated layout (EHT: offsets, enums, ABI hash)
                │  wasm: WasmBridge + embind        native: QuickJS `es_*` bindings
┌───────────────▼──────────────────────────────────────────────────────┐
│  C++ core  (src/esengine)                                             │
│  Registry (SparseSet) · RenderFrame → GfxDevice · ResourceManager     │
│  particle · tilemap · text · animation · math · platform              │
└───────────────┬──────────────────────────────────────────────────────┘
                │  GfxDevice — the only GPU door
      ┌─────────┴──────────┬─────────────────────┐
   GLDevice           WebGPUDevice          WebGPUDevice
   (WebGL2)           (browser WebGPU)      (embedded Dawn → Metal/Vulkan)
   └── wasm host: web · WeChat · playable ──┘   └── native host: desktop/iOS/Android

On the wasm host these are side modules — wasm of their own, fetched only by a project that uses one: Box2D (2D physics), Jolt or PhysX (3D physics), Spine, DragonBones, Basis/KTX2, video. The native host links them in instead, since there is no download to defer. pipeline/ (@estella/pipeline) cooks a project into a shipped build with no window and no editor; editor-api/ is the plugin type surface, so a plugin author builds against the contract without private code. Each side module with a game-facing API has a subpath entry of its own — esengine/physics and esengine/physics3d hand a game the plugin, the world resource and the contact events; the components reach the main entry either way.

Core Modules (src/esengine/)

Core (core/)

  • Types.hpp — base types (u32, f32, Entity), and the domain-scoped TypeId system. Instead of one global getTypeId<T>() counter shared across unrelated concerns, each domain (ComponentDomain, EventDomain, ServiceDomain, ResourceDomain) has its own dense, 0-based sequence (Types.hpp:189-219). Component ids stay dense, so they index the pools_ vector and the per-entity component bitmask without waste or overflow (RC4).
  • Log.hpp — leveled logging. Note: ES_ASSERT compiles out in release; boundary validation that must always run does not rely on it (RC3).
  • PackedId.hpp — entity index/generation packing.
  • Engine / Application — engine singleton, version, lifecycle hooks.

ECS (ecs/)

Entity-Component-System inspired by EnTT, with a single storage core (RC2).

┌──────────────────────────────────────────────────────────────┐
│                         Registry                              │
│  Entity management: create() / destroy() / valid()           │
│  Component pools: one SparseSet<T> per component type         │
│  Single destroy path: mask-driven, no parallel storages       │
└──────────────────────────────────────────────────────────────┘

SparseSet — the one storage core

There is exactly one component-storage implementation. The earlier parallel DynamicComponentPool / SchemaComponentPool were dead/near-dead code and were deleted (RC2); JS zero-copy access already read the typed pool's pointer directly.

class SparseSetBase {
    virtual u32 version() const = 0;   // pointer-staleness generation
};

template<typename T>
class SparseSet : public SparseSetBase {
    std::vector<Entity> sparse_;     // Entity → dense index (paged)
    std::vector<Entity> dense_;      // dense index → Entity
    std::vector<T>      components_;  // contiguous component data
    u32 version_;                    // bumped on realloc/relocate
    u32 version() const override { return version_; }  // SparseSet.hpp:370
};
  • O(1) add / remove / lookup; cache-friendly dense iteration; swap-and-pop delete.
  • version() (SparseSet.hpp:97,370) is the single source for pointer invalidation: it increments whenever the component buffer reallocates (emplace growth) or relocates (remove swap-pop, sort/rebuild). It is the guard any caller that caches a cross-boundary pointer must re-check.

Views / Queries

registry.view<A, B>() iterates entities holding all requested components, filtered via the per-entity component mask. The SDK exposes this as Query(...) with Mut, change-detection, and resource/event parameters.

Renderer (renderer/)

Compiled to WASM. There is one rendering path: the legacy Renderer / BatchRenderer2D classes were removed. Everything goes through RenderFrame, and all GPU access goes through GfxDevice — a backend-agnostic RHI. Two concrete backends now sit behind it: GLDevice (WebGL2) and WebGPUDevice (Dawn/WebGPU), chosen at the platform edge with no #ifdef in the renderer above. Shaders carry a source language (GfxShaderSource); .esshader / material-graph / built-in programs emit both GLSL ES 300 and WGSL twins, and cook-time tooling auto-twins user GLSL to WGSL. The two backends are pixel-verified against each other in CI on every push.

┌──────────────────────────────────────────────────────────────┐
│  RenderFrame  (per-frame orchestration, frustum cull, stats)  │
│      │ collects RenderItems via typed RenderTypePlugins:      │
│      │   BatchPlugin · SpritePlugin · ParticlePlugin ·        │
│      │   ShapePlugin · TextPlugin · TilemapRenderPlugin ·     │
│      │   UIElementPlugin                                      │
│      ▼                                                        │
│  DrawList  (sort + coalesce; multi-texture batch; u32 index)  │
│      ▼                                                        │
│  GfxDevice  (the render backend boundary / RHI)               │
│    ├── GLDevice     : public GfxDevice   (WebGL2)             │
│    └── WebGPUDevice : public GfxDevice   (Dawn/WebGPU)        │
│  Shader · Texture · Buffer · Framebuffer · CustomGeometry     │
│  all take GfxDevice&; no raw gl* outside GLDevice (CI-guarded)│
└──────────────────────────────────────────────────────────────┘

Key facts:

  • GfxDevice (GfxDevice.hpp) speaks in typed handles and descriptors, not GL concepts: resources are created from BufferDesc / TextureDesc / FramebufferDesc / VertexLayoutDesc and addressed as BufferHandle / TextureHandle / ShaderHandle / FramebufferHandle / VertexLayoutHandle (on GL a handle's value is the GL id — zero cost). There is no bind-target buffer protocol (updateBuffer / resizeBuffer act on the handle) and no VAO in the interface — the vertex layout is part of PipelineDesc, buffers bind per draw via setVertexBuffer(slot, buffer, offset) / setIndexBuffer, and GLDevice keeps one lazily re-pointed VAO per layout as a backend cache.
  • Immutable pipelines + render passes: every draw path binds a cached PipelineHandle (program + vertex layout + blend + depth + stencil mode + culling; PipelineState.hpp); framebuffer targeting and clears are beginRenderPass(RenderPassDesc) / endRenderPass with load-op clear semantics. The only dynamic state outside the pipeline is the scissor rectangle and the stencil reference — mirroring WebGPU's split. The loose blend/depth/stencil/cull setters are private to GLDevice. Per-frame / material / light constants live in UBOs at fixed binding slots (setUniformBuffer, the future BindGroup seam); loose setUniform* survives for the custom-mesh and post-process shader paths. A CI guard (tools/check-gl-boundary.mjs) rejects raw gl* calls outside GLDevice.cpp; a MockGfxDevice harness exercises the contract headlessly.
  • DrawList sorts and coalesces draw commands, merging up to 8 textures per call; indices are u32 (no >65535 vertex wraparound). A per-layer y-sort mask (opt-in via project settings) packs a 24-bit order-preserving world-Y into the sort key so lower-on-screen entities paint on top (top-down occlusion); painter's order deliberately beats batching inside a y-sorted layer, every other layer keeps its key bit-for-bit.
  • Pointing at something is a ray. uiHitTest_update takes the world ray a screen point names, not a point on z = 0: UI nodes and sprites resolve it against their own plane, MeshRenderer against its oriented bounds, and world content ranks by distance along the ray with the sorting layer breaking the tie a flat scene produces. Orthographically every plane gives the same x/y, so a flat game picks exactly as it did.
  • RenderFrame owns transient buffers (TransientBufferPool), frustum culling, render-to-texture (RenderTarget, which a Camera.renderTarget now names), masking (RenderFrameMask: scissor + stencil), optional post-processing (PostProcessPipeline, ping-pong FBOs), material UBOs (MaterialStore), skinning palettes (SkinConstants) and lighting (LightStore / LightConstants). ImmediateDraw provides debug/shape primitives on the same buffers.
  • Lighting is one model, not a flat one and a solid one. Up to MAX_LIGHTS = 16 dynamic lights reach the GPU as one GpuLight record, read by both the flat model (applyLighting2D) and PBR (applyLightingPBR) under the single Lit shader domain — Lit2D / Unlit2D are still read as Lit / Unlit, normalized at the parser, because a .esshader carries no version to migrate by. Shadows are a tiled atlas (ShadowAtlas, MAX_SHADOW_TILES): a spot resolves one cone, a point light six faces (SHADOW_CUBE_FACES), a sun up to MAX_SHADOW_CASCADES = 4 cascades, with a real penumbra from Light.shadowSoftness / sourceAngle. 2D shadows are a second target, not a tile: the edges of every ShadowCaster2D are drawn as what they hide from each casting light into a screen-sized mask, one channel per light (MAX_SHADOW_2D_LIGHTS = 4), and a lit fragment reads its own channel. Drawn rather than solved, so a scene holds as many occluders as it has walls.

Resource pipeline (resource/)

  • ResourceManager / ResourcePool — reference-counted GPU resources with a three-state lifecycle (Held → Evictable → Evicted). An intrusive LRU list plus a byte budget (setTextureBudget) evicts the oldest unreferenced entries when resident bytes exceed the budget. Textures loaded through the SDK carry a path identity (residency key), so a released texture is retained evictable and the next load revives it via acquireTextureByPath instead of re-decoding; hot reload severs the identity (invalidateTexturePath) so stale bytes are never revived. The SDK owns the asset-level refcount (one pool reference per cached texture); the pool owns residency. Surfaced to TS as setTextureBudget(bytes) / getResourceStats(), with a default budget from RuntimeConfig.textureCacheBudget applied at engine init. Decoded audio buffers mirror the same lifecycle SDK-side (AudioAPI retain/release + byte-budgeted warm cache, RuntimeConfig.audioCacheBudget). OS memory warnings (wx.onMemoryWarning via the platform adapter) trim both warm caches (trimTextureCache / AudioAPI.trimBufferCache) without touching held resources.

Other C++ subsystems

particle/ (CPU simulation, GPU-instanced rendering, simulated in three axes and drawn on a billboard that faces the viewer), tilemap/, text/ (SDF/glyph), animation/, data/, math/ (glm-backed), platform/.

SDK / engine boundary (sdk/src/)

The SDK is the authored surface: defineComponent, defineSystem, Query, Commands, Res, events, Schedule, and Plugin-based composition (App). Subsystems (asset, physics, physics3d, ai — FSM / behaviour tree / perception / navigation, skeletal, spine, dragonbones, tilemap, ui, audio, video, scene, prefab, camera, particle, trail, postprocess, timeline, net) are plugins.

  • One WASM boundary: WasmBridge<M> (sdk/src/WasmBridge.ts:57) is the single base class — one loader, one ready promise, one missing-binding policy, one error path, with an abort guard. CoreApiBridge, PhysicsBridge, and SpineModuleBridge all extend it (F2). The five ad-hoc bridge styles described in REARCHITECTURE.md have been consolidated here.
  • Generated layout, no hand mirrors: EHT (tools/eht) generates embind, pointer accessors, the TS component layout, cross-boundary enums, and the ABI layout hash. C++ carries static_assert(offsetof==N) for every component field; the bridge compares the ABI hash on connect() and refuses to start on mismatch (RC1).
  • Lifecycle/error model: -fno-exceptions in C++ + explicit status at the boundary + a fatal onAbort death flag (moduleHealth.ts); transient _malloc is RAII-scoped via withScratch() (RC3).
  • Per-App state (F3): Camera (CameraView), Timeline, PostProcess, and SpriteAnimator are per-App/per-World resources, so isolated realms (e.g. the editor's play realm) never alias process-global state.

Platform Integration

JavaScript (SDK)                 C++ (WASM)
   es_init(w, h) ───────────────►
   requestAnimationFrame ◄────────
   update(dt) ──────────────────►   World.systems → Registry
   render() ────────────────────►   RenderFrame → GfxDevice
  • Web/Emscripten — WebGL2 or WebGPU context, HTML5 events, canvas management.
  • WeChat MiniGame — a platform adapter (sdk/src/platform/wechat) wraps wx.* APIs (WXWebAssembly, sync file I/O, storage, a dedicated audio backend) behind the same PlatformAdapter interface used by web. The wechat and playable variants carry the GL backend only, so neither pays for WebGPU glue it cannot use.
  • Playable ad — one self-contained HTML file; assets are inlined and reached through the same logical-path resolution every other export uses.
  • Native (native/) — desktop, Android and iOS. The engine C++ is compiled ahead of time and renders through an embedded Dawn (Metal on iOS, Vulkan on Android); the game runs on QuickJS-ng driving the real SDK bundle (dist/index.native.bundled.js), so what boots is an editor export, not a parallel content path. One host with a platform seam (eshost::Platform), not one host per OS. Dawn and QuickJS are fetched, not vendored, and nothing here is compiled by the web build.
  • Node — esengine/node runs the same wasm and the same gameplay code with no DOM, for an authoritative headless server (see Networking).

Both hosts reach the C++ through one generated layout. On wasm that is embind plus the EHT pointer accessors; natively it is a QuickJS es_* surface whose per-component half (es_set_<C>, es_<C>_buffer, _has, _remove) is generated from the same reflection, with only what cannot be generated — the registry surface, which the web build reaches as an embind class — hand-written.

Scene Management (SDK)

SceneManager is a resource over the single ECS World. Scenes share one World; entities are tagged with SceneOwner to track ownership. The render path filters cameras and draw callbacks by active scene; scene systems are gated to run only when their scene is running. sceneManagerPlugin runs the transition update each frame. Prefabs expand to tagged entities on load and collapse on save, using the same expand/collapse core in the SDK as the editor.

Networking (SDK)

Multiplayer is server-authoritative state replication (RC11), built as an ordinary plugin over the existing schedule — no second tick loop. Which fields replicate is a single source of truth: EHT emits replicatedFields from C++ annotations and defineComponent accepts them for user components, so the wire schema is derived, not hand-mirrored. State travels as per-field binary delta frames; spawn/despawn reuse the scene-serialization primitives (so late joiners get current state for free). Entity handles never cross the wire — a NetId map does. NetChannel adds a typed message/RPC layer over the raw socket; sockets are created through PlatformAdapter.createSocket. Snapshot interpolation, client input upload, and ownership (Replicated.owner) round out the client side.

The same wasm and gameplay code runs headless on Node via the esengine/node entry (createHeadlessApp + runHeadless): a Node platform adapter (filesystem assets, global WebSocket, NullAudioBackend, no DOM). The editor's Play mode drives 1–4 players in-process by wiring realms over a MessagePortTransport — the same NetSession stack shipping games use, exercised with zero network.

Performance Considerations

  1. Component iteration — views touch only matching entities; dense arrays.
  2. Memory locality — components stored contiguously in SparseSet.
  3. Batching — DrawList sorts + coalesces; multi-texture per draw; u32 index.
  4. Minimal allocations — entity recycling, transient buffer pools, RAII scratch.
  5. Eviction — ResourcePool LRU + byte budget bounds VRAM.

Extension Points

  1. Custom components — any registered struct (ES_COMPONENT/ES_PROPERTY).
  2. Custom systems / plugins — defineSystem + App.addPlugin.
  3. Custom shaders / materials — GLSL with reflected #pragma param UBO layout.
  4. Custom render types — implement a RenderTypePlugin.
  5. Platform adaptation — implement PlatformAdapter.

Status / Future Improvements

The correctness and foundation campaigns are complete. Landed:

  • RC1–RC5 (correctness root causes): generated layout + ABI handshake (RC1), single storage core (RC2), always-on C++ boundary validation via boundarySpan (RC3), domain TypeIds (RC4), single render path + GfxDevice + u32 index (RC5).
  • F1–F4 (foundation): the platform seam (F1) was recorded in 2026-07 as "closed by deletion — a pure Emscripten target", and that is no longer true: native/ builds the same core ahead of time against an embedded Dawn for desktop, Android and iOS. The seam is real and load-bearing again, and the gate check-native-build compiles the engine off emscripten before a push. Single WasmBridge base class (F2); per-App resources (F3); this document is the F4 rewrite, re-baselined here for the 3D / two-host / two-backend reality.
  • RHI modernization + WGSL/WebGPU: GfxDevice is a backend-neutral RHI with a real WebGPUDevice beside GLDevice; dual-backend pixel verification runs in CI on every push.
  • RC6 / T1 (asset delivery): WeChat subpackages (folder convention), Assets.loadGroup/loadByLabel/preload, cook-time auto-atlas, import-time KTX2 compression, texture + audio residency with SDK-exposed VRAM budget + LRU.
  • RC11 (networking): server-authoritative replication + headless Node server.
  • T2/T3/T4 parity, landed: animation state machines + 1D blend + Spine driver; shadows (hard/soft/directional) + normal maps + extended post-processing (color grade, tonemap, FXAA, distortion, pixelate, LUT); pixel-perfect camera + 4-renderable parallax + per-layer y-sort; SDK math library; i18n; save versioning; hex tilemaps; Tiled object layers; single .tmj parser.
  • The third dimension (0.52–0.56): Transform is vec3 + quaternion; MeshRenderer draws imported glTF with GPU skinning, PBR, an environment probe and a sky; a Light casts spot cones, point cubes and sun cascades into one shadow atlas; particles simulate and billboard in three axes; navigation bakes a polygon navmesh (areas, links, doors, agent avoidance) beside the flat grid; 3D physics is a side module on Jolt or, per project, PhysX — one physics3d_* interface, two implementations (RigidBody3D + box/sphere/capsule/mesh colliders, joints, character controllers). Light2D / Mesh2D dropped the plane from their names (they are the only light and the only mesh renderer); ShadowCaster2D keeps it, because it shadows what has no mesh to rasterize. Physics is the one place where two worlds really do exist, so both are named for their plane, components and subsystem surface alike: RigidBody2D, the six *Collider2D shapes, Physics2D, Physics2DPlugin, Collider2DShape, beside RigidBody3D, Physics3DPlugin and Collider3DShape. Neither set owns the bare name. Two things deliberately keep it: BodyType, shared because a body is static, kinematic or dynamic in either world (and now in a header of its own rather than the flat one's, which is where the 3D component used to reach for it), and PhysicsWasmModule / loadPhysicsModule, which name the side module physics.wasm rather than a world.

Remaining capability work (see REARCH_2D_PARITY.md, gitignored):

  • T2 — editor keyframe/curve editing UI; particle visual editor; native 2D skeletal rig (own project).
  • T3 — GPU particles / trails (transform-feedback or compute).
  • T4 — one-way platforms + remaining Box2D joints; editor multi-atlas painting; tile-gid objects in tilemaps.
  • Two pixel gates still run on one backend: camera-render-target (a frame holding both an offscreen and a surface pass returns nothing from the WebGPU readback) and device-loss. The other 121 assert on both.