VibeTiles

AI-Native Tile Management System for Bevy Engine

VibeTiles is a data-driven tile system that combines declarative design with AI agent collaboration. Through the Model Context Protocol (MCP), AI agents can design tilesets and maps, while the Bevy engine automatically interprets them and injects physics and logic.

🎨 Core Concepts

Blueprint (Tileset Definition)

A Blueprint is a design document for a tileset - it describes what tiles exist and their properties:

• Defines the structure of a tileset image (PNG)
• Maps grid positions to tile IDs (e.g., position (0,0) = "floor_stone", (1,0) = "wall_n")
• Specifies gameplay properties for each tile (collision, y-sorting, lighting, etc.)
• Used by AI/artists to know what to draw in each cell of the tileset image

Map (Game Level Layout)

A Map uses tiles from blueprints to create game levels:

• References tiles by their IDs from one or more blueprints
• Arranges tiles in layers to form a playable level
• Supports multiple layers for ground, walls, decorations, etc.
• Defines the actual game world layout

Key distinction: Blueprint = "What tiles exist?" | Map = "Where do tiles go?"

🎯 Vision

Enable AI agents to architect game worlds by providing them with:

• Declarative blueprints (JSON-based tileset definitions)
• Declarative maps (JSON-based level layouts)
• Structured configuration (TOML-based project settings)
• MCP tool interface (File I/O, validation, generation)

Meanwhile, Bevy developers get:

• Hot-reloadable tileset and map assets
• Automatic component injection (colliders, y-sorting, lighting)
• Type-safe, schema-validated workflows
• Seamless integration with existing Bevy ECS patterns

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    AI Agent (Zed/MCP)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ AGENTS.md    │  │ vibe.toml    │  │ *.blueprint  │  │
│  │ (prompts)    │  │ (config)     │  │ (tilesets)   │  │
│  └──────────────┘  └──────────────┘  └──────┬───────┘  │
│                                              │          │
│                                     ┌────────▼───────┐  │
│                                     │ *.map.json     │  │
│                                     │ (levels)       │  │
│                                     └────────────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │ MCP Protocol
                         ▼
              ┌──────────────────────┐
              │ vibe_tiles_mcp       │
              │ (stdio server)       │
              └──────────────────────┘
                         │
                         │ reads/writes
                         ▼
              ┌──────────────────────────────┐
              │ Project Files                │
              │ • vibe.toml                  │
              │ • blueprints/*.blueprint.json│
              │ • maps/*.map.json            │
              │ • images/*.png               │
              └──────────────────────────────┘
                         │
                         │ AssetServer
                         ▼
              ┌──────────────────────┐
              │ bevy_vibe_tiles      │
              │ (Bevy plugin)        │
              │ • AssetLoader        │
              │ • Component Injector │
              │ • Hot Reload         │
              └──────────────────────┘
                         │
                         ▼
              ┌──────────────────────┐
              │ Bevy Game Runtime    │
              └──────────────────────┘

📦 Workspace Structure

vibe-tiles/
├── crates/
│   ├── bevy_vibe_tiles/      # Bevy plugin (AssetLoader, ECS integration)
│   ├── vibe_tiles_mcp/        # MCP server (AI agent interface)
│   └── vibe_tiles_core/       # Shared types, schemas, validation
├── examples/
│   └── basic_tilemap/         # Minimal working example
├── assets/
│   └── schemas/
│       └── blueprint.schema.json
├── docs/
│   ├── SPECIFICATION.md       # Original design document
│   ├── AGENTS.md              # AI agent instructions
│   └── API.md                 # Tool reference
└── Cargo.toml                 # Workspace manifest

🚀 Quick Start

For Game Developers

1. Add VibeTiles to your Bevy app:

use bevy::prelude::*;
use bevy_vibe_tiles::{VibeTilesPlugin, MapHandle};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(VibeTilesPlugin)
        .add_systems(Startup, load_map)
        .run();
}

fn load_map(mut commands: Commands, asset_server: Res<AssetServer>) {
    // Load a map (which references blueprints)
    let map_handle = asset_server.load("maps/test_level.map.json");
    
    // Spawn map entity
    commands.spawn((
        MapHandle { handle: map_handle },
        Transform::default(),
        Visibility::default(),
    ));
}

2. Project Structure:

my_game/
├── assets/
│   ├── blueprints/
│   │   └── dungeon_tiles.blueprint.json  # Tileset definition
│   ├── maps/
│   │   └── level_1.map.json              # Game level layout
│   └── images/
│       └── dungeon_tiles.png             # Tileset image (optional)
├── src/
│   └── main.rs
└── vibe.toml                              # Project config

3. Example Blueprint (Tileset):

{
  "metadata": {
    "name": "Dungeon Tileset",
    "cell_size": 32,
    "grid": { "columns": 8, "rows": 4 },
    "image_path": "dungeon_tiles.png"
  },
  "tiles": [
    ["floor_stone", "wall_n", "wall_e", "wall_s", "door", "torch", "barrel", "chest"],
    ["floor_wood", "wall_corner_ne", "wall_corner_se", "wall_corner_sw", ...]
  ],
  "tile_definitions": {
    "floor_stone": {
      "type": "terrain",
      "components": { "collider": false }
    },
    "wall_n": {
      "type": "building",
      "components": { 
        "collider": true,
        "y_sort": { "layer": 20, "pivot": "bottom" }
      }
    }
  }
}

4. Example Map (Game Level):

{
  "metadata": {
    "name": "Level 1",
    "size": { "width": 20, "height": 15 }
  },
  "layers": [
    {
      "name": "ground",
      "tiles": [
        [
          { "blueprint": "dungeon_tiles", "tile_id": "floor_stone" },
          { "blueprint": "dungeon_tiles", "tile_id": "floor_stone" },
          { "blueprint": "dungeon_tiles", "tile_id": "wall_n" },
          ...
        ],
        ...
      ],
      "z_order": 0
    },
    {
      "name": "objects",
      "tiles": [
        [
          null,
          { "blueprint": "dungeon_tiles", "tile_id": "barrel" },
          null,
          ...
        ]
      ],
      "z_order": 10
    }
  ]
}

For AI Agents (via MCP)

1. Initialize project:

   {
     "tool": "init_vibe_project",
     "arguments": {
       "style_tags": ["pixel_art", "top_down", "16x16"]
     }
   }

2. Create blueprint:

   {
     "tool": "create_blueprint",
     "arguments": {
       "name": "dungeon_walls",
       "data": {
         "metadata": {
           "name": "Dungeon Walls",
           "cell_size": 16,
           "grid": { "columns": 8, "rows": 4 }
         },
         "tile_definitions": {
           "wall_stone_N": {
             "type": "building",
             "components": {
               "collider": true,
               "y_sort": true
             }
           }
         }
       }
     }
   }

🔧 Configuration (vibe.toml)

[project]
name = "my_game"
version = "0.1.0"

[tiles]
grid_size = 16
perspective = "top_down_4_way"

[paths]
assets = "assets/images/"
blueprints = "assets/blueprints/"

[style]
tone = "whimsical"

📖 Features

• ✅ Schema-validated blueprints (JSON Schema)
• ✅ Automatic component injection (Collider, YSort, Lighting)
• ✅ Hot-reloading (runtime asset updates)
• ✅ MCP integration (AI agent collaboration)
• 🚧 Procedural generation (AI-assisted tile variants)
• 🚧 Visual debugging (ASCII preview, grid overlay)

🛠️ Development Status

Phase 0: Prototyping (Current)

• Workspace setup
• vibe.toml parser + validation
• Basic blueprint schema
• Manual blueprint → Bevy sprite rendering

Phase 1: Foundation

• JSON Schema finalization
• AssetLoader implementation
• Sample blueprints

Phase 2: Component Injection

• Collider injection system
• YSort layer system
• Hot-reload infrastructure

Phase 3: MCP Integration

• stdio MCP server
• Core CRUD tools
• Zed editor integration guide

Phase 4: AI Workflow

• AGENTS.md prompt engineering
• Advanced tools (suggest, validate, lint)
• Example workflows

🤝 Contributing

This is an experimental project exploring AI-native game development workflows. Contributions, ideas, and feedback are welcome!

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

🙏 Acknowledgments

• Bevy Engine for the amazing ECS framework
• Model Context Protocol for AI-human collaboration primitives
• Zed Editor for pioneering native MCP integration

---

Status: 🚧 Early Development
Bevy Version: 0.15+
Rust Version: 1.91+