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.
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):
- 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. - One channel per abstraction —
GfxDevicefor the GPU, a singleSparseSetfor component storage,WasmBridgefor 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 globalgetTypeId<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 thepools_vector and the per-entity component bitmask without waste or overflow (RC4). - Log.hpp — leveled logging. Note:
ES_ASSERTcompiles 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 fromBufferDesc/TextureDesc/FramebufferDesc/VertexLayoutDescand addressed asBufferHandle/TextureHandle/ShaderHandle/FramebufferHandle/VertexLayoutHandle(on GL a handle's value is the GL id — zero cost). There is no bind-target buffer protocol (updateBuffer/resizeBufferact on the handle) and no VAO in the interface — the vertex layout is part ofPipelineDesc, buffers bind per draw viasetVertexBuffer(slot, buffer, offset)/setIndexBuffer, andGLDevicekeeps 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 arebeginRenderPass(RenderPassDesc)/endRenderPasswith 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 toGLDevice. Per-frame / material / light constants live in UBOs at fixed binding slots (setUniformBuffer, the future BindGroup seam); loosesetUniform*survives for the custom-mesh and post-process shader paths. A CI guard (tools/check-gl-boundary.mjs) rejects rawgl*calls outsideGLDevice.cpp; aMockGfxDeviceharness exercises the contract headlessly. DrawListsorts 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_updatetakes the world ray a screen point names, not a point on z = 0: UI nodes and sprites resolve it against their own plane,MeshRendereragainst 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. RenderFrameowns transient buffers (TransientBufferPool), frustum culling, render-to-texture (RenderTarget, which aCamera.renderTargetnow names), masking (RenderFrameMask: scissor + stencil), optional post-processing (PostProcessPipeline, ping-pong FBOs), material UBOs (MaterialStore), skinning palettes (SkinConstants) and lighting (LightStore/LightConstants).ImmediateDrawprovides 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 oneGpuLightrecord, read by both the flat model (applyLighting2D) and PBR (applyLightingPBR) under the singleLitshader domain —Lit2D/Unlit2Dare still read asLit/Unlit, normalized at the parser, because a.esshadercarries 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 toMAX_SHADOW_CASCADES= 4 cascades, with a real penumbra fromLight.shadowSoftness/sourceAngle. 2D shadows are a second target, not a tile: the edges of everyShadowCaster2Dare 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 viaacquireTextureByPathinstead 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 assetTextureBudget(bytes)/getResourceStats(), with a default budget fromRuntimeConfig.textureCacheBudgetapplied at engine init. Decoded audio buffers mirror the same lifecycle SDK-side (AudioAPIretain/release + byte-budgeted warm cache,RuntimeConfig.audioCacheBudget). OS memory warnings (wx.onMemoryWarningvia 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, andSpineModuleBridgeall extend it (F2). The five ad-hoc bridge styles described inREARCHITECTURE.mdhave 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++ carriesstatic_assert(offsetof==N)for every component field; the bridge compares the ABI hash onconnect()and refuses to start on mismatch (RC1). - Lifecycle/error model:
-fno-exceptionsin C++ + explicit status at the boundary + a fatalonAbortdeath flag (moduleHealth.ts); transient_mallocis RAII-scoped viawithScratch()(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) wrapswx.*APIs (WXWebAssembly, sync file I/O, storage, a dedicated audio backend) behind the samePlatformAdapterinterface 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/noderuns 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
- Component iteration — views touch only matching entities; dense arrays.
- Memory locality — components stored contiguously in
SparseSet. - Batching —
DrawListsorts + coalesces; multi-texture per draw; u32 index. - Minimal allocations — entity recycling, transient buffer pools, RAII scratch.
- Eviction —
ResourcePoolLRU + byte budget bounds VRAM.
Extension Points
- Custom components — any registered struct (
ES_COMPONENT/ES_PROPERTY). - Custom systems / plugins —
defineSystem+App.addPlugin. - Custom shaders / materials — GLSL with reflected
#pragma paramUBO layout. - Custom render types — implement a
RenderTypePlugin. - 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 gatecheck-native-buildcompiles the engine off emscripten before a push. SingleWasmBridgebase 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:
GfxDeviceis a backend-neutral RHI with a realWebGPUDevicebesideGLDevice; 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
.tmjparser. - The third dimension (0.52–0.56):
Transformisvec3+ quaternion;MeshRendererdraws imported glTF with GPU skinning, PBR, an environment probe and a sky; aLightcasts 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 — onephysics3d_*interface, two implementations (RigidBody3D+ box/sphere/capsule/mesh colliders, joints, character controllers).Light2D/Mesh2Ddropped the plane from their names (they are the only light and the only mesh renderer);ShadowCaster2Dkeeps 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*Collider2Dshapes,Physics2D,Physics2DPlugin,Collider2DShape, besideRigidBody3D,Physics3DPluginandCollider3DShape. 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), andPhysicsWasmModule/loadPhysicsModule, which name the side modulephysics.wasmrather 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) anddevice-loss. The other 121 assert on both.