Spaces:

dylanebert
/

VibeGame

Running

VibeGame / llms.txt

dylanebert

improved prompting/UX

db9635c about 22 hours ago

61 kB

	# 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

	### 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
	<script src="https://cdn.jsdelivr.net/npm/vibegame@latest/dist/cdn/vibegame.standalone.iife.js"></script>

	<world canvas="#game-canvas" sky="#87ceeb">
	<!-- Ground (REQUIRED to prevent player falling) -->
	<static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>
	</world>

	<canvas id="game-canvas"></canvas>
	<script>
	GAME.run();
	</script>
	```

	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
	<world canvas="#game-canvas">
	<!-- 1. Static: Never moves (grounds, walls, platforms) -->
	<static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#808080"></static-part>

	<!-- 2. Dynamic: Falls with gravity (balls, crates, debris) -->
	<dynamic-part pos="0 5 0" shape="sphere" size="1" color="#ff0000"></dynamic-part>

	<!-- 3. Kinematic: Script-controlled movement (moving platforms, doors) -->
	<kinematic-part pos="5 2 0" shape="box" size="3 0.5 3" color="#0000ff">
	<!-- Animate the platform up and down -->
	<tween target="body.pos-y" from="2" to="5" duration="3" loop="ping-pong"></tween>
	</kinematic-part>
	</world>
	```

	## CRITICAL: Physics Position vs Transform Position

	<warning>
	⚠️ Physics bodies override transform positions!
	Always set position on the body, not the transform, for physics entities.
	</warning>

	```xml
	<!-- ✅ BEST: Use recipe with pos shorthand -->
	<dynamic-part pos="0 5 0" shape="sphere" size="1"></dynamic-part>

	<!-- ❌ WRONG: Transform position ignored if body exists -->
	<entity transform="pos: 0 5 0" body collider></entity> <!-- Falls to 0,0,0! -->

	<!-- ✅ CORRECT: Set body position explicitly (if using raw entity) -->
	<entity transform body="pos: 0 5 0" collider></entity>
	```

	## 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 - 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
	<world canvas="#game-canvas">
	<static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>

	<!-- Custom player spawn position and properties -->
	<player pos="0 10 0" speed="8" jump-height="3"></player>

	<!-- Custom camera settings -->
	<camera orbit-camera="distance: 10; target-pitch: 0.5"></camera>

	<!-- Custom lighting (or use <light> for both ambient + directional) -->
	<ambient-light sky-color="#ff6b6b" ground-color="#4ecdc4" intensity="0.8"></ambient-light>
	<directional-light color="#ffffff" intensity="0.5" direction="-1 -2 -1"></directional-light>
	</world>
	```

	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

	```xml
	<!-- Bloom effect for glow -->
	<camera bloom="intensity: 2; luminance-threshold: 0.8"></camera>

	<!-- Retro dithering (reduces color palette) -->
	<camera dithering="color-bits: 3; scale: 2; noise: 1"></camera>

	<!-- Tonemapping for HDR-like visuals -->
	<camera tonemapping="mode: aces-filmic"></camera>

	<!-- Combined cinematic style -->
	<camera bloom="intensity: 1.5" tonemapping="mode: aces-filmic"></camera>
	```

	## Common Game Patterns

	### Basic Platformer
	```xml
	<world canvas="#game-canvas">
	<!-- Ground -->
	<static-part pos="0 -0.5 0" shape="box" size="50 1 50" color="#90ee90"></static-part>

	<!-- Platforms at different heights -->
	<static-part pos="-5 2 0" shape="box" size="3 0.5 3" color="#808080"></static-part>
	<static-part pos="0 4 0" shape="box" size="3 0.5 3" color="#808080"></static-part>
	<static-part pos="5 6 0" shape="box" size="3 0.5 3" color="#808080"></static-part>

	<!-- Moving platform -->
	<kinematic-part pos="0 3 5" shape="box" size="4 0.5 4" color="#4169e1">
	<tween target="body.pos-x" from="-10" to="10" duration="5" loop="ping-pong"></tween>
	</kinematic-part>

	<!-- Goal area -->
	<static-part pos="10 8 0" shape="box" size="5 0.5 5" color="#ffd700"></static-part>
	</world>
	```

	### Collectible Coins (Collision-based)
	```xml
	<world canvas="#game-canvas">
	<static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>

	<!-- Spinning coins -->
	<kinematic-part pos="2 1 0" shape="cylinder" size="0.5 0.1 0.5" color="#ffd700">
	<tween target="body.euler-y" from="0" to="360" duration="2" loop="loop"></tween>
	</kinematic-part>

	<kinematic-part pos="-2 1 0" shape="cylinder" size="0.5 0.1 0.5" color="#ffd700">
	<tween target="body.euler-y" from="0" to="360" duration="2" loop="loop"></tween>
	</kinematic-part>
	</world>
	```

	### Physics Playground
	```xml
	<world canvas="#game-canvas">
	<!-- Ground -->
	<static-part pos="0 -0.5 0" shape="box" size="30 1 30" color="#90ee90"></static-part>

	<!-- Walls -->
	<static-part pos="15 5 0" shape="box" size="1 10 30" color="#808080"></static-part>
	<static-part pos="-15 5 0" shape="box" size="1 10 30" color="#808080"></static-part>
	<static-part pos="0 5 15" shape="box" size="30 10 1" color="#808080"></static-part>
	<static-part pos="0 5 -15" shape="box" size="30 10 1" color="#808080"></static-part>

	<!-- Spawn balls at different positions -->
	<dynamic-part pos="-5 10 0" shape="sphere" size="1" color="#ff0000"></dynamic-part>
	<dynamic-part pos="0 12 0" shape="sphere" size="1.5" color="#00ff00"></dynamic-part>
	<dynamic-part pos="5 8 0" shape="sphere" size="0.8" color="#0000ff"></dynamic-part>

	<!-- Bouncy ball (high restitution) -->
	<dynamic-part pos="0 15 5" shape="sphere" size="1" color="#ff00ff"
	collider="restitution: 0.9"></dynamic-part>
	</world>
	```

	## Recipe Reference

	\| Recipe \| Purpose \| Key Attributes \| Common Use \|
	\|--------\|---------\|---------------\|------------\|
	\| `<static-part>` \| Immovable objects \| `pos`, `shape`, `size`, `color` \| Grounds, walls, platforms \|
	\| `<dynamic-part>` \| Gravity-affected objects \| `pos`, `shape`, `size`, `color`, `mass` \| Balls, crates, falling objects \|
	\| `<kinematic-part>` \| Script-controlled physics \| `pos`, `shape`, `size`, `color` \| Moving platforms, doors \|
	\| `<player>` \| Player character \| `pos`, `speed`, `jump-height` \| Main character (auto-created) \|
	\| `<entity>` \| Base entity \| Any components via attributes \| Custom entities \|

	### Shape Options
	- `box` - Rectangular solid (default)
	- `sphere` - Ball shape
	- `cylinder` - Cylindrical shape
	- `capsule` - Pill shape (good for characters)

	### Size Attribute
	- Box: `size="width height depth"` or `size="2 1 2"`
	- Sphere: `size="diameter"` or `size="1"`
	- Cylinder: `size="diameter height"` or `size="1 2"`
	- Broadcast: `size="2"` becomes `size="2 2 2"`

	## How Recipes and Shorthands Work

	### Everything is an Entity
	Every XML tag creates an entity. Recipes like `<static-part>` are just shortcuts for `<entity>` with preset components.

	```xml
	<!-- These are equivalent: -->
	<static-part pos="0 0 0" color="#ff0000"></static-part>

	<entity
	transform
	body="type: fixed"
	collider
	renderer="color: 0xff0000"
	pos="0 0 0"></entity>
	```

	### Component Attributes
	Components are declared using bare attributes (no value means "use defaults"):

	```xml
	<!-- Bare attributes declare components with default values -->
	<entity transform body collider renderer></entity>

	<!-- Add properties to override defaults -->
	<entity transform="pos-x: 5; pos-y: 2; pos-z: -3; scale: 2"></entity>

	<!-- Mix bare and valued attributes -->
	<entity transform="pos: 0 5 0" body="type: dynamic; mass: 10" collider renderer></entity>

	<!-- Property groups -->
	<entity transform="pos: 5 2 -3; scale: 2 2 2"></entity>
	```

	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
	<!-- "pos" shorthand applies to components with posX, posY, posZ -->
	<entity transform body pos="0 5 0"></entity>
	<!-- Both transform AND body get pos values -->

	<!-- "color" shorthand applies to renderer.color -->
	<entity renderer color="#ff0000"></entity>

	<!-- "size" shorthand (broadcasts single value) -->
	<entity collider size="2"></entity>
	<!-- Expands to: sizeX: 2, sizeY: 2, sizeZ: 2 -->

	<!-- Multiple shorthands together -->
	<entity transform body collider renderer pos="0 5 0" size="1" color="#ff0000"></entity>
	```

	### Recipe Internals
	Recipes are registered component bundles with defaults:

	```xml
	<!-- What <dynamic-part> actually is: -->
	<entity
	transform
	body="type: dynamic" <!-- Override -->
	collider
	renderer
	respawn
	></entity>

	<!-- So this: -->
	<dynamic-part pos="0 5 0" color="#ff0000"></dynamic-part>

	<!-- Is really: -->
	<entity
	transform="pos: 0 5 0"
	body="type: dynamic; pos: 0 5 0" <!-- pos applies to body too! -->
	collider
	renderer="color: 0xff0000"
	respawn
	></entity>
	```

	### Common Pitfall: Component Requirements
	```xml
	<!-- ❌ BAD: Missing required components -->
	<entity pos="0 5 0"></entity> <!-- No transform component! -->

	<!-- ✅ GOOD: Explicit components -->
	<entity transform="pos: 0 5 0"></entity>

	<!-- ✅ BEST: Use recipe with built-in components -->
	<static-part pos="0 5 0"></static-part>
	```

	### Best Practices Summary
	1. Use recipes (`<static-part>`, `<dynamic-part>`, etc.) instead of raw `<entity>` 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., `<dynamic-part health="max: 100">`

	## 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
	- 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 `<world>` 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 `<static-part>`

	## 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
	GAME.Transform.posX[entity] = 10;
	GAME.Transform.posY[entity] = 5;

	// Read values
	const x = GAME.Transform.posX[entity];
	const health = GAME.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
	<!-- BAD: No ground, player falls forever -->
	<world canvas="#game-canvas">
	<dynamic-part pos="0 5 0" shape="sphere"></dynamic-part>
	</world>
	```

	### ❌ Setting Transform Position on Physics Objects
	```xml
	<!-- BAD: Transform position ignored -->
	<entity transform="pos: 0 5 0" body collider></entity>

	<!-- GOOD: Set body position (raw entity) -->
	<entity transform body="pos: 0 5 0" collider></entity>

	<!-- BEST: Use recipes with pos shorthand -->
	<dynamic-part pos="0 5 0" shape="sphere"></dynamic-part>
	```

	### ❌ Missing World Tag
	```xml
	<!-- BAD: Entities outside world tag -->
	<static-part pos="0 0 0" shape="box"></static-part>

	<!-- GOOD: Everything inside world -->
	<world canvas="#game-canvas">
	<static-part pos="0 0 0" shape="box"></static-part>
	</world>
	```

	### ❌ Wrong Physics Type
	```xml
	<!-- BAD: Dynamic platform (falls with gravity) -->
	<dynamic-part pos="0 3 0" shape="box">
	<tween target="body.pos-x" from="-5" to="5"></tween>
	</dynamic-part>

	<!-- GOOD: Kinematic for controlled movement -->
	<kinematic-part pos="0 3 0" shape="box">
	<tween target="body.pos-x" from="-5" to="5"></tween>
	</kinematic-part>
	```

	## 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
	<world canvas="#game-canvas">
	<!-- Add health to a dynamic entity (best practice: use recipes) -->
	<dynamic-part pos="0 2 0" shape="sphere" color="#ff0000"
	health="current: 50; max: 100"></dynamic-part>
	</world>
	```

	## 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';

	// Start with no plugins
	GAME
	.withoutDefaultPlugins()
	.withPlugin(TransformsPlugin) // Just transforms
	.withPlugin(RenderingPlugin) // Add rendering
	.withPlugin(PhysicsPlugin) // Add physics
	.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 - Third-person camera
	- PlayerPlugin - Character controller
	- TweenPlugin - Animation system
	- RespawnPlugin - Fall detection and reset
	- StartupPlugin - Auto-create player/camera/lights

	## 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';

	// Add animated character to a player entity
	const player = state.createEntity();
	state.addComponent(player, GAME.AnimatedCharacter);
	state.addComponent(player, GAME.CharacterController);
	state.addComponent(player, GAME.Transform);

	// The AnimatedCharacterInitializationSystem will automatically
	// create body parts in the next setup phase
	```

	### Accessing Animation State

	```typescript
	import * as GAME from 'vibegame';

	const characterQuery = GAME.defineQuery([GAME.AnimatedCharacter]);
	const MySystem: GAME.System = {
	update: (state) => {
	const characters = characterQuery(state.world);
	for (const entity of characters) {
	const animState = GAME.AnimatedCharacter.animationState[entity];
	if (animState === 2) { // JUMPING
	console.log('Character is jumping!');
	}
	}
	}
	};
	```

	### XML Declaration

	```xml
	<!-- Player entity with animated character -->
	<entity
	animated-character
	character-controller
	transform="pos: 0 2 0"
	/>
	```

	### 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';

	GAME
	.withPlugin(GAME.InputPlugin)
	.run();
	```

	### Reading Input in a Custom System

	```typescript
	import * as GAME from 'vibegame';

	const playerQuery = GAME.defineQuery([GAME.Player, GAME.InputState]);
	const PlayerControlSystem: GAME.System = {
	update: (state) => {
	const players = playerQuery(state.world);

	for (const player of players) {
	// Read movement axes
	const moveX = GAME.InputState.moveX[player];
	const moveY = GAME.InputState.moveY[player];

	// Check for jump
	if (GAME.InputState.jump[player]) {
	// Jump is available this frame
	}

	// Check mouse buttons
	if (GAME.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);
	```

	### Orbit Camera

	Orbital camera controller for third-person views and smooth target following.

	### Components

	#### OrbitCamera
	- target: eid (0) - Target entity ID
	- current-yaw: f32 (π) - Current horizontal angle
	- current-pitch: f32 (π/6) - Current vertical angle
	- current-distance: f32 (4) - Current distance
	- target-yaw: f32 (π) - 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)

	### Systems

	#### OrbitCameraSystem
	- Group: draw
	- Updates camera position and rotation around target

	### Recipes

	#### camera
	- Creates orbital camera with default settings
	- Components: orbit-camera, transform, world-transform, main-camera

	#### Examples

	## Examples

	### Basic Camera

	```xml
	<!-- Create default orbital camera -->
	<camera />
	```

	### Camera Following Player

	```xml
	<world>
	<!-- Player entity -->
	<player id="player" pos="0 0 0" />

	<!-- Camera following player -->
	<camera
	target="#player"
	target-distance="10"
	min-distance="5"
	max-distance="20"
	offset-y="2"
	/>
	</world>
	```

	### Custom Orbit Settings

	```xml
	<entity
	orbit-camera="
	target: #boss;
	target-distance: 15;
	target-yaw: 0;
	target-pitch: 0.5;
	smoothness: 0.2;
	offset-y: 3
	"
	transform
	main-camera
	/>
	```

	### Programmatic Usage

	```typescript
	import * as GAME from 'vibegame';

	const cameraQuery = GAME.defineQuery([GAME.OrbitCamera]);
	const CameraControlSystem = {
	update: (state) => {
	const cameras = cameraQuery(state.world);

	for (const camera of cameras) {
	// Rotate camera on input
	if (state.input.mouse.deltaX) {
	GAME.OrbitCamera.targetYaw[camera] += state.input.mouse.deltaX * 0.01;
	}

	// Zoom on scroll
	if (state.input.mouse.wheel) {
	GAME.OrbitCamera.targetDistance[camera] = Math.max(
	GAME.OrbitCamera.minDistance[camera],
	Math.min(
	GAME.OrbitCamera.maxDistance[camera],
	GAME.OrbitCamera.targetDistance[camera] - state.input.mouse.wheel * 0.5
	)
	);
	}
	}
	}
	};
	```

	### Dynamic Target Switching

	```typescript
	import * as GAME from 'vibegame';

	// Switch camera target
	const switchTarget = (state, cameraEntity, newTargetEntity) => {
	GAME.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
	- Capsule = 2

	### 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
	- lastPosX, lastPosY, lastPosZ: 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
	- platformDeltaX, platformDeltaY, platformDeltaZ: f32

	#### 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)

	#### 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
	- PlatformDeltaSystem - Tracks platform position changes
	- CharacterMovementSystem - Character controller movement with platform sticking
	- 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<void>
	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
	<static-part
	pos="0 -0.5 0"
	shape="box"
	size="20 1 20"
	color="#90ee90"
	/>
	```

	##### Dynamic Ball
	```xml
	<dynamic-part
	pos="0 5 0"
	shape="sphere"
	radius="0.5"
	color="#ff0000"
	mass="2"
	restitution="0.8"
	/>
	```

	##### Moving Platform
	```xml
	<kinematic-part
	pos="0 2 0"
	shape="box"
	size="3 0.2 3"
	color="#4169e1"
	>
	<!-- Add movement with tweening -->
	<tween
	target="body.pos-y"
	from="2"
	to="5"
	duration="3"
	ease="sine-in-out"
	loop="ping-pong"
	/>
	</kinematic-part>
	```

	##### Character with Controller
	```xml
	<entity
	pos="0 1 0"
	body="type: kinematic-position"
	collider="shape: capsule; height: 1.8; radius: 0.4"
	character-controller
	character-movement
	transform
	renderer
	/>
	```

	#### JavaScript API

	##### Create Physics Entity
	```typescript
	import * as GAME from 'vibegame';

	// Create a dynamic physics box
	const entity = state.createEntity();

	state.addComponent(entity, GAME.Body, {
	type: GAME.BodyType.Dynamic,
	mass: 5,
	posX: 0, posY: 10, posZ: 0
	});

	state.addComponent(entity, GAME.Collider, {
	shape: GAME.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';

	// Dynamic bodies - Use forces/impulses for movement
	if (GAME.Body.type[entity] === GAME.BodyType.Dynamic) {
	// Apply force for gradual acceleration
	state.addComponent(entity, GAME.ApplyForce, { x: 10, y: 0, z: 0 });

	// Apply impulse for instant velocity change
	state.addComponent(entity, GAME.ApplyImpulse, { x: 0, y: 50, z: 0 });

	// Direct position setting only for teleportation
	GAME.Body.posX[entity] = 10; // Teleport - use sparingly
	}

	// Kinematic bodies - Direct control via movement components
	if (GAME.Body.type[entity] === GAME.BodyType.KinematicPositionBased) {
	state.addComponent(entity, GAME.KinematicMove, { x: 5, y: 2, z: 0 });
	}

	if (GAME.Body.type[entity] === GAME.BodyType.KinematicVelocityBased) {
	state.addComponent(entity, GAME.SetLinearVelocity, { x: 3, y: 0, z: 0 });
	}

	// Never modify Transform directly for physics entities
	// GAME.Transform.posX[entity] = 10; // ❌ Will be overwritten by Body
	```

	##### Apply Forces
	```typescript
	import * as GAME from 'vibegame';

	// Apply upward impulse (jump)
	state.addComponent(entity, GAME.ApplyImpulse, {
	x: 0, y: 50, z: 0
	});

	// Apply continuous force
	state.addComponent(entity, GAME.ApplyForce, {
	x: 10, y: 0, z: 0
	});

	// Set velocity directly
	state.addComponent(entity, GAME.SetLinearVelocity, {
	x: 0, y: 5, z: 0
	});
	```

	##### Handle Collisions
	```typescript
	import * as GAME from 'vibegame';

	const touchedQuery = GAME.defineQuery([GAME.TouchedEvent]);
	const CollisionSystem: GAME.System = {
	update: (state) => {
	// Query entities with collision events
	for (const entity of touchedQuery(state.world)) {
	const otherEntity = GAME.TouchedEvent.other[entity];
	console.log(`Entity ${entity} collided with ${otherEntity}`);

	// React to collision
	state.addComponent(entity, GAME.ApplyImpulse, {
	x: 0, y: 10, z: 0
	});
	}
	}
	};
	```

	##### Character Movement
	```typescript
	import * as GAME from 'vibegame';

	const PlayerMovementSystem: GAME.System = {
	update: (state) => {
	const movementQuery = GAME.defineQuery([GAME.CharacterMovement, GAME.CharacterController]);
	for (const entity of movementQuery(state.world)) {
	// Set desired movement based on input
	GAME.CharacterMovement.desiredVelX[entity] = input.x * 5;
	GAME.CharacterMovement.desiredVelZ[entity] = input.z * 5;

	// Jump if grounded
	if (GAME.CharacterController.grounded[entity] && input.jump) {
	GAME.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)
	- cameraSensitivity: f32 (0.007)
	- cameraZoomSensitivity: f32 (1.5)
	- cameraEntity: eid (0)
	- inheritedVelX: f32 (0) - Horizontal momentum inherited from platform
	- inheritedVelZ: f32 (0) - Horizontal momentum inherited from platform

	### Systems

	#### PlayerMovementSystem
	- Group: fixed
	- Handles movement, rotation, jumping with platform momentum preservation

	#### PlayerGroundedSystem
	- Group: fixed
	- Tracks grounded state, jump availability, and clears inherited momentum on landing

	#### PlayerCameraLinkingSystem
	- Group: simulation
	- Links player to orbit camera

	#### PlayerCameraControlSystem
	- Group: simulation
	- Camera control via mouse input

	### 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

	#### handleJump(entity, jumpPressed, currentTime): number
	Processes jump with buffering

	#### updateRotation(entity, inputVector, deltaTime, rotationData): Quaternion
	Smooth rotation towards movement

	#### Examples

	## Examples

	### Basic Player Usage (XML)

	```xml
	<world>
	<!-- Player auto-created if not specified -->
	<player pos="0 2 0" speed="6" jump-height="3" />
	</world>
	```

	### Custom Player Configuration (XML)

	```xml
	<world>
	<player
	pos="5 1 -10"
	speed="8"
	jump-height="4"
	rotation-speed="15"
	camera-sensitivity="0.005"
	/>
	</world>
	```

	### 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) => {
	// Create player entity
	const player = state.createEntity();

	// Add player recipe components
	state.addComponent(player, GAME.Player, {
	speed: 7,
	jumpHeight: 3.5,
	cameraSensitivity: 0.01
	});

	// Add required components
	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:
	- Right-click + drag - Rotate camera
	- Scroll wheel - Zoom in/out

	### Plugin Registration

	```typescript
	import * as GAME from 'vibegame';

	GAME
	.withPlugin(GAME.PlayerPlugin) // Included in defaults
	.run();
	```

	### Rendering

	Three.js rendering pipeline with meshes, lights, cameras, and post-processing effects.

	### Components

	#### Renderer
	- shape: ui8 - 0=box, 1=sphere, 2=cylinder, 3=plane
	- sizeX, sizeY, sizeZ: f32 (1)
	- color: ui32 (0xffffff)
	- visible: ui8 (1)

	#### RenderContext
	- clearColor: ui32 (0x000000)
	- hasCanvas: ui8

	#### MainCamera
	Tag component (no properties)

	#### Ambient
	- skyColor: ui32 (0x87ceeb)
	- groundColor: ui32 (0x4a4a4a)
	- intensity: f32 (0.6)

	#### Directional
	- color: ui32 (0xffffff)
	- intensity: f32 (1)
	- castShadow: ui8 (1)
	- shadowMapSize: ui32 (4096)
	- directionX: f32 (-1)
	- directionY: f32 (2)
	- directionZ: f32 (-1)
	- distance: f32 (30)

	#### Bloom
	- intensity: f32 (1.0) - Bloom intensity
	- luminanceThreshold: f32 (1.0) - Luminance threshold for bloom
	- luminanceSmoothing: f32 (0.03) - Smoothness of luminance threshold
	- 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

	### Systems

	#### MeshInstanceSystem
	- Group: draw
	- Synchronizes transforms with Three.js meshes

	#### LightSyncSystem
	- Group: draw
	- Updates Three.js lights

	#### CameraSyncSystem
	- Group: draw
	- Updates Three.js camera and manages post-processing effects

	#### WebGLRenderSystem
	- Group: draw (last)
	- Renders scene through EffectComposer

	### Functions

	#### setCanvasElement(entity, canvas): void
	Associates canvas with RenderContext

	### Recipes

	- ambient-light - Ambient hemisphere lighting
	- directional-light - Directional light with shadows
	- light - Both ambient and directional

	#### Examples

	## Examples

	### Basic Rendering Setup

	```xml
	<!-- Declarative scene with lighting and rendered objects -->
	<world canvas="#game-canvas" sky="#87ceeb">
	<!-- Default lighting -->
	<light></light>

	<!-- Rendered box -->
	<entity
	transform
	renderer="shape: box; color: 0xff0000; size-x: 2"
	pos="0 1 0"
	/>

	<!-- Rendered sphere -->
	<entity
	transform
	renderer="shape: sphere; color: 0x00ff00"
	pos="3 1 0"
	/>
	</world>
	```

	### Custom Lighting

	```xml
	<!-- Separate ambient and directional lights -->
	<ambient-light
	sky-color="#ffd4a3"
	ground-color="#808080"
	intensity="0.4"
	/>

	<directional-light
	color="#ffffff"
	intensity="1.5"
	direction-x="-1"
	direction-y="3"
	direction-z="-0.5"
	cast-shadow="1"
	shadow-map-size="2048"
	/>
	```

	### 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,
	cylinder: 2,
	plane: 3
	};

	// Use in XML
	<entity renderer="shape: sphere"></entity>

	// Or with enum names
	<entity renderer="shape: 1"></entity>
	```

	### 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
	<entity renderer="visible: 0"></entity> <!-- Initially hidden -->
	```

	### Post-Processing Effects

	```xml
	<!-- Camera with bloom effect (using defaults) -->
	<camera bloom></camera>

	<!-- Camera with custom bloom settings -->
	<camera bloom="intensity: 2; luminance-threshold: 0.8; luminance-smoothing: 0.05"></camera>

	<!-- Camera with mipmap blur settings -->
	<camera bloom="mipmap-blur: 1; radius: 0.9; levels: 10"></camera>

	<!-- Camera without effects (still uses composer internally) -->
	<camera></camera>

	<!-- Camera with retro dithering effect -->
	<camera dithering="color-bits: 3; intensity: 0.8; scale: 2"></camera>

	<!-- Combined bloom and dithering for retro aesthetic -->
	<camera bloom="intensity: 1.5" dithering="color-bits: 2; grayscale: 1; scale: 3"></camera>

	<!-- Subtle dithering for vintage look -->
	<camera dithering="color-bits: 5; intensity: 0.5; scale: 1"></camera>

	<!-- Coarse pixel-art style dithering -->
	<camera dithering="color-bits: 2; scale: 4; intensity: 1"></camera>
	```

	### 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 `<player>` recipe automatically includes respawn:

	```xml
	<world>
	<!-- Player spawns at 0,5,0 and respawns there if falling -->
	<player pos="0 5 0"></player>
	</world>
	```

	### Manual Respawn Component

	```xml
	<entity transform body collider respawn="pos: 0 10 -5">
	<!-- Entity respawns at 0,10,-5 when falling below Y=-100 -->
	</entity>
	```

	### 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
	<!-- Position sets both transform and respawn -->
	<player pos="5 3 -2" euler="0 90 0"></player>
	```

	### 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 main camera if none exists

	#### 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
	<world>
	<!-- Creating your own player prevents auto-creation -->
	<player pos="10 2 -5" speed="12" />

	<!-- Creating custom lighting prevents default lights -->
	<entity ambient="sky-color: 0xff0000" directional />
	</world>
	```

	### 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
	```

	### 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
	<!-- Position only -->
	<entity transform="pos: 0 5 -3"></entity>

	<!-- Euler rotation (degrees) -->
	<entity transform="euler: 0 45 0"></entity>

	<!-- Scale (single value applies to all axes) -->
	<entity transform="scale: 2"></entity>

	<!-- Combined transform -->
	<entity transform="pos: 0 5 0; euler: 0 45 0; scale: 1.5"></entity>
	```

	#### 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
	<!-- Parent at origin -->
	<entity transform="pos: 0 0 0">
	<!-- Children positioned relative to parent -->
	<entity transform="pos: 2 0 0"></entity>
	<entity transform="pos: -2 0 0"></entity>
	</entity>

	<!-- Rotating parent affects all children -->
	<entity transform="euler: 0 45 0">
	<entity id="arm" transform="pos: 0 2 0">
	<entity id="hand" transform="pos: 0 2 0"></entity>
	</entity>
	</entity>
	```

	#### 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 and loop modes. Kinematic velocity bodies use velocity-based tweening for smooth physics-correct movement.

	### Components

	#### Tween
	- duration: f32 (1) - Seconds
	- elapsed: f32
	- easingIndex: ui8
	- loopMode: ui8 - 0=Once, 1=Loop, 2=PingPong

	#### TweenValue
	- source: ui32 - Tween entity
	- target: ui32 - Target entity
	- componentId: ui32
	- fieldIndex: ui32
	- from: f32
	- to: f32
	- value: f32 - Current value

	#### KinematicTween
	- tweenEntity: ui32 - Associated tween entity
	- targetEntity: ui32 - Kinematic body entity
	- axis: ui8 - 0=X, 1=Y, 2=Z
	- from: f32 - Start position
	- to: f32 - End position
	- lastPosition: f32
	- targetPosition: f32

	### Systems

	#### KinematicTweenSystem
	- Group: fixed
	- Converts position tweens to velocity for kinematic bodies

	#### TweenSystem
	- Group: simulation
	- Interpolates values with easing and auto-cleanup

	### Functions

	#### createTween(state, entity, target, options): number \| null
	Animates component property

	### Easing Functions

	- linear
	- sine-in, sine-out, sine-in-out
	- quad-in, quad-out, quad-in-out
	- cubic-in, cubic-out, cubic-in-out
	- quart-in, quart-out, quart-in-out
	- expo-in, expo-out, expo-in-out
	- circ-in, circ-out, circ-in-out
	- back-in, back-out, back-in-out
	- elastic-in, elastic-out, elastic-in-out
	- bounce-in, bounce-out, bounce-in-out

	### Loop Modes

	- once - Play once and destroy
	- loop - Repeat indefinitely
	- ping-pong - Alternate directions

	### Shorthand Targets

	- rotation - body.eulerX/Y/Z
	- at - body.posX/Y/Z
	- scale - transform.scaleX/Y/Z

	#### Examples

	## Examples

	### Basic XML Tween

	```xml
	<!-- Animate Y position from 5 to 10 over 2 seconds -->
	<kinematic-part pos="0 5 -5">
	<tween
	target="body.pos-y"
	from="5"
	to="10"
	duration="2"
	ease="sine-in-out"
	loop="ping-pong"
	/>
	</kinematic-part>
	```

	### Multiple Properties

	```xml
	<!-- Animate rotation on all axes -->
	<entity transform renderer>
	<tween
	target="rotation"
	to="0 360 0"
	duration="4"
	loop="loop"
	/>
	</entity>
	```

	### Body Physics Properties

	```xml
	<!-- Animate physics body velocity -->
	<dynamic-part pos="0 10 0">
	<tween
	target="body.velocity-x"
	from="0"
	to="10"
	duration="1"
	ease="quad-out"
	/>
	</tween>
	```

	### Programmatic Usage

	```typescript
	import * as GAME from 'vibegame';

	// In a system
	const MySystem = {
	setup: (state) => {
	const entity = state.createEntity();
	state.addComponent(entity, GAME.Transform);

	// Create tween programmatically
	GAME.createTween(state, entity, 'body.pos-y', {
	from: 0,
	to: 10,
	duration: 2,
	easing: 'bounce-out',
	loop: 'once'
	});
	}
	};
	```

	### Complex Animation Sequence

	```xml
	<!-- Platform with multiple animated properties -->
	<kinematic-part pos="0 0 0" color="#ff0000">
	<!-- Position animation -->
	<tween target="body.pos-x" from="-5" to="5" duration="3" loop="ping-pong"></tween>
	<!-- Rotation animation -->
	<tween target="body.euler-y" to="360" duration="10" loop="loop"></tween>
	<!-- Scale pulse -->
	<tween target="transform.scale-x" from="1" to="1.5" duration="1" ease="sine-in-out" loop="ping-pong"></tween>
	<tween target="transform.scale-z" from="1" to="1.5" duration="1" ease="sine-in-out" loop="ping-pong"></tween>
	</kinematic-part>
	```

	### 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
	<div id="game-ui">
	<div class="hud">
	<span id="score">0</span>
	<span id="health">100</span>
	</div>
	</div>
	```

	#### 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
	<!doctype html>
	<html>
	<head>
	<style>
	body { margin: 0; font-family: Arial; }
	#game-ui {
	position: fixed;
	top: 0;
	left: 0;
	right: 0;
	bottom: 0;
	pointer-events: none;
	z-index: 1000;
	}
	.hud {
	position: absolute;
	top: 20px;
	left: 20px;
	background: rgba(0,0,0,0.7);
	padding: 15px;
	border-radius: 8px;
	color: white;
	pointer-events: auto;
	}
	</style>
	</head>
	<body>
	<world canvas="#game-canvas">
	<static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>
	</world>

	<canvas id="game-canvas"></canvas>

	<div id="game-ui">
	<div class="hud">
	<div>Score: <span id="score">0</span></div>
	<div>Coins: <span id="coins">0</span></div>
	</div>
	</div>

	<script type="module">
	import * as GAME from 'vibegame';

	const GameState = GAME.defineComponent({
	score: GAME.Types.ui32,
	coins: GAME.Types.ui32
	});

	const UISystem = {
	update: (state) => {
	const query = GAME.defineQuery([GameState]);
	const entities = query(state.world);

	if (entities.length > 0) {
	const entity = entities[0];
	document.getElementById('score').textContent = GameState.score[entity];
	document.getElementById('coins').textContent = GameState.coins[entity];
	}
	}
	};

	GAME.withPlugin({
	components: { GameState },
	systems: [UISystem]
	}).run();
	</script>
	</body>
	</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();
	}
	}
	};
	```