@loonylabs/create-game 0.1.0

package/template/.claude/skills/aigdtk-new-game/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: aigdtk-new-game
+description: Start here to create a new game. Leads a structured conversation to capture your game idea, then saves a Game Brief for the next step.
+disable-model-invocation: true
+---
+
+# New Game — Discovery Conversation
+
+## Supporting files (shared knowledge base)
+- Framework reference: [../aigdtk-shared/framework.md](../aigdtk-shared/framework.md)
+- ASCII room grammar: [../aigdtk-shared/ascii-grammar.md](../aigdtk-shared/ascii-grammar.md)
+- Enemy definitions reference: [../aigdtk-shared/enemies.md](../aigdtk-shared/enemies.md)
+- Cell visuals / palettes: [../aigdtk-shared/visuals.md](../aigdtk-shared/visuals.md)
+
+Do NOT load these files during the conversation. They are used by `/aigdtk-create-game-stories`.
+
+---
+
+<activation CRITICAL="TRUE">
+You are now in game discovery mode. Your role is **interviewer and listener**.
+The human is the game designer. You capture their vision — nothing more, nothing less.
+
+## NON-NEGOTIABLE RULES
+
+1. **NEVER ask technical questions.** No questions about: file formats, schemas,
+   ECS, tick rates, area types, JSON, TypeScript, or anything requiring dev knowledge.
+
+2. **NEVER generate any game files.** No code, no JSON, no room layouts.
+   This session is for listening and saving — not building.
+
+3. **Ask product questions only.** Any question must be answerable by someone
+   who has only ever played games, never made one.
+
+4. **Dig deeper when answers are vague.** If the answer to any question is
+   short or unclear, ask ONE follow-up before moving on. Example:
+   - "Dark and moody" → "What game or movie has that exact feeling you're after?"
+   - "Fast enemies" → "Fast like a cat circling you, or fast like a bullet?"
+
+---
+
+## STEP 1 — Ask exactly these 5 questions, all at once
+
+Present them as a numbered list. Do NOT split them across messages.
+
+> **Ich habe 5 Fragen zu deinem Spiel — beantworte sie so ausführlich oder knapp wie du möchtest:**
+>
+> 1. Wie heißt dein Spiel?
+> 2. Beschreib den Core Loop in einem Satz — was macht der Spieler die ganze Zeit?
+> 3. Nenn ein Spiel das sich ähnlich anfühlen soll (Stimmung, Tempo, Schwierigkeit).
+> 4. Beschreib einen Feind — wie heißt er, wie bewegt er sich, wie fühlt es sich an gegen ihn zu kämpfen?
+> 5. Wann wärst du zufrieden? Was muss passieren damit du sagst: "Ja, das ist mein Spiel"?
+
+Wait for answers. Then follow up on anything vague before proceeding.
+
+---
+
+## STEP 2 — Clarify if needed
+
+For each answer that is vague or very short, ask ONE targeted follow-up question.
+Do not bombard with multiple questions at once.
+Do not move to Step 3 until you have enough to paint a clear picture.
+
+---
+
+## STEP 3 — Write the Game Brief
+
+Write `docs/aigdtk/game-brief.md` with this exact structure:
+
+```markdown
+# Game Brief: [Spielname]
+
+_Generated by /aigdtk-new-game — [heutiges Datum]_
+
+## Dev Answers
+
+- **Name:** [Spielname]
+- **Core Loop:** [Core Loop in einem Satz]
+- **Reference Game:** [Referenzspiel]
+- **Enemy:** [Feind-Beschreibung]
+- **Happy When:** [Erfolgs-Kriterium]
+
+## Additional Context
+
+[Alle weiteren Antworten aus Nachfragen, freie Form. Leer lassen wenn keine Nachfragen nötig waren.]
+
+## Derived Decisions
+
+_Diese Sektion wird von /aigdtk-create-game-stories befüllt._
+```
+
+---
+
+## STEP 4 — Show summary for confirmation
+
+Show the developer a compact summary:
+
+> **Hier ist was ich verstanden habe:**
+>
+> 🎮 **[Spielname]**
+> Loop: [Core Loop]
+> Fühlt sich an wie: [Referenzspiel]
+> Feind: [kurze Feind-Beschreibung]
+> Fertig wenn: [Happy When]
+>
+> Passt das so? Dann geht's weiter.
+
+Wait for confirmation ("ja", "yes", "ok", "passt", "stimmt", or similar).
+If the developer corrects something, update the Game Brief and show the summary again.
+
+---
+
+## STEP 5 — Handover message
+
+After confirmation, output exactly this:
+
+```
+✅ Game Brief gespeichert: docs/aigdtk/game-brief.md
+
+Starte eine neue Claude Code Session und führe aus:
+
+/aigdtk-create-game-stories
+```
+
+Nothing else. Do not generate files. Do not explain next steps in detail.
+
+</activation>

package/template/.claude/skills/aigdtk-shared/ascii-grammar.md

@@ -0,0 +1,133 @@
+# ASCII Room Grammar — AI Reference
+
+Load this file when generating or modifying room_*.json files.
+
+---
+
+## Room File Format
+
+Every room is a JSON file in `apps/game-data/src/rooms/`.
+
+```json
+{
+  "id": "room_start",
+  "ascii": [
+    "WWWWWWWWWW",
+    "W........W",
+    "W...S....W",
+    "W........D",
+    "WWWWWWWWWW"
+  ],
+  "tags": ["start"]
+}
+```
+
+---
+
+## Symbol Map
+
+| Symbol | Cell Type | Description |
+|--------|-----------|-------------|
+| `W` | wall | Solid, impassable block |
+| `.` | floor | Walkable ground |
+| `D` | door | Room connection point (must be on outer wall) |
+| `S` | spawn | Player start position |
+| `>` | transition | Transition to another area |
+| `N` | npc | NPC position |
+| `F` | fire | Fire cell (walkable but harmful) |
+| ` ` | empty | No mesh, no collision (void) |
+
+---
+
+## Rules (Critical — violations cause runtime errors)
+
+1. **All rows must be the same length** — pad with spaces if needed
+2. **Exactly one room must have `"tags": ["start"]`** — this is where players spawn
+3. **Doors (`D`) must be on the outermost row or column** — doors on interior walls break navigation
+4. **`S` appears at most once per room** — multiple S cells = undefined behavior
+5. **Rooms must be fully enclosed** — no open edges (walls or doors only on perimeter)
+
+---
+
+## Tags
+
+| Tag | Meaning |
+|-----|---------|
+| `"start"` | Initial spawn room — exactly one room must have this |
+| `"boss"` | Boss encounter room |
+| `"corridor"` | Narrow connecting room |
+| `"treasure"` | Loot room |
+
+Tags are used by the dungeon generator to decide room placement.
+
+---
+
+## Room Design Patterns
+
+### Minimal start room (safe default)
+```json
+{
+  "id": "room_start",
+  "ascii": [
+    "WWWWWWWW",
+    "W......W",
+    "W..S...W",
+    "W......D",
+    "WWWWWWWW"
+  ],
+  "tags": ["start"]
+}
+```
+
+### Corridor (east-west)
+```json
+{
+  "id": "room_corridor_ew",
+  "ascii": [
+    "WWWWWWWWWWWWW",
+    "D...........D",
+    "WWWWWWWWWWWWW"
+  ],
+  "tags": ["corridor"]
+}
+```
+
+### Combat room (multiple doors)
+```json
+{
+  "id": "room_combat",
+  "ascii": [
+    "WWWDWWWWWDWWW",
+    "W...........W",
+    "D...........D",
+    "W...........W",
+    "WWWDWWWWWDWWW"
+  ],
+  "tags": []
+}
+```
+
+### Room with transition to overworld
+```json
+{
+  "id": "room_exit",
+  "ascii": [
+    "WWWWWWWW",
+    "W......W",
+    "W..>...W",
+    "D......W",
+    "WWWWWWWW"
+  ],
+  "tags": []
+}
+```
+
+---
+
+## Minimum Room Set for a Working Dungeon
+
+Provide at least:
+1. One start room (with `"tags": ["start"]` and `S`)
+2. One or two additional rooms with doors for the generator to connect
+
+More rooms = more variety in generated dungeons.

package/template/.claude/skills/aigdtk-shared/enemies.md

@@ -0,0 +1,112 @@
+# Enemy Definitions — AI Reference
+
+Load this file when generating or modifying `apps/game-data/src/enemies/enemy-defs.json`.
+
+---
+
+## File Format
+
+`enemy-defs.json` is a JSON array. Each object defines one enemy type.
+
+```json
+[
+  {
+    "id": "grunt",
+    "hp": 50,
+    "maxHp": 50,
+    "speed": 2.5,
+    "attackDamage": 10,
+    "attackRange": 1.2,
+    "aggroRange": 6,
+    "color": "#cc4444",
+    "scale": 1.0
+  }
+]
+```
+
+**The array must never be empty** — the server will throw on startup.
+
+---
+
+## Field Reference
+
+| Field | Type | Description | Typical range |
+|-------|------|-------------|---------------|
+| `id` | string | Unique identifier, lowercase, no spaces | `"grunt"`, `"fire_bat"` |
+| `hp` | number | Starting hit points | 20–300 |
+| `maxHp` | number | Maximum hit points (usually same as `hp`) | same as `hp` |
+| `speed` | number | Movement speed in world units/second | 1.0–7.0 |
+| `attackDamage` | number | Damage per hit | 5–50 |
+| `attackRange` | number | Distance at which enemy can attack player | 1.0–2.5 |
+| `aggroRange` | number | Distance at which enemy notices player | 4–12 |
+| `color` | string | Hex color string for the enemy mesh | `"#cc4444"` |
+| `scale` | number | Size multiplier (1.0 = normal humanoid) | 0.5–2.5 |
+
+---
+
+## Existing Enemy Examples (Reference Game)
+
+```json
+[
+  {
+    "id": "grunt",
+    "hp": 50, "maxHp": 50, "speed": 2.5,
+    "attackDamage": 10, "attackRange": 1.2, "aggroRange": 6,
+    "color": "#cc4444", "scale": 1.0
+  },
+  {
+    "id": "wolf",
+    "hp": 30, "maxHp": 30, "speed": 5.5,
+    "attackDamage": 8, "attackRange": 1.0, "aggroRange": 7,
+    "color": "#888888", "scale": 0.7
+  },
+  {
+    "id": "skeleton",
+    "hp": 45, "maxHp": 45, "speed": 2.0,
+    "attackDamage": 12, "attackRange": 1.2, "aggroRange": 8,
+    "color": "#e8e0d0", "scale": 0.9
+  },
+  {
+    "id": "golem",
+    "hp": 150, "maxHp": 150, "speed": 1.2,
+    "attackDamage": 30, "attackRange": 1.5, "aggroRange": 4,
+    "color": "#607060", "scale": 1.6
+  }
+]
+```
+
+---
+
+## Deriving Enemy Stats from a Description
+
+### Archetype Defaults
+
+| Description | hp | speed | attackDamage | aggroRange | scale |
+|-------------|-----|-------|--------------|------------|-------|
+| "slow and tanky" | 120–200 | 1.0–2.0 | 20–35 | 4–6 | 1.4–1.8 |
+| "fast and fragile" | 20–35 | 4.5–6.5 | 5–10 | 7–10 | 0.6–0.8 |
+| "balanced fighter" | 45–70 | 2.5–3.5 | 10–18 | 5–7 | 0.9–1.1 |
+| "boss" | 250–500 | 1.5–2.5 | 30–60 | 6–8 | 1.8–2.5 |
+| "swarm unit" | 15–25 | 3.0–4.5 | 4–8 | 6–9 | 0.5–0.7 |
+
+### Color Derivation from Description
+
+| Description keywords | Suggested color |
+|----------------------|-----------------|
+| skeleton, bone, white | `"#e8e0d0"` |
+| fire, flame, lava | `"#ff4400"` |
+| shadow, dark, void | `"#221133"` |
+| ice, frost, cold | `"#88ccff"` |
+| poison, slime, green | `"#44aa33"` |
+| stone, golem, rock | `"#607060"` |
+| wolf, beast, grey | `"#888888"` |
+| demon, blood, red | `"#cc2222"` |
+| ghost, spirit, pale | `"#ccddee"` |
+
+---
+
+## Naming Convention
+
+- Use lowercase with underscores: `"fire_bat"`, `"cave_spider"`
+- Keep ids short and descriptive
+- Avoid spaces, hyphens, or special characters in ids

package/template/.claude/skills/aigdtk-shared/framework.md

@@ -0,0 +1,93 @@
+# Toolkit Framework — AI Reference
+
+This file is loaded by AI tools to understand the gamedev-ai-toolkit structure.
+Read this first before making any changes to a game.
+
+---
+
+## The Mental Model
+
+This toolkit separates **framework** (never touch) from **game content** (your playground).
+
+```
+packages/          ← Framework code — NEVER modify
+apps/client/       ← Framework renderer — NEVER modify
+apps/server/       ← Framework server — NEVER modify
+apps/protocol/     ← Framework network schemas — NEVER modify
+apps/game-data/    ← YOUR game content lives here — modify freely
+```
+
+**Rule:** You only ever touch files inside `apps/game-data/src/`.
+
+---
+
+## What Lives Where (game-data)
+
+| What | File |
+|------|------|
+| Enemy definitions | `apps/game-data/src/enemies/enemy-defs.json` |
+| Room layouts | `apps/game-data/src/rooms/room_*.json` |
+| Area configuration | `apps/game-data/src/areas/area-manifest.json` |
+| Cell visuals (colors/heights) | `apps/game-data/src/dungeon/cell-visuals.ts` |
+| Cell types (symbol map) | `apps/game-data/src/dungeon/cell-types.ts` |
+| Items | `apps/game-data/src/items/item-pool.json` |
+| Audio | `apps/game-data/src/audio/sound-config.json` |
+
+---
+
+## Area Types
+
+| Type | Description | When to use |
+|------|-------------|-------------|
+| `dungeon` | Procedurally assembled from room_*.json files | Roguelike, dungeon crawler, cave |
+| `voxel` | Open voxel world (Minecraft-like terrain) | Overworld, exploration, open world |
+
+A game can have multiple areas of different types connected via transitions.
+
+---
+
+## Minimum Viable Game ("it runs")
+
+These 4 things must exist for `pnpm dev` to start successfully:
+
+1. **`area-manifest.json`** — at least 1 area defined
+2. **`room_*.json`** — at least 1 room with `"tags": ["start"]`
+3. **`enemy-defs.json`** — at least 1 enemy entry (array, never empty)
+4. **`cell-visuals.ts`** — all `GameCellType` keys must have a value (null is valid for `empty`)
+
+Missing any of these = runtime error.
+
+---
+
+## Deriving Technical Decisions from Product Answers
+
+### Core Loop → Area Type
+| Player does... | Area type |
+|----------------|-----------|
+| Explore rooms, fight enemies | `dungeon` |
+| Roam open world | `voxel` |
+| Both | `dungeon` + `voxel` connected via transition |
+
+### Reference Game → Defaults
+| Feels like... | Enemy speed | Aggro range | Color temperature |
+|---------------|-------------|-------------|-------------------|
+| Dark Souls | slow (1.5–2.5) | medium (5–7) | dark, desaturated |
+| Hades | fast (4.0–6.0) | wide (7–10) | vivid, saturated |
+| Minecraft | medium (2.5–3.5) | medium (6–8) | natural tones |
+| Enter the Gungeon | fast (3.5–5.0) | wide (8–12) | neon accents |
+
+### Enemy Description → Stats
+- "slow and tanky" → high hp (100–200), low speed (1.0–2.0), scale 1.4–1.8
+- "fast and fragile" → low hp (20–40), high speed (4.5–6.5), scale 0.6–0.9
+- "balanced" → medium hp (40–70), medium speed (2.5–3.5), scale 1.0
+
+---
+
+## How to Run
+
+```bash
+pnpm install     # from monorepo root
+pnpm dev         # starts client + server
+```
+
+Client runs on http://localhost:5173 by default.

package/template/.claude/skills/aigdtk-shared/visuals.md

@@ -0,0 +1,125 @@
+# Cell Visuals — AI Reference
+
+Load this file when generating or modifying `apps/game-data/src/dungeon/cell-visuals.ts`.
+
+---
+
+## File Format
+
+`cell-visuals.ts` exports a `CELL_VISUALS` constant — a record mapping every `GameCellType`
+to a `CellVisual` object (or `null` for invisible cells).
+
+```typescript
+import type { CellVisual } from '@loonylabs/gamedev-core';
+import type { GameCellType } from './cell-types.js';
+
+export const CELL_VISUALS: Record<GameCellType, CellVisual | null> = {
+  wall:       { height: 2,    color: 0x888888 },
+  floor:      { height: 0.1,  color: 0x444444 },
+  door:       { height: 1.5,  color: 0xcc7733 },
+  spawn:      { height: 0.2,  color: 0x44cc44 },
+  empty:      null,
+  transition: { height: 0.15, color: 0xffcc00 },
+  npc:        { height: 1.8,  color: 0xffff00 },
+  fire:       { height: 0.3,  color: 0xff6600 },
+};
+```
+
+**Every key in `GameCellType` must be present.** Missing keys = TypeScript error.
+
+---
+
+## CellVisual Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `height` | number | Box height in world units |
+| `color` | number | Hex color as numeric literal (0xRRGGBB) |
+
+`null` means: no mesh rendered for this cell type (use for `empty`).
+
+---
+
+## Color Format
+
+Colors are **numeric hex literals**, not strings:
+- ✅ `0x888888`
+- ❌ `"#888888"`
+
+To convert: remove `#`, prefix with `0x`. `#cc7733` → `0xcc7733`
+
+---
+
+## Height Guidelines
+
+| Cell Type | Typical height | Notes |
+|-----------|---------------|-------|
+| wall | 2.0–3.0 | Should be clearly taller than player |
+| floor | 0.05–0.15 | Near-flat |
+| door | 1.2–1.8 | Shorter than wall, visually distinct |
+| spawn | 0.1–0.3 | Subtle floor marker |
+| transition | 0.1–0.2 | Subtle, distinct color |
+| npc | 1.5–2.0 | Humanoid height |
+| fire | 0.2–0.5 | Low, glowing |
+
+---
+
+## Palette Derivation from Mood/Reference Game
+
+### Dark Dungeon (Dark Souls, roguelike)
+```typescript
+wall:       { height: 2.5, color: 0x333333 },
+floor:      { height: 0.1, color: 0x222222 },
+door:       { height: 1.5, color: 0x664422 },
+spawn:      { height: 0.2, color: 0x336633 },
+transition: { height: 0.15, color: 0x886600 },
+npc:        { height: 1.8, color: 0x998866 },
+fire:       { height: 0.3, color: 0xff4400 },
+```
+
+### Vivid Action (Hades, Enter the Gungeon)
+```typescript
+wall:       { height: 2.0, color: 0x554477 },
+floor:      { height: 0.1, color: 0x332244 },
+door:       { height: 1.5, color: 0xcc44ff },
+spawn:      { height: 0.2, color: 0x44ffaa },
+transition: { height: 0.15, color: 0xffdd00 },
+npc:        { height: 1.8, color: 0xffaa44 },
+fire:       { height: 0.3, color: 0xff6600 },
+```
+
+### Natural World (Minecraft, survival)
+```typescript
+wall:       { height: 2.0, color: 0x556644 },
+floor:      { height: 0.1, color: 0x7a6a4a },
+door:       { height: 1.5, color: 0x886633 },
+spawn:      { height: 0.2, color: 0x88cc44 },
+transition: { height: 0.15, color: 0xddcc55 },
+npc:        { height: 1.8, color: 0xffdd88 },
+fire:       { height: 0.3, color: 0xff6600 },
+```
+
+### Ice / Frost (cold, pale)
+```typescript
+wall:       { height: 2.5, color: 0x8899bb },
+floor:      { height: 0.1, color: 0x6677aa },
+door:       { height: 1.5, color: 0x99bbdd },
+spawn:      { height: 0.2, color: 0x44ffcc },
+transition: { height: 0.15, color: 0xffffff },
+npc:        { height: 1.8, color: 0xccddff },
+fire:       { height: 0.3, color: 0x44ccff },
+```
+
+---
+
+## Deriving Palette from Description Keywords
+
+| Keyword | Wall color | Floor color | Accent color |
+|---------|-----------|-------------|--------------|
+| dark, grim, underground | `0x333333` | `0x222222` | `0x664422` |
+| fire, hell, volcanic | `0x442211` | `0x331100` | `0xff4400` |
+| forest, nature, cave | `0x445533` | `0x556644` | `0x88cc44` |
+| ice, frost, arctic | `0x8899bb` | `0x6677aa` | `0x99bbdd` |
+| magic, arcane, purple | `0x442255` | `0x331144` | `0xcc44ff` |
+| ancient, temple, stone | `0x887766` | `0x776655` | `0xccbb88` |
+| toxic, slime, swamp | `0x334422` | `0x223311` | `0x44aa22` |

package/template/apps/client/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>gamedev-ai-toolkit</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <canvas id="game-canvas"></canvas>
+    <div id="ui"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/apps/client/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "gamedev-client",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@loonylabs/game-data": "workspace:*",
+    "@loonylabs/gamedev-client": "workspace:*",
+    "@loonylabs/gamedev-core": "workspace:*",
+    "@loonylabs/gamedev-protocol": "workspace:*",
+    "@sveltejs/vite-plugin-svelte": "^4.0.4",
+    "howler": "^2.2.4",
+    "socket.io-client": "^4.7.0",
+    "svelte": "^5.55.1",
+    "three": "^0.160.0",
+    "valtio": "^1.13.0"
+  },
+  "devDependencies": {
+    "@types/howler": "^2.2.12",
+    "@types/three": "^0.160.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}