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.

feat(spine): a culling promise is a setting, and a scan is how you propose one

esengineb8122bba00d6
diff --git a/desktop b/desktop
index ff7045bff..2cc52ab98 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit ff7045bffe6012f1404d5faef053afbfca9d70a4
+Subproject commit 2cc52ab9888a127a3b27c69fe6a5e403717d6f09
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 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.ts
index 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 fields
diff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.md
index 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 | undefined
ResourceDef<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) => boolean
listConstraints: (entity: Entity) => ConstraintList | null
loadEntity: (entity: Entity, era: SpineEraBinding, _registry: CppRegistry) => Promise<SpineVersion | null>
observe: (on: boolean) => void
+observedBounds: (entity: Entity, sampleStep?: number) => SpineCullingEnvelope | null
removeEntity: (entity: Entity) => void
setAnimation: (entity: Entity, animation: string, loop: boolean) => void
setAttachment: (entity: Entity, slotName: string, attachmentName: string) => boolean
@@ -183,6 +236,7 @@ loadEntity: (entity: Entity, era: SpineEraBinding) => boolean
mayDefer: (entity: Entity) => boolean
metrics: () => SpineFrameMetrics | null
observe: (on: boolean) => void
+observedBounds: (entity: Entity, sampleStep?: number) => SpineCullingEnvelope | null
poseEligibility: (entity: Entity) => { culling: SpineCullingEnvelope; requiresContinuousWorldPose: boolean; } | null
removeEntity: (entity: Entity) => void
setAnimation: (entity: Entity, animation: string, loop: boolean) => void
@@ -204,6 +258,13 @@ static new (version: SpineVersion, module: SpineWasmModule): SpineRuntime
static 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): SpineWrappedAPI
diff --git a/sdk/src/spine/SpineManager.ts b/sdk/src/spine/SpineManager.ts
index 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.ts
index 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.ts
index 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';