Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
GameContextProtocol
Running

App Files Community
GameContextProtocol / README.md
ArturoNereu's picture
ArturoNereu
Added tools, and improved player movement
5b29015
preview code
|
raw
history blame contribute delete
9.37 kB

A newer version of the Gradio SDK is available: 6.2.0

Upgrade
metadata
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 

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

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