AI Agent

Razorbill's AI agent translates natural language prompts into typed operations. It has access to all 25 operations and understands the full component system, enabling you to build scenes conversationally.

Using the AI Agent

Via CLI

./build/toolchain/cli/eng_cli agent ~/MyProject Main \
  --prompt "Create a forest scene with trees, a river, and a cabin"

Via Editor

The editor includes an AI chat panel where you can type prompts and see the operations the agent generates in real time.

What the Agent Can Do

The AI agent can execute any combination of typed operations:

• Create entities — primitives, lights, cameras, empty containers
• Build scenes — arrange objects, set up lighting, create environments
• Write scripts — generate C++ gameplay code with the ScriptContext API
• Set up physics — add rigidbodies, colliders, character controllers
• Create UI — canvases, text, buttons, sliders, progress bars
• Generate terrain — wilderness landscapes, caves, multi-chunk worlds
• Manage prefabs — create and instantiate reusable templates

Example Prompts

Scene Building

• "Create a cube at position 0,5,0 with a red PBR material"
• "Add outdoor sunny lighting to the scene"
• "Create a 3x3 grid of spheres spaced 2 units apart"
• "Build a simple room with floor, walls, and ceiling"

Scripting

• "Make the cube rotate around the Y axis"
• "Add a first-person controller to the Player entity"
• "Create a script that makes objects bounce up and down"
• "Write a script that fires projectiles when I click"

Physics

• "Add physics to the ball so it bounces when it falls"
• "Create a stack of crates that can be knocked over"
• "Add a character controller to the Player with double jump"

UI

• "Create a HUD with a health bar and score counter"
• "Add a pause menu with resume and quit buttons"
• "Create a settings panel with a volume slider"

World Generation

• "Generate a forest terrain with hills"
• "Create a cave system with crystal biome"
• "Build a 4x4 world with mixed biomes and water"

How It Works

1. Prompt — You describe what you want in natural language
2. Planning — The agent breaks your request into a sequence of operations
3. Validation — Each operation is validated before execution
4. Execution — Operations are applied as an atomic transaction
5. Diff — A structured diff shows exactly what changed

If any operation fails validation, the entire transaction is rolled back and the agent reports the error.

Safety Guarantees

The AI agent has the same safety guarantees as manual editing:

• Typed operations only — The agent cannot bypass the operation system or write files directly
• Validation — All operations are validated before applying
• Atomic transactions — Partial failures are rolled back completely
• Structured diffs — Every change is tracked and reversible
• Capability system — Controls which operations the agent can execute
• Rate limiting — Prevents expensive operations from running unchecked

Text-to-3D Asset Generation

Razorbill integrates with Hunyuan3D-2 for generating 3D assets from text descriptions. From the editor's asset generation dialog, you can:

1. Describe the asset you want in natural language
2. Preview generated variations with PBR textures
3. Import the selected model directly into your project as a game-ready GLB

Generated assets are fully integrated with the typed operations system — they get proper mesh GUIDs, material assignments, and collision shapes (via V-HACD convex decomposition).

In-Editor AI Chat

The editor includes a multi-turn AI chat panel:

• Real-time streaming — See tokens appear as the AI generates
• Cancel mid-generation — Stop the AI at any time
• Scene-aware context — The AI sees your current scene entities each turn
• Inline operation badges — Color-coded badges show each operation with expandable parameter views
• Accept/Reject controls — Review and approve operations inline
• Auto-compile with retry — When the AI writes scripts, compilation is automatic with up to 3 retry attempts on error
• Token budgeting — 180K token context window with sliding window pruning

Verbose Mode

Use --verbose to see the operations the agent generates:

./build/toolchain/cli/eng_cli agent ~/MyProject Main \
  --prompt "Create a spinning cube" --verbose

This shows:

• The operations planned by the agent
• Validation results for each operation
• The structured diff after execution
• Any scripts created or modified