castle-web-cli 0.4.128 → 0.4.130

package/kits/physics-2d/engine/ui.module.css

@@ -1072,7 +1072,8 @@
 
 .fieldRowOverridden .input,
 .fieldRowOverridden .select,
-.fieldRowOverridden .colorInput {
+.fieldRowOverridden .colorInput,
+.fieldRowOverridden .checkbox {
   border-color: var(--castle-override-border);
 }
 
@@ -1084,6 +1085,25 @@
   padding-bottom: 4px;
 }
 
+/* A muted line of explanation under a field, sitting in the control column the
+   same way the override sub-line above does. For a prop whose name can't carry
+   its own meaning -- see `hint` in a behavior's propertyMeta. */
+.fieldNote {
+  display: grid;
+  grid-template-columns: minmax(82px, 0.5fr) minmax(0, 1fr);
+  gap: 12px;
+  margin-top: -6px;
+  padding-bottom: 12px;
+}
+
+.fieldNoteInner {
+  grid-column: 2;
+  min-width: 0;
+  font-size: 12px;
+  line-height: 1.35;
+  color: var(--castle-inspector-muted);
+}
+
 .fieldDefault {
   display: grid;
   grid-template-columns: minmax(82px, 0.5fr) minmax(0, 1fr);
@@ -1143,6 +1163,64 @@
   text-overflow: ellipsis;
 }
 
+.fileField {
+  display: flex;
+  align-items: center;
+  font: inherit;
+  box-shadow: none;
+  cursor: pointer;
+}
+
+.fileFieldLabel {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.fileFieldEmpty {
+  color: var(--castle-inspector-muted);
+}
+
+.filePicker {
+  position: fixed;
+  z-index: 200;
+  box-sizing: border-box;
+  max-height: min(240px, calc(100vh - 16px));
+  overflow: auto;
+  padding: 4px;
+  border: 1px solid var(--castle-inspector-border);
+  border-radius: var(--castle-radius);
+  background: var(--castle-workspace-bg);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.28);
+}
+
+.filePickerOption {
+  display: block;
+  width: 100%;
+  overflow: hidden;
+  text-align: left;
+  border: 0;
+  border-radius: 3px;
+  background: transparent;
+  color: var(--castle-inspector-text);
+  font: inherit;
+  font-size: 13px;
+  padding: 6px 8px;
+  cursor: pointer;
+}
+
+.filePickerPath {
+  display: block;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.filePickerOption:hover,
+.filePickerOptionSelected {
+  background: var(--castle-inspector-input-bg);
+}
+
 .numberField {
   position: relative;
   width: 100%;
@@ -1383,34 +1461,35 @@
   cursor: pointer;
 }
 
-.toggle {
-  width: 44px;
-  height: 24px;
+.checkbox {
+  width: 20px;
+  height: 20px;
+  flex: 0 0 auto;
+  justify-self: end;
   border: 1px solid var(--castle-inspector-border);
-  border-radius: 999px;
+  border-radius: var(--castle-radius);
   background: var(--castle-inspector-input-bg);
-  padding: 2px;
+  padding: 0;
   cursor: pointer;
   display: flex;
   align-items: center;
-  justify-content: flex-start;
+  justify-content: center;
   box-shadow: none;
+  color: var(--castle-text);
 }
 
-.toggleOn {
+.checkboxOn {
   background: var(--castle-black);
-  justify-content: flex-end;
 }
 
-.toggleKnob {
-  width: 18px;
-  height: 18px;
-  border-radius: 999px;
-  background: var(--castle-inspector-muted);
+.checkboxMark {
+  display: none;
+  width: 12px;
+  height: 12px;
 }
 
-.toggleOn .toggleKnob {
-  background: var(--castle-text);
+.checkboxOn .checkboxMark {
+  display: block;
 }
 
 .textarea {
@@ -1471,6 +1550,11 @@
   cursor: default;
 }
 
+.button:disabled:hover,
+.iconButton:disabled:hover {
+  background: var(--castle-inspector-button-bg);
+}
+
 .actorList {
   display: grid;
   gap: 4px;
@@ -1529,6 +1613,13 @@
   display: none;
 }
 
+/* Read-only paint/inspector chrome: still there so the layout doesn't jump,
+   but clearly not interactive. */
+.drawingReadOnly {
+  opacity: 0.45;
+  pointer-events: none;
+}
+
 /* Stack the tool rail and the undo/redo rail vertically (the shared rule above is
    a flex row, which pushed the second rail out of the 50px column). */
 .artboardToolColumn {
@@ -1642,6 +1733,22 @@
   color: var(--castle-selected-ink);
 }
 
+.finishSegment:disabled {
+  cursor: default;
+  opacity: 0.4;
+}
+
+.finishSegment:disabled:hover {
+  background: var(--castle-inspector-button-bg);
+}
+
+.finishSegment.finishSegmentOn:disabled,
+.finishSegment.finishSegmentOn:disabled:hover {
+  opacity: 0.85;
+  background: var(--castle-selected);
+  color: var(--castle-selected-ink);
+}
+
 .canvasSizeSep {
   color: var(--castle-inspector-muted);
   user-select: none;
@@ -1663,6 +1770,12 @@
   background-position: right 6px center;
 }
 
+.canvasSizeSelect:disabled {
+  opacity: 0.55;
+  cursor: default;
+  color: var(--castle-inspector-muted);
+}
+
 .pxArtInspector {
   min-width: 0;
   border-left: 1px solid var(--castle-inspector-divider);
@@ -2042,6 +2155,14 @@
   cursor: default;
 }
 
+.drawingToolButton.drawingToolSelected:disabled {
+  opacity: 0.7;
+}
+
+.drawingToolButton:disabled:hover {
+  background: var(--castle-inspector-button-bg);
+}
+
 /* Active / selected square icon button -- the eyedropper reference: a light
    fill with a dark glyph. The single selected/engaged look shared by the
    IconButton component (`active`), the onion-skin toggle, and the pixel

package/kits/physics-2d/scripts/testsounds.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Generate audio to develop the sound library against, so the kit can be
+// exercised without committing binaries to it.
+//
+//   node scripts/testsounds.mjs            # into this kit
+//   node scripts/testsounds.mjs ../../some-deck
+//   node scripts/testsounds.mjs . --dup    # also a clashing stem, to see the warning
+//   node scripts/testsounds.mjs . --long   # also a 20s file INSIDE assets/sounds/
+//
+// Writes 16-bit mono PCM wavs. The cases are chosen to be awkward on purpose: a
+// 10ms click is shorter than a frame, and the drone is long enough that decoding
+// it into memory is the wrong thing -- which is what `assets/music/` is for.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const RATE = 22050;
+
+function wav(samples) {
+  const data = Buffer.alloc(samples.length * 2);
+  for (let i = 0; i < samples.length; i++) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]));
+    data.writeInt16LE(Math.round(clamped * 32767), i * 2);
+  }
+  const header = Buffer.alloc(44);
+  header.write('RIFF', 0);
+  header.writeUInt32LE(36 + data.length, 4);
+  header.write('WAVE', 8);
+  header.write('fmt ', 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20); // PCM
+  header.writeUInt16LE(1, 22); // mono
+  header.writeUInt32LE(RATE, 24);
+  header.writeUInt32LE(RATE * 2, 28);
+  header.writeUInt16LE(2, 32);
+  header.writeUInt16LE(16, 34);
+  header.write('data', 36);
+  header.writeUInt32LE(data.length, 40);
+  return Buffer.concat([header, data]);
+}
+
+// `shape(t, i)` gets seconds elapsed and the sample index, and returns -1..1.
+function render(seconds, shape) {
+  const total = Math.max(1, Math.round(seconds * RATE));
+  const samples = new Float32Array(total);
+  for (let i = 0; i < total; i++) samples[i] = shape(i / RATE, i);
+  return samples;
+}
+
+const decay = (t, seconds) => Math.max(0, 1 - t / seconds);
+const tone = (t, hz) => Math.sin(2 * Math.PI * hz * t);
+const noise = () => Math.random() * 2 - 1;
+
+const SOUNDS = {
+  // A rising blip: the ordinary pickup / UI confirmation.
+  'assets/sounds/blip.wav': render(0.12, (t) => tone(t, 660 + t * 1800) * decay(t, 0.12) * 0.7),
+  // A low thump with a noise transient, for an impact.
+  'assets/sounds/thud.wav': render(0.2, (t) => (tone(t, 90) * 0.8 + noise() * 0.25) * decay(t, 0.2) ** 2),
+  // 10ms -- shorter than a frame at 60fps, and shorter than most scheduling
+  // slop. If anything in the pipeline rounds or defers, this is what shows it.
+  'assets/sounds/click.wav': render(0.01, (t) => noise() * decay(t, 0.01)),
+  // Long, and deliberately OUTSIDE assets/sounds/: 20s decoded is ~3.5MB here and
+  // would be ~70MB as 44.1kHz stereo float. This is the streaming case.
+  'assets/music/drone.wav': render(20, (t) => (tone(t, 110) * 0.5 + tone(t, 165) * 0.3) * 0.5),
+};
+
+const args = process.argv.slice(2);
+const target = resolve(args.find((a) => !a.startsWith('--')) ?? '.');
+const extras = {};
+if (args.includes('--dup')) {
+  // Same stem as assets/sounds/click.wav, so `play('click')` becomes ambiguous.
+  extras['assets/sounds/ui/click.wav'] = render(0.03, (t) => tone(t, 1200) * decay(t, 0.03) * 0.5);
+}
+if (args.includes('--long')) {
+  extras['assets/sounds/toolong.wav'] = render(20, (t) => tone(t, 220) * 0.4 * decay(t, 20));
+}
+
+for (const [relative, samples] of Object.entries({ ...SOUNDS, ...extras })) {
+  const path = join(target, relative);
+  mkdirSync(dirname(path), { recursive: true });
+  const bytes = wav(samples);
+  writeFileSync(path, bytes);
+  console.log(`${relative}  ${(bytes.length / 1024).toFixed(1)}KB  ${(samples.length / RATE).toFixed(2)}s`);
+}

package/kits/physics-2d/systems/media.js

@@ -1,29 +1,45 @@
-// Registers sound / video playback as a runtime system. Auto-discovered by
+// Registers audio / video playback as a runtime system. Auto-discovered by
 // engine/systemRegistry.js (`systems/*.js`) and invoked by makeScene, so the
-// media pool plugs in without the shared engine referencing it.
+// playback machinery plugs in without the shared engine referencing it.
 //
-// The system owns the LIFECYCLE only -- behaviors decide what plays. It reaps
-// idle elements once a frame (a despawned actor's sound stops), and silences
-// everything on `reset` (a scene load / restart / transition) and on `dispose`
-// (the player unmounting, i.e. pressing Stop).
+// Two things play sound in this kit and this is the one place that knows about
+// both: `engine/media.js` streams an `<audio>` / `<video>` element (long tracks,
+// video), and `engine/sound.js` fires decoded buffers (sound effects). They share
+// one AudioContext and are silenced together.
 //
-// It also puts `scene.sound` on the runtime: the scene-wide controls, which
-// belong to nobody's actor.
+// The system owns the LIFECYCLE only -- behaviors and game code decide what
+// plays. It reaps idle elements once a frame (a despawned actor's sound stops),
+// and silences everything on `reset` (a scene load / restart / transition) and on
+// `dispose` (the player unmounting, i.e. pressing Stop).
+//
+// It also puts `scene.sound` on the runtime: the sound library itself, so a
+// behavior can `scene.sound.play('hit')` with no import, plus the scene-wide
+// controls, which belong to nobody's actor.
 
+import { initialMedia, mediaFilesOfKind } from '../engine/files';
 import { reapUnusedMedia, stopAllMedia } from '../engine/media';
-import { stopAllTones } from '../engine/tone';
+import { Sound, initSounds, stopAllSounds } from '../engine/sound';
+
+// Preloading is the DECK's, not a scene's, so it starts here at module load
+// rather than per-runtime -- the editor builds a throwaway runtime every frame
+// to draw its preview, and decoding the deck's sounds sixty times a second is
+// not a thing to do. Vite evaluates a module once, which is exactly the scope
+// wanted.
+initSounds(
+  Object.fromEntries(mediaFilesOfKind('audio').map((path) => [path, initialMedia[path]]))
+);
 
 function silence() {
   stopAllMedia();
-  stopAllTones();
+  stopAllSounds();
 }
 
 export function installSystem(runtime) {
-  runtime.sound = {
-    // Everything this scene is playing, off. The blunt instrument for a game
-    // over, a pause, or leaving a level: individual actors need not be found.
-    stopAll: silence,
-  };
+  // The library itself, with `stopAll` widened to mean everything the scene is
+  // playing rather than just its sound effects. Delegating through the prototype
+  // rather than copying keeps `isLoaded` a live getter (a spread would snapshot
+  // it as false forever) and keeps the two in step as the library grows.
+  runtime.sound = Object.create(Sound, { stopAll: { value: silence, enumerable: true } });
   runtime.registerSystem({
     afterBehaviors(scene) {
       reapUnusedMedia(new Set(scene.actors.keys()));

package/kits/physics-3d/CLAUDE.md

@@ -0,0 +1,109 @@
+# physics-3d kit
+
+A 3D actor/behavior kit: three.js rendering with PBR lighting and rapier
+physics, built ON TOP of the `physics-2d` kit as an import. The actor /
+behavior / scene / blueprint model, deck file map, live reload, and the
+`.pxart` pixel-art pipeline (including its editor) all come from
+`imports/castle.physics-2d/` and work exactly as that kit's CLAUDE.md
+describes. This file covers what is different in 3D.
+
+## Quick reference
+
+<!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
+
+- 3D actor / behavior / scene framework: three.js + rapier, 1 unit = 1 meter,
+  y up. Scenes are `scenes/*.scene` (blueprints too, under `blueprints/`),
+  behaviors `behaviors/*.jsx` -- same JSON shapes as physics-2d, but the
+  component vocabulary is 3D (`Transform`, `Shape`, `Body`, `Solid`, ...).
+- Every actor needs a `Transform` (`x/y/z`, `rotationX/Y/Z` in degrees).
+  Every Transform actor gets a rapier body automatically -- fixed by default,
+  `Body { type: 'dynamic' }` to be simulated, `'kinematic'` to be unpushable
+  but follow Transform edits (doors, platforms).
+- Colliders come from `Shape` and are **sensors unless solid**: add a
+  `Solid {}` behavior (or `Shape.solid: true`) to block; leave it off for
+  pickups / trigger zones. Behaviors get `onCollisionEnter(actor, scene,
+other)` / `onCollisionExit` for both contacts and sensor overlaps.
+- `Shape`: `kind` `'box' | 'sphere' | 'capsule' | 'cylinder'` with
+  `width/height/depth` or `radius`, PBR knobs (`color`, `roughness`,
+  `metalness`, `clearcoat`, `emissive`, `emissiveIntensity`), and `art` -- a
+  `.pxart`/image path baked as a nearest-filtered albedo map. On boxes `art`
+  may be a per-face object `{ all, sides, front, back, left, right, top,
+bottom }`; any ref can pick a frame of a multi-frame pxart with
+  `path#<frame>`. A flat `color` with no art is a fine look.
+- Motion goes through `scene.physics3d`, never by writing a dynamic actor's
+  Transform: `setVelocity(actor, {x,y,z})`, `applyImpulse`, `getVelocity`,
+  `mass`, `castRay(origin, dir, maxToi, excludeActor)` (rays skip sensors).
+  Fixed/kinematic actors ARE moved by writing their Transform.
+- The scene has the lighting rig built in (hemisphere + ambient + one
+  shadow-casting sun, ground plane at y=0); meshes cast and receive shadows
+  automatically. Don't add your own lights for a normal scene.
+- Built-in gameplay behaviors: `Player` (WASD/arrows move, space jumps,
+  drag orbits the camera, faux-isometric follow cam), `Pickup` (sensor
+  collectible -> player score), `Door` (kinematic slide-up when the player is
+  near), `Lookable { text }` (hud caption when the player faces it nearby).
+- Hud: behaviors write `scene.hud = { score, look }`; the player behavior
+  already does.
+- Scene switching: place a `Portal { scene: 'scenes/other.scene' }` actor (a
+  sensor -- the portal blueprint is a glowing ring), or set
+  `scene.requestedScene = 'scenes/other.scene'` from any behavior (applied
+  between frames; safer than calling `scene.loadFromFile` mid-callback). A
+  load rebuilds the physics world and resets the scene to its authored state;
+  `scene.persistent` survives loads -- the player's score, collected-pickup
+  memory, and camera angle live there, so they cross scenes.
+- A scene can dress the ground: `"ground": { "art": "drawings/floor.pxart",
+"tile": 2, "color": "#..." }` at the scene file's top level (`tile` = meters
+  per texture repeat). `Shape.artRepeat: [u, v]` tiles a texture across a
+  face so long walls don't stretch.
+- `.scene` files open in the kit's 3d scene editor (same chrome as the 2d
+  kit's): blueprint hotbar (tap to inspect/edit the template, drag onto the
+  stage to place), orbit camera (drag orbits, wheel zooms), click to select /
+  click again to cycle / shift to multi-select, move & rotate gizmos (keys
+  1/2/3 pick select/move/rotate), floating clone/delete toolbar on the
+  selection, behavior-panel inspector with instance-override tints, undo/redo
+  (cmd+z / cmd+shift+z), cmd+d duplicate, delete key removes. `.pxart` opens
+  in the imported pixel-art editor.
+- Blueprint thumbnails in the hotbar / inspector are live 3d corner-view
+  renders of each template (engine3d/thumbnails.js) -- no icon data needed on
+  the blueprint.
+- 3d models are `.pxmodel` files under `models/` -- part-based JSON (named
+  primitive parts with hierarchy, per-part material/art), spec in
+  docs/pxmodel-format.md. A `Model` behavior (`{ file, scale, yOffset }`)
+  renders one instead of the Shape mesh; part ids legL/legR/armL/armR/torso
+  walk-animate automatically from observed motion. `.pxmodel` opens in the
+  kit's model editor (parts list, gizmos, part inspector, walk preview);
+  `scenes/model-lab.scene` is an all-model scene for trying it.
+- Controls are tank-style: W/S (or up/down) walk forward/back along facing,
+  A/D (or left/right) turn; a pointer/touch drag is a virtual stick where the
+  drag angle blends walking and turning. Space jumps.
+- After any edit: `npm run restart`. After a coherent change: `npm run check`
+  (lint + duplicate gate + single-file bundle) must pass.
+
+## What lives where
+
+- `engine3d/` -- the renderer (`world3d.js`, vase-style rig: PCFSoft shadows,
+  EffectComposer RenderPass + OutputPass), `materials.js` (pxart -> albedo
+  textures, per-face box materials), `Scene3DPlayer.jsx` / `PlayOnly3D.jsx`
+  (the play mount). Internal; behaviors shouldn't import from here.
+- `systems/physics3d.js` -- the rapier system, auto-discovered by the imported
+  engine's `systems/*.js` seam. Fixed 1/60 step, body-per-actor reconcile,
+  collision/overlap events, `scene.physics3d` API.
+- `behaviors/` -- the 3D component vocabulary plus gameplay behaviors. Same
+  rules as physics-2d: `static behaviorName`, `defaultProps`, per-frame
+  instances (state on `actor.runtime`).
+- `imports/castle.physics-2d/` -- read-only. Its engine modules are imported
+  directly (scene runtime, files, live reload, pxart, art, behavior
+  registry); its 2D-only pieces (canvas ScenePlayer, matter physics, 2D
+  editors other than pxart) are present but unused here.
+
+## Known state / caveats
+
+- The 2D kit's behaviors (Layout, Sprite, Collider, RigidBody, ...) are still
+  in the behavior registry via the import's root-anchored globs, and its
+  matter-js system installs (idle) into every runtime. Harmless but present;
+  don't attach 2D components to 3D actors.
+- Transform is the source of truth: dynamic bodies write back position (and
+  rotation unless `lockRotations`), fixed/kinematic bodies follow Transform.
+  A locked-rotation dynamic actor (the player) keeps `rotationY` free for
+  facing.
+- Space is bound to jump in this kit (unlike physics-2d, where the editor
+  reserves it).

package/kits/physics-3d/behaviors/Body.jsx

@@ -0,0 +1,51 @@
+// Physics options. Every actor with a Transform gets a rapier body whether or
+// not it carries this behavior -- fixed by default. Add a Body to opt into
+// motion: 'dynamic' is simulated (gravity, pushes), 'kinematic' is unpushable
+// but follows Transform edits with proper contact resolution (moving doors,
+// platforms). `lockRotations` keeps a dynamic body upright (characters).
+import React from 'react';
+import { SelectField } from '@imports/castle.physics-2d/engine/ui';
+import { AutoFields, overrideProps } from '@imports/castle.physics-2d/engine/autoInspector';
+
+const TYPE_OPTIONS = [
+  { value: 'fixed', label: 'Fixed' },
+  { value: 'dynamic', label: 'Dynamic' },
+  { value: 'kinematic', label: 'Kinematic' },
+];
+
+function BodyInspector({ component, setComponent, override }) {
+  return (
+    <>
+      <SelectField
+        label="Type"
+        value={component.type}
+        options={TYPE_OPTIONS}
+        onChange={(type) => setComponent({ type })}
+        {...overrideProps(override, 'type')}
+      />
+      <AutoFields
+        defaultProps={Body.defaultProps}
+        component={component}
+        setComponent={setComponent}
+        exclude={['type']}
+        override={override}
+      />
+    </>
+  );
+}
+
+export class Body {
+  static Inspector = BodyInspector;
+  static behaviorName = 'Body';
+  static defaultProps = {
+    type: 'fixed', // 'fixed' | 'dynamic' | 'kinematic'
+    friction: 0.6,
+    restitution: 0,
+    gravityScale: 1,
+    lockRotations: false,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+}

package/kits/physics-3d/behaviors/Door.jsx

@@ -0,0 +1,31 @@
+// A sliding door: solid, kinematic, and opens (slides up) while the player is
+// within range. Motion is written to the Transform; the physics system feeds
+// it to the kinematic body so contacts resolve properly.
+export class Door {
+  static behaviorName = 'Door';
+  static defaultProps = { range: 3, slide: 2.1, speed: 2.5 };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor, scene, dt) {
+    const player = scene.actorWith('Player');
+    const pt = player?.components.Transform;
+    const t = actor.components.Transform;
+    const rt = actor.runtime;
+    if (rt.openT === undefined) {
+      rt.openT = 0;
+      rt.baseY = t.y;
+    }
+    let target = 0;
+    if (pt) {
+      const dist = Math.hypot(pt.x - t.x, pt.z - t.z);
+      target = dist < this.props.range ? 1 : 0;
+    }
+    const delta = Math.sign(target - rt.openT) * this.props.speed * dt;
+    rt.openT = Math.max(0, Math.min(1, rt.openT + delta));
+    const eased = rt.openT * rt.openT * (3 - 2 * rt.openT);
+    t.y = rt.baseY + eased * this.props.slide;
+  }
+}

package/kits/physics-3d/behaviors/Lookable.jsx

@@ -0,0 +1,11 @@
+// Something the player can look at. When the player is near and facing this
+// actor, the hud shows `text`. Pure data -- the Player behavior does the
+// looking.
+export class Lookable {
+  static behaviorName = 'Lookable';
+  static defaultProps = { text: '', range: 4 };
+
+  constructor(props) {
+    this.props = props;
+  }
+}

package/kits/physics-3d/behaviors/Model.jsx

@@ -0,0 +1,14 @@
+// Render a `.pxmodel` (see docs/pxmodel-format.md) instead of the Shape mesh.
+// The Shape still provides the physics collider. `yOffset` places the model's
+// own origin relative to the actor's Transform -- e.g. -0.7 puts a
+// feet-at-zero model under a capsule whose center is the Transform. Models
+// with the walk part ids (legL/legR/armL/armR/torso) animate automatically
+// from how the actor actually moves.
+export class Model {
+  static behaviorName = 'Model';
+  static defaultProps = { file: '', scale: 1, yOffset: 0 };
+
+  constructor(props) {
+    this.props = props;
+  }
+}

package/kits/physics-3d/behaviors/Pickup.jsx

@@ -0,0 +1,39 @@
+// A collectible: bobs and spins in place, and despawns into the player's score
+// on touch. No Solid behavior, so its collider is a sensor -- it overlaps
+// instead of blocking, which is what fires onCollisionEnter here.
+//
+// Collection is remembered in the persistent store keyed by scene + actor id,
+// so walking back through a portal doesn't respawn (and double-count) shards
+// -- scene loads otherwise reset the world to its authored state.
+function pickupKey(scene, actor) {
+  return `${scene.currentScenePath ?? ''}:${actor.id}`;
+}
+
+export class Pickup {
+  static behaviorName = 'Pickup';
+  static defaultProps = { bob: 0.12, spin: 120 };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor, scene, dt) {
+    if (scene.persistent?.collected?.has(pickupKey(scene, actor))) {
+      scene.despawnActor(actor.id);
+      return;
+    }
+    const t = actor.components.Transform;
+    const rt = actor.runtime;
+    if (rt.baseY === undefined) rt.baseY = t.y;
+    t.y = rt.baseY + Math.sin(scene.time * 2.5) * this.props.bob;
+    t.rotationY += this.props.spin * dt;
+  }
+
+  onCollisionEnter(actor, scene, other) {
+    if (!other.components.Player) return;
+    const per = (scene.persistent ??= {});
+    per.score = (per.score ?? 0) + 1;
+    (per.collected ??= new Set()).add(pickupKey(scene, actor));
+    scene.despawnActor(actor.id);
+  }
+}