# YAGE

> A modular 2D game engine for TypeScript: hybrid OOP+ECS architecture, plugin-based, built on PixiJS v8 and Rapier2D.

## For coding agents

- This file is the canonical documentation index for coding agents. Prefer the Markdown references linked here over the human-facing HTML pages at https://yage.dev.
- For implementation questions, read Core Concepts plus the reference for each package, tool, or addon involved.
- Do not infer API details from examples when a dedicated reference exists.
- Use [llms-full.txt](llms-full.txt), every reference concatenated, only when engine-wide context is genuinely useful.

## Docs

- [Core Concepts](llms/core-concepts.md): Architecture, lifecycle, ECS, scenes, events, DI, processes, save-state boundary
- [Quick Start](llms/quick-start.md): Installation, engine setup, scene class, first project
- [Patterns](llms/patterns.md): Component, entity, process, and testing patterns; common gotchas
- [Play Sessions](llms/play-sessions.md): Driving a running game — picking a mechanism, rule-driven runs, frame budgets, traps
- [Performance](llms/performance.md): Allocation-aware APIs, hot-loop tips, debug-mode cost, pooling
- [Assets](llms/assets.md): Asset handles, scene preload, manifests, cache lifetime, base path
- [Loading Scene](llms/loading-scene.md): Loading-scene orchestration, progress events, error handling
- [Scene Transitions](llms/scene-transitions.md): Built-in transitions and the SceneTransition contract
- [Local Engine](llms/local-engine.md): Running a game against an unreleased engine build from a local clone — path links, one Pixi install, install flags, Playwright browsers
- [Troubleshooting](llms/troubleshooting.md): Dev-mode `[yage]` warnings and what each one means

## Packages

- [core](llms/packages/core.md): ECS, DI, game loop, scenes, events (zero runtime deps)
- [renderer](llms/packages/renderer.md): PixiJS v8 rendering, sprites, camera, layers, draw order and depth/Y-sort
- [lighting](llms/packages/lighting.md): Radial lights, light-level queries, pluggable renderers
- [input](llms/packages/input.md): Keyboard/mouse/gamepad input, action maps, rebinding
- [physics](llms/packages/physics.md): Rapier2D physics, rigid bodies, colliders, raycasting
- [audio](llms/packages/audio.md): Sound effects, music, channels, SoundComponent
- [particles](llms/packages/particles.md): Particle emitters, presets, pooling
- [tilemap](llms/packages/tilemap.md): Tiled map loading, collision extraction
- [pathfinding](llms/packages/pathfinding.md): Grid A* pathfinding — works without a tilemap, with an optional tilemap adapter
- [ui](llms/packages/ui.md): Yoga flexbox UI, panels, buttons, anchoring
- [ui-react](llms/packages/ui-react.md): React reconciler, hooks, reactive stores
- [level](llms/packages/level.md): Authored level files — placeable entity declarations, parameter schemas, strict loading into a scene
- [save](llms/packages/save.md): Controlled save/load, slots, adapters, migrations
- [debug](llms/packages/debug.md): Debug overlay, custom contributors, stats
- [effects](llms/packages/effects.md): Visual-effect presets — bloom, outline, CRT, vignette, color grade, etc.

## Addons

Installable, opinionated gameplay patterns (`@yagejs-addons` scope), independently versioned. Each addon's doc is sourced from its co-located `packages/addons/<name>/docs/llms/`.

- [Addons Overview](llms/addons.md): Scope, versioning, peer dependencies, and how an addon layers on the engine
- [dialogue](llms/addons/dialogue.md): Branching runner, typewriter box & bubbles, markup, themeable presenters
- [inventory](llms/addons/inventory.md): Slot inventory — stacking, item actions, sorting, one slot view with swappable cell presets
- [abilities](llms/addons/abilities.md): Phase-based abilities, input intent mapping, and a concrete hit contract
- [stats](llms/addons/stats.md): Numeric stats, source-owned modifiers, timed effects, stacking rules, derived values, and damage formulas
- [feel](llms/addons/feel.md): Game feel — squash, flash, shake, hit-stop, sound, and particles composed into one named trigger
- [i18n](llms/addons/i18n.md): Localization — `msg` descriptors, an i18next-backed service, and localized text for renderer, UI, React, dialogue, and inventory
- [interaction](llms/addons/interaction.md): Proximity interaction — walk up, see a prompt, press E; headless
- [quests](llms/addons/quests.md): Headless quest log — objectives and progression
- [steering](llms/addons/steering.md): Movement AI — seek, flee, arrive, wander, pursue/evade, obstacle avoidance, flocking, path-following
- [synth](llms/addons/synth.md): Procedural sound effects — patches, presets, and jingles rendered to playable aliases, no audio files
- [virtual-controls](llms/addons/virtual-controls.md): Mobile touch overlay — virtual joystick(s) and on-screen buttons driving InputManager

## Tools

Development tools for building YAGE games (`@yagejs-tools` scope, independently versioned). Each tool's doc is sourced from its co-located `packages/tools/<name>/docs/llms/`.

- [editor](llms/tools/editor.md): Level editor — open a `*.yage-level.json` file, build it up in a real engine, and save it back
- [lab](llms/tools/lab.md): Scenario browser — mount a scene or entity in a real engine, tune it with controls, and run every scenario headless
- [feedback](llms/tools/feedback.md): Runtime feedback — freeze the game, comment on entities or areas, and read captures with screenshots and inspector snapshots from a CLI

## Optional

- Testing: `createMockEntity`, `createTestEngine`, `advanceFrames` from `@yagejs/core/test-utils`
- API index: see per-package `src/index.ts` barrel exports