castle-web-cli 0.4.195 → 0.4.197

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,8 +10,8 @@
10
10
  <link rel="icon" type="image/png" sizes="32x32" href="/__castle/ide/favicon-32x32.png" />
11
11
  <link rel="icon" type="image/png" sizes="16x16" href="/__castle/ide/favicon-16x16.png" />
12
12
  <link rel="icon" href="/__castle/ide/favicon.ico" sizes="any" />
13
- <script type="module" crossorigin src="/__castle/ide/assets/index-kMH1qj6D.js"></script>
14
- <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-D6leLNUq.css">
13
+ <script type="module" crossorigin src="/__castle/ide/assets/index-yHGXRGlX.js"></script>
14
+ <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-MSHtKPXt.css">
15
15
  </head>
16
16
  <body>
17
17
  <div id="root"></div>
@@ -82,7 +82,7 @@
82
82
  "title": "base",
83
83
  "deckId": "yRcmH4_aYllE",
84
84
  "cardId": "zkFdingmIm3m",
85
- "publishedVersion": "2026-09-17T20:55:24.712Z",
85
+ "publishedVersion": "2026-09-18T20:02:20.225Z",
86
86
  "provides": [
87
87
  "castle-web-sdk"
88
88
  ]
@@ -14,7 +14,7 @@
14
14
  },
15
15
  "../../sdk": {
16
16
  "name": "castle-web-sdk",
17
- "version": "0.4.26",
17
+ "version": "0.4.28",
18
18
  "dev": true,
19
19
  "devDependencies": {
20
20
  "eslint": "^9.0.0",
@@ -18,6 +18,7 @@ Do you already know what you want to make, or do you want to figure it out toget
18
18
 
19
19
  - Actor / behavior / scene framework on a fixed 500x700 canvas ("card").
20
20
  - Game logic lives in `behaviors/*.jsx` classes. A behavior's `static behaviorName` must match the component key used in scene JSON.
21
+ - A behavior is a class with **one instance per actor**: creator-tuned settings in `static defaultProps` (read as `this.props`), per-actor state in `this.state` seeded from `static initialState` (not bare `this.foo` fields or `actor.runtime`). Anything another behavior triggers is a public method, called as `actor.behaviors.Name?.method()` — `this.actor.behaviors` for a sibling, `other.behaviors` for another actor.
21
22
  - Editable screens live in `scenes/*.scene` files (plain JSON). Use a separate scene file per distinct screen, and switch with `scene.loadFromFile('name.scene')`.
22
23
  - Every actor is an instance of a **blueprint** (`blueprints/*.scene`) — see `## Blueprints` below. Always author the blueprint file yourself and reference it via `"blueprint"`. Don't write inline actors (full `components`, no `blueprint` field): the editor auto-migrates each one into its own new blueprint file on open, one per actor with no dedup, which litters the deck with junk blueprints.
23
24
  - Real game objects and scenery should usually be editable sprites: generate `.sprite` with `npm run draw -- name`, then place it via a `Sprite` component pointing at `drawings/name.sprite`. Dynamic UI/effects stay procedural.
@@ -243,6 +244,10 @@ export class MyThing {
243
244
  static behaviorName = 'MyThing'; // must match the key used in .scene
244
245
  static defaultProps = { speed: 200, power: 0.5 };
245
246
 
247
+ // Per-actor state, seeded into `this.state` for each actor carrying this
248
+ // behavior. Plain data only. Settings the creator tunes are props, not state.
249
+ static initialState = { dash: 0 };
250
+
246
251
  // Optional. Inspector ranges for numeric props. Without one, a number field is
247
252
  // an unbounded scrubber stepping by 1 — wrong for anything living in 0..1.
248
253
  // Giving BOTH min and max makes it a real slider. A `max` also caps typed
@@ -268,7 +273,15 @@ export class MyThing {
268
273
  // Called every frame in play mode. dt is seconds.
269
274
  update(actor, scene, dt) {
270
275
  const layout = actor.components.Layout;
271
- layout.x += this.props.speed * dt; // mutate component in place
276
+ const boost = this.state.dash > 0 ? 3 : 1;
277
+ layout.x += this.props.speed * boost * dt; // mutate component in place
278
+ this.state.dash = Math.max(0, this.state.dash - dt);
279
+ }
280
+
281
+ // A public method: how another behavior triggers this one. Called as
282
+ // `actor.behaviors.MyThing?.dash()`; `this.actor` and `this.scene` are bound.
283
+ dash() {
284
+ this.state.dash = 0.3; // seconds of triple speed
272
285
  }
273
286
 
274
287
  // Optional. Custom drawing (you usually don't need this; use a Sprite
@@ -303,7 +316,46 @@ export class MyThing {
303
316
  }
304
317
  ```
305
318
 
306
- A fresh `Behavior` instance is constructed per actor per frame from the actor's component props — DO NOT store per-actor state on `this`. Persist transient state on `actor.runtime` (a free-form object the framework will not serialize) or on the component props themselves.
319
+ Every actor that carries a behavior gets **one instance** of that class,
320
+ created on first use after load/spawn and kept for the actor's life. Inside
321
+ any hook `this.props` is the actor's component (live; the same object as
322
+ `actor.components.X`), `this.actor` and `this.scene` are bound, and
323
+ `this.state` is this behavior's private per-actor scratch: a plain object
324
+ seeded from `static initialState`, never serialized, reset when the scene
325
+ loads or the actor spawns, kept across a code hot-reload. `initialState` is
326
+ copied with `structuredClone`, so it holds plain data only (no functions,
327
+ class instances or DOM nodes -- those throw on the first `this.state` read).
328
+ Because state survives a hot-reload, a key you ADD to `initialState` while
329
+ playing stays `undefined` on actors already seeded until you Restart. Hook
330
+ signatures `(actor, scene, ...)` are unchanged. Call a sibling with
331
+ `actor.behaviors.Jump?.onLand()`; that IS the sibling's instance.
332
+
333
+ Reserved instance members: `actor`, `scene`, `props`, `state`, `enabled` — a
334
+ behavior prop or state field must not collide with one of these names. The
335
+ constructor still only receives `props`; nothing else changes about
336
+ construction from the author's point of view.
337
+
338
+ ```jsx
339
+ export class Cooldown {
340
+ static behaviorName = 'Cooldown';
341
+ static initialState = { cooldown: 0 };
342
+
343
+ constructor(props) {
344
+ this.props = props;
345
+ }
346
+
347
+ update(actor, scene, dt) {
348
+ this.state.cooldown = Math.max(0, this.state.cooldown - dt);
349
+ }
350
+
351
+ // A public method a sibling (or another actor) can call directly.
352
+ kick(power) {
353
+ if (this.state.cooldown > 0) return;
354
+ this.scene.physics.applyImpulse(this.actor, { x: 0, y: -power });
355
+ this.state.cooldown = 1;
356
+ }
357
+ }
358
+ ```
307
359
 
308
360
  ## Scene file (`scenes/main.scene`, plain JSON)
309
361
 
@@ -421,11 +473,14 @@ The kit also ships a few presets under `blueprints/` (e.g. `text.scene`, `ball.s
421
473
  - **SoundPlayer** — `{ file: "assets/music/theme.mp3", stream?: false, volume?: 1, playbackRate?: 1, pan?: 0, loop?: false, playOnStart?: true }`. Plays one audio file from an actor. `stream: false` (the default) fires it from memory — instant and overlapping, for effects; `stream: true` streams it from an `<audio>` element — for music and long ambience, whose decoded audio would be far too big to hold. `loop` applies to `stream: true` only. `playbackRate` retunes it (2 = an octave up and twice as fast, 0.5 = an octave down); `pan` places it left (−1) to right (+1). With `playOnStart` it starts with the scene; otherwise trigger it through the handle it puts on the actor:
422
474
 
423
475
  ```jsx
424
- scene.getActor('music').runtime.soundPlayer.play();
425
- await actor.runtime.soundPlayer.play(); // ...and wait for it to finish
426
- actor.runtime.soundPlayer.stop(); // stream also: pause(), resume(), .playing
476
+ scene.getActor('music').behaviors.SoundPlayer.play();
477
+ await actor.behaviors.SoundPlayer.play(); // ...and wait for it to finish
478
+ actor.behaviors.SoundPlayer.stop(); // stream also: pause(), resume(), .playing
427
479
  ```
428
480
 
481
+ `runtime.soundPlayer` is the older spelling and still works the same way
482
+ (`actor.runtime.soundPlayer.play()`).
483
+
429
484
  **For a one-off sound effect, don't place one of these** — `scene.sound.play('hit')` needs no actor and no component. See `## Sound` below.
430
485
 
431
486
  Sound only plays during play, never in the editor, and everything stops on Stop / a scene change. Browsers refuse audio until the player has touched the page; a sound that starts before that is queued and begins on the first tap or key, so don't work around it.
@@ -610,12 +665,13 @@ stick itself receives them and ignores them.
610
665
  ```jsx
611
666
  export class StickSlowDownToggle {
612
667
  static behaviorName = 'StickSlowDownToggle';
668
+ static initialState = { held: false };
613
669
  onAnalogStickBegin(actor, scene) {
614
670
  // e.g. mute a sibling Slow Down while the stick is active
615
- actor.runtime.stickHeld = true;
671
+ this.state.held = true;
616
672
  }
617
673
  onAnalogStickEnd(actor, scene) {
618
- actor.runtime.stickHeld = false;
674
+ this.state.held = false;
619
675
  }
620
676
  }
621
677
  ```
@@ -640,6 +696,31 @@ export class TapCounter {
640
696
  }
641
697
  ```
642
698
 
699
+ ### Talking to another behavior
700
+
701
+ Every behavior with a component on an actor has one cached instance,
702
+ reachable as `actor.behaviors.<Name>` — the same object `update`/`draw` run
703
+ on, so a method call sees the same `this.state`.
704
+
705
+ ```jsx
706
+ this.actor.behaviors.Jump?.onLand(); // a sibling on this actor
707
+ other.behaviors.Health?.damage(1); // another actor, e.g. inside onCollisionEnter
708
+ ```
709
+
710
+ `actor.behaviors.X` is `undefined` when the actor has no `X` component (the
711
+ `?.` is doing real work, not defensive boilerplate). The `.enabled`
712
+ getter/setter is the recommended way to flip a behavior off/on at runtime —
713
+ `actor.behaviors.Jump.enabled = false` — replacing the older
714
+ `component.$enabled = false` poke (that raw JSON spelling is still how you
715
+ author it in a `.scene` file — see `## Scene file` above).
716
+
717
+ The method form, `scene.behavior(actorOrId, 'Jump')`, is the same lookup and
718
+ takes an actor id as well as an actor, like `scene.colliderRect`.
719
+
720
+ **Look a sibling up each time; don't cache `other.behaviors.X` across
721
+ frames** — hold `other` (or its id) and re-look-up the behavior, since a hot
722
+ swap or a removed component can change what comes back.
723
+
643
724
  ### Built-in controls (add these behaviors, no code needed)
644
725
 
645
726
  These read input and drive the actor through the physics system, so the actor
@@ -881,7 +962,9 @@ To generate path art, emit an svg of **shapes** rather than per-pixel rects and
881
962
  - `scene.load(sceneData)` — replace the running scene with the given scene data object.
882
963
  - `scene.readFromFile(name)` — read and parse a scene file (`'gameover.scene'`, `'levels/2.scene'`), returning its scene data. Use this instead of importing a `.scene` file.
883
964
  - `scene.loadFromFile(name)` — read a scene file and transition the running scene to it. The way to switch screens/levels and to restart, e.g. `scene.loadFromFile('main.scene')`.
884
- - `actor.runtime` — per-instance scratchpad for transient state across frames (e.g. velocity, trail history). Not serialized.
965
+ - `scene.behavior(actor, name)` — the actor's cached instance of behavior `name`, or `undefined` when the actor has no such component or the class is unregistered.
966
+ - `actor.behaviors` — the per-actor accessor: `actor.behaviors.Jump?.onLand()` is the same lookup, keyed by behavior name. See `### Talking to another behavior`.
967
+ - `actor.runtime` — the LEGACY free-form scratchpad, kept for a behavior that hasn't moved onto `this.state` yet (or a deck's own ad-hoc use). Not serialized. `$`-prefixed keys (`$state`, `$behaviors`, `$enabled`, `$tap`) are reserved by the engine — a behavior should use `this.state` instead of adding its own bare keys here.
885
968
 
886
969
  ## Input shortcuts
887
970
 
@@ -898,8 +981,8 @@ For HUD text prefer a `Text` actor with `space: 'screen'` (or `drawUi` for custo
898
981
  ## Common breakout-shaped recipe (sketch)
899
982
 
900
983
  - `Paddle` behavior: read keys, move `layout.x`, and keep the box on the card — `const box = scene.layoutRect(actor)` and clamp so `box.x >= 0` and `box.x + box.width <= 500`.
901
- - `Ball` behavior: store `vx, vy` on `actor.runtime`; integrate; bounce off the wall edges read from `const box = scene.layoutRect(actor)` (`box.x < 0`, `box.x + box.width > 500`, `box.y < 0`); on `scene.overlaps(actor, paddle)`, flip `vy`; for each `brick` in `scene.actorsWith('Brick')` check `scene.overlaps(actor, brick)` → flip `vy` and `scene.despawnActor(brick.id)`; if `box.y > 700` lose a life.
902
- - `Brick` behavior: typically just a marker — `kind: 'solid'` collider is enough. State (hit count) goes on `actor.runtime` or the brick's own props.
984
+ - `Ball` behavior: store `vx, vy` on `this.state`; integrate; bounce off the wall edges read from `const box = scene.layoutRect(actor)` (`box.x < 0`, `box.x + box.width > 500`, `box.y < 0`); on `scene.overlaps(actor, paddle)`, flip `vy`; for each `brick` in `scene.actorsWith('Brick')` check `scene.overlaps(actor, brick)` → flip `vy` and `scene.despawnActor(brick.id)`; if `box.y > 700` lose a life.
985
+ - `Brick` behavior: typically just a marker — `kind: 'solid'` collider is enough. State (hit count) goes on `this.state` or the brick's own props.
903
986
  - `GameController` (no Layout needed if you don't draw it): tracks score / lives / status; expose HUD via `Text` with `space: 'screen'` or `drawUi()`.
904
987
 
905
988
  ## Don't
@@ -909,7 +992,9 @@ For HUD text prefer a `Text` actor with `space: 'screen'` (or `drawUi` for custo
909
992
  - Don't revert, replace, or re-scaffold a deck's `scenes/*.scene`, `blueprints/*.scene` or `behaviors/*.jsx` back to this kit's starter content, and don't rewrite or delete a whole scene to diagnose a problem — those files are the creator's game. Fix forward with targeted edits.
910
993
  - Don't answer "how do I …" by inserting a demo behavior or actor into the scene. Explain it, or give a standalone snippet; only build it into the game when that's what was asked, and then say which file and which actor or blueprint it landed on.
911
994
  - Don't `console.log` in tight loops — flood the serve log.
912
- - Don't keep per-actor state on the behavior class instance; it's recreated each frame. Use `actor.runtime` or component props.
995
+ - Don't hang per-actor state on a bare `this.foo`: the engine can't reset it and a hot reload drops it. Use `this.state`.
996
+ - Don't hold `other.behaviors.X` across frames — look it up again each time you need it.
997
+ - Don't signal between behaviors through `actor.runtime` flags, component props used as flags, or module-level globals. Put a method on the behavior that owns the reaction and call `actor.behaviors.X?.method()`.
913
998
  - Don't skip `constructor(props) { this.props = props; }`. `this.props` exists because the constructor assigns it; `defaultProps` alone does not put it there.
914
999
  - Don't try to import from `editors/`; behaviors run in the play runtime too.
915
1000
  - Don't add types or `.ts`/`.tsx` files. This kit is JavaScript.
@@ -106,11 +106,11 @@ function fireStickHook(actor, scene, hook) {
106
106
  scene.forEachBehavior(actor, (inst) => inst[hook]?.(actor, scene));
107
107
  }
108
108
 
109
- function clearStickRuntime(rt) {
110
- rt._stickBegan = false;
111
- rt._stickPointerId = null;
112
- rt._stickOrigin = null;
113
- rt._stickKnob = null;
109
+ function resetStick(state) {
110
+ state.began = false;
111
+ state.pointerId = null;
112
+ state.origin = null;
113
+ state.knob = null;
114
114
  }
115
115
 
116
116
  export class AnalogStick {
@@ -137,6 +137,8 @@ export class AnalogStick {
137
137
  maxRadius: { min: 10, step: 5 },
138
138
  };
139
139
 
140
+ static initialState = { began: false, pointerId: null, origin: null, knob: null };
141
+
140
142
  constructor(props) {
141
143
  this.props = props;
142
144
  }
@@ -146,44 +148,44 @@ export class AnalogStick {
146
148
  // second finger elsewhere (another stick, a drag) never yanks it -- and it
147
149
  // gives the pointer up if a targeted control outranks its claim.
148
150
  trackedPointer(actor, scene) {
149
- const rt = actor.runtime;
150
- if (rt._stickPointerId != null && scene.ownsPointer(rt._stickPointerId, actor.id)) {
151
- const held = scene.pointers.get(rt._stickPointerId);
151
+ const state = this.state;
152
+ if (state.pointerId != null && scene.ownsPointer(state.pointerId, actor.id)) {
153
+ const held = scene.pointers.get(state.pointerId);
152
154
  if (held?.down) return held;
153
155
  }
154
- rt._stickPointerId = null;
156
+ state.pointerId = null;
155
157
  // Any fresh press will do -- the stick is placed wherever you touch -- but
156
158
  // only one nobody more specific wants.
157
159
  const press = acquirePress(scene, actor.id, () => GREEDY_CLAIM);
158
160
  if (!press) return null;
159
- rt._stickPointerId = press.id;
160
- rt._stickOrigin = { x: press.screenX, y: press.screenY };
161
+ state.pointerId = press.id;
162
+ state.origin = { x: press.screenX, y: press.screenY };
161
163
  return press;
162
164
  }
163
165
 
164
166
  update(actor, scene, dt) {
165
- const rt = actor.runtime;
167
+ const state = this.state;
166
168
  const p = this.trackedPointer(actor, scene);
167
- if (p?.down && rt._stickOrigin) {
169
+ if (p?.down && state.origin) {
168
170
  const maxRadius = this.props.maxRadius ?? 60;
169
171
  const sp = screenPoint(p);
170
- const knob = stickVector(sp, rt._stickOrigin, maxRadius);
171
- rt._stickKnob = knob;
172
+ const knob = stickVector(sp, state.origin, maxRadius);
173
+ state.knob = knob;
172
174
  const deflection = { x: knob.x / maxRadius, y: knob.y / maxRadius };
173
175
  const vel = scene.physics.getVelocity(actor);
174
176
  scene.physics.applyImpulse(actor, stickDrive(vel, deflection, this.props, dt));
175
177
  // OG fires on first movement, not on a still press.
176
- if (!rt._stickBegan && length(deflection) > 0) {
177
- rt._stickBegan = true;
178
+ if (!state.began && length(deflection) > 0) {
179
+ state.began = true;
178
180
  fireStickHook(actor, scene, 'onAnalogStickBegin');
179
181
  }
180
182
  return;
181
183
  }
182
184
 
183
- if (rt._stickBegan) {
185
+ if (state.began) {
184
186
  fireStickHook(actor, scene, 'onAnalogStickEnd');
185
187
  }
186
- clearStickRuntime(rt);
188
+ resetStick(state);
187
189
  // Idle every frame: brake on driven axes only (gravity/momentum elsewhere stay).
188
190
  const vel = scene.physics.getVelocity(actor);
189
191
  scene.physics.applyImpulse(actor, stickBrake(vel, this.props, dt));
@@ -192,18 +194,18 @@ export class AnalogStick {
192
194
  // Switched off mid-hold: fire end and drop runtime state. `update` stops
193
195
  // running once disabled, so this is the only chance to release the gesture.
194
196
  onDisable(actor, scene) {
195
- const rt = actor.runtime;
196
- if (rt._stickBegan) fireStickHook(actor, scene, 'onAnalogStickEnd');
197
- clearStickRuntime(rt);
197
+ const state = this.state;
198
+ if (state.began) fireStickHook(actor, scene, 'onAnalogStickEnd');
199
+ resetStick(state);
198
200
  }
199
201
 
200
202
  // Drawn in screen space (drawUi) so the ring stays under the thumb while the
201
203
  // camera scrolls, and doesn't rotate with the actor.
202
204
  drawUi(actor, scene, ctx) {
203
- const rt = actor.runtime;
204
- if (!rt._stickOrigin) return;
205
- const o = rt._stickOrigin;
206
- const k = rt._stickKnob ?? { x: 0, y: 0 };
205
+ const state = this.state;
206
+ if (!state.origin) return;
207
+ const o = state.origin;
208
+ const k = state.knob ?? { x: 0, y: 0 };
207
209
  const radius = this.props.maxRadius ?? 60;
208
210
  ctx.strokeStyle = 'rgba(255, 255, 255, 0.5)';
209
211
  ctx.lineWidth = 3;
@@ -37,6 +37,8 @@ export class Draggable {
37
37
  stiffness: UNIT,
38
38
  };
39
39
 
40
+ static initialState = { pointerId: null };
41
+
40
42
  constructor(props) {
41
43
  this.props = props;
42
44
  }
@@ -45,19 +47,19 @@ export class Draggable {
45
47
  // the sole caller of `release`, and it stops running the moment the behavior
46
48
  // is disabled. Without this the actor stays welded to the pointer.
47
49
  onDisable(actor, scene) {
48
- if (actor.runtime._dragPointerId == null) return;
50
+ if (this.state.pointerId == null) return;
49
51
  scene.physics.release(actor);
50
- actor.runtime._dragPointerId = null;
52
+ this.state.pointerId = null;
51
53
  }
52
54
 
53
55
  update(actor, scene) {
54
- const rt = actor.runtime;
55
- const held = rt._dragPointerId == null ? null : scene.pointers.get(rt._dragPointerId);
56
+ const state = this.state;
57
+ const held = state.pointerId == null ? null : scene.pointers.get(state.pointerId);
56
58
 
57
59
  // The finger that started this drag lifted (or its contact was cancelled).
58
- if (rt._dragPointerId != null && !held?.down) {
60
+ if (state.pointerId != null && !held?.down) {
59
61
  scene.physics.release(actor);
60
- rt._dragPointerId = null;
62
+ state.pointerId = null;
61
63
  return;
62
64
  }
63
65
  if (held) return scene.physics.moveGrab(actor, held.x, held.y);
@@ -73,7 +75,7 @@ export class Draggable {
73
75
  // merely takes presses anywhere -- whatever order the actors update in.
74
76
  if (!scene.claimPointer(p.id, actor.id, TARGETED_CLAIM)) continue;
75
77
  if (scene.physics.grab(actor, p.x, p.y, dragHold(this.props.stiffness))) {
76
- rt._dragPointerId = p.id;
78
+ state.pointerId = p.id;
77
79
  }
78
80
  return;
79
81
  }
@@ -86,7 +88,7 @@ export class Draggable {
86
88
  // physics holds the object and tracks it through rotation. Drawn in world
87
89
  // space so the overlay itself doesn't spin with the actor.
88
90
  draw(actor, scene, ctx) {
89
- const id = actor.runtime._dragPointerId;
91
+ const id = this.state.pointerId;
90
92
  if (id == null) return;
91
93
  const handle = scene.physics.grabPoint(actor);
92
94
  const touch = scene.pointers.get(id);
@@ -10,20 +10,33 @@ export class Goal {
10
10
 
11
11
  static defaultProps = {};
12
12
 
13
+ static initialState = { scored: 0, flashUntil: 0 };
14
+
13
15
  constructor(props) {
14
16
  this.props = props;
15
17
  }
16
18
 
17
19
  onCollisionEnter(actor, scene, other) {
18
20
  if (!other.components.RigidBody) return; // only score moving bodies
19
- actor.runtime.scored = (actor.runtime.scored ?? 0) + 1;
20
- actor.runtime.flashUntil = scene.time + 0.6;
21
+ this.score();
22
+ }
23
+
24
+ // Public method other behaviors can call directly:
25
+ // `other.behaviors.Goal?.score()`. A pure refactor of the old
26
+ // onCollisionEnter body -- same increment, same flash window.
27
+ score() {
28
+ this.state.scored += 1;
29
+ this.state.flashUntil = this.scene.time + 0.6;
30
+ // Kept as the older spelling -- a deck reading `goal.runtime.scored` or
31
+ // `.flashUntil` (where this lived before `this.state`) still sees them.
32
+ this.actor.runtime.scored = this.state.scored;
33
+ this.actor.runtime.flashUntil = this.state.flashUntil;
21
34
  }
22
35
 
23
36
  draw(actor, scene, ctx) {
24
37
  const box = layoutRect(actor.components.Layout);
25
38
  if (!box) return;
26
- const lit = (actor.runtime.flashUntil ?? 0) > scene.time;
39
+ const lit = this.state.flashUntil > scene.time;
27
40
  ctx.save();
28
41
  ctx.strokeStyle = lit ? '#5ac54f' : 'rgba(255, 235, 87, 0.9)';
29
42
  ctx.lineWidth = 4;
@@ -38,14 +38,16 @@ export class Slingshot {
38
38
  maxDrag: PIXELS,
39
39
  };
40
40
 
41
+ static initialState = { slinging: false, pointerId: null, anchor: null, aim: null };
42
+
41
43
  constructor(props) {
42
44
  this.props = props;
43
45
  }
44
46
 
45
47
  update(actor, scene) {
46
- const rt = actor.runtime;
48
+ const state = this.state;
47
49
 
48
- if (!rt._slinging) {
50
+ if (!state.slinging) {
49
51
  const grabAnywhere = this.props.grabAnywhere ?? true;
50
52
  const press = acquirePress(scene, actor.id, (p) => {
51
53
  // Collider-accurate, at the body's live orientation -- the same pick
@@ -57,30 +59,30 @@ export class Slingshot {
57
59
  return onSelf ? TARGETED_CLAIM : GREEDY_CLAIM;
58
60
  });
59
61
  if (press) {
60
- rt._slingPointerId = press.id;
61
- rt._slinging = true;
62
+ state.pointerId = press.id;
63
+ state.slinging = true;
62
64
  // Anchor at the press point (like castle-client): the aim/launch depends
63
65
  // on the drag gesture, not where the press landed relative to the actor.
64
- rt._slingAnchor = { x: press.x, y: press.y };
66
+ state.anchor = { x: press.x, y: press.y };
65
67
  // A same-frame tap (down already false) is not an aim — cancel before we
66
68
  // can launch with a zero pull. A TARGETED control that updates later this
67
69
  // frame may still steal a greedy claim; we must not freeze velocity yet.
68
70
  if (!press.down) {
69
- rt._slinging = false;
70
- rt._slingPointerId = null;
71
+ state.slinging = false;
72
+ state.pointerId = null;
71
73
  return;
72
74
  }
73
75
  }
74
76
  }
75
- if (!rt._slinging) return;
77
+ if (!state.slinging) return;
76
78
 
77
- const p = scene.pointers.get(rt._slingPointerId);
79
+ const p = scene.pointers.get(state.pointerId);
78
80
  // Outranked mid-aim, or the contact was cancelled: drop the shot rather than
79
81
  // launching from an anchor the player has stopped steering.
80
- if (!p || !scene.ownsPointer(rt._slingPointerId, actor.id)) {
81
- rt._slinging = false;
82
- rt._slingPointerId = null;
83
- rt._slingAim = null;
82
+ if (!p || !scene.ownsPointer(state.pointerId, actor.id)) {
83
+ state.slinging = false;
84
+ state.pointerId = null;
85
+ state.aim = null;
84
86
  return;
85
87
  }
86
88
 
@@ -91,22 +93,22 @@ export class Slingshot {
91
93
  // and then drop the shot with no launch. Matches claimPointer's contract
92
94
  // that the press frame costs a greedy control nothing visible.
93
95
  if (!p.justPressed) scene.physics.setVelocity(actor, { x: 0, y: 0 });
94
- rt._slingAim = { x: p.x, y: p.y };
96
+ state.aim = { x: p.x, y: p.y };
95
97
  } else {
96
- scene.physics.setVelocity(actor, slingLaunch(rt._slingAnchor, p, this.props));
97
- rt._slinging = false;
98
- rt._slingPointerId = null;
99
- rt._slingAim = null;
98
+ scene.physics.setVelocity(actor, slingLaunch(state.anchor, p, this.props));
99
+ state.slinging = false;
100
+ state.pointerId = null;
101
+ state.aim = null;
100
102
  }
101
103
  }
102
104
 
103
105
  // Aim overlay in the castle-client style: a translucent grab circle plus a
104
106
  // line + arrowhead pointing in the launch direction (opposite the pull).
105
107
  draw(actor, scene, ctx) {
106
- const rt = actor.runtime;
107
- if (!rt._slinging || !rt._slingAim) return;
108
- const a = rt._slingAnchor;
109
- const pull = slingPull(a, rt._slingAim, this.props.maxDrag ?? 160);
108
+ const state = this.state;
109
+ if (!state.slinging || !state.aim) return;
110
+ const a = state.anchor;
111
+ const pull = slingPull(a, state.aim, this.props.maxDrag ?? 160);
110
112
  const len = Math.hypot(pull.x, pull.y);
111
113
  if (len < 0.001) return;
112
114
  const dir = { x: -pull.x / len, y: -pull.y / len }; // launch direction (opposite pull)
@@ -21,11 +21,16 @@ import { PAN, UNIT } from '../engine/propertyRanges';
21
21
  // playing again restarts it rather than overlapping.
22
22
  //
23
23
  // Set `playOnStart` and it plays when the scene starts. Either way you can
24
- // trigger it from a behavior, through the handle this puts on the actor:
24
+ // trigger it from a behavior:
25
+ //
26
+ // scene.getActor('music').behaviors.SoundPlayer.play();
27
+ // await actor.behaviors.SoundPlayer.play(); // ...and wait for it to end
28
+ // actor.behaviors.SoundPlayer.stop();
29
+ //
30
+ // `actor.runtime.soundPlayer` still holds the handle too (the older spelling,
31
+ // still written every `update`):
25
32
  //
26
33
  // scene.getActor('music').runtime.soundPlayer.play();
27
- // await actor.runtime.soundPlayer.play(); // ...and wait for it to end
28
- // actor.runtime.soundPlayer.stop();
29
34
  //
30
35
  // To fire a sound effect that no actor owns -- most of them -- don't place one of
31
36
  // these at all. `scene.sound.play('hit')` needs no actor and no import.
@@ -60,24 +65,56 @@ export class SoundPlayer {
60
65
  pan: PAN,
61
66
  };
62
67
 
68
+ static initialState = { handle: null };
69
+
63
70
  constructor(props) {
64
71
  this.props = props;
65
72
  }
66
73
 
67
74
  update(actor) {
68
- if (!actor.runtime || actor.runtime.collected) return;
75
+ if (actor.runtime.collected) return;
69
76
  const file = resolveDeckFile(this.props.file);
70
77
  const settings = readSettings(this.props);
71
- const previous = actor.runtime.soundPlayer;
78
+ const previous = this.state.handle;
72
79
  const handle = settings.stream
73
80
  ? streamHandleFor(actor.id, file, settings, previous)
74
81
  : bufferHandleFor(file, settings, previous);
82
+ this.state.handle = handle;
83
+ // Kept as the older spelling -- `scene.getActor('music').runtime.soundPlayer`
84
+ // still works alongside `.behaviors.SoundPlayer`.
75
85
  actor.runtime.soundPlayer = handle;
76
86
  // Only a NEW handle starts itself: this runs every frame, and `playOnStart`
77
87
  // means the start of the scene, not the start of each one.
78
88
  if (handle && handle !== previous && this.props.playOnStart) void handle.play();
79
89
  }
80
90
 
91
+ // Instance methods so `actor.behaviors.SoundPlayer.play()` works, delegating
92
+ // to whatever handle `update` last built. Before the first `update()` runs
93
+ // (frame 0, before any `update` has ticked -- see engine/scene.js's ordering,
94
+ // taps are processed before per-actor updates) `this.state.handle` is still
95
+ // null, so these are no-ops that frame; a pre-existing race (the old code had
96
+ // the identical gap via `actor.runtime.soundPlayer` being undefined until the
97
+ // first `update`), not a regression.
98
+ play() {
99
+ return this.state.handle?.play();
100
+ }
101
+
102
+ stop() {
103
+ this.state.handle?.stop();
104
+ }
105
+
106
+ pause() {
107
+ this.state.handle?.pause();
108
+ }
109
+
110
+ resume() {
111
+ this.state.handle?.resume();
112
+ }
113
+
114
+ get playing() {
115
+ return this.state.handle?.playing ?? false;
116
+ }
117
+
81
118
  static Inspector({ component, setComponent, override }) {
82
119
  // `loop` is an element's, not a buffer's -- a decoded one-shot has no loop
83
120
  // in v0. Hiding it rather than showing a dead control is the difference