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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(spine): whether this camera would draw it, asked of the renderer
esengine2a614bddcc7d
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 0c7d81b5b..5bc83c751 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -348,6 +348,7 @@ renderer_captureNextFrame: () => voidrenderer_createTarget: (width: number, height: number, flags: number) => numberrenderer_diagnose: () => voidrenderer_end: () => void+renderer_entityVisibleToCamera: ((registry: CppRegistry, entity: number, layer: number, minX: number, minY: number, maxX: number, maxY: number, outVisiblePtr: number) => void) | undefinedrenderer_flush: () => voidrenderer_getCapturedCameraCount: () => numberrenderer_getCapturedEntities: () => numberdiff --git a/sdk/src/spine/SpineRuntime.ts b/sdk/src/spine/SpineRuntime.tsindex 216f7fd8c..89edf96cb 100644--- a/sdk/src/spine/SpineRuntime.ts+++ b/sdk/src/spine/SpineRuntime.ts@@ -29,6 +29,7 @@ import { submitEntityMeshes, type SkeletalMaterialOf } from '../skeletal/submitMimport type { SpineClipBudget } from './spineMetrics';import { mayDeferWorldPose } from './spineBounds';import type { SpineCullingEnvelope } from './spineBounds';+import { withScratch } from '../wasm/wasmScratch';interface EntityInfo {skelHandle: number;@@ -323,6 +324,37 @@ export class SpineRuntime {return result;}+ /**+ * Whether the camera in hand would draw this entity, or null where the+ * question cannot be asked — no certified extent, or a core without the+ * entry point. Null is not "invisible": an unknown extent makes visibility+ * unknown, and the only answer a caller may act on is `false`.+ */+ private cameraWouldDraw_(+ core: NonNullable<EngineApi>, registry: CppRegistry, entity: Entity, info: EntityInfo,+ ): boolean | null {+ const ask = (core as { renderer_entityVisibleToCamera?: unknown })+ .renderer_entityVisibleToCamera as+ | ((r: CppRegistry, e: number, layer: number,+ minX: number, minY: number, maxX: number, maxY: number, out: number) => void)+ | undefined;+ if (!ask) return null;+ const residency = this.skeletons_.get(info.era);+ if (!residency || residency.culling.kind !== 'certified') return null;++ const { bounds } = residency.culling;+ const scale = info.skeletonScale;+ const heap = core.HEAPU32;+ if (!heap || !core._malloc || !core._free) return null;+ return withScratch({ _malloc: core._malloc, _free: core._free }, (alloc) => {+ const ptr = alloc(4);+ ask(registry, entity as unknown as number, info.layer,+ bounds.minX * scale, bounds.minY * scale,+ bounds.maxX * scale, bounds.maxY * scale, ptr);+ return heap[ptr >> 2] !== 0;+ });+ }+/*** Whether this entity's world pose may be left owed when nothing wants it —* both proofs, settled when its residency was made. The scheduler that will@@ -415,6 +447,12 @@ export class SpineRuntime {const started = m ? performance.now() : 0;for (const [entity, info] of this.entities_) {if (this.disabledEntities_.has(entity)) continue;+ // What this camera would do with it, asked of the renderer rather+ // than worked out here. Nothing acts on the answer yet: this pass+ // still resolves, extracts and submits exactly what it did before.+ if (m && this.cameraWouldDraw_(core, registry, entity, info) === false) {+ m.pose.renderCulled++;+ }// The renderer is a consumer of the world pose like any other, and// asks for it the same way. Today it is already resolved.this.ensurePose(entity);diff --git a/sdk/src/spine/spineMetrics.ts b/sdk/src/spine/spineMetrics.tsindex 75a03d2da..e20197710 100644--- a/sdk/src/spine/spineMetrics.ts+++ b/sdk/src/spine/spineMetrics.ts@@ -91,6 +91,8 @@ export interface SpinePoseCounts {worldMaterializations: number;worldDeferred: number;meshExtractions: number;+ /** Extractions the camera in hand would not have drawn. Counted, not acted on. */+ renderCulled: number;}export interface SpineFrameMetrics {@@ -113,7 +115,7 @@ export function newSpineFrameMetrics(): SpineFrameMetrics {return {frame: 0, entities: 0, residencies: 0, meshBatches: 0, vertices: 0, indices: 0,abi: { pose: 0, world: 0, batchCount: 0, vertexCount: 0, indexCount: 0, batchData: 0, malloc: 0, free: 0, submit: 0 },- pose: { logicalUpdates: 0, worldMaterializations: 0, worldDeferred: 0, meshExtractions: 0 },+ pose: { logicalUpdates: 0, worldMaterializations: 0, worldDeferred: 0, meshExtractions: 0, renderCulled: 0 },bytes: { wasmRead: 0, coreWrite: 0, scratchAllocated: 0 },time: { pose: 0, readback: 0, total: 0 },};@@ -127,7 +129,7 @@ export function beginSpineFrame(m: SpineFrameMetrics): void {m.abi.batchData = 0; m.abi.malloc = 0; m.abi.free = 0; m.abi.submit = 0;m.bytes.wasmRead = 0; m.bytes.coreWrite = 0; m.bytes.scratchAllocated = 0;m.pose.logicalUpdates = 0; m.pose.worldMaterializations = 0;- m.pose.worldDeferred = 0; m.pose.meshExtractions = 0;+ m.pose.worldDeferred = 0; m.pose.meshExtractions = 0; m.pose.renderCulled = 0;m.time.pose = 0; m.time.readback = 0; m.time.total = 0;}diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex a72dc083a..960f08f4b 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -287,6 +287,15 @@ export interface ESEngineModule {* Geometry posed by a skeletal runtime (Spine, DragonBones): x,y,u,v,r,g,b,a per* vertex, drawn as `entity`'s, with `materialId` resolved as a Sprite's is.*/+ /**+ * Whether the camera being rendered right now would draw this entity's+ * geometry at the local extent it promises to stay inside. The frame's own+ * frustum and culling mask — a fact, not a permission.+ */+ renderer_entityVisibleToCamera?(+ registry: CppRegistry, entity: number, layer: number,+ minX: number, minY: number, maxX: number, maxY: number, outVisiblePtr: number): void;+renderer_submitSkeletalBatchByEntity?(registry: CppRegistry,verticesPtr: number, vertexCount: number,diff --git a/sdk/tests/spine-camera-visibility.test.ts b/sdk/tests/spine-camera-visibility.test.tsnew file mode 100644index 000000000..f47bc422e--- /dev/null+++ b/sdk/tests/spine-camera-visibility.test.ts@@ -0,0 +1,169 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file spine-camera-visibility.test.ts+ * @brief Whether this camera would draw it — asked of the renderer, acted on+ * by nobody yet.+ *+ * @details The engine culls per CAMERA, not per frame: `collectAll` runs once+ * for each, with that camera's frustum and its culling mask, and the+ * draw list is cleared between them. There is no camera bitmask to+ * propagate — `cullBit` on a draw is which LAYER it belongs to.+ *+ * So visibility is a per-camera question and the union over cameras+ * falls out of the revision model rather than being computed: the first+ * camera that wants an entity resolves its pose, and the rest find the+ * debt paid. Nothing here needs a bitmask, and nothing invents one.+ *+ * This cut only asks. Behaviour is identical — the same entities are+ * resolved, extracted and submitted as before — which is what keeps the+ * scheduling decision in the cut that will make it.+ */+import { describe, it, expect } from 'vitest';+import { SpineRuntime } from '../src/spine/SpineRuntime';+import { fakeSpineModule, fakeSpineEra } from './helpers/fakeSpineModule';+import { certifyBounds } from '../src/spine/spineBounds';+import type { Entity } from '../src/types';++const PROMISE = certifyBounds({ minX: -100, minY: -100, maxX: 100, maxY: 100 });++/** A core that answers the visibility question however the test wants. */+function core(answer: ((entity: number, layer: number) => boolean) | null): {+ core: never; asked: Array<{ entity: number; layer: number; rect: number[] }>;+} {+ const asked: Array<{ entity: number; layer: number; rect: number[] }> = [];+ const heap = new Uint32Array(64);+ const api: Record<string, unknown> = {+ renderer_submitSkeletalBatchByEntity: () => {},+ _malloc: () => 4,+ _free: () => {},+ HEAPU8: new Uint8Array(heap.buffer),+ HEAPU32: heap,+ };+ if (answer) {+ api.renderer_entityVisibleToCamera = (+ _r: unknown, entity: number, layer: number,+ minX: number, minY: number, maxX: number, maxY: number, out: number,+ ): void => {+ asked.push({ entity, layer, rect: [minX, minY, maxX, maxY] });+ heap[out >> 2] = answer(entity, layer) ? 1 : 0;+ };+ }+ return { core: api as never, asked };+}++function runtimeWith(culling = PROMISE): { runtime: SpineRuntime; fake: ReturnType<typeof fakeSpineModule> } {+ const fake = fakeSpineModule();+ const runtime = new SpineRuntime('3.8', fake.module);+ runtime.loadEntity(1 as Entity, fakeSpineEra('era#1', new Uint8Array([1]), culling));+ runtime.setAnimation(1 as Entity, 'walk', true);+ runtime.observe(true);+ return { runtime, fake };+}++describe('what this camera would draw, asked of the renderer', () => {+ it('a certified entity is asked about, in its own extent', () => {+ const { runtime } = runtimeWith();+ const { core: engine, asked } = core(() => true);+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(engine, {} as never);++ expect(asked).toHaveLength(1);+ expect(asked[0].rect, 'the promise was not the extent that was asked about')+ .toEqual([-100, -100, 100, 100]);+ expect(runtime.metrics()!.pose.renderCulled).toBe(0);+ runtime.dispose();+ });++ it('an entity this camera cannot see is counted, not skipped', () => {+ // The whole point of this cut landing before the next one: the fact is+ // available and changes nothing.+ const { runtime } = runtimeWith();+ const { core: engine } = core(() => false);+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(engine, {} as never);++ const m = runtime.metrics()!;+ expect(m.pose.renderCulled, 'the camera fact was not recorded').toBe(1);+ expect(m.pose.worldMaterializations, 'a world pose was skipped already').toBe(1);+ expect(m.pose.meshExtractions, 'an extraction was skipped already').toBe(1);+ runtime.dispose();+ });++ it('an uncertified entity is not asked about at all', () => {+ // Its extent is unknown, so its visibility is unknown; there is nothing+ // to ask with, and "unknown" may never be read as "invisible".+ const { runtime } = runtimeWith({ kind: 'unknown' });+ const { core: engine, asked } = core(() => false);+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(engine, {} as never);++ expect(asked, 'an uncertified extent was used to ask about visibility').toHaveLength(0);+ expect(runtime.metrics()!.pose.renderCulled).toBe(0);+ runtime.dispose();+ });++ it('an observed extent is not asked about either', () => {+ // The rule from the certification cut, reaching the render path: an+ // observation is not a promise, so it is not an extent to cull against.+ const { runtime } = runtimeWith({+ kind: 'observed', source: 'animation-scan', sampleStep: 1 / 30, era: 'era#1',+ bounds: { minX: -100, minY: -100, maxX: 100, maxY: 100 },+ coverage: { animations: 1, skins: 1, samples: 30 },+ });+ const { core: engine, asked } = core(() => false);+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(engine, {} as never);++ expect(asked, 'a scan was used as the extent to cull against').toHaveLength(0);+ runtime.dispose();+ });++ it('a core that cannot answer is not treated as a no', () => {+ const { runtime } = runtimeWith();+ const { core: engine } = core(null);+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(engine, {} as never);+ expect(runtime.metrics()!.pose.renderCulled).toBe(0);+ runtime.dispose();+ });++ it('the entity scale is carried into the extent it is asked about', () => {+ const { runtime } = runtimeWith();+ runtime.setEntityProps(1 as Entity, { skeletonScale: 3 });+ const { core: engine, asked } = core(() => true);+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(engine, {} as never);+ expect(asked[0].rect, 'a scaled skeleton was culled against its unscaled extent')+ .toEqual([-300, -300, 300, 300]);+ runtime.dispose();+ });++ it('the layer is the one the entity draws on', () => {+ const { runtime } = runtimeWith();+ runtime.setEntityProps(1 as Entity, { layer: 7 });+ const { core: engine, asked } = core(() => true);+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(engine, {} as never);+ expect(asked[0].layer, "the camera was asked about the wrong layer").toBe(7);+ runtime.dispose();+ });++ it('two cameras are two passes, and the second finds the pose paid', () => {+ // The union, without a bitmask: each camera runs its own submit, and the+ // revision model means only the first one that wants it pays.+ const { runtime } = runtimeWith();+ const invisible = core(() => false);+ const visible = core(() => true);+ runtime.updateAll(1 / 60);+ const before = runtime.metrics()!.pose.worldMaterializations;++ runtime.extractAndSubmitMeshes(invisible.core, {} as never);+ runtime.extractAndSubmitMeshes(visible.core, {} as never);++ const m = runtime.metrics()!;+ expect(m.pose.worldMaterializations, 'a second camera re-resolved the pose').toBe(before);+ expect(m.pose.renderCulled, 'only one of the two cameras declined it').toBe(1);+ runtime.dispose();+ });+});diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 364bfa1ac..a0f497b04 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -2,6 +2,8 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team#include "RendererBindings.hpp"++#include <limits>#include "../resource/ShaderParser.hpp"#include "ActiveContext.hpp"#include "BoundarySpan.hpp"@@ -114,6 +116,42 @@ void renderer_submitSkeletalBatchByEntity(textureId, blendMode, &model[0][0], ent, layer, depth, materialId);}+/**+ * Whether the camera being rendered right now would draw this entity, given the+ * local extent it promises to stay inside. All four corners are transformed,+ * because under rotation the result's corners are not the input's. The frustum+ * and mask are the frame's own — a fact, not a permission.+ */+void renderer_entityVisibleToCamera(+ ecs::Registry& registry, u32 entity, i32 layer,+ f32 minX, f32 minY, f32 maxX, f32 maxY, uintptr_t outVisiblePtr+) {+ auto* out = reinterpret_cast<i32*>(outVisiblePtr);+ if (!out) return;+ *out = 1;+ if (!g_initialized || !g_renderFrame) return;+ const Entity ent = Entity::fromRaw(entity);+ if (!registry.has<ecs::Transform>(ent)) return;++ auto& t = registry.get<ecs::Transform>(ent);+ t.ensureDecomposed();+ const glm::mat4 model = glm::translate(glm::mat4(1.0f), t.worldPosition)+ * glm::mat4_cast(t.worldRotation)+ * glm::scale(glm::mat4(1.0f), t.worldScale);++ const glm::vec2 corners[4] = {+ { minX, minY }, { maxX, minY }, { maxX, maxY }, { minX, maxY },+ };+ glm::vec3 lo{std::numeric_limits<f32>::max()};+ glm::vec3 hi{-std::numeric_limits<f32>::max()};+ for (const glm::vec2& corner : corners) {+ const glm::vec4 world = model * glm::vec4(corner.x, corner.y, 0.0f, 1.0f);+ lo = glm::min(lo, glm::vec3(world));+ hi = glm::max(hi, glm::vec3(world));+ }+ *out = g_renderFrame->visibleToCamera(layer, (lo + hi) * 0.5f, (hi - lo) * 0.5f) ? 1 : 0;+}+// TS lays out glyph quads against the dynamic SDF atlas and// submits them here (ungated — text is core, unlike spine).void renderer_submitTextBatch(diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex e360d2033..1b5a79507 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -34,6 +34,12 @@ void renderer_end();#endif/// Geometry posed by a skeletal runtime (Spine, DragonBones): x,y,u,v,r,g,b,a per/// vertex, drawn as @p entity's, with its material resolved as a Sprite's is.+// Whether the camera being rendered right now would draw this entity's geometry+// at the local extent it promises to stay inside. A fact, not a permission.+void renderer_entityVisibleToCamera(+ ecs::Registry& registry, u32 entity, i32 layer,+ f32 minX, f32 minY, f32 maxX, f32 maxY, uintptr_t outVisiblePtr);+void renderer_submitSkeletalBatchByEntity(ecs::Registry& registry,uintptr_t verticesPtr, i32 vertexCount,diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 7c51e146e..1aff85abc 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -518,6 +518,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {// Every skeletal runtime is a side module; this is the one door their posed// geometry comes through, so it belongs to neither of their build flags.emscripten::function("renderer_submitSkeletalBatchByEntity", &esengine::renderer_submitSkeletalBatchByEntity);+ emscripten::function("renderer_entityVisibleToCamera", &esengine::renderer_entityVisibleToCamera);emscripten::function("renderer_submitTextBatch", &esengine::renderer_submitTextBatch);emscripten::function("meshRenderer_setGeometry", &esengine::meshRenderer_setGeometry);emscripten::function("mesh_createFromChannels", &esengine::mesh_createFromChannels);diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 7fbda5d02..100ccf899 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1359,6 +1359,12 @@ void RenderFrame::collectSky(RenderCollectContext& ctx) {BATCH_QUAD_INDICES, 6, key);}+bool RenderFrame::visibleToCamera(i32 layer, const glm::vec3& center,+ const glm::vec3& halfExtents) const {+ if (!draw_list_.layerVisible(DrawList::layerBit(layer))) return false;+ return frustum_.intersectsAABB(center, halfExtents);+}+void RenderFrame::collectAll(ecs::Registry& registry) {ES_PROFILE_SCOPE("render.collect");buildClipState();diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 4269182ac..996e9fd17 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -252,6 +252,16 @@ public:void addPlugin(std::unique_ptr<RenderTypePlugin> plugin);void collectAll(ecs::Registry& registry);+ /**+ * @brief Whether the camera being rendered right now would draw something of+ * @p layer at these world bounds.+ *+ * @details The frame's OWN frustum and culling mask, both set by `begin`+ * for the camera in hand — asked rather than reimplemented, so+ * geometry from outside `collect` is culled by the same fact.+ */+ bool visibleToCamera(i32 layer, const glm::vec3& center, const glm::vec3& halfExtents) const;+/*** Compiled program id for a batch-shader feature variant, compiled+cached on* first use. `{}` is the default batch program; `{"SDF"}`