README.md

---
title: GCP - Game Context Protocol
emoji: ⚙️
colorFrom: pink
colorTo: blue
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
license: mit
short_description: Sample space with tags for MCP 1st Birthday party
tags:
  - mcp-in-action-track-creative
  - building-mcp-track-creative
---

# GCP - Game Context Protocol

**Build 3D scenes and games with natural language**

## What is it?

GCP (Game Context Protocol) is an AI-powered scene builder that lets you create interactive 3D game environments using simple commands. Built with Three.js and designed for LLM integration via MCP, it also works as a standalone HTTP service.

Simply describe what you want:

> "Add a red cube at 0,2,0"
> "Create a level 50 units wide"
> "Set lighting to night"

…and it instantly builds your 3D scene with:
- Real-time 3D rendering
- Interactive camera controls
- Dynamic object placement
- Lighting presets
- Primitive shapes (cubes, spheres, cylinders, etc.)

---

## Features

### 🎨 Scene Building
- **6 primitive types**: cube, sphere, cylinder, plane, cone, torus
- **LEGO-style bricks**: 10 brick types from Kenney kit (1x1, 2x4, slopes, etc.)
- **Flexible positioning**: Place objects anywhere in 3D space
- **Material system**: Colors, metalness, roughness, opacity, toon shading
- **Dynamic scaling**: Custom size for each object

### 💡 Lighting & Environment
- **4 lighting presets**: day, night, sunset, studio
- **Procedural skybox**: Realistic sky with sun positioning
- **Multiple light types**: ambient, directional, point, spot
- **Fog effects**: Linear and exponential fog
- **Automatic shadows**: Realistic lighting effects

### ✨ Particle Effects
- **5 presets**: fire, smoke, sparkle, rain, snow
- **Localized effects**: Fire, smoke at specific positions
- **Weather effects**: Rain and snow cover entire world

### 📊 UI System
- **2D text overlay**: Render text on screen at any position
- **Progress bars**: Health bars, mana bars with labels
- **HUD elements**: Score displays, status indicators

### 🎮 FPS Controller
- **Physics-based movement**: Cannon.js integration with gravity, jumping, collisions
- **WASD controls**: Smooth keyboard-based movement
- **Mouse look**: Full 360° camera control with configurable sensitivity
- **Configurable feel**: Adjustable speed, jump force, FOV, air control
- **10x10 bounded world**: White floor and walls with collision detection

### 👀 Interactive Viewer
- **Dual camera modes**: FPS (first-person) and Orbit (overview)
- **Real-time updates**: See changes instantly via postMessage API
- **Grid helper**: Optional floor grid for spatial reference
- **Auto-centering**: Camera automatically frames your scene in Orbit mode

### 🤖 AI Integration
- **MCP protocol**: Works with Claude, GPT, and other AI assistants
- **Natural language**: Simple commands like "add a blue sphere" or "add rain"
- **Context aware**: Builds on existing scenes
- **40+ MCP tools**: Scene (6) + Player (10) + Rendering (10) + Environment (4) + UI (4) + Post-processing (8)
- **No coding required**: Pure natural language scene building

---

## Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/ArturoNereu/3DViz-MCP.git
cd 3DViz-MCP

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

The app will start two servers:
- **FastAPI** (port 8000): MCP server and scene API
- **Gradio** (port 7860): Chat interface

Open `http://localhost:7860` in your browser.

### Example Commands

```
Add a red cube at 0,2,0
Add a blue sphere at 5,1,5
Add a sunset skybox
Add fire particles at 0,1,0
Add rain
Render "Score: 100" at the top of the screen
Add a health bar with value 75
Add a red brick_2x4 at 0,0,0
Apply toon shading to the cube
Set lighting to night
```

---

## How It Works

### For AI Assistants (MCP)

The MCP server exposes 40+ tools that AI assistants can call:

**Scene Building (6 tools):**
- `create_scene` - Create a new 3D scene/level
- `add_object` - Add primitive objects (cube, sphere, etc.)
- `add_brick` - Add LEGO-style bricks from Kenney kit
- `remove_object` - Remove objects from scene
- `set_lighting` - Change lighting preset
- `get_scene_info` - Get scene details

**Environment (4 tools):**
- `add_skybox` - Add procedural sky (day, sunset, night, etc.)
- `remove_skybox` - Remove skybox
- `add_particles` - Add particle effects (fire, smoke, rain, snow)
- `remove_particles` - Remove particle systems

**UI Overlay (4 tools):**
- `render_text_on_screen` - Display 2D text
- `render_bar_on_screen` - Display health/progress bars
- `remove_ui_element` - Remove UI elements
- `get_ui_elements` - List all UI elements

**Rendering (10 tools):**
- `add_light` - Add light sources
- `remove_light` - Remove lights
- `update_light` - Modify light properties
- `get_lights` - List all lights
- `update_object_material` - Change material properties
- `update_material_to_toon` - Apply toon/cel shading
- `set_background_color` - Set solid or gradient background
- `set_fog` - Add atmospheric fog

**Player Controller (10 tools):**
- `set_player_speed` - Movement speed
- `set_jump_force` - Jump height
- `set_mouse_sensitivity` - Mouse look + Y-invert
- `set_gravity` - World gravity
- `set_player_dimensions` - Player size
- `set_movement_acceleration` - Movement feel
- `set_air_control` - Airborne control
- `set_camera_fov` - Field of view
- `set_vertical_look_limits` - Look angle limits
- `get_player_config` - Get all settings

**Post-Processing (8 tools):**
- `set_bloom` - Glow effect
- `set_ssao` - Ambient occlusion
- `set_color_grading` - Color adjustments
- `set_vignette` - Vignette effect
- `set_depth_of_field` - Focus blur
- `set_motion_blur` - Movement blur
- `set_chromatic_aberration` - Lens effect
- `get_post_processing` - Get all effects

### For Developers (HTTP API)

```python
import requests

# Create a new scene
response = requests.post("http://localhost:8000/api/scenes", json={
    "name": "My Scene",
    "world_width": 50.0,
    "lighting_preset": "day"
})

scene_id = response.json()["scene_id"]

# Add an object
requests.post(f"http://localhost:8000/api/scenes/{scene_id}/objects", json={
    "object_type": "cube",
    "position": {"x": 0, "y": 1, "z": 0},
    "material": {"color": "#ff0000"}
})

# View your scene
viewer_url = f"http://localhost:8000/view/scene/{scene_id}"
```

---

## Architecture

```
GCP - Game Context Protocol
├── app.py                 # Gradio chat interface
├── backend/
│   ├── main.py           # FastAPI + GCP server
│   ├── game_models.py    # Scene, GameObject, Light models
│   ├── game_tools.py     # GCP tool implementations
│   └── storage.py        # In-memory scene storage
└── frontend/
    └── game_viewer.html  # Three.js 3D renderer
```

### Tech Stack
- **Backend**: FastAPI, FastMCP, Pydantic
- **Frontend**: Three.js, Gradio
- **3D Rendering**: Three.js with orbit controls
- **AI Integration**: MCP (Model Context Protocol)

---

## API Endpoints

### Scenes
- `POST /api/scenes` - Create a new scene
- `GET /api/scenes/{scene_id}` - Get scene data
- `GET /view/scene/{scene_id}` - View scene in browser

### MCP
- `GET /mcp` - MCP protocol endpoint
- `GET /docs` - API documentation

---

## Supported Objects

| Type | Description |
|------|-------------|
| `cube` | Box geometry |
| `sphere` | Spherical geometry |
| `cylinder` | Cylindrical geometry |
| `plane` | Flat surface (floor/wall) |
| `cone` | Conical geometry |
| `torus` | Donut shape |

## Supported Colors

red, blue, green, yellow, purple, orange, pink, brown, black, white, or any hex code (#ff0000)

## Lighting Presets

- **day**: Bright white directional light
- **night**: Dark blue moonlight
- **sunset**: Warm orange light
- **studio**: Neutral balanced lighting

---

## Development

### Project Structure

```
backend/game_models.py    # Data models (Scene, GameObject, etc.)
backend/game_tools.py     # Tool implementations
backend/main.py           # FastAPI routes + MCP tools
frontend/game_viewer.html # Three.js viewer
app.py                    # Gradio chat interface
```

### Adding New Object Types

1. Add to `ObjectType` enum in `game_models.py`
2. Add geometry case in `game_viewer.html` `renderGameObjects()`
3. Update command parsing in `app.py` `chat_response()`

---

## Roadmap

### ✅ Completed
- **Phase 1**: Player Controller - Core Controls (5 tools)
- **Phase 2**: Player Controller - Enhanced Feel (4 tools)
- **Phase 3**: Rendering & Lighting Tools (10 tools)
- **Phase 4**: Post-Processing Effects (8 tools)
- **Phase 5**: Environment Tools - Skybox & Particles (4 tools)
- **Phase 6**: UI Overlay System (4 tools)
- **Phase 7**: LEGO Brick Kit Integration (Kenney assets)
- **Phase 8**: Toon/Cel Shading Materials
- Physics engine integration (Cannon.js)
- FPS controls (WASD + mouse look)

### 🔮 Next Steps
- Transform controls for object manipulation
- Scene templates and prefabs
- Export to Unity/Unreal
- Persistent scene storage

### 💭 Future Ideas
- NPC system with behaviors
- Multiplayer support
- Procedural generation
- Audio system

---

## License

MIT License - feel free to use in your projects!

## Contributing

Contributions welcome! Please open an issue or PR.

---

**Built with ❤️ for AI-powered game development**