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.

docs(architecture): the record catches up to the door, the ray and a closed gap

esengine6fb57cc304aa
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 132093a68..44bb190eb 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -64,7 +64,10 @@ project that uses one: Box2D (2D physics), Jolt (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.
+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/`)
@@ -187,6 +190,12 @@ Key facts:
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
@@ -387,7 +396,3 @@ Remaining capability work (see `REARCH_2D_PARITY.md`, gitignored):
- [ ] 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.
-- [ ] A point light runs six cube-face collects and draws whether or not any mesh
- falls in a face; the frustum is already extracted per tile, so skipping an
- empty one is cheap — unmeasured, because nothing in the corpus has several
- point lights.
diff --git a/tools/check-architecture-doc.mjs b/tools/check-architecture-doc.mjs
index b048679f9..14413e5dd 100644
--- a/tools/check-architecture-doc.mjs
+++ b/tools/check-architecture-doc.mjs
@@ -41,9 +41,19 @@ const DIR_ROOTS = ['src/esengine', 'sdk/src', 'docs', '.'];
*/
const ABSENT_BY_DESIGN = new Set([
'REARCH_2D_PARITY.md', 'REARCH_WGSL.md', 'desktop/',
- 'dist/index.native.bundled.js', 'esengine/node',
+ 'dist/index.native.bundled.js',
]);
+/**
+ * `esengine/<name>` is a package entry specifier, not a path — and the set of them
+ * is published, so this reads it rather than keeping a second list. The doc can
+ * name a subpath only if the package actually exports one.
+ */
+const ENTRY_SPECIFIERS = new Set(
+ Object.keys(JSON.parse(readFileSync(path.join(ROOT, 'sdk', 'package.json'), 'utf8')).exports)
+ .filter((k) => k.startsWith('./'))
+ .map((k) => `esengine/${k.slice(2)}`));
+
/**
* Names the doc mentions BECAUSE they are gone. Asserted in the other direction:
* if one comes back, the sentence saying it was deleted has quietly become false.
@@ -81,6 +91,7 @@ for (const m of doc.matchAll(/`([^`\n]+)`/g)) {
if (/^[\w./-]+\/[\w./-]*$/.test(raw) || /^[\w-]+\.(md|ts|mjs|cpp|hpp|json|esshader)$/.test(raw)) {
const bare = raw.replace(/:[\d,\-\s]+$/, '');
if (ABSENT_BY_DESIGN.has(bare) || ABSENT_BY_DESIGN.has(`${bare}/`)) continue;
+ if (ENTRY_SPECIFIERS.has(bare)) continue;
if (existsSync(path.join(ROOT, bare))) continue;
if (DIR_ROOTS.some((r) => existsSync(path.join(ROOT, r, bare)))) continue;
// A bare filename is cited without its directory all over the doc.