# SAGE

> Game engine, simplified.

A modern TypeScript engine built on BabylonJS with entity composition, event-driven architecture, and Havok physics.

## Table of Contents

### Getting Started

- [What is SAGE?](/getting-started.md): An overview of SAGE, the SkewedAspect Game Engine -- a TypeScript game engine built on BabylonJS with entity composition, event-driven architecture, and Havok physics.
- [Installation](/getting-started/installation.md): Install SAGE and its dependencies, then create a minimal spinning cube to verify everything works.

### Concepts

- [Architecture](/concepts/architecture.md): How SAGE is structured -- layered architecture, event-driven communication, core managers, data flow, and resource lifecycle.
- [Entities](/concepts/entities.md): The SAGE entity system -- composition over inheritance, entity definitions, behaviors, parent-child hierarchies, node attachment, querying, and object pooling.
- [Events](/concepts/events.md): The SAGE event bus -- pub/sub communication, subscription types, type safety, built-in events, and common patterns.

### API Reference

- [Audio](/api/audio.md): API reference for SAGE's audio system -- AudioEngine, AudioManager, channel-based mixing, volume control, and integration with SoundBehavior and the Blender sound handler.
- [Behaviors](/api/behaviors.md): API reference for SAGE's behavior system -- the GameEntityBehavior base class, lifecycle hooks, event handling, state machines, and composition patterns.
- [Input & Bindings](/api/input.md): API reference for SAGE's input and binding system -- actions, bindings, contexts, the BindingManager, and input device readers.
- [Levels](/api/levels.md): API reference for SAGE's level system -- LevelManager, Level base class, GameLevel, YAML configuration, transitions, property handlers, and progress reporting.
- [Scenes](/api/scenes.md): API reference for SAGE's scene system -- SceneEngine utilities, cameras, lighting, meshes, materials, model loading, asset management, and raycasting.
- [Physics](/api/physics.md): API reference for SAGE's physics system -- Havok integration via BabylonJS, PhysicsAggregate, static and dynamic bodies, forces, collision detection, and constraints.
- [Timer](/api/timer.md): API reference for SAGE's GameTimer -- pause-aware delay, interval, cooldown, and cancelAll for game-time scheduling.
- [Serialization & Save/Load](/api/serialization.md): API reference for SAGE's serialization system -- SaveManager, serialize/deserialize, SaveData structure, ID remapping, and extension hooks.

### Integration

- [Vue 3 Integration](/integration/vue.md): Integrate the SAGE game engine with Vue 3 using the @skewedaspect/sage-vue package. Covers the SageCanvas component and all composables for building reactive game UI.

### Guides

- [Hello Cube](/guides/hello-cube.md): Build the simplest possible SAGE application — a rotating cube with pause/resume controls.
- [Input System](/guides/input-system.md): Build a fully interactive scene with keyboard, mouse, and gamepad controls using SAGE's input binding system.
- [Entity Behaviors](/guides/entity-behaviors.md): Build a survival game using SAGE's entity-behavior composition system with health, mana, shields, enemy AI, and collectibles.
- [Entity Messaging](/guides/entity-messaging.md): Targeted entity-to-entity communication in SAGE -- fire-and-forget commands, request-response queries, behavior-level messaging, and when to use messaging vs. the event bus.
- [Physics Playground](/guides/physics-playground.md): Integrate Havok physics with SAGE entities using PhysicsBodyBehavior, physics state interfaces, and the onNodeAttached lifecycle hook.
- [Level Loading](/guides/level-loading.md): Load levels from YAML configs with spawn points, property handlers, level transitions, and puzzle mechanics built on GameLevel subclasses.
- [Sandbox](/guides/sandbox.md): Build a first-person 3D sandbox combining GLB scene loading, physics character controller, doors with spatial audio, a multi-floor elevator, pickups, and input contexts.
- [Blender Workflow](/guides/blender-workflow.md): Author SAGE levels in Blender using GLB export, custom properties for spawn points, entity markers, sounds, colliders, triggers, and performance optimization.
- [Migration Guide](/guides/migration.md)
- [Coordinate Systems](/guides/coordinate-systems.md)
- [Collider Debug Visualization](/guides/collider-debugging.md): Visualize physics colliders in your scene using SAGE's debug tools — per-entity, per-node, or config-driven through entity definitions and level YAML.
- [Debug Console](/guides/debug-console.md): Turn your browser's dev console into a game debug console with window.sage -- inspect entities, teleport objects, toggle colliders, log events, and control the game loop in real time.

### AI

- [LLM Documentation](/ai/llms-txt.md): Machine-readable documentation for LLMs and AI assistants.