castle-web-cli 0.4.128 → 0.4.130

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

@@ -0,0 +1,172 @@
+// The walkable player: a dynamic locked-rotation capsule driven by impulses
+// (the vase floating-capsule controller), a faux-isometric follow camera, and
+// the "look at things" reading of nearby Lookables into the hud.
+//
+// Controls: WASD / arrows move (camera-relative), Q / E orbit the camera.
+// State lives on `actor.runtime` -- behavior instances are per-frame.
+
+const DEG = Math.PI / 180;
+
+function keyDown(keys, ...codes) {
+  return codes.some((code) => keys.has(code));
+}
+
+// Tank-style drive input: `forward` (-1..1) walks along the facing direction,
+// `turn` (-1..1) steers it. W/S (and up/down arrows) drive, A/D (and
+// left/right) turn. The pointer-drag stick maps the same way -- drag up walks,
+// drag sideways turns, and the drag ANGLE blends the two, so a diagonal drag
+// walks a curve and a pure sideways drag turns in place.
+// Keys turn a bit harder than a full stick deflection -- discrete input wants
+// the snappier response.
+const KEY_TURN = 1.35;
+
+function readDrive(keys, stick) {
+  let forward = 0;
+  let turn = 0;
+  if (keyDown(keys, 'KeyW', 'ArrowUp')) forward += 1;
+  if (keyDown(keys, 'KeyS', 'ArrowDown')) forward -= 1;
+  if (keyDown(keys, 'KeyD', 'ArrowRight')) turn += KEY_TURN;
+  if (keyDown(keys, 'KeyA', 'ArrowLeft')) turn -= KEY_TURN;
+  if (forward === 0 && turn === 0 && stick?.active && Math.hypot(stick.x, stick.y) >= 0.15) {
+    forward = -stick.y;
+    turn = stick.x;
+  }
+  return {
+    forward: Math.max(-1, Math.min(1, forward)),
+    turn: Math.max(-KEY_TURN, Math.min(KEY_TURN, turn)),
+  };
+}
+
+// Spring-hover the capsule a touch above the ground (smooths steps and edges);
+// returns whether the player counts as grounded. The spring stays out of the
+// way while the player is on the way up from a jump.
+function applyHover(phys, actor, t, dims, dt) {
+  const hit = phys.castRay({ x: t.x, y: t.y, z: t.z }, { x: 0, y: -1, z: 0 }, dims.height, actor);
+  const hoverHeight = dims.height / 2 + 0.15;
+  const grounded = Boolean(hit && hit.distance < hoverHeight + 0.25);
+  const vel = phys.getVelocity(actor);
+  if (hit && hit.distance < hoverHeight + 0.4 && vel.y <= 1) {
+    const accel = 160 * (hoverHeight - hit.distance) - 18 * vel.y;
+    phys.applyImpulse(actor, { x: 0, y: accel * phys.mass(actor) * dt, z: 0 });
+  }
+  return grounded;
+}
+
+function applyMove(phys, actor, move, speed, grounded, dt) {
+  const mass = phys.mass(actor);
+  const vel = phys.getVelocity(actor);
+  if (move) {
+    const factor = Math.min(1, dt * 14) * (grounded ? 1 : 0.3);
+    phys.applyImpulse(actor, {
+      x: (move.x * speed - vel.x) * mass * factor,
+      y: 0,
+      z: (move.z * speed - vel.z) * mass * factor,
+    });
+  } else if (grounded) {
+    const factor = Math.min(1, dt * 12);
+    phys.applyImpulse(actor, { x: -vel.x * mass * factor, y: 0, z: -vel.z * mass * factor });
+  }
+}
+
+function updateCamera(scene, t, rt, props, dt) {
+  const cam = scene.three?.camera;
+  if (!cam) return;
+  const targetX = t.x - props.camDistance * Math.sin(rt.camAngle);
+  const targetY = t.y + props.camHeight;
+  const targetZ = t.z + props.camDistance * Math.cos(rt.camAngle);
+  // A scene switch teleports the player; snap instead of swooshing the
+  // camera across the whole map.
+  if (Math.hypot(targetX - cam.position.x, targetZ - cam.position.z) > 20) {
+    cam.position.set(targetX, targetY, targetZ);
+  } else {
+    const lerp = 1 - Math.exp(-12 * dt);
+    cam.position.x += (targetX - cam.position.x) * lerp;
+    cam.position.y += (targetY - cam.position.y) * lerp;
+    cam.position.z += (targetZ - cam.position.z) * lerp;
+  }
+  cam.lookAt(t.x, t.y + 0.5, t.z);
+}
+
+// The nearest Lookable the player is facing, within its range.
+function findLookText(scene, actor, t, facing) {
+  const fx = Math.sin(facing);
+  const fz = Math.cos(facing);
+  let bestText = '';
+  let bestDist = Infinity;
+  for (const other of scene.actorsWith('Lookable')) {
+    if (other.id === actor.id) continue;
+    const ot = other.components.Transform;
+    if (!ot) continue;
+    const dx = ot.x - t.x;
+    const dz = ot.z - t.z;
+    const dist = Math.hypot(dx, dz);
+    const range = other.components.Lookable.range ?? 4;
+    if (dist < 0.01 || dist > range || dist >= bestDist) continue;
+    if ((dx * fx + dz * fz) / dist < 0.7) continue;
+    bestText = other.components.Lookable.text ?? '';
+    bestDist = dist;
+  }
+  return bestText;
+}
+
+export class Player {
+  static behaviorName = 'Player';
+  static defaultProps = { speed: 6, turnSpeed: 2.4, jumpSpeed: 8, camDistance: 9, camHeight: 7 };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor, scene, dt) {
+    const phys = scene.physics3d;
+    if (!phys?.ready()) return;
+    const t = actor.components.Transform;
+    // Cross-scene state (camera angle, score) lives on the runtime's
+    // persistent store so it survives `loadFromFile`; actor.runtime is
+    // rebuilt on every scene load.
+    const per = (scene.persistent ??= {});
+    const rt = actor.runtime;
+    if (per.camAngle === undefined) per.camAngle = Math.PI / 4;
+    if (per.score === undefined) per.score = 0;
+
+    const shape = actor.components.Shape;
+    const dims = { radius: shape?.radius ?? 0.35, height: shape?.height ?? 1.4 };
+    const grounded = applyHover(phys, actor, t, dims, dt);
+    const drive = readDrive(scene.keys, scene.moveInput);
+    per.camAngle += drive.turn * this.props.turnSpeed * dt;
+    rt.facing = Math.PI - per.camAngle;
+    const move =
+      drive.forward !== 0
+        ? {
+            x: Math.sin(per.camAngle) * drive.forward,
+            z: -Math.cos(per.camAngle) * drive.forward,
+          }
+        : null;
+    applyMove(phys, actor, move, this.props.speed, grounded, dt);
+    t.rotationY = rt.facing / DEG;
+
+    // Jump: Space on keyboard, or a short tap anywhere on the canvas (which
+    // works while another finger drives the drag stick). A tap is buffered
+    // briefly so one made just before touchdown still fires.
+    if (scene.moveInput?.consumeJump?.()) rt.jumpBuffer = 0.18;
+    else rt.jumpBuffer = Math.max(0, (rt.jumpBuffer ?? 0) - dt);
+    if ((keyDown(scene.keys, 'Space') || rt.jumpBuffer > 0) && grounded) {
+      rt.jumpBuffer = 0;
+      const vel = phys.getVelocity(actor);
+      phys.setVelocity(actor, { x: vel.x, y: this.props.jumpSpeed, z: vel.z });
+    }
+    // Fall faster than the rise: extra downward pull past the jump apex kills
+    // the floaty arc.
+    if (!grounded) {
+      const vel = phys.getVelocity(actor);
+      if (vel.y < 1) phys.applyImpulse(actor, { x: 0, y: -14 * phys.mass(actor) * dt, z: 0 });
+    }
+
+    updateCamera(scene, t, per, this.props, dt);
+    const remaining = scene.actorsWith('Pickup').length;
+    const total = per.score + remaining;
+    const score =
+      total === 0 ? '' : remaining === 0 ? '◆ all shards found' : `◆ ${per.score}/${total}`;
+    scene.hud = { score, look: findLookText(scene, actor, t, rt.facing) };
+  }
+}

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

@@ -0,0 +1,19 @@
+// Walk-through scene switching: a sensor actor (a glowing ring works well)
+// that asks the runtime to load another scene when the player touches it.
+// The request is applied by the player loop BETWEEN frames -- never mid
+// physics dispatch -- and a short grace after each switch keeps a portal from
+// instantly bouncing the player back where they came from.
+export class Portal {
+  static behaviorName = 'Portal';
+  static defaultProps = { scene: '' };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  onCollisionEnter(actor, scene, other) {
+    if (!other.components.Player || !this.props.scene) return;
+    if (scene.time < (scene.persistent?.portalGraceUntil ?? 0)) return;
+    scene.requestedScene = this.props.scene;
+  }
+}

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

@@ -0,0 +1,75 @@
+// The actor's visual: a primitive mesh with a PBR material, and the source of
+// its collider dimensions. `art` names a `.pxart` (or image) file used as the
+// albedo map, nearest-filtered so pixels stay crisp; `color` tints (or is the
+// whole surface when there is no art -- a flat colour is a fine look here).
+// `solid: true` is one of the two ways to make the collider solid (the other is
+// a `Solid` behavior on the actor); without either the collider is a sensor
+// that reports overlaps but doesn't block.
+import React from 'react';
+import { SelectField, TextField } from '@imports/castle.physics-2d/engine/ui';
+import { AutoFields, overrideProps } from '@imports/castle.physics-2d/engine/autoInspector';
+
+const KIND_OPTIONS = [
+  { value: 'box', label: 'Box' },
+  { value: 'sphere', label: 'Sphere' },
+  { value: 'capsule', label: 'Capsule' },
+  { value: 'cylinder', label: 'Cylinder' },
+];
+
+function ShapeInspector({ component, setComponent, override }) {
+  const art = component.art;
+  return (
+    <>
+      <SelectField
+        label="Kind"
+        value={component.kind}
+        options={KIND_OPTIONS}
+        onChange={(kind) => setComponent({ kind })}
+        {...overrideProps(override, 'kind')}
+      />
+      {typeof art === 'object' && art !== null ? (
+        <TextField label="Art" value="(per-face art -- edit as JSON)" onChange={() => {}} />
+      ) : (
+        <TextField
+          label="Art"
+          value={art ?? ''}
+          onChange={(next) => setComponent({ art: next })}
+          {...overrideProps(override, 'art')}
+        />
+      )}
+      <AutoFields
+        defaultProps={Shape.defaultProps}
+        component={component}
+        setComponent={setComponent}
+        exclude={['kind', 'art', 'artRepeat']}
+        override={override}
+      />
+    </>
+  );
+}
+
+export class Shape {
+  static Inspector = ShapeInspector;
+  static behaviorName = 'Shape';
+  static defaultProps = {
+    kind: 'box', // 'box' | 'sphere' | 'capsule' | 'cylinder'
+    width: 1,
+    height: 1,
+    depth: 1,
+    radius: 0.5,
+    color: '#c7cfdd',
+    art: '',
+    artRepeat: null,
+    tint: '',
+    roughness: 0.7,
+    metalness: 0,
+    clearcoat: 0,
+    emissive: '#000000',
+    emissiveIntensity: 1,
+    solid: false,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+}

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

@@ -0,0 +1,11 @@
+// Marker: this actor's collider blocks things. Without it (and without
+// `Shape.solid`), colliders are sensors -- they overlap and report it, which is
+// what pickups and trigger zones want.
+export class Solid {
+  static behaviorName = 'Solid';
+  static defaultProps = {};
+
+  constructor(props) {
+    this.props = props;
+  }
+}

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

@@ -0,0 +1,24 @@
+// Every 3d actor needs a Transform: position and rotation (degrees) in world
+// units, 1 unit = 1 meter. The physics system keeps it in sync with the actor's
+// rapier body -- dynamic bodies write simulated results back here, fixed and
+// kinematic bodies follow edits made here. The renderer reads it every frame,
+// so Transform is the source of truth for where an actor is.
+export class Transform {
+  static behaviorName = 'Transform';
+  static defaultProps = { x: 0, y: 0, z: 0, rotationX: 0, rotationY: 0, rotationZ: 0 };
+  // Position and rotation are always instance-local (like the 2d kit's Layout
+  // x/y): they never read as "overriding" a blueprint value in the inspector,
+  // and blueprint edits never move placed instances.
+  static propertyMeta = {
+    x: { inherit: false },
+    y: { inherit: false },
+    z: { inherit: false },
+    rotationX: { inherit: false },
+    rotationY: { inherit: false },
+    rotationZ: { inherit: false },
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+}

package/kits/physics-3d/blueprints/barrel.scene

@@ -0,0 +1,15 @@
+{
+  "name": "Barrel",
+  "actors": [
+    {
+      "components": {
+        "Transform": { "y": 0.45 },
+        "Shape": { "kind": "cylinder", "radius": 0.4, "height": 0.9 },
+        "Model": { "file": "models/barrel.pxmodel", "yOffset": -0.45 },
+        "Body": { "type": "dynamic", "friction": 0.7 },
+        "Solid": {},
+        "Lookable": { "text": "a barrel. push it around.", "range": 3 }
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/crate.scene

@@ -0,0 +1,29 @@
+{
+  "name": "Crate",
+  "actors": [
+    {
+      "components": {
+        "Transform": {
+          "y": 0.5
+        },
+        "Shape": {
+          "kind": "box",
+          "width": 1,
+          "height": 1,
+          "depth": 1,
+          "art": "drawings/crate.pxart",
+          "roughness": 0.85
+        },
+        "Body": {
+          "type": "dynamic",
+          "friction": 0.8
+        },
+        "Solid": {},
+        "Lookable": {
+          "text": "a crate. push it around.",
+          "range": 3
+        }
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/door.scene

@@ -0,0 +1,35 @@
+{
+  "name": "Door",
+  "actors": [
+    {
+      "components": {
+        "Transform": {
+          "y": 1.1
+        },
+        "Shape": {
+          "kind": "box",
+          "width": 2,
+          "height": 2.2,
+          "depth": 0.3,
+          "art": {
+            "front": "drawings/door.pxart",
+            "back": "drawings/door.pxart",
+            "sides": "drawings/door-edge.pxart",
+            "top": "drawings/door-edge.pxart"
+          },
+          "color": "#c9a17a",
+          "roughness": 0.8
+        },
+        "Body": {
+          "type": "kinematic"
+        },
+        "Solid": {},
+        "Door": {},
+        "Lookable": {
+          "text": "a door. it opens when someone comes close.",
+          "range": 5
+        }
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/gem.scene

@@ -0,0 +1,26 @@
+{
+  "name": "Gem",
+  "actors": [
+    {
+      "components": {
+        "Transform": {
+          "y": 0.7
+        },
+        "Shape": {
+          "kind": "sphere",
+          "radius": 0.28,
+          "color": "#0cf1ff",
+          "roughness": 0.25,
+          "metalness": 0.2,
+          "emissive": "#0cf1ff",
+          "emissiveIntensity": 0.5
+        },
+        "Pickup": {},
+        "Lookable": {
+          "text": "a shard. walk into it to collect it.",
+          "range": 3.5
+        }
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/pillar.scene

@@ -0,0 +1,25 @@
+{
+  "name": "Pillar",
+  "actors": [
+    {
+      "components": {
+        "Transform": {
+          "y": 1.5
+        },
+        "Shape": {
+          "kind": "cylinder",
+          "radius": 0.3,
+          "height": 3,
+          "art": "drawings/wall.pxart",
+          "artRepeat": [
+            1,
+            1.5
+          ],
+          "color": "#868188",
+          "roughness": 0.85
+        },
+        "Solid": {}
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/platform.scene

@@ -0,0 +1,23 @@
+{
+  "name": "Platform",
+  "actors": [
+    {
+      "components": {
+        "Transform": {
+          "y": 0.2
+        },
+        "Shape": {
+          "kind": "box",
+          "width": 2,
+          "height": 0.4,
+          "depth": 2,
+          "art": "drawings/platform.pxart",
+          "color": "#657392",
+          "roughness": 0.8,
+          "metalness": 0.35
+        },
+        "Solid": {}
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/player.scene

@@ -0,0 +1,29 @@
+{
+  "name": "Player",
+  "actors": [
+    {
+      "components": {
+        "Transform": {
+          "y": 1
+        },
+        "Shape": {
+          "kind": "capsule",
+          "radius": 0.35,
+          "height": 1.4,
+          "color": "#cf8acb",
+          "roughness": 0.4,
+          "clearcoat": 0.5
+        },
+        "Body": {
+          "type": "dynamic",
+          "lockRotations": true,
+          "friction": 0,
+          "gravityScale": 2
+        },
+        "Solid": {},
+        "Model": { "file": "models/player.pxmodel", "yOffset": -0.7 },
+        "Player": {}
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/portal.scene

@@ -0,0 +1,21 @@
+{
+  "name": "Portal",
+  "actors": [
+    {
+      "components": {
+        "Transform": { "y": 1.05, "rotationX": 90 },
+        "Shape": {
+          "kind": "cylinder",
+          "radius": 0.9,
+          "height": 0.16,
+          "color": "#0cf1ff",
+          "emissive": "#0cf1ff",
+          "emissiveIntensity": 0.65,
+          "roughness": 0.3
+        },
+        "Portal": {},
+        "Lookable": { "text": "a portal.", "range": 4.5 }
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/rock.scene

@@ -0,0 +1,14 @@
+{
+  "name": "Rock",
+  "actors": [
+    {
+      "components": {
+        "Transform": { "y": 0.4 },
+        "Shape": { "kind": "box", "width": 1, "height": 0.8, "depth": 1 },
+        "Model": { "file": "models/rock.pxmodel", "yOffset": -0.4 },
+        "Solid": {},
+        "Lookable": { "text": "a rock.", "range": 3 }
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/statue.scene

@@ -0,0 +1,26 @@
+{
+  "name": "Statue",
+  "actors": [
+    {
+      "components": {
+        "Transform": {
+          "y": 0.8
+        },
+        "Shape": {
+          "kind": "cylinder",
+          "radius": 0.5,
+          "height": 1.6,
+          "art": "drawings/statue.pxart",
+          "color": "#b8b5b9",
+          "roughness": 0.55,
+          "metalness": 0.1
+        },
+        "Solid": {},
+        "Lookable": {
+          "text": "an old stone statue.",
+          "range": 4
+        }
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/tree.scene

@@ -0,0 +1,14 @@
+{
+  "name": "Tree",
+  "actors": [
+    {
+      "components": {
+        "Transform": { "y": 0.9 },
+        "Shape": { "kind": "cylinder", "radius": 0.22, "height": 1.8 },
+        "Model": { "file": "models/tree.pxmodel", "yOffset": -0.9 },
+        "Solid": {},
+        "Lookable": { "text": "a tree.", "range": 3.5 }
+      }
+    }
+  ]
+}

package/kits/physics-3d/blueprints/wall.scene

@@ -0,0 +1,26 @@
+{
+  "name": "Wall",
+  "actors": [
+    {
+      "components": {
+        "Transform": {
+          "y": 1
+        },
+        "Shape": {
+          "kind": "box",
+          "width": 4,
+          "height": 2,
+          "depth": 0.4,
+          "art": "drawings/wall.pxart",
+          "artRepeat": [
+            2,
+            1
+          ],
+          "color": "#45444f",
+          "roughness": 0.9
+        },
+        "Solid": {}
+      }
+    }
+  ]
+}

package/kits/{basic-2d → physics-3d}/castle.json

@@ -1,4 +1,5 @@
 {
+  "title": "physics-3d",
   "editor": {
     "initialPanels": [
       {
@@ -20,9 +21,11 @@
     "hiddenPaths": [],
     "visiblePaths": [
       "drawings/**",
+      "models/**",
       "scenes/**",
       "blueprints/**",
-      "behaviors/**"
+      "behaviors/**",
+      "assets/**"
     ],
     "fileTypes": [
       {
@@ -41,6 +44,14 @@
         "editor": "kit",
         "data": true
       },
+      {
+        "ext": ".pxmodel",
+        "label": "Model",
+        "new": "New model",
+        "icon": "clone",
+        "editor": "kit",
+        "data": true
+      },
       {
         "ext": ".jsx",
         "label": "Behavior",
@@ -50,8 +61,15 @@
     ],
     "defaultPlayFile": "scenes/main.scene"
   },
-  "deckId": "5R39TxaRfLLQ",
-  "cardId": "AZk0PWHTrFcT",
-  "title": "basic-2d",
-  "publishedVersion": "2026-08-06T19:58:54.294Z"
+  "imports": {
+    "castle.physics-2d": {
+      "deckId": "ckRZGFW4iPrx",
+      "version": "2026-08-14T21:20:31.152Z"
+    }
+  },
+  "main": "main.jsx",
+  "autoUpdateWhenImported": true,
+  "deckId": "JH0SclbPVP0y",
+  "cardId": "eXfAaUdbSU5A",
+  "publishedVersion": "2026-08-21T22:11:54.424Z"
 }