castle-web-cli 0.4.0 → 0.4.2

package/kits/rpg-2d/engine/files.ts

@@ -0,0 +1,215 @@
+export type FileMap = Record<string, string>;
+export type FileKind = 'scene' | 'drawing' | 'code' | 'text';
+
+// Fully transparent pixel -- the empty value in a pixel grid.
+export const TRANSPARENT = '#00000000';
+
+export type DrawingPlayMode = 'still' | 'once' | 'loop';
+
+// One layer of a drawing: an ordered stack of frames, each frame a flat
+// row-major pixel grid of `width * height` hex-RGBA strings.
+export interface DrawingLayer {
+  id: string;
+  name: string;
+  visible: boolean;
+  frames: string[][];
+}
+
+// A drawing is a stack of layers, each animated across a shared frame count.
+// Layers composite bottom-to-top; animation advances all layers in lockstep.
+// `initialFrame` is 1-based.
+export interface DrawingData {
+  width: number;
+  height: number;
+  fps: number;
+  playMode: DrawingPlayMode;
+  initialFrame: number;
+  palette: string[];
+  layers: DrawingLayer[];
+}
+
+// Number of animation frames -- layers stay frame-count-synced, so layer 0
+// is authoritative.
+export function frameCount(drawing: DrawingData): number {
+  return drawing.layers[0]?.frames.length ?? 1;
+}
+
+let layerIdCounter = 0;
+
+export function newLayerId(): string {
+  layerIdCounter += 1;
+  return `layer_${Date.now().toString(36)}_${layerIdCounter}`;
+}
+
+export function blankPixelGrid(width: number, height: number): string[] {
+  return Array<string>(Math.max(1, width * height)).fill(TRANSPARENT);
+}
+
+// Default palette for fresh drawings; user-editable per file.
+const DEFAULT_PALETTE: string[] = [
+  '#00000000',
+  '#000000FF',
+  '#444444FF',
+  '#888888FF',
+  '#ffffffFF',
+  '#8db7ffFF',
+  '#3fae5dFF',
+  '#ffe17aFF',
+  '#ff5d5dFF',
+];
+
+// Coerce arbitrary parsed JSON into a valid DrawingData. Accepts the legacy
+// flat `{width,height,pixels}` shape and lifts it into a single layer/frame
+// so old `.drawing` files keep loading.
+export function normalizeDrawing(raw: unknown): DrawingData {
+  const obj = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;
+  const width = clampDim(obj.width, 16);
+  const height = clampDim(obj.height, 16);
+
+  let layers: DrawingLayer[];
+  if (Array.isArray(obj.layers) && obj.layers.length > 0) {
+    layers = obj.layers.map((rawLayer, index) =>
+      normalizeLayer(rawLayer, index, width, height)
+    );
+  } else if (Array.isArray(obj.pixels)) {
+    layers = [
+      {
+        id: newLayerId(),
+        name: 'Layer 1',
+        visible: true,
+        frames: [normalizeFrame(obj.pixels as unknown[], width, height)],
+      },
+    ];
+  } else {
+    layers = [
+      { id: newLayerId(), name: 'Layer 1', visible: true, frames: [blankPixelGrid(width, height)] },
+    ];
+  }
+  const count = layers[0]?.frames.length ?? 1;
+  for (const layer of layers) {
+    while (layer.frames.length < count) layer.frames.push(blankPixelGrid(width, height));
+    layer.frames.length = count;
+  }
+
+  const palette = Array.isArray(obj.palette)
+    ? (obj.palette as unknown[]).filter((c): c is string => typeof c === 'string')
+    : DEFAULT_PALETTE.slice();
+  const fps = typeof obj.fps === 'number' ? obj.fps : 4;
+  const playMode: DrawingPlayMode =
+    obj.playMode === 'once' || obj.playMode === 'loop' ? obj.playMode : 'still';
+  const initialFrame = typeof obj.initialFrame === 'number' ? Math.max(1, obj.initialFrame) : 1;
+
+  return { width, height, fps, playMode, initialFrame, palette, layers };
+}
+
+function clampDim(value: unknown, fallback: number): number {
+  return typeof value === 'number' && value > 0 ? Math.floor(value) : fallback;
+}
+
+function normalizeFrame(raw: unknown[], width: number, height: number): string[] {
+  const out = blankPixelGrid(width, height);
+  for (let i = 0; i < out.length; i++) {
+    const cell = raw[i];
+    if (typeof cell === 'string') out[i] = cell;
+  }
+  return out;
+}
+
+function normalizeLayer(
+  raw: unknown,
+  index: number,
+  width: number,
+  height: number
+): DrawingLayer {
+  const obj = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>;
+  const frames: string[][] = Array.isArray(obj.frames)
+    ? obj.frames.map((frame) =>
+        Array.isArray(frame) ? normalizeFrame(frame as unknown[], width, height) : blankPixelGrid(width, height)
+      )
+    : [blankPixelGrid(width, height)];
+  return {
+    id: typeof obj.id === 'string' ? obj.id : newLayerId(),
+    name: typeof obj.name === 'string' ? obj.name : `Layer ${index + 1}`,
+    visible: obj.visible !== false,
+    frames,
+  };
+}
+
+// Seed the file map by scanning the deck dir. Vite module-cache is invalidated
+// on restart, so a newly-created file just shows up on the next reload.
+const rawModules = import.meta.glob<string>(
+  ['../scenes/*.scene', '../drawings/*.drawing', '../behaviors/*.tsx'],
+  { query: '?raw', import: 'default', eager: true }
+);
+
+export const initialFiles: FileMap = Object.fromEntries(
+  Object.entries(rawModules)
+    .map(([globPath, text]): [string, string] => [globPath.replace(/^\.\.\//, ''), text])
+    .sort(([a], [b]) => a.localeCompare(b))
+);
+
+export function getFileKind(path: string): FileKind {
+  if (path.endsWith('.scene')) return 'scene';
+  if (path.endsWith('.drawing')) return 'drawing';
+  if (path.endsWith('.ts') || path.endsWith('.tsx')) return 'code';
+  return 'text';
+}
+
+export function parseJsonFile<TValue = unknown>(
+  path: string,
+  text: string
+): { value: TValue | null; error: string | null } {
+  try {
+    return { value: JSON.parse(text) as TValue, error: null };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { value: null, error: `${path}: ${message}` };
+  }
+}
+
+export function formatJson(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export function basename(path: string): string {
+  return path.split('/').pop() ?? path;
+}
+
+type OrderNode = {
+  isFile: boolean;
+  path: string;
+  children: OrderNode[];
+  childMap: Map<string, OrderNode>;
+};
+
+// Flat list of file paths in the order FileBrowser renders them: a
+// depth-first walk of the directory tree, mirroring buildFileTree there.
+export function flatFileOrder(paths: string[]): string[] {
+  const root: OrderNode = { isFile: false, path: '', children: [], childMap: new Map() };
+  for (const path of paths) {
+    const parts = path.split('/');
+    let parent = root;
+    for (let index = 0; index < parts.length; index++) {
+      const name = parts[index];
+      const nodePath = parts.slice(0, index + 1).join('/');
+      const isFile = index === parts.length - 1;
+      if (!parent.childMap.has(name)) {
+        const node: OrderNode = { isFile, path: nodePath, children: [], childMap: new Map() };
+        parent.childMap.set(name, node);
+        parent.children.push(node);
+      }
+      const child = parent.childMap.get(name);
+      if (!child || child.isFile) break;
+      parent = child;
+    }
+  }
+  const order: string[] = [];
+  const walk = (node: OrderNode): void => {
+    for (const child of node.children) {
+      if (child.isFile) order.push(child.path);
+      else walk(child);
+    }
+  };
+  walk(root);
+  return order;
+}

package/kits/rpg-2d/engine/scene.ts

@@ -0,0 +1,484 @@
+import type { DrawingData, FileMap } from './files';
+import type { LayoutProps } from '../behaviors/Layout.tsx';
+import type { DrawingProps } from '../behaviors/Drawing.tsx';
+
+export type ComponentProps = object;
+
+export interface ActorData {
+  id: string;
+  components: Record<string, ComponentProps | undefined>;
+  runtime?: Record<string, unknown>;
+}
+
+export interface SceneData {
+  name?: string;
+  background?: string;
+  actors: ActorData[];
+  status?: string;
+}
+
+export interface SceneDrawOptions {
+  selectedActorIds?: string[];
+  marquee?: SelectionRect | null;
+  showGrid?: boolean;
+  showDebugColliders?: boolean;
+  useCamera?: boolean;
+  // When true, draw a faint outlined placeholder for every actor that has a
+  // Layout. Editor-only, so actors without a Drawing component are still
+  // visible + selectable on the stage.
+  editPlaceholders?: boolean;
+}
+
+export interface SelectionRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Behavior<TProps extends object = object> {
+  props: TProps;
+  update?: (actor: ActorData, scene: SceneRuntime, dt: number) => void;
+  draw?: (
+    actor: ActorData,
+    scene: SceneRuntime,
+    ctx: CanvasRenderingContext2D,
+    options: SceneDrawOptions
+  ) => void;
+  // Game-time UI. Returns React nodes rendered into a deck-sized, clipped
+  // overlay above the canvas; coordinates are card units, like Layout. Called
+  // every frame during play -- read state set by `update`, return null to
+  // render nothing. The host parents these nodes, so there is no DOM teardown
+  // to manage.
+  ui?: (actor: ActorData, scene: SceneRuntime) => React.ReactNode;
+}
+
+export interface BehaviorClass {
+  behaviorName: string;
+  defaultProps: object;
+  new (props: never): Behavior;
+  Inspector?: (props: never) => React.ReactNode;
+}
+
+const CARD_WIDTH = 500;
+const CARD_HEIGHT = 700;
+
+export class SceneRuntime {
+  behaviors: Map<string, BehaviorClass>;
+  drawings: Record<string, DrawingData>;
+  time: number;
+  keys: Set<string>;
+  pointer: { x: number; y: number; down: boolean };
+  data: SceneData;
+  actors: Map<string, ActorData>;
+  camera?: { x: number; y: number };
+  status?: string;
+  // Set by PlayerController on E-press: the id of the actor to interact with
+  // this frame. Behaviors like Dialog watch their own id here and consume it.
+  interactTarget?: string;
+  // Set by Portal when the player overlaps it; ScenePlayer reloads the scene.
+  requestedScene?: string;
+
+  constructor(
+    sceneData: SceneData,
+    behaviors: BehaviorClass[],
+    drawings: Record<string, DrawingData>
+  ) {
+    this.behaviors = new Map(behaviors.map((Behavior) => [Behavior.behaviorName, Behavior]));
+    this.drawings = drawings;
+    this.time = 0;
+    this.keys = new Set();
+    this.pointer = { x: 0, y: 0, down: false };
+    this.data = { actors: [] };
+    this.actors = new Map();
+    this.load(sceneData);
+  }
+
+  load(sceneData: SceneData): void {
+    this.data = structuredClone(sceneData);
+    this.actors = new Map();
+    for (const actor of this.data.actors ?? []) {
+      this.actors.set(actor.id, actor);
+      for (const [behaviorName, Behavior] of this.behaviors) {
+        const component = actor.components[behaviorName];
+        if (component) {
+          actor.components[behaviorName] = {
+            ...Behavior.defaultProps,
+            ...component,
+          };
+        }
+      }
+    }
+  }
+
+  clone(): SceneRuntime {
+    return new SceneRuntime(this.serialize(), [...this.behaviors.values()], this.drawings);
+  }
+
+  serialize(): SceneData {
+    return structuredClone(this.data);
+  }
+
+  getActor(actorId: string): ActorData | undefined {
+    return this.actors.get(actorId);
+  }
+
+  // Depth-sorted draw order. Top-down feel: the actor whose base
+  // (Layout.y + height) sits lower on screen draws in front, so the player
+  // walks behind a building when north of its base and in front of it when
+  // south. `z` is only a tiebreaker on identical feet-y -- it doesn't
+  // override the painterly y sort, which is what bloom-run does too.
+  getActors(): ActorData[] {
+    return [...this.actors.values()].sort((a, b) => {
+      const al = getLayout(a);
+      const bl = getLayout(b);
+      const afeet = (al?.y ?? 0) + (al?.height ?? 0);
+      const bfeet = (bl?.y ?? 0) + (bl?.height ?? 0);
+      if (afeet !== bfeet) return afeet - bfeet;
+      const az = al?.z ?? 0;
+      const bz = bl?.z ?? 0;
+      return az - bz;
+    });
+  }
+
+  getComponent(actor: ActorData | null | undefined, behaviorName: string): ComponentProps | null {
+    return actor?.components?.[behaviorName] ?? null;
+  }
+
+  // Translate a screen-space pointer event into the scene's world-space
+  // `pointer`. The runtime owns this mapping (it knows the camera) so every
+  // input path -- the standalone ScenePlayer and the editor's play mode -- agree
+  // on it; behaviors read `scene.pointer` in world coordinates. Pass `down` to
+  // also update the press state.
+  setPointerFromScreen(
+    canvas: HTMLCanvasElement,
+    clientX: number,
+    clientY: number,
+    down?: boolean
+  ): void {
+    const point = screenToCard(canvas, clientX, clientY);
+    this.pointer.x = point.x + (this.camera?.x ?? 0);
+    this.pointer.y = point.y + (this.camera?.y ?? 0);
+    if (down !== undefined) this.pointer.down = down;
+  }
+
+  update(dt: number): void {
+    this.time += dt;
+    for (const actor of this.getActors()) {
+      this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, dt));
+    }
+  }
+
+  private forEachBehavior(actor: ActorData, callback: (instance: Behavior) => void): void {
+    for (const [behaviorName, props] of Object.entries(actor.components)) {
+      if (!props) continue;
+      const Behavior = this.behaviors.get(behaviorName);
+      if (!Behavior) continue;
+      callback(new Behavior(props as never));
+    }
+  }
+
+  draw(ctx: CanvasRenderingContext2D, options: SceneDrawOptions = {}): void {
+    ctx.clearRect(0, 0, CARD_WIDTH, CARD_HEIGHT);
+    ctx.fillStyle = this.data.background ?? '#0f2a1d';
+    ctx.fillRect(0, 0, CARD_WIDTH, CARD_HEIGHT);
+
+    ctx.save();
+    if (options.useCamera && this.camera) {
+      ctx.translate(-Math.round(this.camera.x ?? 0), -Math.round(this.camera.y ?? 0));
+    }
+
+    for (const actor of this.getActors()) {
+      // Per-actor transform: Layout's `rotation` (degrees) rotates every draw
+      // behavior of the actor about its center.
+      ctx.save();
+      applyLayoutRotation(ctx, getLayout(actor));
+      if (options.editPlaceholders) drawEditPlaceholder(ctx, actor);
+      this.forEachBehavior(actor, (instance) => instance.draw?.(actor, this, ctx, options));
+      ctx.restore();
+    }
+
+    if (options.showGrid) drawGrid(ctx);
+    if (options.selectedActorIds) {
+      for (const id of options.selectedActorIds) {
+        const actor = this.getActor(id);
+        if (actor) drawSelection(ctx, actor);
+      }
+    }
+    if (options.marquee) drawMarquee(ctx, options.marquee);
+    ctx.restore();
+  }
+
+  actorAt(x: number, y: number): ActorData | null {
+    const actors = this.getActors().slice().reverse();
+    for (const actor of actors) {
+      const layout = getLayout(actor);
+      if (!layout) continue;
+      if (
+        x >= layout.x &&
+        x <= layout.x + layout.width &&
+        y >= layout.y &&
+        y <= layout.y + layout.height
+      ) {
+        return actor;
+      }
+    }
+    return null;
+  }
+
+  actorIdsInRect(rect: SelectionRect): string[] {
+    const minX = rect.x;
+    const minY = rect.y;
+    const maxX = rect.x + rect.width;
+    const maxY = rect.y + rect.height;
+    const ids: string[] = [];
+    for (const actor of this.getActors()) {
+      const layout = getLayout(actor);
+      if (!layout) continue;
+      if (
+        layout.x + layout.width >= minX &&
+        layout.x <= maxX &&
+        layout.y + layout.height >= minY &&
+        layout.y <= maxY
+      ) {
+        ids.push(actor.id);
+      }
+    }
+    return ids;
+  }
+}
+
+export function makeScene(
+  sceneData: SceneData,
+  behaviors: BehaviorClass[],
+  drawings: Record<string, DrawingData>
+): SceneRuntime {
+  return new SceneRuntime(sceneData, behaviors, drawings);
+}
+
+export function setActorComponent<TProps extends ComponentProps>(
+  sceneData: SceneData,
+  actorId: string,
+  behaviorName: string,
+  nextProps: Partial<TProps>
+): SceneData {
+  const next = structuredClone(sceneData);
+  const actor = next.actors.find((candidate) => candidate.id === actorId);
+  if (!actor) return sceneData;
+  actor.components[behaviorName] = {
+    ...(actor.components[behaviorName] ?? {}),
+    ...nextProps,
+  };
+  return next;
+}
+
+export function removeActorComponent(
+  sceneData: SceneData,
+  actorId: string,
+  behaviorName: string
+): SceneData {
+  const next = structuredClone(sceneData);
+  const actor = next.actors.find((candidate) => candidate.id === actorId);
+  if (!actor || !(behaviorName in actor.components)) return sceneData;
+  delete actor.components[behaviorName];
+  return next;
+}
+
+export function moveActors(
+  sceneData: SceneData,
+  actorIds: string[],
+  dx: number,
+  dy: number
+): SceneData {
+  if (actorIds.length === 0) return sceneData;
+  const next = structuredClone(sceneData);
+  let changed = false;
+  for (const id of actorIds) {
+    const actor = next.actors.find((candidate) => candidate.id === id);
+    const layout = actor ? (actor.components.Layout as LayoutProps | undefined) : null;
+    if (!actor || !layout) continue;
+    actor.components.Layout = {
+      ...layout,
+      x: Math.round(layout.x + dx),
+      y: Math.round(layout.y + dy),
+    };
+    changed = true;
+  }
+  return changed ? next : sceneData;
+}
+
+export function removeActors(sceneData: SceneData, actorIds: string[]): SceneData {
+  if (actorIds.length === 0) return sceneData;
+  const toRemove = new Set(actorIds);
+  const next = structuredClone(sceneData);
+  next.actors = next.actors.filter((actor) => !toRemove.has(actor.id));
+  return next.actors.length === sceneData.actors.length ? sceneData : next;
+}
+
+export function duplicateActors(
+  sceneData: SceneData,
+  actorIds: string[]
+): { sceneData: SceneData; newIds: string[] } {
+  if (actorIds.length === 0) return { sceneData, newIds: [] };
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const newIds: string[] = [];
+  for (const id of actorIds) {
+    const source = next.actors.find((candidate) => candidate.id === id);
+    if (!source) continue;
+    const copy = structuredClone(source);
+    copy.id = mintActorId(existingIds);
+    existingIds.add(copy.id);
+    const layout = copy.components.Layout as LayoutProps | undefined;
+    if (layout) {
+      copy.components.Layout = {
+        ...layout,
+        x: Math.round(layout.x + 1),
+        y: Math.round(layout.y + 1),
+      };
+    }
+    next.actors.push(copy);
+    newIds.push(copy.id);
+  }
+  return { sceneData: next, newIds };
+}
+
+export function addActor(
+  sceneData: SceneData,
+  _files: FileMap,
+  drawings: Record<string, DrawingData>
+): { sceneData: SceneData; newId: string } {
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const id = mintActorId(existingIds);
+  const width = 64;
+  const height = 64;
+  const layout: LayoutProps = {
+    x: Math.round((CARD_WIDTH - width) / 2),
+    y: Math.round((CARD_HEIGHT - height) / 2),
+    width,
+    height,
+    z: 0,
+    rotation: 0,
+  };
+  const components: ActorData['components'] = { Layout: layout };
+  const drawingPath = Object.keys(drawings).sort()[0];
+  if (drawingPath) {
+    const drawing: DrawingProps = { file: drawingPath };
+    components.Drawing = drawing;
+  }
+  next.actors.push({ id, components });
+  return { sceneData: next, newId: id };
+}
+
+function mintActorId(existing: Set<string>): string {
+  for (let attempt = 0; attempt < 64; attempt++) {
+    const candidate = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, '0');
+    if (!existing.has(candidate)) return candidate;
+  }
+  return `${Date.now().toString(16)}${Math.floor(Math.random() * 0xffff).toString(16)}`;
+}
+
+export function screenToCard(
+  canvas: HTMLCanvasElement,
+  clientX: number,
+  clientY: number
+): { x: number; y: number } {
+  const rect = canvas.getBoundingClientRect();
+  return {
+    x: ((clientX - rect.left) / rect.width) * CARD_WIDTH,
+    y: ((clientY - rect.top) / rect.height) * CARD_HEIGHT,
+  };
+}
+
+export const cardSize = { width: CARD_WIDTH, height: CARD_HEIGHT };
+
+export function configureSceneCanvas(
+  canvas: HTMLCanvasElement,
+  ctx = canvas.getContext('2d')
+): CanvasRenderingContext2D | null {
+  if (!ctx) return null;
+  const rect = canvas.getBoundingClientRect();
+  const dpr = window.devicePixelRatio || 1;
+  const displayWidth = rect.width || CARD_WIDTH;
+  const displayHeight = rect.height || CARD_HEIGHT;
+  const pixelWidth = Math.max(1, Math.round(displayWidth * dpr));
+  const pixelHeight = Math.max(1, Math.round(displayHeight * dpr));
+  if (canvas.width !== pixelWidth) canvas.width = pixelWidth;
+  if (canvas.height !== pixelHeight) canvas.height = pixelHeight;
+  ctx.setTransform(pixelWidth / CARD_WIDTH, 0, 0, pixelHeight / CARD_HEIGHT, 0, 0);
+  ctx.imageSmoothingEnabled = true;
+  return ctx;
+}
+
+function drawGrid(ctx: CanvasRenderingContext2D): void {
+  ctx.save();
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.08)';
+  ctx.lineWidth = 1;
+  for (let x = 0; x <= CARD_WIDTH; x += 25) {
+    ctx.beginPath();
+    ctx.moveTo(x + 0.5, 0);
+    ctx.lineTo(x + 0.5, CARD_HEIGHT);
+    ctx.stroke();
+  }
+  for (let y = 0; y <= CARD_HEIGHT; y += 25) {
+    ctx.beginPath();
+    ctx.moveTo(0, y + 0.5);
+    ctx.lineTo(CARD_WIDTH, y + 0.5);
+    ctx.stroke();
+  }
+  ctx.restore();
+}
+
+function drawEditPlaceholder(ctx: CanvasRenderingContext2D, actor: ActorData): void {
+  const layout = getLayout(actor);
+  if (!layout) return;
+  ctx.save();
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.04)';
+  ctx.fillRect(layout.x, layout.y, layout.width, layout.height);
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.25)';
+  ctx.lineWidth = 1;
+  ctx.strokeRect(layout.x + 0.5, layout.y + 0.5, layout.width - 1, layout.height - 1);
+  ctx.restore();
+}
+
+function drawMarquee(ctx: CanvasRenderingContext2D, rect: SelectionRect): void {
+  if (rect.width === 0 || rect.height === 0) return;
+  ctx.save();
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.12)';
+  ctx.fillRect(rect.x, rect.y, rect.width, rect.height);
+  ctx.strokeStyle = 'rgba(255, 255, 255, 0.85)';
+  ctx.lineWidth = 1;
+  ctx.setLineDash([4, 3]);
+  ctx.strokeRect(rect.x + 0.5, rect.y + 0.5, rect.width - 1, rect.height - 1);
+  ctx.restore();
+}
+
+function drawSelection(ctx: CanvasRenderingContext2D, actor: ActorData): void {
+  const layout = getLayout(actor);
+  if (!layout) return;
+  ctx.save();
+  applyLayoutRotation(ctx, layout);
+  ctx.strokeStyle = '#fff';
+  ctx.lineWidth = 2;
+  ctx.setLineDash([6, 4]);
+  ctx.strokeRect(layout.x + 1, layout.y + 1, layout.width - 2, layout.height - 2);
+  ctx.restore();
+}
+
+function applyLayoutRotation(
+  ctx: CanvasRenderingContext2D,
+  layout: LayoutProps | undefined
+): void {
+  const rotation = layout?.rotation ?? 0;
+  if (!rotation || !layout) return;
+  const cx = layout.x + layout.width / 2;
+  const cy = layout.y + layout.height / 2;
+  ctx.translate(cx, cy);
+  ctx.rotate((rotation * Math.PI) / 180);
+  ctx.translate(-cx, -cy);
+}
+
+function getLayout(actor: ActorData): LayoutProps | undefined {
+  return actor.components.Layout as LayoutProps | undefined;
+}