html5-game-editor: Skill for Cursor

Create Game Component (OOP)

Prefer an OOP behaviour class that implements ScriptInstance, then wrap it with defineComponent({ create: (ctx) => new MyBehaviour(ctx) }).

This skill is only Script components (type: "Script"). Scene node types → .cursor/skills/add-node-type/SKILL.md. Runtime services / GameRuntime / audio host (not a new defineComponent) → .cursor/skills/implement-runtime-feature/SKILL.md. New game package → .cursor/skills/create-game/SKILL.md.

Do not put large logic in a bare create closure. Do not store class instances in scene JSON.

Placement

Shared components must stay runtime-safe: no React, Pixi, Three, or editor-core.

OOP pattern (required)

import {
  defineComponent,
  type ComponentDefinition,
  type ComponentRegistry,
  type ScriptCreateContext,
  type ScriptInstance,
} from "@game-editor/game-components";

type Props = {
  speed: number;
  enabled: boolean;
};

function readProps(raw: Readonly<Record<string, unknown>>): Props {
  return {
    speed: typeof raw.speed === "number" ? raw.speed : 1,
    enabled: typeof raw.enabled === "boolean" ? raw.enabled : true,
  };
}

/** Live instance — one per Script component on a node. */
export class SpinControllerBehaviour implements ScriptInstance {
  private speed = 1;
  private enabled = true;
  private unsubscribers: Array<() => void> = [];

  constructor(private readonly ctx: ScriptCreateContext) {
    this.applyProperties(ctx.properties);
  }

  start(): void {
    this.bind();
  }

  onPropertiesChanged(
    properties: Readonly<Record<string, unknown>>,
  ): void {
    this.applyProperties(properties);
  }

  update(dt: number): void {
    if (!this.enabled || dt <= 0) {
      return;
    }
    this.ctx.transform.rotation += this.speed * dt;
  }

  destroy(): void {
    this.unbind();
  }

  private applyProperties(raw: Readonly<Record<string, unknown>>): void {
    const props = readProps(raw);
    this.speed = props.speed;
    this.enabled = props.enabled;
  }

  private bind(): void {
    this.unbind();
    const { bus } = this.ctx.services;
    this.unsubscribers.push(
      bus.on("game.tick", () => {
        if (!this.enabled) return;
        // use ctx.nodeId, ctx.transform, ctx.transform3D, ctx.animations, services
      }),
    );
  }

  private unbind(): void {
    for (const off of this.unsubscribers) off();
    this.unsubscribers = [];
  }
}

const PROPERTIES: ComponentDefinition["properties"] = {
  speed: { kind: "number", default: 1, min: 0, step: 0.1 },
  enabled: { kind: "boolean", default: true },
};

export const spinControllerComponent = defineComponent({
  id: "example.SpinController",
  displayName: "Spin Controller",
  category: "UI",
  categoryOrder: 20,
  order: 10,
  allowMultiple: false,
  properties: PROPERTIES,
  create: (ctx) => new SpinControllerBehaviour(ctx),
});

/** Re-attach create after metadata-only catalog load. */
export function installSpinControllerRuntime(registry: ComponentRegistry): void {
  registry.attachRuntime(spinControllerComponent.id, spinControllerComponent.create);
}