@rune-kit/rune 2.1.1 → 2.2.1

package/extensions/gamedev/skills/audio-system.md

@@ -0,0 +1,129 @@
+---
+name: "audio-system"
+pack: "@rune/gamedev"
+description: "Web Audio API, spatial audio, SFX management — AudioManager with spatial audio, music crossfade, and SFX pooling."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# audio-system
+
+Web Audio API, spatial audio, SFX management — AudioManager with spatial audio, music crossfade, and SFX pooling.
+
+#### Workflow
+
+**Step 1 — Detect audio setup**
+Use Grep to find audio code: `AudioContext`, `Howler`, `Audio`, `createBufferSource`, `createGain`. Read the audio initialization to understand: context management, volume controls, and loading strategy.
+
+**Step 2 — Audit audio configuration**
+Check for: AudioContext not resumed on user gesture (browser autoplay policy), SFX creating new nodes on every play (memory pressure), no volume normalization (clipping), missing cleanup on scene exit.
+
+**Step 3 — Emit AudioManager**
+Emit: AudioManager class with master/music/sfx gain chain, music crossfade, spatial (3D) audio via PannerNode, and SFX pooling.
+
+#### Web Audio API — Full Audio Manager
+
+```typescript
+// AudioManager — spatial audio, music crossfade, SFX pooling
+class AudioManager {
+  private ctx: AudioContext;
+  private masterGain: GainNode;
+  private musicGain: GainNode;
+  private sfxGain: GainNode;
+  private buffers = new Map<string, AudioBuffer>();
+  private sfxPool = new Map<string, AudioBufferSourceNode[]>();
+  private currentMusic: AudioBufferSourceNode | null = null;
+
+  constructor() {
+    this.ctx = new AudioContext();
+    this.masterGain = this.ctx.createGain();
+    this.musicGain = this.ctx.createGain();
+    this.sfxGain = this.ctx.createGain();
+
+    this.musicGain.connect(this.masterGain);
+    this.sfxGain.connect(this.masterGain);
+    this.masterGain.connect(this.ctx.destination);
+
+    this.musicGain.gain.value = 0.6;
+    this.sfxGain.gain.value = 1.0;
+  }
+
+  async load(id: string, url: string) {
+    const response = await fetch(url);
+    const arrayBuffer = await response.arrayBuffer();
+    this.buffers.set(id, await this.ctx.decodeAudioData(arrayBuffer));
+  }
+
+  playSfx(id: string, options: { volume?: number; detune?: number } = {}) {
+    const buffer = this.buffers.get(id);
+    if (!buffer) return;
+
+    // Resume context if suspended (browser autoplay policy)
+    if (this.ctx.state === 'suspended') this.ctx.resume();
+
+    const source = this.ctx.createBufferSource();
+    const gain = this.ctx.createGain();
+    source.buffer = buffer;
+    source.detune.value = options.detune ?? 0;
+    gain.gain.value = options.volume ?? 1;
+
+    source.connect(gain).connect(this.sfxGain);
+    source.start();
+  }
+
+  // Music crossfade — smooth transition between tracks
+  async crossfadeTo(id: string, fadeDuration = 2) {
+    const buffer = this.buffers.get(id);
+    if (!buffer) return;
+    if (this.ctx.state === 'suspended') await this.ctx.resume();
+
+    const newSource = this.ctx.createBufferSource();
+    newSource.buffer = buffer;
+    newSource.loop = true;
+
+    const newGain = this.ctx.createGain();
+    newGain.gain.setValueAtTime(0, this.ctx.currentTime);
+    newGain.gain.linearRampToValueAtTime(1, this.ctx.currentTime + fadeDuration);
+
+    newSource.connect(newGain).connect(this.musicGain);
+    newSource.start();
+
+    if (this.currentMusic) {
+      const oldGain = this.ctx.createGain();
+      oldGain.gain.setValueAtTime(1, this.ctx.currentTime);
+      oldGain.gain.linearRampToValueAtTime(0, this.ctx.currentTime + fadeDuration);
+      this.currentMusic.connect(oldGain).connect(this.musicGain);
+      const old = this.currentMusic;
+      setTimeout(() => old.stop(), fadeDuration * 1000);
+    }
+
+    this.currentMusic = newSource;
+  }
+
+  // Spatial (3D) audio — attenuate by distance from listener
+  playSpatial(id: string, x: number, y: number, z: number) {
+    const buffer = this.buffers.get(id);
+    if (!buffer) return;
+
+    const source = this.ctx.createBufferSource();
+    const panner = this.ctx.createPanner();
+    source.buffer = buffer;
+
+    panner.panningModel = 'HRTF';
+    panner.distanceModel = 'inverse';
+    panner.refDistance = 1;
+    panner.maxDistance = 100;
+    panner.rolloffFactor = 1;
+    panner.positionX.value = x;
+    panner.positionY.value = y;
+    panner.positionZ.value = z;
+
+    source.connect(panner).connect(this.sfxGain);
+    source.start();
+  }
+
+  setMasterVolume(v: number) { this.masterGain.gain.value = Math.max(0, Math.min(1, v)); }
+  setMusicVolume(v: number) { this.musicGain.gain.value = Math.max(0, Math.min(1, v)); }
+  setSfxVolume(v: number) { this.sfxGain.gain.value = Math.max(0, Math.min(1, v)); }
+}
+```

package/extensions/gamedev/skills/camera-system.md

@@ -0,0 +1,87 @@
+---
+name: "camera-system"
+pack: "@rune/gamedev"
+description: "Follow camera, screen shake, zoom — 2D camera with smooth lerp follow, dead zone, screen shake on impact, and zoom-to target."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# camera-system
+
+Follow camera, screen shake, zoom — 2D camera with smooth lerp follow, dead zone, screen shake on impact, and zoom-to target.
+
+#### Workflow
+
+**Step 1 — Detect camera usage**
+Use Grep to find camera code: `Camera`, `follow`, `viewport`, `ctx.translate`, `ctx.setTransform`. Read to understand: follow strategy, any existing shake/zoom, and how transform is applied to canvas.
+
+**Step 2 — Audit camera configuration**
+Check for: camera snapping to target each frame (no lerp = no smoothness), no dead zone (camera moves even for tiny player motion), screen shake with random offset not decaying.
+
+**Step 3 — Emit Camera2D**
+Emit: Camera2D with smooth lerp, configurable dead zone, screen shake with intensity decay, zoom-to target, and `applyToContext` helper.
+
+#### Smooth Follow, Screen Shake, Dead Zone
+
+```typescript
+// 2D camera system — smooth follow, screen shake, zoom, dead zone
+class Camera2D {
+  x = 0; y = 0;
+  zoom = 1;
+  private targetX = 0; private targetY = 0;
+  private shakeIntensity = 0; private shakeDuration = 0;
+  lerpSpeed = 5;
+
+  // Dead zone — camera only moves when target leaves this box
+  private deadZone = { w: 80, h: 60 };
+
+  follow(targetX: number, targetY: number, dt: number) {
+    const dx = targetX - this.targetX;
+    const dy = targetY - this.targetY;
+
+    // Only move camera when target exits dead zone
+    if (Math.abs(dx) > this.deadZone.w / 2) this.targetX += dx - Math.sign(dx) * this.deadZone.w / 2;
+    if (Math.abs(dy) > this.deadZone.h / 2) this.targetY += dy - Math.sign(dy) * this.deadZone.h / 2;
+
+    // Smooth lerp
+    this.x += (this.targetX - this.x) * this.lerpSpeed * dt;
+    this.y += (this.targetY - this.y) * this.lerpSpeed * dt;
+  }
+
+  shake(intensity: number, duration: number) {
+    this.shakeIntensity = intensity;
+    this.shakeDuration = duration;
+  }
+
+  zoomTo(target: number, dt: number, speed = 3) {
+    this.zoom += (target - this.zoom) * speed * dt;
+  }
+
+  update(dt: number): { x: number; y: number; zoom: number } {
+    let sx = 0; let sy = 0;
+    if (this.shakeDuration > 0) {
+      this.shakeDuration -= dt;
+      const t = Math.max(0, this.shakeDuration);
+      sx = (Math.random() * 2 - 1) * this.shakeIntensity * t;
+      sy = (Math.random() * 2 - 1) * this.shakeIntensity * t;
+    }
+    return { x: this.x + sx, y: this.y + sy, zoom: this.zoom };
+  }
+
+  // Apply to Canvas 2D context
+  applyToContext(ctx: CanvasRenderingContext2D, screenW: number, screenH: number) {
+    const { x, y, zoom } = this.update(1 / 60);
+    ctx.setTransform(zoom, 0, 0, zoom, screenW / 2 - x * zoom, screenH / 2 - y * zoom);
+  }
+}
+
+// Usage
+const camera = new Camera2D();
+camera.lerpSpeed = 8;
+
+// In game loop render:
+// camera.follow(player.x, player.y, dt);
+// camera.applyToContext(ctx, canvas.width, canvas.height);
+// ... draw scene ...
+// ctx.setTransform(1, 0, 0, 1, 0, 0); // reset for HUD
+```

package/extensions/gamedev/skills/ecs.md

@@ -0,0 +1,98 @@
+---
+name: "ecs"
+pack: "@rune/gamedev"
+description: "Entity Component System architecture — archetype-based ECS with dense array storage for cache efficiency, pure system functions, and query-based entity iteration."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# ecs
+
+Entity Component System architecture — archetype-based ECS with dense array storage for cache efficiency, pure system functions, and query-based entity iteration.
+
+#### Workflow
+
+**Step 1 — Detect ECS usage**
+Use Grep to find ECS patterns: `Entity`, `Component`, `System`, `World`, `bitECS`, `createWorld`. Read entity management code to understand: component storage, system execution order, and query patterns.
+
+**Step 2 — Audit ECS architecture**
+Check for: logic mixed into components (components should be pure data), O(n²) entity iteration without spatial partitioning, components stored as objects (prefer flat arrays for cache efficiency), and missing entity cleanup on destroy.
+
+**Step 3 — Emit ECS scaffold**
+Emit: World class with entity registry + component storage, query-based entity iteration, pure system functions, and proper cleanup.
+
+#### Lightweight ECS — Archetype-Based
+
+```typescript
+// Minimal ECS — dense array storage per archetype for cache efficiency
+type EntityId = number;
+type ComponentType<T> = { new(...args: unknown[]): T; readonly typeName: string; };
+
+// Components are plain data, no logic
+class Position { static typeName = 'Position'; constructor(public x = 0, public y = 0) {} }
+class Velocity { static typeName = 'Velocity'; constructor(public vx = 0, public vy = 0) {} }
+class Sprite   { static typeName = 'Sprite';   constructor(public textureId = '') {} }
+class Health   { static typeName = 'Health';   constructor(public hp = 100, public max = 100) {} }
+
+// World — entity registry + component storage
+class World {
+  private nextId = 1;
+  private components = new Map<string, Map<EntityId, unknown>>();
+
+  createEntity(): EntityId { return this.nextId++; }
+
+  addComponent<T extends object>(entity: EntityId, component: T & { constructor: { typeName: string } }) {
+    const name = component.constructor.typeName;
+    if (!this.components.has(name)) this.components.set(name, new Map());
+    this.components.get(name)!.set(entity, component);
+  }
+
+  getComponent<T>(entity: EntityId, type: ComponentType<T>): T | undefined {
+    return this.components.get(type.typeName)?.get(entity) as T | undefined;
+  }
+
+  removeComponent<T>(entity: EntityId, type: ComponentType<T>) {
+    this.components.get(type.typeName)?.delete(entity);
+  }
+
+  // Query — iterate entities that have ALL specified components
+  query<T extends object[]>(...types: { [K in keyof T]: ComponentType<T[K]> }): EntityId[] {
+    if (types.length === 0) return [];
+    const [first, ...rest] = types;
+    const candidates = Array.from(this.components.get(first.typeName)?.keys() ?? []);
+    return candidates.filter(id => rest.every(t => this.components.get(t.typeName)?.has(id)));
+  }
+
+  destroyEntity(entity: EntityId) {
+    this.components.forEach(store => store.delete(entity));
+  }
+}
+
+// Systems — pure functions over component queries
+const movementSystem = (world: World, dt: number) => {
+  for (const id of world.query(Position, Velocity)) {
+    const pos = world.getComponent(id, Position)!;
+    const vel = world.getComponent(id, Velocity)!;
+    pos.x += vel.vx * dt;
+    pos.y += vel.vy * dt;
+  }
+};
+
+const healthSystem = (world: World) => {
+  for (const id of world.query(Health)) {
+    const hp = world.getComponent(id, Health)!;
+    if (hp.hp <= 0) world.destroyEntity(id);
+  }
+};
+
+// Usage
+const world = new World();
+const player = world.createEntity();
+world.addComponent(player, new Position(100, 100));
+world.addComponent(player, new Velocity(0, 0));
+world.addComponent(player, new Health(100, 100));
+
+// In fixed update:
+// movementSystem(world, dt);
+// healthSystem(world);
+```

package/extensions/gamedev/skills/game-loops.md

@@ -0,0 +1,72 @@
+---
+name: "game-loops"
+pack: "@rune/gamedev"
+description: "Game loop architecture — fixed timestep, interpolation, input handling, state machines, ECS."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# game-loops
+
+Game loop architecture — fixed timestep, interpolation, input handling, state machines, ECS.
+
+#### Workflow
+
+**Step 1 — Detect game loop pattern**
+Use Grep to find loop code: `requestAnimationFrame`, `setInterval.*16`, `update`, `fixedUpdate`, `deltaTime`, `gameLoop`. Read the main loop to understand: timestep strategy, update/render separation, and input handling.
+
+**Step 2 — Audit loop correctness**
+Check for: variable timestep physics (non-deterministic), no accumulator for fixed update (physics tied to framerate), input polled inside render (inconsistent), missing interpolation between fixed steps (visual stuttering), and no frame budget monitoring.
+
+**Step 3 — Emit fixed timestep loop**
+Emit: fixed timestep (60Hz) with accumulator, interpolation for smooth rendering, decoupled input handler, and frame budget monitoring.
+
+#### Example
+
+```typescript
+// Fixed timestep game loop with interpolation
+const TICK_RATE = 60;
+const TICK_DURATION = 1000 / TICK_RATE;
+
+class GameLoop {
+  private accumulator = 0;
+  private previousTime = 0;
+  private running = false;
+
+  constructor(
+    private update: (dt: number) => void,     // fixed timestep logic
+    private render: (alpha: number) => void,   // interpolated rendering
+  ) {}
+
+  start() {
+    this.running = true;
+    this.previousTime = performance.now();
+    requestAnimationFrame(this.tick);
+  }
+
+  private tick = (currentTime: number) => {
+    if (!this.running) return;
+    const elapsed = Math.min(currentTime - this.previousTime, 250); // cap spiral of death
+    this.previousTime = currentTime;
+    this.accumulator += elapsed;
+
+    while (this.accumulator >= TICK_DURATION) {
+      this.update(TICK_DURATION / 1000); // dt in seconds
+      this.accumulator -= TICK_DURATION;
+    }
+
+    const alpha = this.accumulator / TICK_DURATION; // interpolation factor [0, 1)
+    this.render(alpha);
+    requestAnimationFrame(this.tick);
+  };
+
+  stop() { this.running = false; }
+}
+
+// Usage
+const loop = new GameLoop(
+  (dt) => { world.step(dt); entities.forEach(e => e.update(dt)); },
+  (alpha) => { renderer.render(scene, camera, alpha); },
+);
+loop.start();
+```

package/extensions/gamedev/skills/input-system.md

@@ -0,0 +1,199 @@
+---
+name: "input-system"
+pack: "@rune/gamedev"
+description: "Keyboard/mouse/gamepad/touch input handling — unified InputManager with action mapping, input buffering, coyote time, and touch virtual joystick."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# input-system
+
+Keyboard/mouse/gamepad/touch input handling — unified InputManager with action mapping, input buffering, coyote time, and touch virtual joystick.
+
+#### Workflow
+
+**Step 1 — Detect input handling**
+Use Grep to find input code: `addEventListener.*keydown`, `addEventListener.*gamepad`, `onMouseMove`, `ontouchstart`. Read input handlers to understand: action mapping strategy, polling vs event-driven, and platform support.
+
+**Step 2 — Audit input correctness**
+Check for: input polled inside render loop (should be in fixed update), no gamepad support, missing touch controls for mobile, hardcoded key bindings, and no input buffering (missed jump inputs).
+
+**Step 3 — Emit InputManager**
+Emit: unified InputManager with keyboard/mouse/gamepad/touch, action-based API, justPressed/wasReleased one-frame flags, and runtime rebinding. Always call `flush()` at end of each fixed tick.
+
+#### Unified Input Handler — Keyboard, Mouse, Gamepad, Touch
+
+```typescript
+// InputManager — supports keyboard, mouse, gamepad, touch with action mapping
+type ActionMap = Record<string, string[]>; // action → [key1, key2, ...]
+
+const DEFAULT_ACTIONS: ActionMap = {
+  moveUp:    ['KeyW', 'ArrowUp'],
+  moveDown:  ['KeyS', 'ArrowDown'],
+  moveLeft:  ['KeyA', 'ArrowLeft'],
+  moveRight: ['KeyD', 'ArrowRight'],
+  jump:      ['Space'],
+  attack:    ['Mouse0'],
+  pause:     ['Escape'],
+};
+
+class InputManager {
+  private held = new Set<string>();
+  private justPressed = new Set<string>();
+  private justReleased = new Set<string>();
+  private axes = { x: 0, y: 0 };
+  private gamepad: Gamepad | null = null;
+  private bindings: ActionMap;
+
+  constructor(bindings = DEFAULT_ACTIONS) {
+    this.bindings = { ...bindings };
+    window.addEventListener('keydown', e => { this.held.add(e.code); this.justPressed.add(e.code); });
+    window.addEventListener('keyup', e => { this.held.delete(e.code); this.justReleased.add(e.code); });
+    window.addEventListener('mousedown', e => this.held.add(`Mouse${e.button}`));
+    window.addEventListener('mouseup', e => this.held.delete(`Mouse${e.button}`));
+    window.addEventListener('gamepaddisconnected', () => { this.gamepad = null; });
+  }
+
+  // Call at the START of each fixed update tick, not inside render
+  pollGamepad() {
+    const pads = navigator.getGamepads();
+    this.gamepad = pads[0] ?? null;
+    if (this.gamepad) {
+      this.axes.x = this.gamepad.axes[0];
+      this.axes.y = this.gamepad.axes[1];
+    }
+  }
+
+  // Call at END of each fixed update tick to clear one-frame flags
+  flush() {
+    this.justPressed.clear();
+    this.justReleased.clear();
+  }
+
+  isDown(action: string): boolean {
+    return (this.bindings[action] ?? []).some(key => this.held.has(key));
+  }
+
+  wasPressed(action: string): boolean {
+    return (this.bindings[action] ?? []).some(key => this.justPressed.has(key));
+  }
+
+  wasReleased(action: string): boolean {
+    return (this.bindings[action] ?? []).some(key => this.justReleased.has(key));
+  }
+
+  getAxes() { return { ...this.axes }; }
+
+  // Rebind at runtime (save to localStorage)
+  rebind(action: string, keys: string[]) {
+    this.bindings[action] = keys;
+    localStorage.setItem('inputBindings', JSON.stringify(this.bindings));
+  }
+
+  loadSavedBindings() {
+    const saved = localStorage.getItem('inputBindings');
+    if (saved) this.bindings = { ...this.bindings, ...JSON.parse(saved) };
+  }
+}
+```
+
+#### Input Buffering (Coyote Time + Jump Buffering)
+
+```typescript
+// Input buffer — remember button press for N frames to forgive missed timing
+class InputBuffer {
+  private buffer: Map<string, number> = new Map(); // action → frames remaining
+
+  bufferAction(action: string, frames = 6) { this.buffer.set(action, frames); }
+
+  consume(action: string): boolean {
+    if ((this.buffer.get(action) ?? 0) > 0) {
+      this.buffer.set(action, 0);
+      return true;
+    }
+    return false;
+  }
+
+  tick() {
+    this.buffer.forEach((frames, action) => {
+      if (frames > 0) this.buffer.set(action, frames - 1);
+    });
+  }
+}
+
+// Coyote time — allow jump for N frames after walking off a ledge
+class CoyoteTime {
+  private grounded = false;
+  private coyoteFrames = 0;
+  private readonly maxFrames = 6;
+
+  update(isGrounded: boolean) {
+    if (isGrounded) {
+      this.grounded = true;
+      this.coyoteFrames = this.maxFrames;
+    } else {
+      this.grounded = false;
+      this.coyoteFrames = Math.max(0, this.coyoteFrames - 1);
+    }
+  }
+
+  canJump(): boolean { return this.coyoteFrames > 0; }
+}
+```
+
+#### Touch Virtual Joystick (Mobile)
+
+```typescript
+// Canvas-rendered virtual joystick for mobile
+class VirtualJoystick {
+  private origin: { x: number; y: number } | null = null;
+  private current: { x: number; y: number } | null = null;
+  private touchId: number | null = null;
+  readonly radius = 60;
+
+  constructor(private canvas: HTMLCanvasElement) {
+    canvas.addEventListener('touchstart', this.onStart, { passive: false });
+    canvas.addEventListener('touchmove', this.onMove, { passive: false });
+    canvas.addEventListener('touchend', this.onEnd);
+  }
+
+  private onStart = (e: TouchEvent) => {
+    e.preventDefault();
+    if (this.touchId !== null) return;
+    const t = e.changedTouches[0];
+    this.touchId = t.identifier;
+    this.origin = { x: t.clientX, y: t.clientY };
+    this.current = { ...this.origin };
+  };
+
+  private onMove = (e: TouchEvent) => {
+    e.preventDefault();
+    const t = Array.from(e.changedTouches).find(t => t.identifier === this.touchId);
+    if (!t || !this.origin) return;
+    const dx = t.clientX - this.origin.x;
+    const dy = t.clientY - this.origin.y;
+    const len = Math.hypot(dx, dy);
+    const clamped = Math.min(len, this.radius);
+    const angle = Math.atan2(dy, dx);
+    this.current = {
+      x: this.origin.x + Math.cos(angle) * clamped,
+      y: this.origin.y + Math.sin(angle) * clamped,
+    };
+  };
+
+  private onEnd = (e: TouchEvent) => {
+    if (Array.from(e.changedTouches).some(t => t.identifier === this.touchId)) {
+      this.origin = this.current = null;
+      this.touchId = null;
+    }
+  };
+
+  getAxes(): { x: number; y: number } {
+    if (!this.origin || !this.current) return { x: 0, y: 0 };
+    return {
+      x: (this.current.x - this.origin.x) / this.radius,
+      y: (this.current.y - this.origin.y) / this.radius,
+    };
+  }
+}
+```