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): a culling promise is a setting, and a scan is how you propose one
esengineb8122bba00d6
diff --git a/desktop b/desktopindex ff7045bff..2cc52ab98 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit ff7045bffe6012f1404d5faef053afbfca9d70a4+Subproject commit 2cc52ab9888a127a3b27c69fe6a5e403717d6f09diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 9124630e9..e85450626 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 113,"beta": 91,- "experimental": 1638,+ "experimental": 1653,"deprecated": 3},- "total": 1842,+ "total": 1857,"subsystems": [{"id": "ecs",diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.tsindex 190799c60..83fb42e72 100644--- a/pipeline/src/project/importSettings.ts+++ b/pipeline/src/project/importSettings.ts@@ -88,8 +88,25 @@ const TEXTURE: ImporterFieldSpec[] = [{ key: 'sliceBorder.bottom', label: 'Border Bottom', type: 'number', default: 0, min: 0, category: '9-Slice', advanced: true },];+// `cullingBounds` promises no pose of this skeleton leaves it. The runtime's+// demand-driven posing reads it: with a promise, a skeleton no camera can see+// may be left unposed. A rectangle of no area is the absence of one.const SPINE: ImporterFieldSpec[] = [{ key: 'scale', label: 'Scale', type: 'number', default: 1, min: 0, step: 0.01, category: 'Spine' },+ {+ key: 'cullingBounds.x', label: 'Culling X', type: 'number', default: 0,+ category: 'Culling', advanced: true,+ tooltip: 'Left edge of the area this skeleton promises to stay inside, in its own space. '+ + 'Width or height of zero means no promise, and the skeleton is posed every frame.',+ },+ { key: 'cullingBounds.y', label: 'Culling Y', type: 'number', default: 0, category: 'Culling', advanced: true },+ {+ key: 'cullingBounds.width', label: 'Culling Width', type: 'number', default: 0, min: 0,+ category: 'Culling', advanced: true,+ tooltip: 'Zero means no promise. A skeleton that leaves this area while it is '+ + 'in view can be culled while visible.',+ },+ { key: 'cullingBounds.height', label: 'Culling Height', type: 'number', default: 0, min: 0, category: 'Culling', advanced: true },];// Which armature and animation an entity gets are DragonBonesAnimation fieldsdiff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.mdindex 5b1052e15..6138838c3 100644--- a/sdk/etc/spine.api.md+++ b/sdk/etc/spine.api.md@@ -1,7 +1,7 @@# API surface — esengine/spine<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 0 public · 1 beta · 20 experimental · 0 deprecated+Symbols: 0 public · 1 beta · 35 experimental · 0 deprecated## ConstraintList — interface @experimental```@@ -10,6 +10,11 @@ path: string[]transform: string[]```+## NO_CERTIFICATES — const @experimental+```+SpineCertificateSource+```+## PathMixData — interface @experimental```mixRotate: number@@ -34,6 +39,53 @@ textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefinedResourceDef<SpineManager>```+## SpineAABB — interface @experimental+```+maxX: number+maxY: number+minX: number+minY: number+```++## SpineBoundsSource — interface @experimental+```+animationDuration: (skeletonHandle: number, animation: string) => number+createInstance: (skeletonHandle: number) => number+destroyInstance: (instanceId: number) => void+getAnimations: (instanceId: number) => string[]+getBounds: (instanceId: number) => { x: number; y: number; width: number; height: number; }+getSkins: (instanceId: number) => string[]+play: (instanceId: number, animation: string, loop?: boolean, track?: number) => boolean+setSkin: (instanceId: number, skin: string) => void+skeletonBounds: (skeletonHandle: number) => SpineAABB | null+update: (instanceId: number, dt: number) => void+```++## SpineCertificateSource — interface @experimental+```+envelopeFor: (pairKey: string) => SpineCullingEnvelope+```++## SpineCertificates — class @experimental+```+certify: (pairKey: string, bounds: SpineAABB) => void+clear: () => void+envelopeFor: (pairKey: string) => SpineCullingEnvelope+revoke: (pairKey: string) => void+static new (): SpineCertificates+static prototype: SpineCertificates+```++## SpineCullingEnvelope — type @experimental+```+| { kind: 'certified'; bounds: SpineAABB; source: 'explicit' }+ | {+ kind: 'observed'; bounds: SpineAABB; source: 'animation-scan';+ sampleStep: number; era: string; coverage: SpineScanCoverage;+ }+ | { kind: 'unknown' }+```+## SpineEvent — interface @experimental```animationName: string@@ -81,6 +133,7 @@ hasRuntime: (version: SpineVersion) => booleanlistConstraints: (entity: Entity) => ConstraintList | nullloadEntity: (entity: Entity, era: SpineEraBinding, _registry: CppRegistry) => Promise<SpineVersion | null>observe: (on: boolean) => void+observedBounds: (entity: Entity, sampleStep?: number) => SpineCullingEnvelope | nullremoveEntity: (entity: Entity) => voidsetAnimation: (entity: Entity, animation: string, loop: boolean) => voidsetAttachment: (entity: Entity, slotName: string, attachmentName: string) => boolean@@ -183,6 +236,7 @@ loadEntity: (entity: Entity, era: SpineEraBinding) => booleanmayDefer: (entity: Entity) => booleanmetrics: () => SpineFrameMetrics | nullobserve: (on: boolean) => void+observedBounds: (entity: Entity, sampleStep?: number) => SpineCullingEnvelope | nullposeEligibility: (entity: Entity) => { culling: SpineCullingEnvelope; requiresContinuousWorldPose: boolean; } | nullremoveEntity: (entity: Entity) => voidsetAnimation: (entity: Entity, animation: string, loop: boolean) => void@@ -204,6 +258,13 @@ static new (version: SpineVersion, module: SpineWasmModule): SpineRuntimestatic prototype: SpineRuntime```+## SpineScanCoverage — interface @experimental+```+animations: number+samples: number+skins: number+```+## SpineVersion — type @experimental```'2.1' | '3.8' | '4.1' | '4.2' | '4.3'@@ -224,6 +285,21 @@ mixY: number(opts: { spineManager: SpineManager; sceneData: SceneData; entityMap: Map<number, Entity>; registry: CppRegistry; assetInfo: Map<string, SpineAssetInfo>; }): Promise<void>```+## certifyBounds — function @experimental+```+(bounds: SpineAABB): SpineCullingEnvelope+```++## contains — function @experimental+```+(outer: SpineAABB, inner: SpineAABB): boolean+```++## envelopeFor — function @experimental+```+(envelope: SpineCullingEnvelope, era: string): SpineCullingEnvelope+```+## loadSpineAssets — function @experimental```(module: ESEngineModule | null, source: RuntimeAssetSource, spineManager: SpineManager | null | undefined, spinePairs: ReadonlyArray<{ skeleton: string; atlas: string; }>, transcoderProvider?: TranscoderProvider, owner?: SpineAssetOwner, certificates?: SpineCertificateSource): Promise<Map<string, SpineAssetInfo>>@@ -234,6 +310,26 @@ mixY: number(opts: { module: ESEngineModule | null; source: RuntimeAssetSource; spineManager: SpineManager; sceneData: SceneData; entityMap: Map<number, Entity>; registry: CppRegistry; transcoderProvider?: TranscoderProvider; }): Promise<void>```+## mayDeferWorldPose — function @experimental+```+(envelope: SpineCullingEnvelope, requiresContinuousWorldPose: boolean): boolean+```++## projectSpineCertificates — function @experimental+```+(into: SpineCertificates, entries: ReadonlyArray<{ path: string; importer?: Record<string, unknown>; }>, atlasOf: (skeletonPath: string) => string | null): void+```++## scanObservedBounds — function @experimental+```+(source: SpineBoundsSource, skeletonHandle: number, era: string, sampleStep?: number): SpineCullingEnvelope+```++## setupBounds — function @experimental+```+(source: SpineBoundsSource, skeletonHandle: number): SpineAABB | null+```+## spineEntityProps — function @experimental```(d: Record<string, unknown>): { skeletonScale: number; flipX: boolean; flipY: boolean; layer: number; timeScale: number; playing: boolean; color?: { r: number; g: number; b: number; a: number; }; }@@ -244,6 +340,11 @@ mixY: number(manager?: SpineManager): SpinePlugin```+## worldBounds — function @experimental+```+(local: SpineAABB, transform: SpineAffine): SpineAABB+```+## wrapSpineModule — function @experimental```(raw: SpineWasmModule): SpineWrappedAPIdiff --git a/sdk/src/spine/SpineManager.ts b/sdk/src/spine/SpineManager.tsindex 9095b1370..48249cf76 100644--- a/sdk/src/spine/SpineManager.ts+++ b/sdk/src/spine/SpineManager.ts@@ -9,6 +9,7 @@ import type { SpineModuleFactory } from './SpineModuleLoader';import { SpineRuntime } from './SpineRuntime';import type { SpineEraBinding } from './prepareSpine';import type { SpineClipBudget, SpineFrameMetrics } from './spineMetrics';+import type { SpineCullingEnvelope } from './spineBounds';import { log } from '../util/logger';import type { SpineVersion } from '../sideModules/registry';@@ -200,6 +201,14 @@ export class SpineManager {return this.runtimeOf_(entity)?.getBounds(entity) ?? null;}+ /**+ * What a scan of this entity's skeleton saw — an OBSERVATION, for authoring+ * to propose a culling contract from. Never an authority: see spineBounds.+ */+ observedBounds(entity: Entity, sampleStep?: number): SpineCullingEnvelope | null {+ return this.runtimeOf_(entity)?.observedBounds(entity, sampleStep) ?? null;+ }+clipBudget(entity: Entity): SpineClipBudget | null {return this.runtimeOf_(entity)?.clipBudget(entity) ?? null;}diff --git a/sdk/src/spine/SpineRuntime.ts b/sdk/src/spine/SpineRuntime.tsindex 0cba2bd20..0e0df0fb7 100644--- a/sdk/src/spine/SpineRuntime.ts+++ b/sdk/src/spine/SpineRuntime.ts@@ -27,7 +27,8 @@ import type { SpineVersion } from '../sideModules/registry';import { log } from '../util/logger';import { submitEntityMeshes, type SkeletalMaterialOf } from '../skeletal/submitMeshes';import type { SpineClipBudget } from './spineMetrics';-import { mayDeferWorldPose } from './spineBounds';+import { mayDeferWorldPose, scanObservedBounds } from './spineBounds';+import type { SpineBoundsSource } from './spineBounds';import type { SpineCullingEnvelope } from './spineBounds';import { withScratch } from '../wasm/wasmScratch';@@ -374,6 +375,20 @@ export class SpineRuntime {return residency ? residencyMayDefer(residency) : false;}+ /**+ * Scan this entity's SKELETON — every animation over its whole duration, in+ * every skin — on a scratch instance, so the entity asking keeps its pose.+ * An OBSERVATION whatever it finds: authoring proposes contracts from it and+ * the runtime may never act on it. See spineBounds.+ */+ observedBounds(entity: Entity, sampleStep?: number): SpineCullingEnvelope | null {+ const info = this.entities_.get(entity);+ if (!info) return null;+ return scanObservedBounds(+ this.controller_ as unknown as SpineBoundsSource,+ info.skelHandle, info.era, sampleStep);+ }+/** Why, for a diagnostic: the promise, and what the runtime says of itself. */poseEligibility(entity: Entity): {culling: SpineCullingEnvelope; requiresContinuousWorldPose: boolean;diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.tsindex 9cccbeb52..1b22db4fe 100644--- a/sdk/src/spine/index.ts+++ b/sdk/src/spine/index.ts@@ -9,6 +9,15 @@ export { SpineModuleController } from './SpineController';export type { ConstraintList, TransformMixData, PathMixData } from './SpineController';export type { SpineModuleFactory } from './SpineModuleLoader';export { wrapSpineModule } from './SpineModuleLoader';+export type {+ SpineAABB, SpineCullingEnvelope, SpineScanCoverage, SpineBoundsSource,+} from './spineBounds';+export {+ setupBounds, scanObservedBounds, certifyBounds, envelopeFor, mayDeferWorldPose,+ worldBounds, contains,+} from './spineBounds';+export { SpineCertificates, projectSpineCertificates, NO_CERTIFICATES } from './spineCertificates';+export type { SpineCertificateSource } from './spineCertificates';// Shared spine scene loader — the editor loads spine entities through the same// single implementation the builder runtime uses (see ./loadSpineScene).export { loadSpineSceneEntities, loadSpineAssets, applySpineEntities, spineEntityProps } from './loadSpineScene';