castle-web-cli 0.4.83 → 0.4.85

package/kits/physics-2d/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "physics-2d",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "draw": "node scripts/draw.mjs",
+    "restart": "node ../../cli/dist/index.js restart .",
+    "screenshot": "node ../../cli/dist/index.js screenshot .",
+    "check": "eslint . && jscpd && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\""
+  },
+  "jscpd": {
+    "path": [
+      "engine",
+      "editors",
+      "behaviors"
+    ],
+    "threshold": 0,
+    "reporters": [
+      "consoleFull"
+    ]
+  },
+  "dependencies": {
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.41.1",
+    "@fortawesome/free-solid-svg-icons": "^5.15.4",
+    "@lezer/highlight": "^1.2.3",
+    "castle-web-sdk": "file:../../sdk",
+    "codemirror": "^6.0.2",
+    "matter-js": "^0.20.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "jscpd": "^4.0.5",
+    "prettier": "^3.8.3"
+  }
+}

package/kits/physics-2d/physics/PhysicsSystem.js

@@ -0,0 +1,290 @@
+// The physics system: one matter-js engine per scene runtime. Registered as a
+// runtime system (see engine/scene.js `registerSystem`), it runs once per frame
+// in `afterBehaviors` -- after behaviors have expressed intent (velocities,
+// forces) -- to reconcile bodies, step the simulation on a fixed timestep, and
+// write results back into each dynamic actor's Layout.
+//
+// The matter engine is created lazily on first step, so draw-only editor
+// previews (which never call update) pay nothing.
+
+import Matter from 'matter-js';
+import { getColliderRect } from '../engine/collider';
+import {
+  DEFAULT_GRAVITY,
+  FIXED_STEP_MS,
+  FIXED_STEP_S,
+  MAX_STEPS_PER_FRAME,
+  RAD_TO_DEG,
+  applyAngularDrag,
+  applyWorldGravity,
+  bodySignature,
+  createBody,
+  isPhysicsActor,
+  patchBody,
+  rectCenter,
+  syncBodyToPoint,
+} from './matterBridge';
+
+export class PhysicsSystem {
+  constructor() {
+    this.engine = null;
+    this.bodies = new Map(); // actorId -> { body, sig, offset: {dx, dy} }
+    this.intents = new Map(); // actorId -> { velocity?, impulse?, force? }
+    this.gravity = { ...DEFAULT_GRAVITY };
+    this.acc = 0;
+    this.enterPairs = []; // [aId, bId] collected during this frame's steps
+    this.exitPairs = [];
+    this.active = new Set(); // "aId|bId" (sorted) currently-touching pairs
+    this.ndActive = new Set(); // non-dynamic overlaps from last frame (for diff)
+  }
+
+  // Expose the author-facing API on the runtime so behaviors can call
+  // `scene.physics.setVelocity(actor, v)` from their `update`.
+  attach(runtime) {
+    runtime.physics = this.makeApi();
+  }
+
+  ensureEngine() {
+    if (this.engine) return;
+    this.engine = Matter.Engine.create();
+    // We apply gravity ourselves (per-body gravityScale), so silence matter's.
+    this.engine.gravity.scale = 0;
+    // Sensors (isTrigger colliders) still emit these, so triggers work too.
+    Matter.Events.on(this.engine, 'collisionStart', (e) => this.collectPairs(e, this.enterPairs));
+    Matter.Events.on(this.engine, 'collisionEnd', (e) => this.collectPairs(e, this.exitPairs));
+  }
+
+  collectPairs(event, sink) {
+    for (const pair of event.pairs) {
+      const a = pair.bodyA.plugin.actorId;
+      const b = pair.bodyB.plugin.actorId;
+      if (a && b) sink.push([a, b]);
+    }
+  }
+
+  afterBehaviors(scene, dt) {
+    this.ensureEngine();
+    this.readGravity(scene);
+    this.reconcile(scene);
+    this.applyIntents();
+    this.syncStaticBodies(scene);
+    this.step(dt);
+    this.writeBack(scene);
+    this.detectNonDynamicContacts();
+    this.dispatchCollisions(scene);
+  }
+
+  readGravity(scene) {
+    const p = scene.data?.physics ?? {};
+    this.gravity.x = p.gravityX ?? 0;
+    this.gravity.y = p.gravity ?? DEFAULT_GRAVITY.y;
+  }
+
+  rectOf(scene, actor) {
+    return getColliderRect(actor, scene.sprites);
+  }
+
+  // Create/rebuild/remove bodies to match the current physics actors.
+  reconcile(scene) {
+    const seen = new Set();
+    for (const actor of scene.getActors()) {
+      if (!isPhysicsActor(actor)) continue;
+      const rect = this.rectOf(scene, actor);
+      if (!rect || rect.width <= 0 || rect.height <= 0) continue;
+      seen.add(actor.id);
+      const entry = this.bodies.get(actor.id);
+      const sig = bodySignature(actor, rect);
+      if (!entry) this.addBody(actor, rect);
+      else if (entry.sig !== sig) {
+        this.removeBody(actor.id);
+        this.addBody(actor, rect);
+      } else patchBody(entry.body, actor);
+    }
+    for (const id of [...this.bodies.keys()]) if (!seen.has(id)) this.removeBody(id);
+  }
+
+  addBody(actor, rect) {
+    const body = createBody(actor, rect);
+    const center = rectCenter(rect);
+    const layout = actor.components.Layout;
+    const offset = { dx: center.x - layout.x, dy: center.y - layout.y };
+    this.bodies.set(actor.id, { body, sig: bodySignature(actor, rect), offset });
+    Matter.Composite.add(this.engine.world, body);
+  }
+
+  removeBody(id) {
+    const entry = this.bodies.get(id);
+    if (!entry) return;
+    Matter.Composite.remove(this.engine.world, entry.body);
+    this.bodies.delete(id);
+    // Drop live contacts involving this actor so isColliding doesn't go stale
+    // (matter doesn't always emit collisionEnd when a body is removed).
+    for (const set of [this.active, this.ndActive]) {
+      for (const key of [...set]) {
+        const [a, b] = unpairKey(key);
+        if (a === id || b === id) set.delete(key);
+      }
+    }
+  }
+
+  applyIntents() {
+    for (const [id, intent] of this.intents) {
+      const body = this.bodies.get(id)?.body;
+      if (!body) continue;
+      if (intent.velocity) Matter.Body.setVelocity(body, intent.velocity);
+      if (intent.impulse) {
+        Matter.Body.setVelocity(body, {
+          x: body.velocity.x + intent.impulse.x,
+          y: body.velocity.y + intent.impulse.y,
+        });
+      }
+      if (intent.force) Matter.Body.applyForce(body, body.position, intent.force);
+    }
+    this.intents.clear();
+  }
+
+  // Keep static + kinematic bodies wherever Layout says (editor edits, or a
+  // behavior moving a platform by writing Layout).
+  syncStaticBodies(scene) {
+    for (const [id, entry] of this.bodies) {
+      if (!entry.body.isStatic) continue;
+      const actor = scene.getActor(id);
+      if (!actor) continue;
+      const layout = actor.components.Layout;
+      syncBodyToPoint(entry.body, { x: layout.x + entry.offset.dx, y: layout.y + entry.offset.dy }, layout.rotation);
+    }
+  }
+
+  step(dt) {
+    this.acc += dt;
+    const dynamic = this.dynamicBodies();
+    let steps = 0;
+    while (this.acc >= FIXED_STEP_S && steps < MAX_STEPS_PER_FRAME) {
+      applyWorldGravity(dynamic, this.gravity);
+      applyAngularDrag(dynamic);
+      Matter.Engine.update(this.engine, FIXED_STEP_MS);
+      this.acc -= FIXED_STEP_S;
+      steps += 1;
+    }
+    if (steps >= MAX_STEPS_PER_FRAME) this.acc = 0; // drop backlog, avoid spiral
+  }
+
+  writeBack(scene) {
+    for (const [id, entry] of this.bodies) {
+      if (entry.body.isStatic) continue;
+      const actor = scene.getActor(id);
+      if (!actor) continue;
+      const layout = actor.components.Layout;
+      layout.x = entry.body.position.x - entry.offset.dx;
+      layout.y = entry.body.position.y - entry.offset.dy;
+      layout.rotation = entry.body.angle * RAD_TO_DEG;
+    }
+  }
+
+  // matter-js only generates contacts when at least one body is dynamic, so it
+  // never reports overlaps between two non-dynamic bodies (static-static, or
+  // any pair involving an emulated-kinematic body, which is matter-static).
+  // Detect those ourselves by narrow-phase testing every non-dynamic pair, and
+  // feed enter/exit into the same pipeline as matter's events. This closes the
+  // gap so onCollisionEnter/Exit + isColliding fire for moving kinematic bodies
+  // (platforms, moving sensors) and static trigger zones too.
+  detectNonDynamicContacts() {
+    const bodies = [];
+    for (const entry of this.bodies.values()) if (entry.body.isStatic) bodies.push(entry.body);
+    const current = new Set();
+    for (let i = 0; i < bodies.length - 1; i++) {
+      const collisions = Matter.Query.collides(bodies[i], bodies.slice(i + 1));
+      for (const c of collisions) {
+        const ida = c.bodyA.plugin.actorId;
+        const idb = c.bodyB.plugin.actorId;
+        if (ida && idb && ida !== idb) current.add(pairKey(ida, idb));
+      }
+    }
+    for (const key of current) if (!this.ndActive.has(key)) this.enterPairs.push(unpairKey(key));
+    for (const key of this.ndActive) if (!current.has(key)) this.exitPairs.push(unpairKey(key));
+    this.ndActive = current;
+  }
+
+  // Fire onCollisionEnter/Exit(actor, scene, other) on both actors of each
+  // pair, and maintain the live `active` set for isColliding queries.
+  dispatchCollisions(scene) {
+    for (const [a, b] of this.enterPairs) {
+      this.active.add(pairKey(a, b));
+      this.fireContact(scene, a, b, 'onCollisionEnter');
+    }
+    for (const [a, b] of this.exitPairs) {
+      this.active.delete(pairKey(a, b));
+      this.fireContact(scene, a, b, 'onCollisionExit');
+    }
+    this.enterPairs.length = 0;
+    this.exitPairs.length = 0;
+  }
+
+  fireContact(scene, aId, bId, hook) {
+    const a = scene.getActor(aId);
+    const b = scene.getActor(bId);
+    if (!a || !b) return;
+    scene.forEachBehavior(a, (inst) => inst[hook]?.(a, scene, b));
+    scene.forEachBehavior(b, (inst) => inst[hook]?.(b, scene, a));
+  }
+
+  dynamicBodies() {
+    const out = [];
+    for (const entry of this.bodies.values()) if (!entry.body.isStatic) out.push(entry.body);
+    return out;
+  }
+
+  bodyOf(actorOrId) {
+    const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
+    return this.bodies.get(id)?.body ?? null;
+  }
+
+  queue(actorOrId, key, value) {
+    const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
+    if (!id) return;
+    const intent = this.intents.get(id) ?? {};
+    intent[key] = value;
+    this.intents.set(id, intent);
+  }
+
+  queueAdd(actorOrId, key, value) {
+    const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
+    if (!id) return;
+    const intent = this.intents.get(id) ?? {};
+    const prev = intent[key] ?? { x: 0, y: 0 };
+    intent[key] = { x: prev.x + value.x, y: prev.y + value.y };
+    this.intents.set(id, intent);
+  }
+
+  makeApi() {
+    return {
+      // Set velocity directly (px per fixed step; ~*60 for px/s).
+      setVelocity: (actor, v) => this.queue(actor, 'velocity', v),
+      // Add to velocity this frame (velocity-space delta).
+      applyImpulse: (actor, v) => this.queueAdd(actor, 'impulse', v),
+      // Add a matter-space force to the accumulator (advanced).
+      applyForce: (actor, f) => this.queueAdd(actor, 'force', f),
+      getVelocity: (actor) => {
+        const body = this.bodyOf(actor);
+        return body ? { x: body.velocity.x, y: body.velocity.y } : { x: 0, y: 0 };
+      },
+      // True while two actors are touching (updated by collision events).
+      isColliding: (a, b) => {
+        const aId = typeof a === 'string' ? a : a?.id;
+        const bId = typeof b === 'string' ? b : b?.id;
+        return this.active.has(pairKey(aId, bId));
+      },
+      bodyFor: (actor) => this.bodyOf(actor),
+    };
+  }
+}
+
+function pairKey(a, b) {
+  return a < b ? `${a}|${b}` : `${b}|${a}`;
+}
+
+// Inverse of pairKey. Actor ids never contain '|', so split on the first one.
+function unpairKey(key) {
+  const i = key.indexOf('|');
+  return [key.slice(0, i), key.slice(i + 1)];
+}

package/kits/physics-2d/physics/behaviors/AnalogStick.jsx

@@ -0,0 +1,101 @@
+import React from 'react';
+import { Panel, SelectField } from '../../engine/ui';
+import { AutoFields, overrideProps } from '../../engine/autoInspector';
+import { analogVelocity, inActorWorldSpace, stickVector } from '../controls';
+
+// AnalogStick: an on-screen virtual joystick that drives the actor it's on --
+// the look and feel of castle-client's Analog Stick. Press anywhere to place
+// the stick; drag to steer. Draws the stick base ring + knob while held. Best
+// for top-down movement; needs a RigidBody (dynamic) + Collider.
+//
+//   speed     -> velocity at full deflection (px per fixed step).
+//   maxRadius -> stick throw radius in pixels.
+//   axes      -> restrict to 'horizontal' / 'vertical' / 'both'.
+export class AnalogStick {
+  static behaviorName = 'AnalogStick';
+
+  static defaultProps = {
+    speed: 6,
+    maxRadius: 60,
+    axes: 'both',
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor, scene) {
+    const p = scene.pointer;
+    const rt = actor.runtime;
+    const pressed = p.down && !rt._stickWasDown;
+    rt._stickWasDown = p.down;
+    if (pressed) rt._stickOrigin = { x: p.x, y: p.y };
+
+    // Only drive velocity while the stick is actually held.
+    if (p.down && rt._stickOrigin) {
+      rt._stickKnob = stickVector(p, rt._stickOrigin, this.props.maxRadius ?? 60);
+      scene.physics.setVelocity(actor, analogVelocity(p, rt._stickOrigin, this.props));
+      rt._stickActive = true;
+      return;
+    }
+
+    rt._stickOrigin = null;
+    rt._stickKnob = null;
+    // Stop ONCE on release, and only on the driven axes (so a top-down mover
+    // doesn't drift). Critically, do NOT touch velocity while idle -- doing that
+    // every frame zeroes the velocity gravity builds up, so the actor barely
+    // falls. An idle AnalogStick must leave physics (gravity, momentum) alone.
+    if (rt._stickActive) {
+      rt._stickActive = false;
+      const axes = this.props.axes ?? 'both';
+      const cur = scene.physics.getVelocity(actor);
+      scene.physics.setVelocity(actor, {
+        x: axes === 'vertical' ? cur.x : 0,
+        y: axes === 'horizontal' ? cur.y : 0,
+      });
+    }
+  }
+
+  // Base ring anchored where the user pressed + knob at the current (clamped)
+  // deflection. Drawn in world space so it stays put instead of rotating/sliding
+  // with the actor.
+  draw(actor, scene, ctx) {
+    const rt = actor.runtime;
+    if (!rt._stickOrigin) return;
+    const o = rt._stickOrigin;
+    const k = rt._stickKnob ?? { x: 0, y: 0 };
+    const radius = this.props.maxRadius ?? 60;
+    inActorWorldSpace(ctx, actor.components.Layout, (c) => {
+      c.strokeStyle = 'rgba(255, 255, 255, 0.5)';
+      c.lineWidth = 3;
+      c.beginPath();
+      c.arc(o.x, o.y, radius, 0, Math.PI * 2);
+      c.stroke();
+      c.fillStyle = 'rgba(255, 255, 255, 0.85)';
+      c.beginPath();
+      c.arc(o.x + k.x, o.y + k.y, 20, 0, Math.PI * 2);
+      c.fill();
+    });
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    return (
+      <Panel title="AnalogStick" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="Axes"
+          value={component.axes}
+          onChange={(axes) => setComponent({ axes })}
+          options={['both', 'horizontal', 'vertical']}
+          {...overrideProps(override, 'axes')}
+        />
+        <AutoFields
+          defaultProps={AnalogStick.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          exclude={['axes']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}

package/kits/physics-2d/physics/behaviors/Draggable.jsx

@@ -0,0 +1,79 @@
+import React from 'react';
+import { Panel } from '../../engine/ui';
+import { AutoFields } from '../../engine/autoInspector';
+import { centerOf, chaseVelocity, inActorWorldSpace } from '../controls';
+
+// Draggable: grab the actor with the pointer and fling it around. Chases the
+// pointer with a springy velocity (via the physics system) so it still collides
+// with the world -- the same feel as castle-client's Drag. Grabs the topmost
+// actor under the press (uses scene.actorAt), and keeps dragging until release
+// even if the pointer slips off. Needs a RigidBody (dynamic) + Collider.
+//
+//   stiffness -> how hard it chases the pointer (fraction of the gap per step).
+export class Draggable {
+  static behaviorName = 'Draggable';
+
+  static defaultProps = {
+    stiffness: 0.1,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor, scene) {
+    const p = scene.pointer;
+    const rt = actor.runtime;
+    const pressed = p.down && !rt._dragWasDown;
+    rt._dragWasDown = p.down;
+    if (pressed && scene.actorAt(p.x, p.y)?.id === actor.id) rt._dragging = true;
+    if (!p.down) rt._dragging = false;
+    if (!rt._dragging) return;
+
+    scene.physics.setVelocity(actor, chaseVelocity(p, actor.components.Layout, this.props));
+  }
+
+  // Feedback while held (castle-client's Drag overlay): a circle on the grabbed
+  // object + a circle at the touch, connected by a line -- both translucent white
+  // with a solid white border. Drawn in world space so it doesn't spin with the
+  // actor.
+  draw(actor, scene, ctx) {
+    if (!actor.runtime._dragging) return;
+    const handle = centerOf(actor.components.Layout);
+    const touch = { x: scene.pointer.x, y: scene.pointer.y };
+    inActorWorldSpace(ctx, actor.components.Layout, (g) => drawDrag(g, handle, touch));
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    return (
+      <Panel title="Draggable" overridden={override?.anyOverridden()}>
+        <AutoFields
+          defaultProps={Draggable.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+// Matches sling/drag.cpp: line first, then a circle at each end -- translucent
+// white fill (0.3) + solid white border (0.8), radius 18.
+function drawDrag(ctx, a, b) {
+  const radius = 18;
+  ctx.lineWidth = 1.5;
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.8)';
+  ctx.beginPath();
+  ctx.moveTo(a.x, a.y);
+  ctx.lineTo(b.x, b.y);
+  ctx.stroke();
+  for (const p of [a, b]) {
+    ctx.beginPath();
+    ctx.arc(p.x, p.y, radius, 0, Math.PI * 2);
+    ctx.fillStyle = 'rgba(255, 255, 255, 0.3)';
+    ctx.fill();
+    ctx.strokeStyle = 'rgba(255, 255, 255, 0.8)';
+    ctx.stroke();
+  }
+}

package/kits/physics-2d/physics/behaviors/RigidBody.jsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import { Panel, SelectField } from '../../engine/ui';
+import { AutoFields, overrideProps } from '../../engine/autoInspector';
+
+// RigidBody makes an actor a physics object. Pair it with a Collider (which
+// gives the shape + material). The simulation reads these props each frame; the
+// behavior itself does no per-frame work -- author code drives motion through
+// `scene.physics` (setVelocity / applyImpulse / applyForce).
+//
+//   bodyType 'dynamic'   -> simulated: gravity, collisions, forces move it.
+//            'static'     -> never moves (a wall); a Collider alone is also this.
+//            'kinematic'  -> unpushable, but you move it by writing its Layout.
+//   gravityScale         -> multiplies world gravity for this body (0 = float).
+//   drag                 -> linear damping (matter frictionAir).
+//   angularDrag          -> extra spin damping.
+//   freezeRotation       -> lock rotation (stays upright).
+//   velocityX/velocityY  -> initial velocity, applied once when play starts.
+export class RigidBody {
+  static behaviorName = 'RigidBody';
+
+  static defaultProps = {
+    bodyType: 'dynamic',
+    gravityScale: 1,
+    drag: 0.01,
+    angularDrag: 0,
+    freezeRotation: false,
+    velocityX: 0,
+    velocityY: 0,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    return (
+      <Panel title="RigidBody" overridden={override?.anyOverridden()}>
+        <SelectField
+          label="Body type"
+          value={component.bodyType}
+          onChange={(bodyType) => setComponent({ bodyType })}
+          options={['dynamic', 'static', 'kinematic']}
+          {...overrideProps(override, 'bodyType')}
+        />
+        <AutoFields
+          defaultProps={RigidBody.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          exclude={['bodyType']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}

package/kits/physics-2d/physics/behaviors/Slingshot.jsx

@@ -0,0 +1,118 @@
+import React from 'react';
+import { Panel } from '../../engine/ui';
+import { AutoFields } from '../../engine/autoInspector';
+import { inActorWorldSpace, slingLaunch, slingPull } from '../controls';
+
+// Slingshot: pull back and release to fling the actor the opposite way
+// (angry-birds style) -- the physics feel of castle-client's Sling. While
+// aiming it draws an arrow showing the launch direction and power. Needs a
+// RigidBody (dynamic) + Collider.
+//
+//   speed        -> launch velocity per pixel of pull.
+//   maxDrag      -> pull distance cap (also caps launch power).
+//   grabAnywhere -> start the sling from a press ANYWHERE on screen (default,
+//                   like castle-client); set false to require pressing the actor.
+export class Slingshot {
+  static behaviorName = 'Slingshot';
+
+  static defaultProps = {
+    speed: 0.08,
+    maxDrag: 160,
+    grabAnywhere: true,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor, scene) {
+    const p = scene.pointer;
+    const rt = actor.runtime;
+    const pressed = p.down && !rt._slingWasDown;
+    rt._slingWasDown = p.down;
+
+    const grabAnywhere = this.props.grabAnywhere ?? true;
+    if (pressed && (grabAnywhere || scene.actorAt(p.x, p.y)?.id === actor.id)) {
+      rt._slinging = true;
+      // Anchor at the press point (like castle-client): the aim/launch depends
+      // on the drag gesture, not where the press landed relative to the actor.
+      rt._slingAnchor = { x: p.x, y: p.y };
+    }
+    if (!rt._slinging) return;
+
+    if (p.down) {
+      // Hold still while aiming, and remember the aim point for draw().
+      scene.physics.setVelocity(actor, { x: 0, y: 0 });
+      rt._slingAim = { x: p.x, y: p.y };
+    } else {
+      scene.physics.setVelocity(actor, slingLaunch(rt._slingAnchor, p, this.props));
+      rt._slinging = false;
+      rt._slingAim = null;
+    }
+  }
+
+  // Aim overlay in the castle-client style: a translucent grab circle plus a
+  // line + arrowhead pointing in the launch direction (opposite the pull).
+  draw(actor, scene, ctx) {
+    const rt = actor.runtime;
+    if (!rt._slinging || !rt._slingAim) return;
+    const a = rt._slingAnchor;
+    const pull = slingPull(a, rt._slingAim, this.props.maxDrag ?? 160);
+    const len = Math.hypot(pull.x, pull.y);
+    if (len < 0.001) return;
+    const dir = { x: -pull.x / len, y: -pull.y / len }; // launch direction (opposite pull)
+    const end = { x: a.x - pull.x * 0.8, y: a.y - pull.y * 0.8 };
+
+    // The launch is absolute, so draw the aim in world space too (castle-client
+    // draws the sling as a screen overlay for the same reason).
+    inActorWorldSpace(ctx, actor.components.Layout, (c) => drawSling(c, a, end, dir));
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    return (
+      <Panel title="Slingshot" overridden={override?.anyOverridden()}>
+        <AutoFields
+          defaultProps={Slingshot.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+// castle-client's sling overlay: a white grab circle (solid outline + faint
+// fill) at `start`, a line to the base of a filled triangle arrowhead at `end`,
+// pointing along `dir`. Sizes mirror sling.cpp (circle 18, arrowhead 25x10).
+function drawSling(ctx, start, end, dir) {
+  const radius = 18;
+  const triLen = 25;
+  const triW = 10;
+  const baseX = end.x - dir.x * triLen;
+  const baseY = end.y - dir.y * triLen;
+  const perpX = -dir.y;
+  const perpY = dir.x;
+
+  ctx.lineWidth = 1.5;
+  // Grab circle.
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.3)';
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.8)';
+  ctx.beginPath();
+  ctx.arc(start.x, start.y, radius, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.stroke();
+  // Line from the grab circle to the arrowhead base.
+  ctx.beginPath();
+  ctx.moveTo(start.x, start.y);
+  ctx.lineTo(baseX, baseY);
+  ctx.stroke();
+  // Filled triangle arrowhead.
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.8)';
+  ctx.beginPath();
+  ctx.moveTo(end.x, end.y);
+  ctx.lineTo(baseX + perpX * triW, baseY + perpY * triW);
+  ctx.lineTo(baseX - perpX * triW, baseY - perpY * triW);
+  ctx.closePath();
+  ctx.fill();
+}