Imported from Asgarrrr/Rogue-III (apps/server/src/game/AGENTS.md). Install upstream with npx skills add Asgarrrr/Rogue-III --skill game. Copyright stays with the author.

Game Simulation Knowledge Base

Scope: Game engine core - ECS, dungeon generation, networking

Structure

game/
├── ecs/              # Entity-Component-System (archetype-based)
│   ├── core/         # World, entities, components, archetypes, queries
│   ├── event/        # EventQueue, Observers (reactive hooks)
│   ├── relationship/ # Relations (ChildOf, Contains, entity refs)
│   ├── schedule/     # System scheduler, sets, run conditions
│   ├── query/        # Query cache, filters, union queries
│   ├── spatial/      # Spatial grid for efficient lookups
│   ├── prefab/       # Prefab templates
│   ├── serialization/# Save/load with migrations
│   ├── storage/      # String pool, resources
│   └── docs/         # Complete ECS documentation
├── dungeon/          # Procedural generation
│   ├── generators/   # BSP + Cellular algorithms
│   ├── core/         # Grid, flood-fill, union-find, spatial-hash
│   └── entities/     # Room, Connection, Dungeon
├── network/          # Multiplayer
│   ├── game-server.ts    # Session management
│   ├── game-session.ts   # Player state
│   ├── sync-manager.ts   # State synchronization
│   └── message-handler.ts# Protocol handling
└── game-init.ts      # Singleton game instance

Where to Look

Key Patterns

ECS Component Definition

import { component, i32, f32, str, entityRef } from "./ecs";

@component
class Position {
  x = i32(0);
  y = i32(0);
}

@component
class Item {
  name = str("Unknown");
  damage = i32(0);
  holder = entityRef();  // Reference to holding entity
}

System Registration

import { defineSystem, Phase } from "./ecs";

const MovementSystem = defineSystem("Movement")
  .inPhase(Phase.Update)
  .before("Collision")
  .execute((world) => {
    world.query(Position, Velocity).run(view => {
      const x = view.column(Position, "x");
      const vx = view.column(Velocity, "vx");
      for (let i = 0; i < view.count; i++) {
        x[i] += vx[i];
      }
    });
  });

world.addSystem(MovementSystem);

Turn System

• Energy threshold: 100 to act
• Speed modifier: (energyPerTurn * speed) / 100
• Fast-forward: calculates min ticks for any entity to reach threshold

Dungeon Generation

• BSP: Partitioning → room placement → corridor carving
• Cellular: Noise init → CA evolution → cavern analysis → pathfinding
• Both output Uint8Array terrain for zero-copy ECS loading

Anti-Patterns

Game Instance

const { world, gameServer } = getGameInstance();
const instance = createGameInstance();