# VibeGame Engine
A 3D game engine with declarative XML syntax and ECS architecture. Start playing immediately with automatic player, camera, and lighting - just add a ground to prevent falling.
## Core Architecture
### ECS (Entity Component System)
- **Entities**: Just numbers (IDs), no data or behavior
- **Components**: Pure data containers (position, health, color)
- **Systems**: Functions that process entities with specific components
- **Queries**: Find entities with specific component combinations
### Plugin System
Bevy-inspired modular architecture:
- **Components**: Data definitions using bitECS
- **Systems**: Logic organized by update phases (setup, fixed, simulation, draw)
- **Recipes**: XML entity templates with preset components
- **Config**: Defaults, shorthands, enums, validations, parsers, adapters
### Update Phases
1. **SetupBatch**: Input gathering and frame setup
2. **FixedBatch**: Physics simulation at fixed timestep (50Hz)
3. **SimulationBatch**: Game logic and state updates
4. **DrawBatch**: Rendering and interpolation
## Critical Rules
⚠️ **Physics Position Override**: Physics bodies override transform positions. Always use `pos` attribute on physics entities, not transform position.
⚠️ **Ground Required**: Always include ground/platforms or the player falls infinitely.
⚠️ **Component Declaration**: Bare attributes mean "include with defaults", not "empty".
## Essential Knowledge
## Instant Playable Game
```html
```
This creates a complete game with:
- ✅ Player character (auto-created)
- ✅ Orbital camera (auto-created)
- ✅ Directional + ambient lighting (auto-created)
- ✅ Ground platform (you provide this)
- ✅ WASD movement, mouse camera, space to jump
## Development Setup
After installation with `npm create vibegame@latest my-game`:
```bash
cd my-game
bun dev # Start dev server with hot reload
```
### Project Structure
- **TypeScript** - Full TypeScript support with strict type checking
- **src/main.ts** - Entry point for your game
- **index.html** - HTML template with canvas element
- **vite.config.ts** - Build configuration
### Commands
- `bun dev` - Development server with hot reload
- `bun run build` - Production build
- `bun run preview` - Preview production build
- `bun run check` - TypeScript type checking
- `bun run lint` - Lint code with ESLint
- `bun run format` - Format code with Prettier
## Physics Objects
```xml
```
## CRITICAL: Physics Position vs Transform Position
⚠️ **Physics bodies override transform positions!**
Always set position on the body, not the transform, for physics entities.
```xml
```
## ECS Architecture Explained
Unlike traditional game engines with GameObjects, VibeGame uses Entity-Component-System:
- **Entities**: Just numbers (IDs), no data or behavior
- **Components**: Pure data containers (position, health, color)
- **Systems**: Functions that process entities with specific components
```typescript
// Component = Data only
const Health = GAME.defineComponent({
current: GAME.Types.f32,
max: GAME.Types.f32
});
// System = Logic only
const healthQuery = GAME.defineQuery([Health]);
const DamageSystem: GAME.System = {
update: (state) => {
const entities = healthQuery(state.world);
for (const entity of entities) {
Health.current[entity] -= 1 * state.time.deltaTime;
if (Health.current[entity] <= 0) {
state.destroyEntity(entity);
}
}
}
};
```
## What's Auto-Created (Game Engine Defaults)
The engine automatically creates these if missing:
1. **Player** - Character with physics, controls, and respawn (at 0, 1, 0)
2. **Camera** - Orbital camera following the player
3. **Lighting** - Combined ambient + directional light with shadows
You only need to provide:
- **Ground/platforms** - Or the player falls forever
- **Game objects** - Whatever makes your game unique
### Override Auto-Creation (When Needed)
While auto-creation is recommended, you can manually create these for customization:
```xml
```
**Best Practice**: Use auto-creation unless you specifically need custom positions, properties, or multiple instances. The defaults are well-tuned for most games.
## Post-Processing Effects
Requires including the PostprocessingPlugin in the builder, as it is not included in the DefaultPlugins.
```typescript
import { PostprocessingPlugin } from 'vibegame/postprocessing';
GAME
.withPlugin(PostprocessingPlugin)
.run();
```
## 3D Text
Requires including the TextPlugin in the builder, as it is not included in the DefaultPlugins.
```typescript
import { TextPlugin } from 'vibegame/text';
GAME
.withPlugin(TextPlugin)
.run();
```
```xml
```
## Vector Lines
Requires including the LinePlugin in the builder, as it is not included in the DefaultPlugins.
```typescript
import { LinePlugin } from 'vibegame/line';
GAME
.withPlugin(LinePlugin)
.run();
```
```xml
```
```xml
```
## Common Game Patterns
### Basic Platformer
```xml
```
### Collectible Coins (Collision-based)
```xml
```
### Physics Playground
```xml
```
## Recipe Reference
| Recipe | Purpose | Key Attributes | Common Use |
|--------|---------|---------------|------------|
| `` | Immovable objects | `name`, `pos`, `shape`, `size`, `color` | Grounds, walls, platforms |
| `` | Gravity-affected objects | `name`, `pos`, `shape`, `size`, `color`, `mass` | Balls, crates, falling objects |
| `` | Script-controlled physics | `name`, `pos`, `shape`, `size`, `color` | Moving platforms, doors |
| `` | Visual entity (no physics) | `name`, `pos`, `shape`, `size`, `color` | Decorations, visual effects |
| `` | Text container | `name`, `pos`, `gap`, `align` | Text layouts |
| `` | Text element | `name`, `text`, `font-size`, `color` | Individual words, labels |
| `` | Player character | `pos`, `speed`, `jump-height` | Main character (auto-created) |
| `` | Base entity | `name`, any components via attributes | Custom entities |
| `` | Animation | `target`, `attr`, `to`, `from`, `duration`, `easing` | Animate named entities |
| `` | Animation group | `name`, `autoplay` | Reusable animation sequences |
| `` | Sequence timing | `duration` | Separate parallel tween groups |
### Shape Options
- `box` - Rectangular solid (default)
- `sphere` - Ball shape
### Size Attribute
- Box: `size="width height depth"` or `size="2 1 2"`
- Sphere: `size="diameter"` or `size="1"`
- Broadcast: `size="2"` becomes `size="2 2 2"`
## Name Resolution Pattern
Entities with `name` attribute are registered at parse time. Names resolve to entity IDs for cross-entity references.
```xml
```
Runtime lookup: `state.getEntityByName('door')` returns entity ID or null.
## Tweening (Animation)
Tweens are one-shot animations that auto-destroy on completion. They reference entities by `name`.
### Tween Attributes
| Attribute | Required | Description |
|-----------|----------|-------------|
| `target` | Yes | Name of entity to animate |
| `attr` | Yes | Property path or shorthand (`at`, `scale`, `rotation`) |
| `to` | Yes | End value (single or "x y z") |
| `from` | No | Start value (defaults to current) |
| `duration` | No | Seconds (default: 1) |
| `easing` | No | Easing function (default: linear) |
### Shorthand Targets
Shorthands expand to 3 tweens (one per axis):
| Shorthand | Expands To | Values |
|-----------|------------|--------|
| `at` | transform.posX/Y/Z | `"x y z"` position |
| `scale` | transform.scaleX/Y/Z | `"x y z"` scale |
| `rotation` | body or transform euler | `"x y z"` degrees |
### Property Paths
- `body.pos-x/y/z` - Physics position (use for kinematic-part)
- `transform.pos-x/y/z` - Transform position
- `transform.scale-x/y/z` - Scale
- `body.euler-x/y/z` or `transform.euler-x/y/z` - Rotation
### Easing Functions
`linear` (default), `sine-in/out/in-out`, `quad-in/out/in-out`, `cubic-in/out/in-out`, `back-in/out/in-out`, `elastic-in/out/in-out`, `bounce-in/out/in-out`
### XML Tween Examples
```xml
```
### TypeScript Tween Examples
```typescript
import { createTween } from 'vibegame/tweening';
// Single field
createTween(state, entity, 'transform.pos-x', { from: 0, to: 10, duration: 2, easing: 'sine-out' });
// Shorthand with array values
createTween(state, entity, 'at', { from: [0, 0, 0], to: [10, 5, 0], duration: 1.5 });
createTween(state, entity, 'scale', { from: [1, 1, 1], to: [2, 2, 2], duration: 0.5, easing: 'back-out' });
```
## Sequences (Animation Groups)
Sequences orchestrate multiple tweens with timing control. Tweens before `` run in parallel; pause separates sequential groups.
### Sequence Attributes
| Attribute | Description |
|-----------|-------------|
| `name` | Register sequence for later playback (starts paused) |
| `autoplay` | Start immediately when parsed |
### Sequence Execution Model
1. All tweens before first `` start simultaneously
2. `` waits for active tweens to complete + pause duration
3. Next group starts after pause
4. Sequence resets to Idle when complete
### XML Sequence Examples
```xml
```
### TypeScript Sequence Control
```typescript
import { completeSequence, playSequence, resetSequence, stopSequence } from 'vibegame/tweening';
// Get sequence by name and trigger
const bounce = state.getEntityByName('bounce');
resetSequence(state, bounce); // Reset to beginning
playSequence(state, bounce); // Start playback
// Stop mid-animation
stopSequence(state, bounce); // Stop, clear active tweens
// Skip to end instantly
completeSequence(state, bounce); // Apply all final values immediately
```
### Event-Driven Sequence Pattern
```typescript
// Define trigger component
const TriggerSequence = GAME.defineComponent({});
const triggerQuery = GAME.defineQuery([TriggerSequence, Sequence]);
// System processes triggers each frame
const TriggerSequenceSystem: GAME.System = {
group: 'simulation',
update(state) {
for (const eid of triggerQuery(state.world)) {
resetSequence(state, eid);
playSequence(state, eid);
state.removeComponent(eid, TriggerSequence);
}
}
};
// Trigger from DOM
document.getElementById('btn')?.addEventListener('click', () => {
const seq = state.getEntityByName('my-sequence');
if (seq !== null) state.addComponent(seq, TriggerSequence);
});
```
## Advanced Animation Patterns
### Driver Pattern: One Value Controls Many Entities
A driver is a single tweened component value that a system uses to control multiple entities. Useful for coordinated effects like breathing, pulsing, or wave animations.
```xml
```
```typescript
// System reads driver, applies to all marked entities
const BreatheSystem: System = {
group: 'simulation',
update(state) {
const driverValue = BreatheDriver.value[drivers[0]];
const oscillation = Math.sin(state.time.elapsed * 2) * 0.2 * driverValue;
for (const eid of breatheQuery(state.world)) {
Transform.scaleX[eid] = 1 + oscillation;
Transform.scaleY[eid] = 1 + oscillation;
Transform.scaleZ[eid] = 1 + oscillation;
}
}
};
```
### Shakers: Layered Effects via Tweening
Shakers allow multiple independent effects on the same property. Each shaker has an `intensity` (0-1) that can be tweened, enabling effects to fade in/out independently.
```xml
```
Key benefits:
- **Safe composition**: Shakers modify at draw time, base values unchanged
- **Independent control**: Each shaker's intensity tweens separately
- **Order guarantees**: Additive first, then multiplicative
- **Alias resolution**: `shaker.intensity` auto-resolves for transform shakers
## How Recipes and Shorthands Work
### Everything is an Entity
Every XML tag creates an entity. Recipes like `` are just shortcuts for `` with preset components.
```xml
```
### Component Attributes
Components are declared using bare attributes (no value means "use defaults"):
```xml
```
**Important**: Bare attributes like `transform` mean "include this component with default values", NOT "empty" or "disabled".
### Automatic Shorthand Expansion
Shorthands expand to ANY component with matching properties:
```xml
```
### Recipe Internals
Recipes are registered component bundles with defaults:
```xml
collider
renderer
respawn
>
collider
renderer="color: 0xff0000"
respawn
>
```
### Common Pitfall: Component Requirements
```xml
```
### Best Practices Summary
1. **Use recipes** (``, ``, etc.) instead of raw `` tags
2. **Use shorthands** (`pos`, `size`, `color`) for cleaner code
3. **Override only what you need** - recipes have good defaults
4. **Mix recipes with custom components** - e.g., ``
## Currently Supported Features
### ✅ What Works Well
- **Basic platforming** - Jump puzzles, obstacle courses
- **Physics interactions** - Balls, dominoes, stacking
- **Moving platforms** - Via kinematic bodies + tweening
- **Collectibles** - Using collision detection in systems
- **Third-person character control** - WASD + mouse camera
- **Gamepad support** - Xbox/PlayStation controllers
- **Visual effects** - Tweening colors, positions, rotations
- **Post-processing** - Bloom, dithering, and tonemapping effects for visual styling
- **3D Text** - In-world text labels, scores, and UI elements
- **Vector Lines** - Line rendering with arrowheads for visualizations
- **Game UI/HUD** - HTML/CSS overlays with GSAP animations, ECS state integration
### Example Prompts That Work
- "Create a platformer with moving platforms and collectible coins"
- "Make bouncing balls that collide with walls"
- "Build an obstacle course with rotating platforms"
- "Add falling crates that stack up"
- "Create a simple parkour level"
- "Add a score display and upgrade menu with animations"
- "Create a game with currency system and floating text effects"
### Troubleshooting
- **Physics not working?** → Check if ground exists, verify `` tag
- **Entity not appearing?** → Verify transform component, check position values
- **Movement feels wrong?** → Physics body position overrides transform position
- **Player falling forever?** → Add a ground/platform with ``
## Plugin Development Pattern
```typescript
// Component Definition
export const MyComponent = GAME.defineComponent({
value: GAME.Types.f32,
enabled: GAME.Types.ui8
});
// System Definition
const myQuery = GAME.defineQuery([MyComponent]);
export const MySystem: GAME.System = {
group: 'simulation', // or 'setup', 'fixed', 'draw'
update: (state) => {
const entities = myQuery(state.world);
for (const entity of entities) {
// System logic
MyComponent.value[entity] += state.time.deltaTime;
}
}
};
// Plugin Bundle
export const MyPlugin: GAME.Plugin = {
components: { MyComponent },
systems: [MySystem],
config: {
defaults: { "my-component": { value: 1, enabled: 1 } },
shorthands: { "my-val": "my-component.value" }
}
};
// Registration
GAME.withPlugin(MyPlugin).run();
```
## State Management Patterns
### Singleton Entities (Game State)
```typescript
function getOrCreateGameState(state: GAME.State): number {
const query = GAME.defineQuery([GameState]);
const entities = query(state.world);
if (entities.length > 0) return entities[0];
const entity = state.createEntity();
state.addComponent(entity, GameState, { score: 0, level: 1 });
return entity;
}
```
### Component Access (bitECS style)
```typescript
// Direct property access
Transform.posX[entity] = 10;
Transform.posY[entity] = 5;
// Read values
const x = Transform.posX[entity];
const health = Health.current[entity];
```
## Features Not Yet Built-In
### ❌ Engine Features Not Available
- **Multiplayer/Networking** - No server sync
- **Sound/Audio** - No audio system yet
- **Save/Load** - No persistence system
- **Inventory** - No item management system built-in (but easily implementable with UI)
- **Dialog/NPCs** - No conversation system built-in (but easily implementable with UI)
- **AI/Pathfinding** - No enemy AI
- **Particles** - No particle effects (though UI can create particle-like effects)
- **Custom shaders** - Fixed rendering pipeline
- **Terrain** - Use box platforms instead
### Recommended Approaches
- **Complex UI** → HTML/CSS overlays (this is actually superior to most game engines)
- **Animations** → GSAP for smooth transitions and effects
- **Level progression** → Reload with different XML or hide/show worlds
- **Enemy behavior** → Tweened movement patterns
- **Interactions** → Collision detection in custom systems
## Common Mistakes to Avoid
### ❌ Forgetting the Ground
```xml
```
### ❌ Setting Transform Position on Physics Objects
```xml
```
### ❌ Missing World Tag
```xml
```
### ❌ Wrong Physics Type
```xml
```
## Custom Components and Systems
### Creating a Health System
```typescript
import * as GAME from 'vibegame';
// Define the component
const Health = GAME.defineComponent({
current: GAME.Types.f32,
max: GAME.Types.f32
});
// Create the system
const HealthSystem: GAME.System = {
update: (state) => {
const entities = GAME.defineQuery([Health])(state.world);
for (const entity of entities) {
// Regenerate health over time
if (Health.current[entity] < Health.max[entity]) {
Health.current[entity] += 5 * state.time.deltaTime;
}
}
}
};
// Bundle as plugin
const HealthPlugin: GAME.Plugin = {
components: { Health },
systems: [HealthSystem],
config: {
defaults: {
"health": { current: 100, max: 100 }
}
}
};
// Use in game
GAME.withPlugin(HealthPlugin).run();
```
### Using in XML
```xml
```
## State API Reference
Available in all systems via the `state` parameter:
### Entity Management
- `createEntity(): number` - Create new entity
- `destroyEntity(entity: number)` - Remove entity
- `query(...Components): number[]` - Find entities with components
### Component Operations
- `addComponent(entity, Component, data?)` - Add component
- `removeComponent(entity, Component)` - Remove component
- `hasComponent(entity, Component): boolean` - Check component
- `getComponent(name: string): Component | null` - Get by name
### Time
- `time.delta: number` - Frame time in seconds
- `time.elapsed: number` - Total time in seconds
- `time.fixed: number` - Fixed timestep (1/50)
### Physics Helpers
- `addComponent(entity, ApplyImpulse, {x, y, z})` - One-time push
- `addComponent(entity, ApplyForce, {x, y, z})` - Continuous force
- `addComponent(entity, KinematicMove, {x, y, z})` - Move kinematic
## Plugin System
### Using Specific Plugins
```typescript
import * as GAME from 'vibegame';
import { TransformsPlugin } from 'vibegame/transforms';
import { RenderingPlugin } from 'vibegame/rendering';
import { PhysicsPlugin } from 'vibegame/physics';
import { AnimationPlugin } from 'vibegame/animation';
// Start with no defaults, add specific plugins
GAME
.withoutDefaultPlugins()
.withPlugin(TransformsPlugin)
.withPlugin(RenderingPlugin)
.withPlugin(PhysicsPlugin)
.run();
// Keep defaults, exclude specific plugins
GAME
.withoutPlugins(AnimationPlugin)
.run();
```
### Default Plugin Bundle
- **RecipesPlugin** - XML parsing and entity creation
- **TransformsPlugin** - Position, rotation, scale, hierarchy
- **RenderingPlugin** - Three.js meshes, lights, camera
- **PhysicsPlugin** - Rapier physics simulation
- **InputPlugin** - Keyboard, mouse, gamepad input
- **OrbitCameraPlugin** - Standalone orbital camera with direct input handling
- **PlayerPlugin** - Character controller
- **TweenPlugin** - Animation system
- **RespawnPlugin** - Fall detection and reset
- **StartupPlugin** - Auto-create player/camera/lights
## Headless CLI (AI Testing)
For AI testing, validation, and video creation without browser/WebGL:
```typescript
import {
createHeadlessState,
parseWorldXml,
getEntityNames,
queryEntities,
hasComponentByName,
getComponentData,
getEntityData,
getAllSequences,
getSequenceInfo,
toJSON,
} from 'vibegame/cli';
import { playSequence, resetSequence } from 'vibegame/tweening';
// Setup headless state
const state = createHeadlessState({ plugins: DefaultPlugins });
await state.initializePlugins();
parseWorldXml(state, xmlContent);
// Entity discovery (no hardcoded names)
const names = getEntityNames(state);
const sequences = getAllSequences(state);
// Query by component name (no imports needed)
const withTransform = queryEntities(state, 'transform');
const hasParent = hasComponentByName(state, eid, 'parent');
const transform = getComponentData(state, eid, 'transform'); // {posX, posY, posZ, ...}
const allComponents = getEntityData(state, eid); // {transform: {...}, parent: {...}}
// Step and snapshot
state.step(1/60);
const snap = state.snapshot({
entities: names,
includeSequences: true,
});
console.log(toJSON(snap)); // Structured JSON for AI parsing
// Sequence control
const seq = state.getEntityByName('intro');
resetSequence(state, seq);
playSequence(state, seq);
for (let i = 0; i < 60; i++) state.step(1/60);
// Check sequence progress
const info = getSequenceInfo(state, 'intro');
console.log(info.state, info.progress); // 'idle' | 'playing', 0-1
state.dispose();
```
### Headless Differences
- `state.headless = true` - Systems can check this to skip rendering
- No canvas/WebGL required
- Text measurement via Typr.js (requires `setHeadlessFont`)
- DOM polyfills provided via jsdom
## Plugin Reference
### Core
Math utilities for interpolation and 3D transformations.
### Functions
#### lerp(a, b, t): number
Linear interpolation
#### slerp(fromX, fromY, fromZ, fromW, toX, toY, toZ, toW, t): Quaternion
Quaternion spherical interpolation
#### Examples
## Usage Note
Math utilities are used internally by systems like tweening and transforms. For animating properties, use the Tween system instead of directly calling interpolation functions. For transformations, use the Transform component's euler angles which are automatically converted to quaternions by the system.
### Animation
Procedural character animation with body parts that respond to movement states.
### Components
#### AnimatedCharacter
- headEntity: eid
- torsoEntity: eid
- leftArmEntity: eid
- rightArmEntity: eid
- leftLegEntity: eid
- rightLegEntity: eid
- phase: f32 - Walk cycle phase (0-1)
- jumpTime: f32
- fallTime: f32
- animationState: ui8 - 0=IDLE, 1=WALKING, 2=JUMPING, 3=FALLING, 4=LANDING
- stateTransition: f32
#### HasAnimator
Tag component (no properties)
### Systems
#### AnimatedCharacterInitializationSystem
- Group: setup
- Creates body part entities for AnimatedCharacter components
#### AnimatedCharacterUpdateSystem
- Group: simulation
- Updates character animation based on movement and physics state
#### Examples
## Examples
### Basic Usage
```typescript
import * as GAME from 'vibegame';
import { AnimatedCharacter } from 'vibegame/animation';
import { CharacterController } from 'vibegame/physics';
import { Transform } from 'vibegame/transforms';
// Add animated character to a player entity
const player = state.createEntity();
state.addComponent(player, AnimatedCharacter);
state.addComponent(player, CharacterController);
state.addComponent(player, Transform);
// The AnimatedCharacterInitializationSystem will automatically
// create body parts in the next setup phase
```
### Accessing Animation State
```typescript
import * as GAME from 'vibegame';
import { AnimatedCharacter } from 'vibegame/animation';
const characterQuery = GAME.defineQuery([AnimatedCharacter]);
const MySystem: GAME.System = {
update: (state) => {
const characters = characterQuery(state.world);
for (const entity of characters) {
const animState = AnimatedCharacter.animationState[entity];
if (animState === 2) { // JUMPING
console.log('Character is jumping!');
}
}
}
};
```
### XML Declaration
```xml
```
### Input
Focus-aware input handling for mouse, keyboard, and gamepad with buffered actions. Keyboard input only responds when canvas has focus.
### Components
#### InputState
- moveX: f32 - Horizontal axis (-1 left, 1 right)
- moveY: f32 - Forward/backward (-1 back, 1 forward)
- moveZ: f32 - Vertical axis (-1 down, 1 up)
- lookX: f32 - Mouse delta X
- lookY: f32 - Mouse delta Y
- scrollDelta: f32 - Mouse wheel delta
- jump: ui8 - Jump available (0/1)
- primaryAction: ui8 - Primary action (0/1)
- secondaryAction: ui8 - Secondary action (0/1)
- leftMouse: ui8 - Left button (0/1)
- rightMouse: ui8 - Right button (0/1)
- middleMouse: ui8 - Middle button (0/1)
- jumpBufferTime: f32
- primaryBufferTime: f32
- secondaryBufferTime: f32
### Systems
#### InputSystem
- Group: simulation
- Updates InputState components with current input data
### Functions
#### setTargetCanvas(canvas: HTMLCanvasElement | null): void
Registers canvas for focus-based keyboard input
#### consumeJump(): boolean
Consumes buffered jump input
#### consumePrimary(): boolean
Consumes buffered primary action
#### consumeSecondary(): boolean
Consumes buffered secondary action
#### handleMouseMove(event: MouseEvent): void
Processes mouse movement
#### handleMouseDown(event: MouseEvent): void
Processes mouse button press
#### handleMouseUp(event: MouseEvent): void
Processes mouse button release
#### handleWheel(event: WheelEvent): void
Processes mouse wheel
### Constants
#### INPUT_CONFIG
Default input mappings and sensitivity settings
#### Examples
## Examples
### Basic Plugin Registration
```typescript
import * as GAME from 'vibegame';
import { InputPlugin } from 'vibegame/input';
GAME
.withPlugin(InputPlugin)
.run();
```
### Reading Input in a Custom System
```typescript
import * as GAME from 'vibegame';
import { Player, InputState } from 'vibegame/input';
const playerQuery = GAME.defineQuery([Player, InputState]);
const PlayerControlSystem: GAME.System = {
update: (state) => {
const players = playerQuery(state.world);
for (const player of players) {
// Read movement axes
const moveX = InputState.moveX[player];
const moveY = InputState.moveY[player];
// Check for jump
if (InputState.jump[player]) {
// Jump is available this frame
}
// Check mouse buttons
if (InputState.leftMouse[player]) {
// Left mouse is held
}
}
}
};
```
### Consuming Buffered Actions
```typescript
import * as GAME from 'vibegame';
const CombatSystem: GAME.System = {
update: (state) => {
// Consume jump if available (prevents double consumption)
if (GAME.consumeJump()) {
// Perform jump
velocity.y = JUMP_FORCE;
}
// Consume primary action
if (GAME.consumePrimary()) {
// Fire weapon
spawnProjectile();
}
}
};
```
### Custom Input Mappings
```typescript
import * as GAME from 'vibegame';
// Modify before starting the game
GAME.INPUT_CONFIG.mappings.jump = ['Space', 'KeyX'];
GAME.INPUT_CONFIG.mappings.moveForward = ['KeyW', 'KeyZ', 'ArrowUp'];
GAME.INPUT_CONFIG.mouseSensitivity.look = 0.3;
GAME.run();
```
### Manual Event Handling
```typescript
import * as GAME from 'vibegame';
// Use the exported handlers directly if needed
canvas.addEventListener('mousedown', GAME.handleMouseDown);
canvas.addEventListener('mouseup', GAME.handleMouseUp);
```
### Line
2D billboard line rendering plugin using Three.js LineSegments2 for GPU-accelerated fat lines with consistent screen-space thickness. Uses batched rendering for performance - lines with matching material properties share a single draw call.
### Components
#### Line
- offsetX: f32 (1) - End point X offset from entity position
- offsetY: f32 (0) - End point Y offset from entity position
- offsetZ: f32 (0) - End point Z offset from entity position
- color: ui32 (0xffffff) - Line color as hex
- thickness: f32 (2) - Line width in pixels
- opacity: f32 (1) - Line opacity 0-1
- visible: ui8 (1) - Visibility flag
- arrowStart: ui8 (0) - Draw arrow at start point
- arrowEnd: ui8 (0) - Draw arrow at end point
- arrowSize: f32 (0.2) - Arrow head size in world units
### Systems
#### LineSystem
- Group: draw
- Batches line segments by material properties
- Start position from WorldTransform, end from start + offset
- Includes arrow wing segments in batch geometry
#### Examples
## Examples
### Basic Line
```xml
```
### Styled Line
```xml
```
### Imperative Usage
```typescript
import { State } from 'vibegame';
import { Line, LinePlugin } from 'vibegame/line';
import { Transform, WorldTransform, TransformsPlugin } from 'vibegame/transforms';
const state = new State();
state.registerPlugin(TransformsPlugin);
state.registerPlugin(LinePlugin);
const lineEntity = state.createEntity();
state.addComponent(lineEntity, Transform);
state.addComponent(lineEntity, WorldTransform);
state.addComponent(lineEntity, Line);
Line.offsetX[lineEntity] = 5;
Line.offsetY[lineEntity] = 3;
Line.offsetZ[lineEntity] = 0;
Line.color[lineEntity] = 0xff0000;
Line.thickness[lineEntity] = 3;
Line.arrowEnd[lineEntity] = 1;
Line.arrowSize[lineEntity] = 0.3;
```
### Orbit Camera
Standalone orbital camera controller with direct input handling for third-person views and smooth target following.
### Components
#### OrbitCamera
- target: eid (0) - Target entity to orbit around
- input-source: eid (0) - Entity with InputState component (player or self)
- current-yaw: f32 (0) - Current horizontal angle
- current-pitch: f32 (π/6) - Current vertical angle
- current-distance: f32 (4) - Current distance
- target-yaw: f32 (0) - Target horizontal angle
- target-pitch: f32 (π/6) - Target vertical angle
- target-distance: f32 (4) - Target distance
- min-distance: f32 (1)
- max-distance: f32 (25)
- min-pitch: f32 (0)
- max-pitch: f32 (π/2)
- smoothness: f32 (0.5) - Interpolation speed
- offset-x: f32 (0)
- offset-y: f32 (1.25)
- offset-z: f32 (0)
- sensitivity: f32 (0.007) - Mouse look sensitivity
- zoom-sensitivity: f32 (1.5) - Scroll zoom sensitivity
### Systems
#### OrbitCameraSetupSystem
- Group: setup
- Auto-creates target entity at origin if target is unassigned (eid 0)
- Auto-assigns inputSource from existing InputState entity, or creates one if none found
#### OrbitCameraInputSystem
- Group: simulation
- Reads InputState from inputSource entity (player or camera)
- Updates camera yaw/pitch/distance based on mouse and scroll input
#### OrbitCameraSystem
- Group: draw
- Smoothly interpolates camera to target values
- Calculates and updates camera position around target
### Recipes
#### orbit-camera
- Creates orbital camera with auto-setup for target and input handling
- Components: orbit-camera, transform, main-camera
#### Examples
## Examples
### Basic Camera
```xml
```
### Camera Following Player
```xml
```
### Custom Orbit Settings
```xml
```
### Dynamic Target Switching
```typescript
import { OrbitCamera } from 'vibegame/orbit-camera';
const switchTarget = (state, cameraEntity, newTargetEntity) => {
OrbitCamera.target[cameraEntity] = newTargetEntity;
};
```
### Physics
3D physics simulation with Rapier including rigid bodies, collisions, and character controllers.
### Constants
- DEFAULT_GRAVITY: -60
### Enums
#### BodyType
- Dynamic = 0 - Affected by forces
- Fixed = 1 - Immovable static
- KinematicPositionBased = 2 - Script position
- KinematicVelocityBased = 3 - Script velocity
#### ColliderShape
- Box = 0
- Sphere = 1
### Components
#### PhysicsWorld
- gravityX: f32 (0)
- gravityY: f32 (-60)
- gravityZ: f32 (0)
#### Body
- type: ui8 - BodyType enum (Fixed)
- mass: f32 (1)
- linearDamping: f32 (0)
- angularDamping: f32 (0)
- gravityScale: f32 (1)
- ccd: ui8 (0)
- lockRotX: ui8 (0)
- lockRotY: ui8 (0)
- lockRotZ: ui8 (0)
- posX, posY, posZ: f32
- rotX, rotY, rotZ, rotW: f32 (rotW=1)
- eulerX, eulerY, eulerZ: f32
- velX, velY, velZ: f32
- rotVelX, rotVelY, rotVelZ: f32
#### Collider
- shape: ui8 - ColliderShape enum (Box)
- sizeX, sizeY, sizeZ: f32 (1)
- radius: f32 (0.5)
- height: f32 (1)
- friction: f32 (0.5)
- restitution: f32 (0)
- density: f32 (1)
- isSensor: ui8 (0)
- membershipGroups: ui16 (0xffff)
- filterGroups: ui16 (0xffff)
- posOffsetX, posOffsetY, posOffsetZ: f32
- rotOffsetX, rotOffsetY, rotOffsetZ, rotOffsetW: f32 (rotOffsetW=1)
#### CharacterController
- offset: f32 (0.08)
- maxSlope: f32 (45°)
- maxSlide: f32 (30°)
- snapDist: f32 (0.5)
- autoStep: ui8 (1)
- maxStepHeight: f32 (0.3)
- minStepWidth: f32 (0.05)
- upX, upY, upZ: f32 (upY=1)
- moveX, moveY, moveZ: f32
- grounded: ui8
- platform: eid - Entity the character is standing on
- platformVelX, platformVelY, platformVelZ: f32 - Inherited velocity from platform
#### CharacterMovement
- desiredVelX, desiredVelY, desiredVelZ: f32
- velocityY: f32
- actualMoveX, actualMoveY, actualMoveZ: f32
#### InterpolatedTransform
- prevPosX, prevPosY, prevPosZ: f32
- prevRotX, prevRotY, prevRotZ, prevRotW: f32
- posX, posY, posZ: f32
- rotX, rotY, rotZ, rotW: f32
#### Force/Impulse Components
- ApplyForce: x, y, z (f32)
- ApplyTorque: x, y, z (f32)
- ApplyImpulse: x, y, z (f32)
- ApplyAngularImpulse: x, y, z (f32)
- SetLinearVelocity: x, y, z (f32)
- SetAngularVelocity: x, y, z (f32)
- KinematicMove: x, y, z (f32)
- KinematicRotate: x, y, z, w (f32)
- KinematicAngularVelocity: x, y, z (f32)
#### Collision Events
- CollisionEvents: activeEvents (ui8)
- TouchedEvent: other, handle1, handle2 (ui32)
- TouchEndedEvent: other, handle1, handle2 (ui32)
### Systems
- PhysicsWorldSystem - Initializes physics world
- PhysicsInitializationSystem - Creates bodies and colliders
- PhysicsCleanupSystem - Removes physics on entity destroy
- CharacterMovementSystem - Character controller with full velocity inheritance (linear + angular)
- CollisionEventCleanupSystem - Clears collision events
- ApplyForcesSystem - Applies forces
- ApplyTorquesSystem - Applies torques
- ApplyImpulsesSystem - Applies impulses
- ApplyAngularImpulsesSystem - Applies angular impulses
- SetVelocitySystem - Sets velocities
- TeleportationSystem - Instant position changes
- KinematicMovementSystem - Kinematic movement
- PhysicsStepSystem - Steps simulation
- PhysicsRapierSyncSystem - Syncs Rapier to ECS
- PhysicsInterpolationSystem - Interpolates for rendering
### Functions
#### initializePhysics(): Promise
Initializes Rapier WASM physics engine
### Recipes
- static-part - Immovable physics objects
- dynamic-part - Gravity-affected objects
- kinematic-part - Script-controlled objects
#### Examples
## Examples
### Basic Usage
#### XML Recipes
##### Static Floor
```xml
```
##### Dynamic Ball
```xml
```
##### Moving Platform
```xml
```
##### Character with Controller
```xml
```
#### JavaScript API
##### Create Physics Entity
```typescript
import * as GAME from 'vibegame';
import { Body, Collider, BodyType, ColliderShape } from 'vibegame/physics';
// Create a dynamic physics box
const entity = state.createEntity();
state.addComponent(entity, Body, {
type: BodyType.Dynamic,
mass: 5,
posX: 0, posY: 10, posZ: 0
});
state.addComponent(entity, Collider, {
shape: ColliderShape.Box,
sizeX: 1, sizeY: 1, sizeZ: 1,
friction: 0.7,
restitution: 0.3
});
// Note: Physics body won't exist until next fixed update
// Transform will be overwritten by Body position after initialization
```
##### Moving Physics Bodies
```typescript
import * as GAME from 'vibegame';
import { Body, BodyType, ApplyForce, ApplyImpulse, KinematicMove, SetLinearVelocity } from 'vibegame/physics';
import { Transform } from 'vibegame/transforms';
// Dynamic bodies - Use forces/impulses for movement
if (Body.type[entity] === BodyType.Dynamic) {
// Apply force for gradual acceleration
state.addComponent(entity, ApplyForce, { x: 10, y: 0, z: 0 });
// Apply impulse for instant velocity change
state.addComponent(entity, ApplyImpulse, { x: 0, y: 50, z: 0 });
// Direct position setting only for teleportation
Body.posX[entity] = 10; // Teleport - use sparingly
}
// Kinematic bodies - Direct control via movement components
if (Body.type[entity] === BodyType.KinematicPositionBased) {
state.addComponent(entity, KinematicMove, { x: 5, y: 2, z: 0 });
}
if (Body.type[entity] === BodyType.KinematicVelocityBased) {
state.addComponent(entity, SetLinearVelocity, { x: 3, y: 0, z: 0 });
}
// Never modify Transform directly for physics entities
// Transform.posX[entity] = 10; // ❌ Will be overwritten by Body
```
##### Apply Forces
```typescript
import * as GAME from 'vibegame';
import { ApplyImpulse, ApplyForce, SetLinearVelocity } from 'vibegame/physics';
// Apply upward impulse (jump)
state.addComponent(entity, ApplyImpulse, {
x: 0, y: 50, z: 0
});
// Apply continuous force
state.addComponent(entity, ApplyForce, {
x: 10, y: 0, z: 0
});
// Set velocity directly
state.addComponent(entity, SetLinearVelocity, {
x: 0, y: 5, z: 0
});
```
##### Handle Collisions
```typescript
import * as GAME from 'vibegame';
import { TouchedEvent, ApplyImpulse } from 'vibegame/physics';
const touchedQuery = GAME.defineQuery([TouchedEvent]);
const CollisionSystem: GAME.System = {
update: (state) => {
// Query entities with collision events
for (const entity of touchedQuery(state.world)) {
const otherEntity = TouchedEvent.other[entity];
console.log(`Entity ${entity} collided with ${otherEntity}`);
// React to collision
state.addComponent(entity, ApplyImpulse, {
x: 0, y: 10, z: 0
});
}
}
};
```
##### Character Movement
```typescript
import * as GAME from 'vibegame';
import { CharacterMovement, CharacterController } from 'vibegame/physics';
const PlayerMovementSystem: GAME.System = {
update: (state) => {
const movementQuery = GAME.defineQuery([CharacterMovement, CharacterController]);
for (const entity of movementQuery(state.world)) {
// Set desired movement based on input
CharacterMovement.desiredVelX[entity] = input.x * 5;
CharacterMovement.desiredVelZ[entity] = input.z * 5;
// Jump if grounded
if (CharacterController.grounded[entity] && input.jump) {
CharacterMovement.velocityY[entity] = 10;
}
}
}
};
```
##### Custom Plugin Integration
```typescript
import * as GAME from 'vibegame';
// Initialize physics before running
await GAME.initializePhysics();
// Use with builder
GAME
.withPlugin(GAME.PhysicsPlugin)
.run();
```
### Player
Complete player character controller with physics movement, jumping, and platform momentum preservation.
### Components
#### Player
- speed: f32 (5.3)
- jumpHeight: f32 (2.3)
- rotationSpeed: f32 (10)
- canJump: ui8 (1)
- isJumping: ui8 (0)
- jumpCooldown: f32 (0)
- lastGroundedTime: f32 (0)
- jumpBufferTime: f32 (-10000)
- cameraEntity: eid (0) - Linked camera for orientation reference
- inheritedVelX: f32 (0) - Horizontal momentum from platform
- inheritedVelZ: f32 (0) - Horizontal momentum from platform
- inheritedAngVelX: f32 (0) - Platform angular velocity X
- inheritedAngVelY: f32 (0) - Platform angular velocity Y
- inheritedAngVelZ: f32 (0) - Platform angular velocity Z
- platformOffsetX: f32 (0) - Position relative to platform center
- platformOffsetY: f32 (0) - Position relative to platform center
- platformOffsetZ: f32 (0) - Position relative to platform center
- lastPlatform: eid (0) - Track platform changes
### Systems
#### PlayerMovementSystem
- Group: fixed
- Reads camera yaw for camera-relative movement
- Handles rotation, jumping with platform momentum inheritance
#### PlayerGroundedSystem
- Group: fixed
- Tracks grounded state and platform changes
- Clears momentum on landing
#### PlayerCameraLinkingSystem
- Group: simulation
- Auto-links player to first available camera
- Sets camera target and inputSource to player entity
### Recipes
#### player
- Complete player setup with physics
- Components: player, character-movement, transform, world-transform, body, collider, character-controller, input-state, respawn
### Functions
#### processInput(moveForward, moveRight, cameraYaw): Vector3
Converts input to world-space movement
#### calculateTangentialVelocity(angVelX, angVelY, angVelZ, offsetX, offsetY, offsetZ): Vector3
Computes tangential velocity from angular rotation (v = ω × r)
#### handleJump(entity, jumpPressed, currentTime, platform?): number
Processes jump with buffering and angular momentum inheritance
#### updateRotation(entity, inputVector, deltaTime, rotationData): Quaternion
Smooth rotation towards movement
#### Examples
## Examples
### Basic Player Usage (XML)
```xml
```
### Custom Player Configuration (XML)
```xml
```
### Accessing Player Component (JavaScript)
```typescript
import * as GAME from 'vibegame';
const playerQuery = GAME.defineQuery([GAME.Player]);
const MySystem: GAME.System = {
update: (state) => {
const players = playerQuery(state.world);
for (const entity of players) {
// Check if player is jumping
if (GAME.Player.isJumping[entity]) {
console.log('Player is airborne!');
}
// Modify player speed
GAME.Player.speed[entity] = 10;
}
}
};
```
### Creating Player Programmatically
```typescript
import * as GAME from 'vibegame';
const PlayerSpawnSystem: GAME.System = {
setup: (state) => {
const player = state.createEntity();
state.addComponent(player, GAME.Player, {
speed: 7,
jumpHeight: 3.5,
});
state.addComponent(player, GAME.Transform, { posY: 5 });
state.addComponent(player, GAME.Body, { type: GAME.BodyType.KinematicPositionBased });
state.addComponent(player, GAME.CharacterController);
state.addComponent(player, GAME.InputState);
}
};
```
### Movement Controls
**Keyboard:**
- W/S or Arrow Up/Down - Move forward/backward
- A/D or Arrow Left/Right - Move left/right
- Space - Jump
**Mouse (via orbit camera):**
- Right-click + drag - Rotate camera
- Scroll wheel - Zoom in/out
Note: Camera controls are handled by OrbitCameraPlugin, not PlayerPlugin.
### Plugin Registration
```typescript
import * as GAME from 'vibegame';
GAME
.withPlugin(GAME.PlayerPlugin) // Included in defaults
.run();
```
### Postprocessing
Post-processing effects layer using the postprocessing library for Three.js rendering.
### Components
#### Bloom
- intensity: f32 (1.0) - Bloom intensity
- luminanceThreshold: f32 (1.0) - Luminance threshold for bloom
- mipmapBlur: ui8 (1) - Enable mipmap blur
- radius: f32 (0.85) - Blur radius for mipmap blur
- levels: ui8 (8) - Number of MIP levels for mipmap blur
#### Dithering
- colorBits: ui8 (4) - Bits per color channel (1-8)
- intensity: f32 (1.0) - Effect intensity (0-1)
- grayscale: ui8 (0) - Enable grayscale mode (0/1)
- scale: f32 (1.0) - Pattern scale (higher = coarser dithering)
- noise: f32 (1.0) - Noise threshold intensity
#### SMAA
- preset: ui8 (2) - Anti-aliasing quality (0=low, 1=medium, 2=high, 3=ultra)
#### Tonemapping
- mode: ui8 (7) - Tonemapping mode (0-9)
- middleGrey: f32 (0.6) - Middle grey value
- whitePoint: f32 (4.0) - White point
- averageLuminance: f32 (1.0) - Average luminance
- adaptationRate: f32 (1.0) - Adaptation rate
### Systems
#### PostprocessingSystem
- Group: draw
- Manages EffectComposer and rebuilds effect passes based on components
#### PostprocessingRenderSystem
- Group: draw (last)
- Renders scene through EffectComposer with effects
### Tonemapping Modes
- 0: linear
- 1: reinhard
- 2: reinhard2
- 3: reinhard2-adaptive
- 4: uncharted2
- 5: optimized-cineon
- 6: cineon
- 7: aces-filmic (default)
- 8: agx
- 9: neutral
#### Examples
## Examples
### Bloom Effect
```xml
```
### Dithering Effect
```xml
```
### SMAA Anti-Aliasing
```xml
```
### Combined Effects
```xml
```
### Imperative Usage
```typescript
import * as GAME from 'vibegame';
// Add bloom to camera entity
const cameraEntity = state.createEntity();
state.addComponent(cameraEntity, GAME.MainCamera);
state.addComponent(cameraEntity, GAME.Bloom, {
intensity: 1.5,
luminanceThreshold: 0.9,
});
// Add dithering
state.addComponent(cameraEntity, GAME.Dithering, {
colorBits: 4,
intensity: 0.8,
scale: 2,
});
// Remove effects
state.removeComponent(cameraEntity, GAME.Bloom);
```
### Rendering
Lightweight Three.js rendering wrapper with meshes, lights, and cameras.
### Components
#### Renderer
- shape: ui8 - 0=box, 1=sphere
- sizeX, sizeY, sizeZ: f32 (1)
- color: ui32 (0xffffff)
- visible: ui8 (1)
- unlit: ui8 (0) - Use unlit material (ignores lighting)
#### RenderContext
- clearColor: ui32 (0x000000)
- hasCanvas: ui8
#### MainCamera
- projection: ui8 (0) - 0=perspective, 1=orthographic
- fov: f32 (75) - Field of view in degrees (perspective only)
- orthoSize: f32 (10) - Vertical size in world units (orthographic only)
#### AmbientLight
- skyColor: ui32 (0x87ceeb)
- groundColor: ui32 (0x4a4a4a)
- intensity: f32 (0.6)
#### DirectionalLight
- color: ui32 (0xffffff)
- intensity: f32 (1)
- castShadow: ui8 (1)
- shadowMapSize: ui32 (4096)
- directionX: f32 (-1)
- directionY: f32 (2)
- directionZ: f32 (-1)
- distance: f32 (30)
### Systems
#### MeshInstanceSystem
- Group: draw
- Synchronizes transforms with Three.js meshes
#### LightSyncSystem
- Group: draw
- Updates Three.js lights
#### CameraSyncSystem
- Group: draw
- Synchronizes camera position and rotation from WorldTransform
#### WebGLRenderSystem
- Group: draw (last)
- Renders scene directly via WebGLRenderer (or through EffectComposer if postprocessing plugin is active)
### Functions
#### setCanvasElement(entity, canvas): void
Associates canvas with RenderContext
#### Examples
## Examples
### Basic Rendering Setup
```xml
```
### Custom Lighting
```xml
```
### Imperative Usage
```typescript
import * as GAME from 'vibegame';
// Create rendered entity programmatically
const entity = state.createEntity();
// Add transform for positioning
state.addComponent(entity, GAME.Transform, {
posX: 0, posY: 5, posZ: 0
});
// Add renderer component
state.addComponent(entity, GAME.Renderer, {
shape: 1, // sphere
sizeX: 2,
sizeY: 2,
sizeZ: 2,
color: 0xff00ff,
visible: 1
});
// Set canvas for rendering context
const contextQuery = GAME.defineQuery([GAME.RenderContext]);
const contextEntity = contextQuery(state.world)[0];
const canvas = document.getElementById('game-canvas');
GAME.setCanvasElement(contextEntity, canvas);
```
### Shape Types
```typescript
import * as GAME from 'vibegame';
// Available shape enums
const shapes = {
box: 0,
sphere: 1
};
// Use in XML
// Or with enum names
```
### Visibility Control
```typescript
import * as GAME from 'vibegame';
// Hide/show entities
GAME.Renderer.visible[entity] = 0; // Hide
GAME.Renderer.visible[entity] = 1; // Show
// In XML
```
### Unlit Rendering
```xml
```
### Orthographic Camera
```xml
```
### Respawn
Automatic respawn system that resets entities when falling below Y=-100.
### Components
#### Respawn
- posX, posY, posZ: f32 - Spawn position
- eulerX, eulerY, eulerZ: f32 - Spawn rotation (degrees)
### Systems
#### RespawnSystem
- Group: simulation
- Resets entities when Y < -100
#### Examples
## Examples
### Player with Respawn (Automatic)
The `` recipe automatically includes respawn:
```xml
```
### Manual Respawn Component
```xml
```
### Imperative Usage
```typescript
import * as GAME from 'vibegame';
// Add respawn to an entity
const entity = state.createEntity();
// Set spawn point from current transform
state.addComponent(entity, GAME.Transform, {
posX: 0, posY: 10, posZ: 0,
eulerX: 0, eulerY: 0, eulerZ: 0
});
state.addComponent(entity, GAME.Respawn, {
posX: 0, posY: 10, posZ: 0,
eulerX: 0, eulerY: 0, eulerZ: 0
});
// Entity will respawn at (0,10,0) when falling
```
### Update Spawn Point
```typescript
import * as GAME from 'vibegame';
// Change respawn position dynamically
GAME.Respawn.posX[entity] = 20;
GAME.Respawn.posY[entity] = 5;
GAME.Respawn.posZ[entity] = -10;
```
### XML with Transform Sync
Position attributes automatically populate the respawn component:
```xml
```
### Startup
Auto-creates player, camera, and lighting entities at startup if missing.
### Systems
#### LightingStartupSystem
- Group: setup
- Creates default lighting if none exists
#### CameraStartupSystem
- Group: setup
- Creates orbit camera with InputState if none exists
- Sets inputSource to self for standalone operation
#### PlayerStartupSystem
- Group: setup
- Creates player entity if none exists
#### PlayerCharacterSystem
- Group: setup
- Adds animated character to players
#### Examples
## Examples
### Basic Usage (Auto-Creation)
```typescript
// The plugin automatically creates defaults when included
import * as GAME from 'vibegame';
// This will create player, camera, and lighting automatically
GAME.run(); // Uses DefaultPlugins which includes StartupPlugin
```
### Preventing Auto-Creation with XML
```xml
```
### Manual Plugin Registration
```typescript
import * as GAME from 'vibegame';
// Use startup plugin without other defaults
GAME.withoutDefaultPlugins()
.withPlugin(GAME.TransformsPlugin)
.withPlugin(GAME.RenderingPlugin)
.withPlugin(GAME.StartupPlugin)
.run();
```
### System Behavior
The startup systems are idempotent - they check for existing entities before creating:
```typescript
import * as GAME from 'vibegame';
// First run: Creates player, camera, lights
const playerQuery = GAME.defineQuery([GAME.Player]);
playerQuery(state.world).length // 0 -> creates player
// Subsequent runs: Skips creation
playerQuery(state.world).length // 1 -> skips creation
```
### Text
3D text rendering with troika-three-text. Paragraph/Word hierarchy for layout. Supports headless mode via injectable measurement function (see CLI module).
### Components
#### Paragraph
- gap: f32 (0.2) - Space between words
- align: ui8 (1) - 0=left, 1=center, 2=right
- anchorX/anchorY: ui8 (1) - Text anchor
- damping: f32 (0) - Position smoothing (0=instant)
#### Word
- fontSize, color, letterSpacing, lineHeight
- outlineWidth/Color/Blur/OffsetX/OffsetY/Opacity
- strokeWidth/Color/Opacity, fillOpacity, curveRadius
- width (internal), dirty (internal)
### Systems
- **WordRenderSystem** (draw): Creates troika meshes (skips in headless)
- **WordMeasureSystem** (draw): Measures word width via injectable `measureFn`
- **ParagraphArrangeSystem** (simulation): Positions words in paragraph
### Headless
Use `setMeasureFn(state, fn)` to inject custom measurement. CLI module provides `setHeadlessFont()` for Typr.js-based measurement.
#### Examples
## Examples
```xml
```
### Transforms
3D transforms with position, rotation, scale, and parent-child hierarchies.
### Components
#### Transform
- posX, posY, posZ: f32 (0)
- rotX, rotY, rotZ, rotW: f32 (rotW=1) - Quaternion
- eulerX, eulerY, eulerZ: f32 (0) - Degrees
- scaleX, scaleY, scaleZ: f32 (1)
#### WorldTransform
- Same properties as Transform
- Auto-computed from hierarchy (read-only)
### Systems
#### TransformHierarchySystem
- Group: simulation (last)
- Syncs euler/quaternion and computes world transforms
#### Examples
## Examples
### Basic Usage
#### XML Position and Rotation
```xml
```
#### JavaScript API
```typescript
import * as GAME from 'vibegame';
// In a system
const MySystem = {
update: (state) => {
const entity = state.createEntity();
// Add transform component with initial values
state.addComponent(entity, GAME.Transform, {
posX: 10, posY: 5, posZ: -3,
eulerX: 0, eulerY: 45, eulerZ: 0,
scaleX: 2, scaleY: 2, scaleZ: 2
});
// Transform system automatically syncs euler to quaternion
}
};
```
### Transform Hierarchy
#### Parent-Child Relationships
```xml
```
#### Accessing World Transform
```typescript
import * as GAME from 'vibegame';
const transformQuery = GAME.defineQuery([GAME.Transform, GAME.WorldTransform]);
const WorldTransformSystem = {
update: (state) => {
// Query entities with both transforms
const entities = transformQuery(state.world);
for (const entity of entities) {
// Local position
const localX = GAME.Transform.posX[entity];
// World position (after parent transforms)
const worldX = GAME.WorldTransform.posX[entity];
console.log(`Local: ${localX}, World: ${worldX}`);
}
}
};
```
### Common Patterns
#### Setting Transform Values
```typescript
import * as GAME from 'vibegame';
// Direct property access (bitECS style)
GAME.Transform.posX[entity] = 10;
GAME.Transform.posY[entity] = 5;
GAME.Transform.posZ[entity] = -3;
// Using euler angles for rotation
GAME.Transform.eulerX[entity] = 0;
GAME.Transform.eulerY[entity] = 45;
GAME.Transform.eulerZ[entity] = 0;
// Quaternion will be auto-synced by TransformHierarchySystem
// Uniform scale
GAME.Transform.scaleX[entity] = 2;
GAME.Transform.scaleY[entity] = 2;
GAME.Transform.scaleZ[entity] = 2;
```
#### Transform Interpolation
```typescript
import * as GAME from 'vibegame';
// Interpolate between two positions
const t = 0.5; // 50% between start and end
GAME.Transform.posX[entity] = startX + (endX - startX) * t;
GAME.Transform.posY[entity] = startY + (endY - startY) * t;
GAME.Transform.posZ[entity] = startZ + (endZ - startZ) * t;
```
### Tweening
Animates component properties with easing functions. Tweens are one-shot animations that destroy on completion. Sequences are reusable animation definitions that can be played, stopped, and reset. Shakers provide additive presentation modifiers without changing base values. Kinematic velocity bodies use velocity-based tweening for smooth physics-correct movement.
### Name Resolution
Entities with `name` attribute are registered in a name→entityId map at parse time. Tweens and sequences reference targets by name, resolved to entity IDs during parsing.
```xml
```
Runtime lookup via `state.getEntityByName('door')` returns the entity ID.
### Components
**Tween** - Animation controller (auto-destroyed on completion)
- duration: f32 (1) - Seconds
- elapsed: f32 - Current time
- easingIndex: ui8 - Index into easing functions
**TweenValue** - Property interpolation (one per animated field)
- source: ui32 - Tween entity reference
- target: ui32 - Animated entity
- from/to: f32 - Value range
- value: f32 - Current interpolated value
**KinematicTween** - Velocity-based position animation for physics bodies
- tweenEntity: ui32, targetEntity: ui32
- axis: ui8 (0=X, 1=Y, 2=Z)
- from/to: f32 - Position range
**KinematicRotationTween** - Velocity-based rotation for physics bodies
- Same structure as KinematicTween, values in radians
**Sequence** - Sequential animation orchestrator
- state: ui8 (Idle=0, Playing=1)
- currentIndex: ui32
- itemCount: ui32
- pauseRemaining: f32
**Shaker** - Presentation modifier for non-transform fields (applied at draw time, restored after)
- target: eid - Entity being modified
- value: f32 - Modification value
- intensity: f32 - Effect multiplier (0-1)
- mode: ui8 (Additive=0, Multiplicative=1)
**TransformShaker** - Presentation modifier for WorldTransform (position/scale/rotation)
- target: eid - Entity being modified
- type: ui8 (Position=0, Scale=1, Rotation=2)
- axes: ui8 - Bitmask (X=1, Y=2, Z=4, XYZ=7)
- value: f32 - Modification value
- intensity: f32 - Effect multiplier (0-1)
- mode: ui8 (Additive=0, Multiplicative=1)
### Shaker System
Shakers modify component values at draw time without affecting simulation. Regular shakers target arbitrary component fields. Transform shakers target WorldTransform (which rendering uses) via quaternion multiplication for rotation (avoiding gimbal lock).
**Auto-detection**: `createShaker()` automatically creates TransformShaker when targeting transform fields (transform.pos-*, transform.scale-*, transform.euler-*, or shorthands).
**Formulas:**
- Additive: `result = base + (value * intensity)`
- Multiplicative: `result = base * (1 + (value - 1) * intensity)`
- Rotation: quaternion multiplication (degrees input)
**Composition order:** All additive shakers apply first, then multiplicative.
### Shorthand Targets
Shorthands expand to multiple TweenValue entities for tweens, or set axes bitmask for shakers:
| Shorthand | Expands To | Notes |
|-----------|------------|-------|
| `at` | transform.posX/Y/Z | Position animation |
| `scale` | transform.scaleX/Y/Z | Scale animation (all axes uniform for shakers) |
| `rotation` | body.eulerX/Y/Z or transform.eulerX/Y/Z | Uses body if present for tweens |
### Kinematic Body Detection
For `` entities, tweens on body.pos-* or body.euler-* fields automatically create KinematicTween/KinematicRotationTween instead of TweenValue. This uses velocity-based movement for physics-correct behavior.
### Sequence Execution Model
1. Tweens before first `` start simultaneously
2. `` waits for all active tweens + pause duration
3. Next group of tweens starts after pause completes
4. Sequence resets to Idle when all items processed
### Functions
```typescript
// Create one-shot tween (returns tween entity ID)
createTween(state, entity, target, options): number | null
// Create shaker (returns shaker entity ID)
createShaker(state, entity, target, options): number | null
// Sequence control
playSequence(state, entity): void // Start from current position
stopSequence(state, entity): void // Stop and clear active tweens
resetSequence(state, entity): void // Stop and reset to beginning
completeSequence(state, entity): void // Jump to end, apply final values
```
### Easing Functions
`linear`, `sine-in/out/in-out`, `quad-in/out/in-out`, `cubic-in/out/in-out`, `quart-in/out/in-out`, `expo-in/out/in-out`, `circ-in/out/in-out`, `back-in/out/in-out`, `elastic-in/out/in-out`, `bounce-in/out/in-out`
#### Examples
## XML (Declarative) Patterns
### Standalone Tween
```xml
```
### Shorthand Tweens
```xml
```
### Named Sequence (Reusable)
Sequences with `name` start paused. Trigger via `playSequence()` in TypeScript.
```xml
```
### Autoplay Sequence (Parallel + Sequential)
Tweens before `` run simultaneously. Pause separates sequential groups.
```xml
```
## TypeScript (Imperative) Patterns
### Basic Tween
```typescript
import { createTween } from 'vibegame/tweening';
// Single field
createTween(state, entity, 'transform.pos-x', {
from: 0,
to: 10,
duration: 2,
easing: 'sine-out'
});
```
### Shorthand Tweens
```typescript
// Position (creates 3 TweenValue entities)
createTween(state, entity, 'at', {
from: [0, 0, 0],
to: [10, 5, 0],
duration: 1.5,
easing: 'quad-out'
});
// Scale
createTween(state, entity, 'scale', {
from: [1, 1, 1],
to: [2, 2, 2],
duration: 0.5,
easing: 'back-out'
});
// Rotation (degrees, auto-detects body vs transform)
createTween(state, entity, 'rotation', {
from: [0, 0, 0],
to: [0, 180, 0],
duration: 2
});
```
### Triggering Named Sequences
```typescript
import { playSequence, resetSequence, stopSequence } from 'vibegame/tweening';
// Get sequence entity by name
const buttonPress = state.getEntityByName('button-press');
// Trigger sequence (reset first for replay)
resetSequence(state, buttonPress);
playSequence(state, buttonPress);
// Or stop mid-animation
stopSequence(state, buttonPress);
```
### Event-Driven Sequence Pattern
```typescript
// Define trigger component
const TriggerSequence = GAME.defineComponent({});
const triggerQuery = GAME.defineQuery([TriggerSequence, Sequence]);
// System processes triggers
const TriggerSequenceSystem: GAME.System = {
group: 'simulation',
update(state) {
for (const eid of triggerQuery(state.world)) {
resetSequence(state, eid);
playSequence(state, eid);
state.removeComponent(eid, TriggerSequence);
}
}
};
// Trigger from DOM event
document.getElementById('btn')?.addEventListener('click', () => {
const seq = state.getEntityByName('my-sequence');
if (seq !== null) state.addComponent(seq, TriggerSequence);
});
```
### Driver Pattern: One Value Drives Many Entities
A driver is a single tweened value that controls multiple entities via a system. This is useful for coordinated animations like breathing, pulsing, or wave effects.
```xml
```
```typescript
// System reads driver value, applies to all marked entities
const BreatheSystem: System = {
group: 'simulation',
update(state) {
const drivers = driverQuery(state.world);
if (drivers.length === 0) return;
const driverValue = BreatheDriver.value[drivers[0]];
const oscillation = Math.sin(state.time.elapsed * 2) * 0.2 * driverValue;
for (const eid of breatheQuery(state.world)) {
Transform.scaleX[eid] = 1 + oscillation;
Transform.scaleY[eid] = 1 + oscillation;
Transform.scaleZ[eid] = 1 + oscillation;
}
}
};
```
### Shakers: Layered Modifications via Tweening
Shakers enable multiple independent effects on the same property. Each shaker has an `intensity` that can be tweened, allowing effects to be faded in/out independently.
```xml
```
Key benefits:
- **Safe composition**: Shakers apply at draw time without modifying base values
- **Independent control**: Each shaker's intensity is separately tweened
- **Order guarantees**: Additive shakers apply first, then multiplicative
- **Alias resolution**: `shaker.intensity` resolves to `transform-shaker.intensity` when targeting transform properties
### Transform Shaker (TypeScript)
```typescript
import { createShaker, createTween } from 'vibegame/tweening';
// Auto-detects transform target, creates TransformShaker
const shakerId = createShaker(state, entity, 'transform.pos-y', {
value: 0.5,
intensity: 1,
mode: 'additive'
});
// Tween intensity to fade effect (use 'shaker.intensity' - resolves automatically)
createTween(state, shakerId, 'shaker.intensity', { from: 1, to: 0, duration: 0.5 });
```
### Ui
Web-native UI system using HTML/CSS overlays positioned over the 3D canvas. Includes GSAP for animations, ECS state synchronization, and external library support. This provides capabilities superior to most game engines' built-in UI systems.
### Components
#### UIManager
- element: HTMLElement - Root UI container
- state: State - ECS state reference for updates
- visible: ui8 (1) - UI visibility toggle
### Systems
#### UIUpdateSystem
- Group: simulation
- Updates UI elements from ECS component state
#### UIEventSystem
- Group: setup
- Handles UI event binding and canvas focus management
### Functions
#### createUIOverlay(canvas: HTMLCanvasElement): HTMLElement
Creates positioned UI overlay container
#### bindUIToState(uiManager: UIManager, state: State): void
Connects UI updates to ECS state changes
#### showFloatingText(x: number, y: number, text: string): void
Creates animated floating text at screen coordinates
### Patterns
#### Basic UI Setup
```html
```
#### ECS Integration
```typescript
const UISystem = {
update: (state) => {
// Update UI from game state components
const scoreEl = document.getElementById('score');
if (scoreEl) scoreEl.textContent = getScore(state);
}
};
```
#### GSAP Animations
```typescript
gsap.to("#currency", {
scale: 1.2,
duration: 0.2,
yoyo: true,
repeat: 1
});
```
#### Examples
## Examples
### Basic Game HUD
```html
```
### Animated Currency with GSAP
```javascript
import gsap from 'gsap';
class AnimatedCounter {
constructor(elementId) {
this.element = document.getElementById(elementId);
this.currentValue = 0;
this.displayValue = 0;
}
setValue(newValue) {
this.currentValue = newValue;
gsap.to(this, {
displayValue: newValue,
duration: 0.8,
ease: "power2.out",
onUpdate: () => {
this.element.textContent = Math.floor(this.displayValue);
}
});
}
}
// Usage in ECS system
const coinCounter = new AnimatedCounter('coins');
const UISystem = {
update: (state) => {
const coins = getCoinsFromState(state);
coinCounter.setValue(coins);
}
};
```
### Floating Damage Text
```javascript
function showDamageText(worldX, worldY, worldZ, damage) {
// Convert 3D world position to screen coordinates
const camera = getMainCamera(state);
const screenPos = worldToScreen(worldX, worldY, worldZ, camera);
const element = document.createElement('div');
element.textContent = `-${damage}`;
element.style.cssText = `
position: fixed;
left: ${screenPos.x}px;
top: ${screenPos.y}px;
color: #ff4444;
font-weight: bold;
font-size: 24px;
pointer-events: none;
z-index: 10000;
`;
document.body.appendChild(element);
gsap.timeline()
.to(element, {
y: screenPos.y - 100,
opacity: 0,
duration: 1.5,
ease: "power2.out"
})
.call(() => element.remove());
}
// Usage in collision system
const DamageSystem = {
update: (state) => {
// When player takes damage
const playerPos = getPlayerPosition(state);
showDamageText(playerPos.x, playerPos.y + 2, playerPos.z, 25);
}
};
```
### Menu System with State
```javascript
class GameMenu {
constructor() {
this.isOpen = false;
this.element = document.getElementById('main-menu');
}
toggle() {
this.isOpen = !this.isOpen;
if (this.isOpen) {
this.show();
} else {
this.hide();
}
}
show() {
this.element.style.display = 'block';
gsap.fromTo(this.element,
{ opacity: 0, scale: 0.8 },
{ opacity: 1, scale: 1, duration: 0.3, ease: "back.out(1.7)" }
);
}
hide() {
gsap.to(this.element, {
opacity: 0,
scale: 0.8,
duration: 0.2,
onComplete: () => {
this.element.style.display = 'none';
}
});
}
}
// Integration with input system
const menu = new GameMenu();
const MenuSystem = {
update: (state) => {
// Check for escape key press
if (GAME.consumeInput(state, 'escape')) {
menu.toggle();
}
}
};
```