better agents.md

agents.md

@@ -1,18 +1,18 @@
-VibeGame is a 3D game engine with declarative XML syntax and ECS architecture. This file provides essential context for AI agents working with the engine.
+# VibeGame Engine Context
 
-## Core Concepts
+You are a VibeGame specialist. VibeGame is a 3D game engine with declarative XML syntax and ECS architecture. Your role is to help users create games efficiently using VibeGame's declarative approach.
 
-**ECS Architecture**: Entity-Component-System pattern where entities are IDs, components are data containers, and systems contain logic.
+## Core Architecture
 
-**Declarative XML**: Game entities defined in HTML-like syntax within `<world>` tags.
-
-**Auto-Creation**: Engine automatically creates player, camera, and lighting if not explicitly defined.
+**ECS Pattern**: Entities (IDs) + Components (data) + Systems (logic)
+**Declarative XML**: Game entities defined in `<world>` tags
+**Auto-Creation**: Engine provides player, camera, lighting by default
 
 ## Essential Syntax
 
 ```xml
 <world canvas="#game-canvas" sky="#87ceeb">
-  <!-- Ground (REQUIRED to prevent player falling) -->
+  <!-- REQUIRED: Ground to prevent falling -->
   <static-part pos="0 -0.5 0" shape="box" size="20 1 20" color="#90ee90"></static-part>
 
   <!-- Physics objects -->
@@ -23,133 +23,66 @@ VibeGame is a 3D game engine with declarative XML syntax and ECS architecture. T
 </world>
 ```
 
-## Key Recipes
+## Key Recipes & Components
 
-- `<static-part>` - Immovable objects (grounds, walls, platforms)
-- `<dynamic-part>` - Gravity-affected objects (balls, crates, debris)
-- `<kinematic-part>` - Script-controlled physics (moving platforms, doors)
-- `<player>` - Player character (auto-created if missing)
-- `<camera>` - Orbital camera (auto-created if missing)
-- `<entity>` - Base entity with any components via attributes
+- `<static-part>` - Immovable (grounds, walls)
+- `<dynamic-part>` - Gravity-affected (balls, crates)
+- `<kinematic-part>` - Script-controlled (moving platforms)
+- `<player>`, `<camera>` - Auto-created if missing
+- `<entity>` - Base with custom components
 
-## Critical Physics Rule
+## Critical Rules
 
-⚠️ **Physics bodies override transform positions!** Always set position on the body, not the transform, for physics entities.
+⚠️ **Physics Override**: Body position overrides transform position. Always use `pos` on physics entities.
 
 ```xml
-<!-- ✅ BEST: Use recipe with pos shorthand -->
-<dynamic-part pos="0 5 0" shape="sphere" size="1"></dynamic-part>
+<!-- ✅ CORRECT -->
+<dynamic-part pos="0 5 0" shape="sphere"></dynamic-part>
 
-<!-- ❌ WRONG: Transform position ignored if body exists -->
+<!-- ❌ WRONG: Transform ignored -->
 <entity transform="pos: 0 5 0" body collider></entity>
 ```
 
-## Component System
-
-Components declared as bare attributes (defaults) or with values:
+## Component Syntax
 
 ```xml
-<!-- Bare attributes use defaults -->
+<!-- Bare attributes = defaults -->
 <entity transform body collider renderer></entity>
 
-<!-- Override specific properties -->
+<!-- Override properties -->
 <entity transform="pos: 0 5 0" body="type: dynamic; mass: 10" collider renderer></entity>
 ```
 
-Shorthands automatically expand to matching component properties:
-
-- `pos="x y z"` → applies to transform.pos* AND body.pos*
-- `color="#ff0000"` → applies to renderer.color
-- `size="2"` → broadcasts to sizeX, sizeY, sizeZ
-
-## TypeScript API
-
-```typescript
-import * as GAME from "vibegame";
-
-// Component definition
-const Health = GAME.defineComponent({
-  current: GAME.Types.f32,
-  max: GAME.Types.f32,
-});
-
-// System with query
-const healthQuery = GAME.defineQuery([Health]);
-const HealthSystem: GAME.System = {
-  update: (state) => {
-    const entities = healthQuery(state.world);
-    for (const entity of entities) {
-      Health.current[entity] -= 1 * state.time.deltaTime;
-    }
-  },
-};
-
-// Plugin registration
-GAME.withComponent("health", Health).withSystem(HealthSystem).run();
-```
-
-## Available Features
-
-✅ **Core Systems**: Physics (Rapier 3D), rendering (Three.js), input (keyboard/mouse/gamepad), tweening, transforms
-
-✅ **Game Elements**: Player controller, orbital camera, collision detection, respawn system, post-processing effects
-
-❌ **Not Built-In**: Audio, multiplayer, save/load, inventory, AI/pathfinding, particles, custom shaders
+**Shorthands**: `pos`, `color`, `size` auto-expand to matching component properties.
 
 ## Development Commands
 
-```bash
-# Project creation
-npm create vibegame@latest my-game
-cd my-game
-
-# Development
-bun dev              # Start dev server
-bun run build        # Production build
-bun run check        # TypeScript validation
-bun run lint --fix   # ESLint analysis
-bun test             # Run tests
-```
-
-## Getting More Information
-
-**Comprehensive Documentation**: Use Context7 to fetch detailed documentation with examples:
-
-```typescript
-// For AI agents with Context7 access:
-// Use mcp__context7__resolve-library-id to find "vibegame"
-// Then use mcp__context7__get-library-docs with the resolved ID
-// This provides the full 2000+ line documentation with detailed examples
-```
+- `bun dev` - Start development server
+- `bun run build` - Production build
+- `bun run check` - TypeScript validation
+- `bun test` - Run tests
 
-**Quick References**:
+## Features Available
 
-- Shapes: `box`, `sphere`, `cylinder`, `capsule`
-- Physics Types: `static` (fixed), `dynamic` (gravity), `kinematic` (scripted)
-- Easing: `linear`, `sine-in-out`, `quad-out`, `bounce-in`, etc.
-- Loop Modes: `once`, `loop`, `ping-pong`
+✅ Physics (Rapier), rendering (Three.js), input, tweening, player controller, orbital camera, collision detection, respawn, post-processing
 
-## Common Patterns
+❌ Audio, multiplayer, save/load, inventory, AI, particles, custom shaders
 
-**Basic Platformer**: Ground + static platforms + player (auto-created)
-**Physics Playground**: Ground + walls + dynamic objects with collision
-**Moving Platforms**: Kinematic bodies + position tweening
-**Collectibles**: Kinematic objects + rotation tweening + collision detection
+## Documentation Access
 
-## Best Practices for AI Development
+**For detailed information**: Use Context7 to fetch comprehensive docs:
+1. `mcp__context7__resolve-library-id` with "/dylanebert/vibegame"
+2. `mcp__context7__get-library-docs` with resolved ID
 
-1. **Always include ground** - Player falls without platforms
-2. **Use recipes over raw entities** - Cleaner and more reliable
-3. **Leverage auto-creation** - Engine handles player/camera/lighting defaults
-4. **Physics position priority** - Set positions on bodies, not transforms
-5. **Query Context7 for details** - This file is overview only, get specifics via Context7
-6. **Test incrementally** - Start simple, add complexity progressively
+**Quick Reference**: Shapes (`box`, `sphere`, `cylinder`, `capsule`), Physics (`static`, `dynamic`, `kinematic`), Easing functions, Loop modes (`once`, `loop`, `ping-pong`)
 
-## Architecture Notes
+## Best Practices
 
-- **Plugin System**: Bevy-inspired modular architecture
-- **Update Phases**: SetupBatch → FixedBatch → DrawBatch
-- **Context Management**: Use /clear frequently in Claude Code sessions
-- **Parallel Operations**: Invoke multiple tools simultaneously for efficiency
+1. Always include ground platforms
+2. Use recipes over raw entities
+3. Leverage auto-creation defaults
+4. Set positions on physics bodies, not transforms
+5. Query Context7 for detailed API references
+6. Test incrementally
 
-This context enables basic VibeGame development. For detailed API references, extensive examples, or advanced features, fetch comprehensive documentation via Context7.
+This provides foundational VibeGame knowledge. Use Context7 for comprehensive documentation and examples.