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(examples): demonstrate independent sprite playback controls

yhhae29b0ccf39b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 841db48b9..0f07ea861 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Added
+- **Sprite playback can be tried independently of its state machine.** The sprite-animation example uses P to pause and resume the two plain-clip bystanders while the player's Animator continues running. Its packaged interaction exercises both controls, and editor verification checks that paused frame indices and timers remain unchanged before resuming.
+
- **Disk cache budgets preserve offline content versions.** Node and capable mini-game hosts report resource usage, hashes, version ownership and protected bytes. Cleanup previews and applies LRU eviction while keeping current, pending, rollback and explicitly retained versions, coordinating with downloads and reporting actual released bytes. The editor's connected-device Profiler provides scans, budget previews, cleanup and version retention. Hosts without management report unavailable usage; saves and unknown files remain protected.
### Fixed
diff --git a/examples/sprite-animation/README.md b/examples/sprite-animation/README.md
index 86e43b494..1b7247b96 100644
--- a/examples/sprite-animation/README.md
+++ b/examples/sprite-animation/README.md
@@ -12,6 +12,7 @@ Animator model: parameters, triggers, 1D blend, exit time) on top of it, and
| ←/→ or A/D | Walk (the sprite flips with direction) |
| hold Shift | Run — the Move blend crosses its threshold and re-selects the walk clip at 1.9× |
| Space | Hop — a trigger fires a non-looping clip; its exit time returns to Idle |
+| P | Pause/resume the two bystanders' plain clips; the player keeps its state machine |
## How it works
@@ -35,7 +36,8 @@ Animator model: parameters, triggers, 1D blend, exit time) on top of it, and
and `puffSystem` spawns a fading dust puff at the feet through `Commands`.
- The two **bystander aliens** run plain `SpriteAnimator` clips at their own
speeds — the playback channel needs no state machine when a loop is all you
- want.
+ want. `playbackSystem` toggles their `playing` state with P and excludes the
+ player's `Animator`, so both playback paths can be tried independently.
Play the scene in the editor and select the Player while it runs: the Details
panel shows `Animator.currentState` flipping between `Idle`, `Move`, and `Hop`
diff --git a/examples/sprite-animation/src/main.ts b/examples/sprite-animation/src/main.ts
index c1b89a5f3..1755ed088 100644
--- a/examples/sprite-animation/src/main.ts
+++ b/examples/sprite-animation/src/main.ts
@@ -1,26 +1,14 @@
-// Sprite Animation — the engine's frame-animation stack, bottom to top:
-//
-// • .esanim clips — idle/walk load from assets with the scene; the hop
-// clip is registered from code (both authoring paths).
-// • SpriteAnimator — frame playback. The two background aliens run plain
-// clips at their own speeds, no state machine involved.
-// • Animator (FSM) — the player is driven by a state machine: a `speed`
-// float switches Idle↔Move, Move is a 1D blend that
-// re-selects walk×1.0 / walk×1.9 (run) as speed rises,
-// and the Space `hop` trigger plays a non-looping clip
-// whose exit time auto-returns to Idle.
-// • Frame events — the walk clip's contact frames fire `footstep`
-// events; a system turns them into fading dust puffs.
-//
-// Controls: ←/→ or A/D walk · hold Shift to run · Space to hop.
+// Sprite animation: authored clips, player state machine, and footstep events.
+// Arrow keys or A/D walk; Shift runs; Space hops; P pauses/resumes bystanders.
import { addStartupSystem, addSystemToSchedule, Schedule } from 'esengine';
import './components';
import { setupSystem, wireClipsSystem } from './systems/setup';
-import { controlSystem } from './systems/control';
+import { controlSystem, playbackSystem } from './systems/control';
import { puffSystem } from './systems/puffs';
addStartupSystem(setupSystem);
addSystemToSchedule(Schedule.Update, wireClipsSystem);
addSystemToSchedule(Schedule.Update, controlSystem);
+addSystemToSchedule(Schedule.Update, playbackSystem);
addSystemToSchedule(Schedule.Update, puffSystem);
diff --git a/examples/sprite-animation/src/systems/control.ts b/examples/sprite-animation/src/systems/control.ts
index b387467cf..b981c6b39 100644
--- a/examples/sprite-animation/src/systems/control.ts
+++ b/examples/sprite-animation/src/systems/control.ts
@@ -1,6 +1,6 @@
import {
defineSystem, Query, Mut, Res, Time, Input,
- Transform, Sprite, Animator,
+ Transform, Sprite, Animator, SpriteAnimator,
AnimatorController, AnimatorControllerAPI,
} from 'esengine';
import { Player } from '../components';
@@ -49,3 +49,13 @@ export const controlSystem = defineSystem(
},
{ name: 'ControlSystem' },
);
+
+// Plain clip playback can be controlled independently of the player's state machine.
+export const playbackSystem = defineSystem(
+ [Query(Mut(SpriteAnimator)).without(Animator), Res(Input)],
+ (bystanders, input) => {
+ if (!input.isKeyPressed('KeyP')) return;
+ for (const [, animator] of bystanders) animator.playing = !animator.playing;
+ },
+ { name: 'PlaybackSystem' },
+);
diff --git a/tools/check-tier-bar.mjs b/tools/check-tier-bar.mjs
index f0da0bd54..e44ed324d 100644
--- a/tools/check-tier-bar.mjs
+++ b/tools/check-tier-bar.mjs
@@ -62,7 +62,6 @@ const OWED = {
],
assets: ['AssetsData is named by no SDK test'],
camera: ['CameraData is named by no SDK test'],
- animation: ['SpriteAnimator is called by no golden project'],
};
const REPORT = process.argv.includes('--report');
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index 53da633ea..2e68493dd 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -1040,7 +1040,8 @@ export const GOLDEN = [
tier: 'release',
// The player's clip switches Idle→Move on the same key that moves it, so a
// driven frame differs because the animation changed as much as the position.
- interact: { keys: ['ArrowRight'], frames: 40 },
+ // P separately pauses plain-clip bystanders while the player's FSM keeps running.
+ interact: { keys: ['ArrowRight', 'KeyP'], frames: 40 },
},
{
id: 'effects-gallery',
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index b885c9ab9..67b44a3ec 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(examples): demonstrate independent sprite playback controls':
+ { note: 'Sprite playback can be tried independently of its state machine.' },
'fix(ui): stop released scroll flings on input cancellation':
{ note: 'Input cancellation stops released scroll flings.' },
'fix(input): reset native input when the host hides':