@starlein/paperclip-plugin-company-wizard 0.2.1

package/templates/modules/game-design/docs/engine-phaser.md

@@ -0,0 +1,310 @@
+# Engine Guide: Phaser
+
+Phaser is a 2D HTML5 game framework. Use it for: platformers, top-down RPGs, puzzle games, arcade games, visual novels — anything 2D that runs in the browser.
+
+## Project Setup
+
+```bash
+npm create @phaserjs/game@latest my-game
+cd my-game && npm install
+```
+
+Or manually:
+
+```bash
+npm init -y && npm install phaser
+```
+
+Minimal game entry:
+
+```javascript
+import Phaser from 'phaser';
+
+const config = {
+  type: Phaser.AUTO,           // WebGL with Canvas fallback
+  width: 800,
+  height: 600,
+  physics: {
+    default: 'arcade',
+    arcade: { gravity: { y: 300 }, debug: false }
+  },
+  scene: { preload, create, update }
+};
+
+const game = new Phaser.Game(config);
+```
+
+## Core Architecture
+
+### Scenes
+
+Scenes are the fundamental organizational unit. Every screen (menu, gameplay, pause, game over) is a Scene.
+
+```javascript
+class GameScene extends Phaser.Scene {
+  constructor() { super('GameScene'); }
+
+  preload() {
+    this.load.image('sky', 'assets/sky.png');
+    this.load.spritesheet('player', 'assets/player.png', {
+      frameWidth: 32, frameHeight: 48
+    });
+  }
+
+  create() {
+    this.add.image(400, 300, 'sky');
+    this.player = this.physics.add.sprite(100, 450, 'player');
+    this.player.setBounce(0.2);
+    this.player.setCollideWorldBounds(true);
+    this.cursors = this.input.keyboard.createCursorKeys();
+  }
+
+  update() {
+    if (this.cursors.left.isDown) {
+      this.player.setVelocityX(-160);
+      this.player.anims.play('left', true);
+    } else if (this.cursors.right.isDown) {
+      this.player.setVelocityX(160);
+      this.player.anims.play('right', true);
+    } else {
+      this.player.setVelocityX(0);
+      this.player.anims.play('idle', true);
+    }
+    if (this.cursors.up.isDown && this.player.body.touching.down) {
+      this.player.setVelocityY(-330);
+    }
+  }
+}
+```
+
+Scene transitions:
+
+```javascript
+this.scene.start('GameOverScene', { score: this.score });  // switch scene
+this.scene.launch('PauseScene');   // run in parallel (overlay)
+this.scene.pause();                // pause this scene
+this.scene.resume('GameScene');    // resume a paused scene
+```
+
+### Physics
+
+**Arcade** — fast, AABB-only. Use for most 2D games.
+
+```javascript
+// Static group (platforms, walls)
+const platforms = this.physics.add.staticGroup();
+platforms.create(400, 568, 'ground').setScale(2).refreshBody();
+
+// Dynamic sprites
+const player = this.physics.add.sprite(100, 450, 'player');
+player.setBounce(0.2);
+player.setCollideWorldBounds(true);
+
+// Collisions
+this.physics.add.collider(player, platforms);
+
+// Overlap (pickup items)
+this.physics.add.overlap(player, stars, collectStar, null, this);
+
+function collectStar(player, star) {
+  star.disableBody(true, true);  // remove from physics + hide
+  score += 10;
+}
+```
+
+**Matter** — full rigid body physics with polygons, constraints, joints. Use when you need realistic physics (ragdolls, chains, complex shapes).
+
+```javascript
+const config = {
+  physics: {
+    default: 'matter',
+    matter: { gravity: { y: 1 }, debug: true }
+  }
+};
+
+// Matter body
+const box = this.matter.add.image(400, 200, 'box');
+box.setFriction(0.005);
+box.setBounce(0.6);
+```
+
+### Animations
+
+```javascript
+this.anims.create({
+  key: 'walk',
+  frames: this.anims.generateFrameNumbers('player', { start: 0, end: 7 }),
+  frameRate: 10,
+  repeat: -1    // -1 = loop forever
+});
+
+this.anims.create({
+  key: 'idle',
+  frames: [{ key: 'player', frame: 4 }],
+  frameRate: 20
+});
+
+sprite.anims.play('walk', true);  // true = ignore if already playing
+sprite.on('animationcomplete', (anim) => { /* ... */ });
+```
+
+### Tilemaps
+
+```javascript
+preload() {
+  this.load.tilemapTiledJSON('map', 'assets/map.json');  // Tiled editor export
+  this.load.image('tiles', 'assets/tileset.png');
+}
+
+create() {
+  const map = this.make.tilemap({ key: 'map' });
+  const tileset = map.addTilesetImage('tileset-name', 'tiles');
+  const ground = map.createLayer('Ground', tileset);
+  const walls = map.createLayer('Walls', tileset);
+
+  walls.setCollisionByProperty({ collides: true });
+  this.physics.add.collider(this.player, walls);
+
+  // Object layer spawn points
+  const spawnPoint = map.findObject('Objects', obj => obj.name === 'Spawn');
+  this.player.setPosition(spawnPoint.x, spawnPoint.y);
+}
+```
+
+### Input
+
+```javascript
+// Keyboard
+const cursors = this.input.keyboard.createCursorKeys();
+const wasd = this.input.keyboard.addKeys('W,A,S,D');
+const space = this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.SPACE);
+
+// Pointer (mouse + touch)
+this.input.on('pointerdown', (pointer) => {
+  console.log(pointer.x, pointer.y, pointer.button);
+});
+
+// Gamepad
+this.input.gamepad.on('connected', (pad) => { /* ... */ });
+```
+
+### Camera
+
+```javascript
+this.cameras.main.startFollow(this.player, true, 0.08, 0.08);
+this.cameras.main.setZoom(2);
+this.cameras.main.setBounds(0, 0, map.widthInPixels, map.heightInPixels);
+this.cameras.main.fadeIn(500);
+```
+
+### Audio
+
+```javascript
+preload() {
+  this.load.audio('bgm', 'assets/music.ogg');
+  this.load.audio('jump', 'assets/jump.wav');
+}
+
+create() {
+  this.bgm = this.sound.add('bgm', { loop: true, volume: 0.5 });
+  this.bgm.play();
+
+  this.jumpSfx = this.sound.add('jump');
+}
+
+// Play on event
+this.jumpSfx.play();
+```
+
+### Groups
+
+```javascript
+const enemies = this.physics.add.group({
+  key: 'enemy',
+  repeat: 5,
+  setXY: { x: 100, y: 0, stepX: 120 }
+});
+
+enemies.children.iterate((child) => {
+  child.setBounceY(Phaser.Math.FloatBetween(0.2, 0.4));
+});
+```
+
+## Project Structure Convention
+
+```
+src/
+├── scenes/
+│   ├── BootScene.js       # Asset loading
+│   ├── MenuScene.js       # Title screen
+│   ├── GameScene.js       # Main gameplay
+│   └── GameOverScene.js   # End screen
+├── objects/
+│   ├── Player.js          # Player class extending Phaser.Physics.Arcade.Sprite
+│   └── Enemy.js
+├── config/
+│   └── constants.js       # Tuning parameters (speeds, gravity, scores)
+└── main.js                # Game config + scene registration
+```
+
+## Tuning Parameters Pattern
+
+Expose all balance values as importable constants — never hardcode in game logic:
+
+```javascript
+// config/constants.js
+export const PLAYER = {
+  SPEED: 160,
+  JUMP_VELOCITY: -330,
+  BOUNCE: 0.2,
+};
+
+export const ENEMIES = {
+  SPEED: 80,
+  SPAWN_INTERVAL: 3000,
+};
+```
+
+## Common Patterns
+
+### State machine for player/enemy states
+
+```javascript
+class Player extends Phaser.Physics.Arcade.Sprite {
+  constructor(scene, x, y) {
+    super(scene, x, y, 'player');
+    scene.add.existing(this);
+    scene.physics.add.existing(this);
+    this.state = 'idle';
+  }
+
+  update(cursors) {
+    switch (this.state) {
+      case 'idle': this.handleIdle(cursors); break;
+      case 'running': this.handleRunning(cursors); break;
+      case 'jumping': this.handleJumping(cursors); break;
+      case 'hurt': this.handleHurt(); break;
+    }
+  }
+}
+```
+
+### Scene data passing
+
+```javascript
+// From GameScene
+this.scene.start('GameOverScene', { score: this.score, level: this.level });
+
+// In GameOverScene
+create(data) {
+  this.add.text(400, 300, `Score: ${data.score}`, { fontSize: '32px' });
+}
+```
+
+## Performance Notes
+
+- Phaser.AUTO picks WebGL when available, falls back to Canvas
+- Use texture atlases (spritesheet packer) instead of individual images to reduce draw calls
+- Object pooling: reuse sprites with `group.get()` instead of creating/destroying
+- Minimize physics bodies — disable physics on off-screen objects
+- Use `this.cameras.main.ignore(uiLayer)` to exclude UI from game camera transforms

package/templates/modules/game-design/docs/engine-pixijs.md

@@ -0,0 +1,289 @@
+# Engine Guide: PixiJS
+
+PixiJS is a fast 2D rendering engine (not a full game framework). Use it for: games where you want full control over the game loop, custom physics, or non-standard rendering. Also great for interactive visualizations, animated UIs, and creative coding. Runs on WebGL/WebGPU with Canvas fallback.
+
+PixiJS handles rendering. You build the game loop, physics, input handling, and scene management yourself (or bring a library).
+
+## Project Setup
+
+```bash
+npm init -y && npm install pixi.js
+```
+
+## Core Architecture
+
+### Application and Game Loop
+
+```javascript
+import { Application, Assets, Sprite, Ticker } from 'pixi.js';
+
+const app = new Application();
+await app.init({
+  width: 800,
+  height: 600,
+  backgroundColor: 0x1099bb,
+  antialias: true,
+  resolution: window.devicePixelRatio,
+  preference: 'webgl',  // or 'webgpu'
+});
+
+document.body.appendChild(app.canvas);
+
+// Game loop via ticker
+app.ticker.add((ticker) => {
+  // ticker.deltaTime = dimensionless scalar (~1.0 at 60fps)
+  // ticker.deltaMS = milliseconds since last frame
+  update(ticker.deltaTime);
+});
+```
+
+### Display Objects and Scene Graph
+
+PixiJS uses a tree of display objects. `app.stage` is the root container.
+
+```javascript
+import { Container, Sprite, Graphics, Text } from 'pixi.js';
+
+// Containers group display objects
+const gameWorld = new Container();
+const uiLayer = new Container();
+app.stage.addChild(gameWorld);
+app.stage.addChild(uiLayer);  // UI renders on top
+
+// Sprites
+const texture = await Assets.load('player.png');
+const player = new Sprite(texture);
+player.anchor.set(0.5);  // center origin
+player.x = 400;
+player.y = 300;
+gameWorld.addChild(player);
+
+// Graphics (primitives)
+const rect = new Graphics();
+rect.rect(0, 0, 50, 50);
+rect.fill(0xff0000);
+gameWorld.addChild(rect);
+
+// Text
+const scoreText = new Text({ text: 'Score: 0', style: { fontSize: 24, fill: 0xffffff } });
+uiLayer.addChild(scoreText);
+```
+
+### Asset Loading
+
+```javascript
+import { Assets, Spritesheet } from 'pixi.js';
+
+// Single asset
+const texture = await Assets.load('bunny.png');
+
+// Multiple assets
+const textures = await Assets.load(['player.png', 'enemy.png', 'tileset.png']);
+
+// Asset bundles (recommended for larger games)
+Assets.addBundle('game', {
+  player: 'assets/player.png',
+  enemy: 'assets/enemy.png',
+  tileset: 'assets/tileset.png',
+  spritesheet: 'assets/sprites.json',
+});
+const assets = await Assets.loadBundle('game');
+
+// Background loading with progress
+Assets.loadBundle('game', (progress) => {
+  console.log(`Loading: ${Math.round(progress * 100)}%`);
+});
+```
+
+### Spritesheet Animations
+
+```javascript
+import { AnimatedSprite, Assets, Texture } from 'pixi.js';
+
+// Load spritesheet (JSON + PNG)
+await Assets.load('spritesheet.json');
+
+// Create frames array
+const frames = [];
+for (let i = 0; i < 8; i++) {
+  frames.push(Texture.from(`walk_${i.toString().padStart(4, '0')}.png`));
+}
+
+const animation = new AnimatedSprite(frames);
+animation.anchor.set(0.5);
+animation.animationSpeed = 0.15;  // speed multiplier
+animation.loop = true;
+animation.play();
+
+// Events
+animation.onComplete = () => { /* non-looping animation finished */ };
+animation.onFrameChange = (frame) => { /* trigger SFX on specific frames */ };
+
+// Controls
+animation.gotoAndPlay(0);   // restart
+animation.gotoAndStop(3);   // freeze on frame
+animation.stop();
+
+gameWorld.addChild(animation);
+```
+
+### Input Handling
+
+PixiJS has pointer events on display objects. For keyboard, use the browser directly.
+
+```javascript
+// Pointer events on sprites
+sprite.eventMode = 'static';  // enable interaction
+sprite.cursor = 'pointer';
+sprite.on('pointerdown', (event) => { /* click/tap */ });
+sprite.on('pointerover', () => { /* hover */ });
+
+// Keyboard (browser API — build your own input manager)
+const keys = {};
+window.addEventListener('keydown', (e) => { keys[e.code] = true; });
+window.addEventListener('keyup', (e) => { keys[e.code] = false; });
+
+// In game loop
+function update(dt) {
+  if (keys['ArrowLeft']) player.x -= SPEED * dt;
+  if (keys['ArrowRight']) player.x += SPEED * dt;
+  if (keys['Space']) jump();
+}
+```
+
+### Ticker (Game Loop) Control
+
+```javascript
+import { Ticker, UPDATE_PRIORITY } from 'pixi.js';
+
+// Priority-based updates (higher priority runs first)
+app.ticker.add((ticker) => {
+  physics.update(ticker.deltaTime);
+}, undefined, UPDATE_PRIORITY.HIGH);
+
+app.ticker.add((ticker) => {
+  render(ticker.deltaTime);
+}, undefined, UPDATE_PRIORITY.NORMAL);
+
+// Speed control (slow motion / fast forward)
+app.ticker.speed = 0.5;  // half speed
+app.ticker.speed = 2.0;  // double speed
+
+// Cap minimum FPS (prevents huge delta spikes on tab-away)
+app.ticker.minFPS = 30;
+```
+
+## Building a Game with PixiJS
+
+Since PixiJS is a renderer, you need to build or bring these yourself:
+
+### Scene Manager Pattern
+
+```javascript
+class SceneManager {
+  constructor(app) {
+    this.app = app;
+    this.currentScene = null;
+  }
+
+  switchTo(SceneClass, data = {}) {
+    if (this.currentScene) {
+      this.app.ticker.remove(this.currentScene.update, this.currentScene);
+      this.currentScene.destroy();
+      this.app.stage.removeChild(this.currentScene.container);
+    }
+    this.currentScene = new SceneClass(this.app, this, data);
+    this.app.stage.addChild(this.currentScene.container);
+    this.app.ticker.add(this.currentScene.update, this.currentScene);
+  }
+}
+
+class GameScene {
+  constructor(app, manager, data) {
+    this.container = new Container();
+    this.manager = manager;
+    // set up game objects...
+  }
+  update(ticker) { /* game loop */ }
+  destroy() { this.container.destroy({ children: true }); }
+}
+```
+
+### Simple AABB Collision
+
+```javascript
+function intersects(a, b) {
+  return a.x < b.x + b.width &&
+         a.x + a.width > b.x &&
+         a.y < b.y + b.height &&
+         a.y + a.height > b.y;
+}
+
+// In update loop
+for (const enemy of enemies) {
+  if (intersects(player.getBounds(), enemy.getBounds())) {
+    handleCollision(player, enemy);
+  }
+}
+```
+
+### Camera (Viewport) Pattern
+
+```javascript
+// Use a container as the "world" and move it to simulate camera
+const world = new Container();
+app.stage.addChild(world);
+
+function updateCamera(target) {
+  world.x = -target.x + app.screen.width / 2;
+  world.y = -target.y + app.screen.height / 2;
+}
+```
+
+## Project Structure Convention
+
+```
+src/
+├── scenes/
+│   ├── MenuScene.js
+│   ├── GameScene.js
+│   └── GameOverScene.js
+├── objects/
+│   ├── Player.js
+│   └── Enemy.js
+├── systems/
+│   ├── InputManager.js    # Keyboard/pointer state
+│   ├── SceneManager.js    # Scene switching
+│   ├── Physics.js         # Collision detection
+│   └── Camera.js          # Viewport management
+├── config/
+│   └── constants.js       # Tuning parameters
+└── main.js                # App init, asset loading, scene start
+```
+
+## Tuning Parameters Pattern
+
+```javascript
+export const PLAYER = {
+  SPEED: 5,            // pixels per frame at 60fps
+  JUMP_FORCE: -12,
+  GRAVITY: 0.5,
+  MAX_FALL_SPEED: 10,
+};
+```
+
+## Performance Notes
+
+- PixiJS is extremely fast — thousands of sprites at 60fps
+- Use spritesheets/texture atlases to reduce draw calls (TexturePacker, free-tex-packer)
+- `Container.cacheAsChild = true` for complex static containers (renders to texture)
+- Use `ParticleContainer` for large numbers of simple sprites (limited features, big perf gain)
+- Destroy textures and display objects when done: `sprite.destroy({ texture: true })`
+- `app.ticker.minFPS = 30` prevents huge delta spikes when tab is backgrounded
+
+## Useful Companion Libraries
+
+- **bump.js** or custom AABB — collision detection
+- **pixi-viewport** — camera/viewport with pan, zoom, follow
+- **pixi-sound** — audio playback (PixiJS has no built-in audio)
+- **pixi-filters** — blur, glow, outline, displacement, and other shader effects