Added v0

README.md

@@ -1,13 +1,265 @@
+# 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
+- **Flexible positioning**: Place objects anywhere in 3D space
+- **Material system**: Colors, metalness, roughness, opacity
+- **Dynamic scaling**: Custom size for each object
+
+### 💡 Lighting System
+- **4 presets**: day, night, sunset, studio
+- **Multiple light types**: ambient, directional, point, spot
+- **Automatic shadows**: Realistic lighting effects
+
+### 🎮 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 "set speed to 10"
+- **Context aware**: Builds on existing scenes
+- **16 MCP tools**: Scene building (5) + Player controller (11)
+- **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 green cylinder at -3,1,0
+Set lighting to night
+Create a level 100 units wide
+```
+
+---
+
+## How It Works
+
+### For AI Assistants (MCP)
+
+The MCP server exposes 16 tools that AI assistants can call:
+
+**Scene Building (5 tools):**
+- `create_scene_tool` - Create a new 3D scene/level
+- `add_object_tool` - Add objects to the scene
+- `remove_object_tool` - Remove objects from scene
+- `set_lighting_tool` - Change lighting preset
+- `get_scene_info_tool` - Get scene details
+
+**Player Controller Phase 1 (5 tools):**
+- `set_player_speed` - Movement speed
+- `set_jump_force` - Jump height
+- `set_mouse_sensitivity` - Mouse look sensitivity + Y-invert
+- `set_gravity` - World gravity
+- `set_player_dimensions` - Player size
+
+**Player Controller Phase 2 (4 tools):**
+- `set_movement_acceleration` - Movement feel
+- `set_air_control` - Airborne control
+- `set_camera_fov` - Field of view
+- `set_vertical_look_limits` - Look angle limits
+
+**Configuration (1 tool):**
+- `get_player_config` - Get all player settings
+
+### 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
+
 ---
-title: GameContextProtocol
-emoji: 🔥
-colorFrom: yellow
-colorTo: indigo
-sdk: gradio
-sdk_version: 6.0.1
-app_file: app.py
-pinned: false
-short_description: Focus on the creative side of making games
+
+## 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)
+- Physics engine integration (Cannon.js)
+- FPS controls (WASD + mouse look)
+
+### 🚧 Next Phase: Rendering & Lighting Tools
+- Add/remove individual lights
+- Update light properties (color, intensity, position)
+- Change object materials (color, metalness, roughness)
+- Set background color
+
+### 🔮 Phase 3: World Building
+- glTF model loading (Kenney assets)
+- Prefab system (props, buildings, terrain)
+- Scene templates
+- Export to Unity/Unreal
+
+### 💭 Future Ideas
+- NPC system with behaviors
+- Multiplayer support
+- Procedural generation
+
+---
+
+## License
+
+MIT License - feel free to use in your projects!
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+**Built with ❤️ for AI-powered game development**

app.py

@@ -0,0 +1,497 @@
+"""
+GCP - Game Context Protocol
+Build 3D game scenes with natural language
+"""
+import os
+import json
+import gradio as gr
+import threading
+import uvicorn
+import time
+import requests
+from backend.main import app as fastapi_app
+
+# Get base URLs from environment
+# SPACE_URL is the public-facing URL (for Gradio)
+# FastAPI runs on port 8000, Gradio on 7860
+SPACE_URL = os.getenv("SPACE_URL", "http://localhost:7860")
+# For local dev, FastAPI is on a different port; in HF Spaces, use same domain
+FASTAPI_URL = os.getenv("FASTAPI_URL", "http://localhost:8000")
+BASE_URL = SPACE_URL  # For display in UI
+
+# Global state for current scene
+current_scene_id = None
+current_scene_url = None
+selected_object_id = None  # Track currently looked-at object (FPS mode)
+
+
+def add_cache_buster(url):
+    """Add timestamp to URL to force iframe reload"""
+    import time
+    timestamp = int(time.time() * 1000)
+    separator = "&" if "?" in url else "?"
+    return f"{url}{separator}t={timestamp}"
+
+
+def wait_for_fastapi(max_retries=30, retry_interval=1):
+    """
+    Wait for FastAPI to be ready with health check.
+
+    Args:
+        max_retries: Maximum number of health check attempts
+        retry_interval: Seconds to wait between retries
+
+    Returns:
+        True if FastAPI is ready, False otherwise
+    """
+    print("\n" + "="*60)
+    print("⏳ Waiting for FastAPI/MCP server to be ready...")
+    print("="*60)
+
+    for i in range(max_retries):
+        try:
+            response = requests.get(f"{FASTAPI_URL}/health", timeout=2)
+            if response.status_code == 200:
+                data = response.json()
+                print(f"\n✅ FastAPI is ready! Service: {data.get('service', 'Unknown')}")
+                print(f"   Version: {data.get('version', 'Unknown')}")
+                print(f"   Status: {data.get('status', 'Unknown')}")
+                print("="*60 + "\n")
+                return True
+        except (requests.ConnectionError, requests.Timeout):
+            if i < max_retries - 1:
+                print(f"   Attempt {i+1}/{max_retries}: FastAPI not ready yet, retrying in {retry_interval}s...")
+                time.sleep(retry_interval)
+            else:
+                print(f"\n⚠️  FastAPI health check failed after {max_retries} attempts")
+                print("   The server might still start, but there could be issues.")
+                print("="*60 + "\n")
+                return False
+        except Exception as e:
+            print(f"   Unexpected error during health check: {e}")
+            time.sleep(retry_interval)
+
+    return False
+
+
+# Start FastAPI/MCP server in background
+def start_fastapi():
+    print("\n" + "="*60)
+    print("Starting FastAPI/MCP server on port 8000...")
+    print("="*60 + "\n")
+    uvicorn.run(fastapi_app, host="0.0.0.0", port=8000, log_level="info")
+
+fastapi_thread = threading.Thread(target=start_fastapi, daemon=True)
+fastapi_thread.start()
+
+# Wait for FastAPI to be ready
+wait_for_fastapi()
+
+
+def create_default_scene():
+    """Use the clean default Welcome Scene created on server startup"""
+    global current_scene_id, current_scene_url
+
+    try:
+        # Use the pre-initialized "welcome" scene from storage
+        # (created in backend/storage.py on module load)
+        current_scene_id = "welcome"
+        current_scene_url = f"{FASTAPI_URL}/view/scene/welcome"
+
+        print(f"✅ Using default Welcome Scene")
+        print(f"   Scene ID: {current_scene_id}")
+        print(f"   Viewer URL: {current_scene_url}")
+        print(f"   - Clean 10x10 FPS world with physics")
+        print(f"   - Ground plane + walls (created by viewer)")
+        print(f"   - Player starts at (0, 1, 0)")
+
+        return current_scene_url
+
+    except Exception as e:
+        import traceback
+        print(f"❌ Error loading default scene: {e}")
+        print(f"   Full traceback:")
+        traceback.print_exc()
+        return None
+
+
+# Initialize the GPT chat client
+gpt_client = None
+
+def get_gpt_client():
+    """Get or create the GPT chat client"""
+    global gpt_client, current_scene_id
+    if gpt_client is None or gpt_client.scene_id != current_scene_id:
+        from chat_client import GCPChatClient
+        gpt_client = GCPChatClient(scene_id=current_scene_id, base_url=FASTAPI_URL)
+    return gpt_client
+
+
+def chat_response(message, history):
+    """Handle chat messages using GPT with tool calling"""
+    global current_scene_id, current_scene_url
+
+    # Handle help command locally (no need for LLM)
+    if message.lower().strip() == "help":
+        return """**GCP - Game Context Protocol**
+
+I'm an AI assistant that can help you build 3D scenes using natural language.
+
+**What I can do:**
+- Add objects: "add a red cube at 2, 1, 0"
+- Change lighting: "set lighting to night"
+- Configure player: "set speed to 10" or "make the player move half as fast"
+- Add lights: "add a point light above the cube"
+- Update materials: "make it shiny and metallic"
+- Set backgrounds: "gradient background from blue to orange"
+- Add fog: "add some fog to the scene"
+- Query state: "what's the current player speed?" or "show me the scene info"
+
+**I understand context**, so you can say things like:
+- "double the jump force"
+- "make it twice as bright"
+- "reduce gravity by half"
+
+**Tips:**
+- Press C in viewer to toggle FPS/Orbit camera
+- WASD to move, Space to jump in FPS mode
+- Click in viewer to enable mouse-look
+""", None
+
+    try:
+        client = get_gpt_client()
+        response, action_data = client.chat(message)
+        return response, action_data
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        return f"Error: {str(e)}", None
+
+
+# Create default scene on startup
+print("Creating default scene...")
+default_viewer_url = create_default_scene()
+print(f"Default viewer URL: {default_viewer_url}")
+if not default_viewer_url:
+    print("⚠️  WARNING: Default scene creation failed! No viewer URL generated.")
+
+
+# Minimal CSS - only essential styling, let Gradio handle layout
+APP_CSS = """
+        /* Viewer iframe needs explicit sizing */
+        #viewer-container {
+            width: 100%;
+            height: 600px;
+        }
+
+        #viewer-container iframe {
+            width: 100%;
+            height: 100%;
+            border: none;
+        }
+
+        /* PostMessage Container - must be invisible */
+        #postmessage-container {
+            position: absolute;
+            width: 0;
+            height: 0;
+            overflow: hidden;
+            pointer-events: none;
+        }
+
+        /* Toast Notifications */
+        #toast-container {
+            position: fixed;
+            top: 20px;
+            right: 20px;
+            z-index: 200;
+        }
+
+        .toast {
+            background: rgba(0, 0, 0, 0.9);
+            color: white;
+            padding: 15px 20px;
+            border-radius: 8px;
+            margin-bottom: 10px;
+            border-left: 4px solid #2196f3;
+        }
+
+        .toast.success { border-left-color: #4caf50; }
+        .toast.error { border-left-color: #f44336; }
+
+        /* Hide the action data textbox but keep it in DOM for events to fire */
+        .hidden-action {
+            position: absolute !important;
+            width: 1px !important;
+            height: 1px !important;
+            padding: 0 !important;
+            margin: -1px !important;
+            overflow: hidden !important;
+            clip: rect(0, 0, 0, 0) !important;
+            white-space: nowrap !important;
+            border: 0 !important;
+        }
+"""
+
+# Build immersive chat interface with overlay
+with gr.Blocks(
+    title="GCP - Game Context Protocol",
+) as demo:
+    # Initialize JavaScript functionality (minimal essentials only)
+    gr.HTML("""
+        <script>
+        (function() {
+            // PostMessage API Helper - sends commands to the 3D viewer iframe
+            window.sendMessageToViewer = function(action, data) {
+                const iframe = document.querySelector('#viewer-container iframe');
+                if (iframe && iframe.contentWindow) {
+                    iframe.contentWindow.postMessage({ action, data }, '*');
+                }
+            };
+
+            // Toast Notification Function
+            window.showToast = function(message, type = 'info') {
+                let toastContainer = document.getElementById('toast-container');
+                if (!toastContainer) {
+                    toastContainer = document.createElement('div');
+                    toastContainer.id = 'toast-container';
+                    document.body.appendChild(toastContainer);
+                }
+                const toast = document.createElement('div');
+                toast.className = `toast ${type}`;
+                toast.textContent = message;
+                toastContainer.appendChild(toast);
+                setTimeout(() => toast.remove(), 3000);
+            };
+
+            // Loading Indicator Functions
+            window.showLoading = function() {
+                let loadingIndicator = document.getElementById('loading-indicator');
+                if (!loadingIndicator) {
+                    loadingIndicator = document.createElement('div');
+                    loadingIndicator.id = 'loading-indicator';
+                    loadingIndicator.innerHTML = '<div class="spinner"></div>';
+                    document.body.appendChild(loadingIndicator);
+                }
+                loadingIndicator.style.display = 'block';
+            };
+
+            window.hideLoading = function() {
+                const loadingIndicator = document.getElementById('loading-indicator');
+                if (loadingIndicator) loadingIndicator.style.display = 'none';
+            };
+
+            // Handle messages from iframe (screenshot, object selection)
+            window.addEventListener('message', function(event) {
+                if (event.data && event.data.action === 'screenshot') {
+                    const { dataURL, sceneName, timestamp } = event.data.data;
+                    const link = document.createElement('a');
+                    link.href = dataURL;
+                    link.download = `${sceneName}_${timestamp}.png`;
+                    link.click();
+                    if (window.showToast) {
+                        window.showToast('Screenshot saved!', 'success');
+                    }
+                }
+
+                if (event.data && event.data.action === 'objectInspect') {
+                    const objInfo = event.data.data;
+                    if (window.showToast) {
+                        window.showToast(`Selected: ${objInfo.name}`, 'info');
+                    }
+                }
+
+                if (event.data && event.data.action === 'objectSelected') {
+                    const objData = event.data.data;
+                    window.selectedObjectId = objData.object_id;
+                    if (window.showToast) {
+                        window.showToast(`Looking at: ${objData.object_type} (${objData.distance}m)`, 'info');
+                    }
+                }
+
+                if (event.data && event.data.action === 'objectDeselected') {
+                    window.selectedObjectId = null;
+                }
+            });
+
+            // Initialize toast container on load
+            setTimeout(function() {
+                if (!document.getElementById('toast-container')) {
+                    const toastContainer = document.createElement('div');
+                    toastContainer.id = 'toast-container';
+                    document.body.appendChild(toastContainer);
+                }
+            }, 1000);
+
+        })();
+        </script>
+    """)
+
+    # State for file handling
+    file_state = gr.State([])
+
+    # Component for passing action data to JavaScript via .change() event
+    #
+    # IMPORTANT: DO NOT set visible=False!
+    # Gradio's visible=False removes the component from the DOM or renders it in a way
+    # that prevents .change() events from firing when the value is updated programmatically.
+    # Instead, we use visible=True and hide it with CSS (see .hidden-action in APP_CSS).
+    # This keeps the element in the DOM so events fire properly.
+    #
+    # The flow: bot() returns JSON → action_data updates → .change() fires → JS sends postMessage to iframe
+    action_data = gr.Textbox(value="", elem_id="action-data", visible=True, elem_classes=["hidden-action"])
+
+    # Main container - side by side layout: Chat (left) | Viewer (right)
+    with gr.Row(elem_id="main-container", equal_height=True):
+        # Left column: Chat interface (scale=1 = ~25% width)
+        with gr.Column(elem_id="chat-column", scale=1, min_width=350):
+            gr.Markdown("### 🎮 GCP - Game Context Protocol")
+            chatbot = gr.Chatbot(
+                height=500,  # Taller to fill vertical space
+                show_label=False,
+                elem_id="chatbot",
+                # Gradio 6: type="messages" is now the default, removed
+            )
+            msg = gr.Textbox(
+                placeholder="'add a red cube' • 'set lighting to night' • 'help'",
+                show_label=False,
+                container=False,
+                elem_id="chat-input"
+            )
+
+        # Right column: 3D Viewer (scale=3 = ~75% width)
+        with gr.Column(elem_id="viewer-column", scale=3):
+            if default_viewer_url:
+                initial_viewer_html = f'<div id="viewer-container"><iframe src="{default_viewer_url}"></iframe></div>'
+                print(f"📊 Setting up viewer iframe with src: {default_viewer_url}")
+            else:
+                initial_viewer_html = '<div id="viewer-container" style="display: flex; align-items: center; justify-content: center; color: #666;"><p>⚠️ Scene failed to load. Check console logs.</p></div>'
+                print("⚠️  No viewer URL available - showing error message")
+
+            viewer = gr.HTML(
+                value=initial_viewer_html,
+                elem_id="viewer-fullscreen"
+            )
+
+    def user(user_message, history):
+        """Handle user input"""
+        history = history or []
+        history.append({"role": "user", "content": user_message})
+        return "", history
+
+    def bot(history):
+        """Generate bot response"""
+        # Gradio 6: content can be a string or list of content blocks
+        content = history[-1]["content"]
+        if isinstance(content, list):
+            # Extract text from content blocks
+            user_message = " ".join(
+                block.get("text", "") if isinstance(block, dict) else str(block)
+                for block in content
+            )
+        else:
+            user_message = content
+
+        # Process command (history not used by chat_response)
+        bot_message, action_result = chat_response(user_message, [])
+        history.append({"role": "assistant", "content": bot_message})
+
+        # Handle action_result
+        viewer_html = viewer.value  # Default: keep current viewer
+        action_json = ""  # Default: no action (empty string)
+
+        if action_result:
+            action_type = action_result.get("action")
+
+            if action_type == "reload":
+                # Full reload: update iframe src
+                viewer_html = f'<div id="viewer-container" style="width:100%; min-height:500px; height:70vh;"><iframe src="{action_result["url"]}" style="width:100%; height:100%; border:none;"></iframe></div>'
+
+            elif action_type in ["addObject", "setLighting", "setControlMode", "updateMaterial", "addLight", "removeLight", "updateLight", "setBackground", "setFog"]:
+                # Build action JSON for the JavaScript watcher
+                import json
+                import time
+
+                # Determine toast message based on action type
+                toast_message = ""
+                if action_type == "addObject":
+                    obj_type = action_result["data"].get("type", "object")
+                    toast_message = f"Added {obj_type} to scene"
+                elif action_type == "setLighting":
+                    toast_message = "Lighting updated"
+                elif action_type == "setControlMode":
+                    mode = action_result["data"].get("mode", "")
+                    toast_message = f"Switched to {mode.upper()} mode"
+                elif action_type == "updateMaterial":
+                    toast_message = "Material updated"
+                elif action_type == "addLight":
+                    light_name = action_result["data"].get("name", "Light")
+                    toast_message = f"Added light: {light_name}"
+                elif action_type == "removeLight":
+                    toast_message = "Light removed"
+                elif action_type == "updateLight":
+                    toast_message = "Light updated"
+                elif action_type == "setBackground":
+                    toast_message = "Background updated"
+                elif action_type == "setFog":
+                    toast_message = "Fog updated"
+
+                # Create JSON payload for the .then() JavaScript handler
+                action_json = json.dumps({
+                    "action": action_result["action"],
+                    "data": action_result["data"],
+                    "toast": toast_message,
+                    "toastType": "success"
+                })
+
+        return history, viewer_html, action_json
+
+    # When action_data changes, this handler sends postMessage to the iframe
+    def handle_action_change(action_json):
+        return action_json  # Pass through for JS
+
+    action_data.change(
+        fn=handle_action_change,
+        inputs=[action_data],
+        outputs=[action_data],
+        js="""
+        (actionJson) => {
+            if (actionJson && actionJson.length > 2) {
+                try {
+                    const actionData = JSON.parse(actionJson);
+                    const iframe = document.querySelector('#viewer-container iframe');
+                    if (iframe && iframe.contentWindow) {
+                        iframe.contentWindow.postMessage({
+                            action: actionData.action,
+                            data: actionData.data
+                        }, '*');
+                        if (actionData.toast && window.showToast) {
+                            window.showToast(actionData.toast, actionData.toastType || 'success');
+                        }
+                    }
+                } catch (e) {
+                    // Silently ignore parse errors
+                }
+            }
+            return actionJson;
+        }
+        """
+    )
+
+    msg.submit(
+        user,
+        [msg, chatbot],
+        [msg, chatbot],
+        queue=False
+    ).then(
+        bot,
+        [chatbot],
+        [chatbot, viewer, action_data]
+    )
+
+
+if __name__ == "__main__":
+    # Enable queue for handling multiple concurrent users (important for HF Spaces)
+    demo.queue()
+    # Gradio 6: theme and css moved from gr.Blocks() to launch()
+    demo.launch(server_name="0.0.0.0", server_port=7860, theme=gr.themes.Soft(), css=APP_CSS)

backend/__init__.py

@@ -0,0 +1,4 @@
+"""
+3DViz MCP Server Backend Package
+"""
+__version__ = "1.0.0"

backend/game_models.py

@@ -0,0 +1,239 @@
+"""
+Data models for GCP - Game Context Protocol
+Using plain dictionaries for simplicity and clarity.
+"""
+from typing import Optional, Literal, Dict, Any, List
+from datetime import datetime
+import uuid
+
+
+# Game Types
+ObjectType = Literal["cube", "sphere", "cylinder", "plane", "cone", "torus", "model"]
+LightType = Literal["ambient", "directional", "point", "spot"]
+LightingPreset = Literal["day", "night", "sunset", "studio"]
+CameraMode = Literal["fps", "orbit", "top_down", "free"]
+MaterialType = Literal["standard", "basic", "phong", "toon"]
+
+
+# Factory functions for creating default data structures
+
+def create_vector3(x: float = 0.0, y: float = 0.0, z: float = 0.0) -> Dict[str, float]:
+    """Create a 3D vector for position, rotation, or scale."""
+    return {"x": x, "y": y, "z": z}
+
+
+def create_material(
+    type: MaterialType = "standard",
+    color: str = "#ffffff",
+    metalness: float = 0.5,
+    roughness: float = 0.5,
+    opacity: float = 1.0,
+    wireframe: bool = False
+) -> Dict[str, Any]:
+    """Create material properties."""
+    return {
+        "type": type,
+        "color": color,
+        "metalness": metalness,
+        "roughness": roughness,
+        "opacity": opacity,
+        "wireframe": wireframe
+    }
+
+
+def create_game_object(
+    object_type: ObjectType = "cube",
+    name: Optional[str] = None,
+    position: Optional[Dict[str, float]] = None,
+    rotation: Optional[Dict[str, float]] = None,
+    scale: Optional[Dict[str, float]] = None,
+    material: Optional[Dict[str, Any]] = None,
+    model_path: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """Create a 3D game object."""
+    return {
+        "id": str(uuid.uuid4()),
+        "name": name,
+        "type": object_type,
+        "position": position or create_vector3(),
+        "rotation": rotation or create_vector3(),
+        "scale": scale or create_vector3(1, 1, 1),
+        "material": material or create_material(),
+        "model_path": model_path,
+        "metadata": metadata or {},
+        "created_at": datetime.utcnow().isoformat()
+    }
+
+
+def create_light(
+    light_type: LightType = "directional",
+    name: Optional[str] = None,
+    color: str = "#ffffff",
+    intensity: float = 1.0,
+    position: Optional[Dict[str, float]] = None,
+    target: Optional[Dict[str, float]] = None,
+    cast_shadow: bool = True
+) -> Dict[str, Any]:
+    """Create a light source."""
+    return {
+        "id": str(uuid.uuid4()),
+        "name": name,
+        "type": light_type,
+        "color": color,
+        "intensity": intensity,
+        "position": position or create_vector3(10, 10, 10),
+        "target": target,
+        "cast_shadow": cast_shadow
+    }
+
+
+def create_environment(
+    background_color: str = "#87CEEB",
+    fog_enabled: bool = False,
+    fog_color: str = "#ffffff",
+    fog_near: float = 10.0,
+    fog_far: float = 100.0,
+    ambient_light_intensity: float = 0.5,
+    lighting_preset: LightingPreset = "day"
+) -> Dict[str, Any]:
+    """Create environment settings."""
+    return {
+        "background_color": background_color,
+        "fog_enabled": fog_enabled,
+        "fog_color": fog_color,
+        "fog_near": fog_near,
+        "fog_far": fog_far,
+        "ambient_light_intensity": ambient_light_intensity,
+        "lighting_preset": lighting_preset
+    }
+
+
+def create_player(
+    position: Optional[Dict[str, float]] = None,
+    rotation: Optional[Dict[str, float]] = None,
+    camera_mode: CameraMode = "orbit",
+    movement_speed: float = 5.0,
+    look_sensitivity: float = 0.002
+) -> Dict[str, Any]:
+    """Create player/camera configuration."""
+    return {
+        "position": position or create_vector3(0, 5, 10),
+        "rotation": rotation or create_vector3(),
+        "camera_mode": camera_mode,
+        "movement_speed": movement_speed,
+        "look_sensitivity": look_sensitivity
+    }
+
+
+def create_player_config(
+    move_speed: float = 5.0,
+    jump_force: float = 5.0,
+    mouse_sensitivity: float = 0.002,
+    invert_y: bool = False,
+    gravity: float = -9.82,
+    player_height: float = 1.7,
+    player_radius: float = 0.3,
+    eye_height: float = 1.6,
+    player_mass: float = 80.0,
+    linear_damping: float = 0.9,
+    movement_acceleration: float = 0.0,
+    air_control: float = 1.0,
+    camera_fov: float = 75.0,
+    min_pitch: float = -89.0,
+    max_pitch: float = 89.0
+) -> Dict[str, Any]:
+    """
+    Create player controller configuration for FPS mode.
+
+    Args:
+        move_speed: Horizontal movement speed in units/second
+        jump_force: Initial upward velocity for jumps in m/s
+        mouse_sensitivity: Mouse look sensitivity multiplier
+        invert_y: Whether to invert vertical mouse look
+        gravity: World gravity in m/s² (negative = downward)
+        player_height: Player collision capsule height in meters
+        player_radius: Player collision capsule radius in meters
+        eye_height: Camera height from player feet in meters
+        player_mass: Player body mass in kg
+        linear_damping: Air resistance (0.0-1.0, higher = more friction)
+        movement_acceleration: Acceleration time (0.0=instant, higher=slower)
+        air_control: Movement control while airborne (0.0-1.0)
+        camera_fov: Field of view in degrees (typical: 60-90)
+        min_pitch: Minimum vertical look angle in degrees (looking down)
+        max_pitch: Maximum vertical look angle in degrees (looking up)
+
+    Returns:
+        Dictionary with player controller configuration
+    """
+    return {
+        "move_speed": move_speed,
+        "jump_force": jump_force,
+        "mouse_sensitivity": mouse_sensitivity,
+        "invert_y": invert_y,
+        "gravity": gravity,
+        "player_height": player_height,
+        "player_radius": player_radius,
+        "eye_height": eye_height,
+        "player_mass": player_mass,
+        "linear_damping": linear_damping,
+        "movement_acceleration": movement_acceleration,
+        "air_control": air_control,
+        "camera_fov": camera_fov,
+        "min_pitch": min_pitch,
+        "max_pitch": max_pitch
+    }
+
+
+def create_scene(
+    name: str = "Untitled Scene",
+    description: Optional[str] = None,
+    world_width: float = 100.0,
+    world_height: float = 100.0,
+    world_depth: float = 100.0,
+    objects: Optional[List[Dict[str, Any]]] = None,
+    lights: Optional[List[Dict[str, Any]]] = None,
+    environment: Optional[Dict[str, Any]] = None,
+    player: Optional[Dict[str, Any]] = None,
+    show_grid: bool = True,
+    grid_size: float = 100.0,
+    grid_divisions: int = 20,
+    tags: Optional[List[str]] = None
+) -> Dict[str, Any]:
+    """Create a complete 3D scene."""
+    now = datetime.utcnow().isoformat()
+    return {
+        "scene_id": str(uuid.uuid4()),
+        "name": name,
+        "description": description,
+        "world_width": world_width,
+        "world_height": world_height,
+        "world_depth": world_depth,
+        "objects": objects or [],
+        "lights": lights or [],
+        "environment": environment or create_environment(),
+        "player": player or create_player(),
+        "show_grid": show_grid,
+        "grid_size": grid_size,
+        "grid_divisions": grid_divisions,
+        "tags": tags or [],
+        "created_at": now,
+        "updated_at": now
+    }
+
+
+# Validation helpers (optional, for type checking)
+
+def validate_vector3(v: Dict[str, float]) -> bool:
+    """Check if a dict is a valid Vector3."""
+    return isinstance(v, dict) and all(k in v for k in ["x", "y", "z"])
+
+
+def validate_lighting_preset(preset: str) -> bool:
+    """Check if a string is a valid lighting preset."""
+    return preset in ["day", "night", "sunset", "studio"]
+
+
+def validate_object_type(obj_type: str) -> bool:
+    """Check if a string is a valid object type."""
+    return obj_type in ["cube", "sphere", "cylinder", "plane", "cone", "torus", "model"]

backend/main.py

@@ -0,0 +1,105 @@
+"""
+GCP - Game Context Protocol Server
+FastAPI server for the 3D scene viewer HTTP endpoints.
+MCP tools are defined in mcp_server.py
+"""
+import os
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+
+from backend.storage import storage
+
+# Create FastAPI app
+app = FastAPI(
+    title="GCP - Game Context Protocol",
+    description="3D scene building server. Use MCP tools via Claude/AI assistants, or view scenes via HTTP.",
+    version="2.0.0",
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# =============================================================================
+# HTTP Endpoints (for viewer and health checks)
+# =============================================================================
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint for startup verification."""
+    return {
+        "status": "healthy",
+        "service": "GCP - Game Context Protocol",
+        "version": "2.0.0",
+    }
+
+
+@app.get("/")
+async def root():
+    """Root endpoint with API information."""
+    return {
+        "name": "GCP - Game Context Protocol",
+        "version": "2.0.0",
+        "description": "MCP server for building 3D scenes with AI assistants",
+        "endpoints": {
+            "viewer": "/view/scene/{scene_id}",
+            "scene_data": "/api/scenes/{scene_id}",
+            "health": "/health",
+        },
+        "mcp": "Connect via stdio transport using: python -m backend.mcp_server",
+    }
+
+
+@app.get("/api/scenes/{scene_id}")
+async def get_scene_api(scene_id: str):
+    """Get scene configuration and data as JSON."""
+    scene = storage.get(scene_id)
+    if not scene:
+        raise HTTPException(status_code=404, detail=f"Scene '{scene_id}' not found")
+    return scene
+
+
+@app.get("/view/scene/{scene_id}")
+async def view_scene(scene_id: str):
+    """Serve the Three.js viewer for a scene."""
+    scene = storage.get(scene_id)
+    if not scene:
+        raise HTTPException(status_code=404, detail=f"Scene '{scene_id}' not found")
+
+    # Serve the game viewer HTML
+    try:
+        viewer_path = os.path.join(os.path.dirname(__file__), "..", "frontend", "game_viewer.html")
+        with open(viewer_path, 'r') as f:
+            html_content = f.read()
+        return HTMLResponse(content=html_content)
+    except FileNotFoundError:
+        raise HTTPException(status_code=500, detail="Game viewer HTML not found")
+
+
+@app.get("/manifest.json")
+async def get_manifest():
+    """Serve PWA manifest to avoid 404 errors."""
+    try:
+        manifest_path = os.path.join(os.path.dirname(__file__), "..", "frontend", "manifest.json")
+        with open(manifest_path, 'r') as f:
+            import json
+            manifest_content = json.load(f)
+        return JSONResponse(content=manifest_content)
+    except FileNotFoundError:
+        return JSONResponse(content={"name": "GCP", "short_name": "GCP"})
+
+
+# =============================================================================
+# Run server
+# =============================================================================
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

backend/mcp_server.py

@@ -0,0 +1,1119 @@
+"""
+GCP - Game Context Protocol
+MCP Server using the official Anthropic MCP SDK
+
+This module defines all MCP tools for building 3D scenes with AI assistants.
+"""
+import os
+from typing import Any
+from mcp.server import Server
+from mcp.types import Tool, TextContent
+
+# Import tool implementations
+from backend.tools.scene_tools import (
+    create_game_scene,
+    add_game_object,
+    remove_game_object,
+    set_scene_lighting,
+    get_scene_info,
+)
+from backend.tools.player_tools import (
+    set_player_speed,
+    set_jump_force,
+    set_mouse_sensitivity,
+    set_gravity,
+    set_player_dimensions,
+    set_movement_acceleration,
+    set_air_control,
+    set_camera_fov,
+    set_vertical_look_limits,
+    get_player_config,
+)
+from backend.tools.rendering_tools import (
+    add_light,
+    remove_light,
+    update_light,
+    get_lights,
+    update_object_material,
+    set_background_color,
+    set_fog,
+    # Post-processing
+    set_bloom,
+    set_ssao,
+    set_color_grading,
+    set_vignette,
+    get_post_processing,
+    # Camera effects
+    set_depth_of_field,
+    set_motion_blur,
+    set_chromatic_aberration,
+    get_camera_effects,
+)
+from backend.game_models import create_vector3, create_material
+
+# Base URL for viewer links
+BASE_URL = os.getenv("SPACE_URL", "http://localhost:8000")
+
+# Create MCP server instance
+server = Server("gcp-server")
+
+
+# =============================================================================
+# Tool Definitions
+# =============================================================================
+
+SCENE_TOOLS = [
+    Tool(
+        name="create_scene",
+        description="""Create a new 3D scene/level.
+
+Args:
+    name: Name of the scene (default: "New Scene")
+    description: Optional description
+    world_width: Width of the world in units (default: 100.0)
+    world_height: Height of the world in units (default: 100.0)
+    world_depth: Depth of the world in units (default: 100.0)
+    lighting_preset: "day", "night", "sunset", or "studio" (default: "day")
+
+Returns: scene_id, viewer_url, and confirmation message""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "default": "New Scene"},
+                "description": {"type": "string"},
+                "world_width": {"type": "number", "default": 100.0},
+                "world_height": {"type": "number", "default": 100.0},
+                "world_depth": {"type": "number", "default": 100.0},
+                "lighting_preset": {
+                    "type": "string",
+                    "enum": ["day", "night", "sunset", "studio"],
+                    "default": "day"
+                },
+            },
+        },
+    ),
+    Tool(
+        name="add_object",
+        description="""Add a 3D object to the scene.
+
+Args:
+    scene_id: ID of the scene to add the object to (required)
+    object_type: "cube", "sphere", "cylinder", "plane", "cone", or "torus" (default: "cube")
+    name: Optional name for the object
+    x, y, z: Position coordinates (default: 0, 0, 0)
+    rotation_x, rotation_y, rotation_z: Rotation in degrees (default: 0, 0, 0)
+    scale_x, scale_y, scale_z: Scale factors (default: 1, 1, 1)
+    color: Hex color code like "#ff0000" for red (default: "#ffffff")
+
+Returns: object_id, scene_id, viewer_url, and confirmation message""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "object_type": {
+                    "type": "string",
+                    "enum": ["cube", "sphere", "cylinder", "plane", "cone", "torus"],
+                    "default": "cube"
+                },
+                "name": {"type": "string"},
+                "x": {"type": "number", "default": 0.0},
+                "y": {"type": "number", "default": 0.0},
+                "z": {"type": "number", "default": 0.0},
+                "rotation_x": {"type": "number", "default": 0.0},
+                "rotation_y": {"type": "number", "default": 0.0},
+                "rotation_z": {"type": "number", "default": 0.0},
+                "scale_x": {"type": "number", "default": 1.0},
+                "scale_y": {"type": "number", "default": 1.0},
+                "scale_z": {"type": "number", "default": 1.0},
+                "color": {"type": "string", "default": "#ffffff"},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="remove_object",
+        description="""Remove an object from the scene.
+
+Args:
+    scene_id: ID of the scene (required)
+    object_id: ID of the object to remove (required)
+
+Returns: scene_id, viewer_url, and confirmation message""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "object_id": {"type": "string"},
+            },
+            "required": ["scene_id", "object_id"],
+        },
+    ),
+    Tool(
+        name="set_lighting",
+        description="""Set the lighting preset for the scene.
+
+Args:
+    scene_id: ID of the scene (required)
+    preset: "day", "night", "sunset", or "studio" (default: "day")
+
+Returns: scene_id, viewer_url, and confirmation message""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "preset": {
+                    "type": "string",
+                    "enum": ["day", "night", "sunset", "studio"],
+                    "default": "day"
+                },
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="get_scene_info",
+        description="""Get detailed information about a scene.
+
+Args:
+    scene_id: ID of the scene to retrieve (required)
+
+Returns: scene details including name, objects, lights, and viewer_url""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+]
+
+PLAYER_TOOLS = [
+    Tool(
+        name="set_player_speed",
+        description="""Set the player's movement speed.
+
+Args:
+    scene_id: ID of the scene (required)
+    walk_speed: Movement speed in units/second (default: 5.0)
+
+Example: set_player_speed(scene_id, walk_speed=8.0) for faster movement""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "walk_speed": {"type": "number", "default": 5.0},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_jump_force",
+        description="""Configure jump height by setting initial upward velocity.
+
+Args:
+    scene_id: ID of the scene (required)
+    jump_force: Initial jump velocity in m/s (default: 5.0, higher = higher jumps)
+
+Example: set_jump_force(scene_id, jump_force=7.0) for higher jumps""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "jump_force": {"type": "number", "default": 5.0},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_mouse_sensitivity",
+        description="""Configure mouse look sensitivity and Y-axis inversion.
+
+Args:
+    scene_id: ID of the scene (required)
+    sensitivity: Mouse sensitivity multiplier (default: 0.002, lower = more precise)
+    invert_y: Invert vertical look, flight-sim style (default: false)
+
+Example: set_mouse_sensitivity(scene_id, sensitivity=0.001) for precise aiming""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "sensitivity": {"type": "number", "default": 0.002},
+                "invert_y": {"type": "boolean", "default": False},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_gravity",
+        description="""Set the world's gravity strength.
+
+Args:
+    scene_id: ID of the scene (required)
+    gravity: Gravity in m/s² (default: -9.82 = Earth, negative = downward)
+
+Examples:
+    -9.82 = Earth gravity (default)
+    -1.62 = Moon gravity (floaty)
+    -3.7 = Mars gravity
+    -20.0 = Heavy gravity""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "gravity": {"type": "number", "default": -9.82},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_player_dimensions",
+        description="""Configure player collision capsule dimensions.
+
+Args:
+    scene_id: ID of the scene (required)
+    height: Player height in meters (default: 1.7)
+    radius: Player radius in meters (default: 0.3)
+    eye_height: Camera height from feet (default: height - 0.1)
+
+Example: set_player_dimensions(scene_id, height=1.2, radius=0.25) for child-sized""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "height": {"type": "number", "default": 1.7},
+                "radius": {"type": "number", "default": 0.3},
+                "eye_height": {"type": "number"},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_movement_acceleration",
+        description="""Configure how quickly player reaches max speed and movement friction.
+
+Args:
+    scene_id: ID of the scene (required)
+    acceleration: Time to reach max speed (0.0=instant, 0.5=snappy, 1.0=sliding)
+    damping: Linear damping/friction (0.0-1.0, higher=more friction, default: 0.9)
+
+Example: set_movement_acceleration(scene_id, acceleration=0.3, damping=0.5) for sliding feel""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "acceleration": {"type": "number", "default": 0.0},
+                "damping": {"type": "number", "default": 0.9},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_air_control",
+        description="""Configure movement control while airborne (jumping/falling).
+
+Args:
+    scene_id: ID of the scene (required)
+    air_control_factor: Control while airborne 0.0-1.0 (default: 1.0)
+        1.0 = full control (typical FPS)
+        0.0 = no air steering (realistic)
+
+Example: set_air_control(scene_id, air_control_factor=0.3) for limited air control""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "air_control_factor": {"type": "number", "default": 1.0},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_camera_fov",
+        description="""Set the camera field of view.
+
+Args:
+    scene_id: ID of the scene (required)
+    fov: Field of view in degrees (default: 75)
+        60-70 = narrow/zoomed (competitive shooters)
+        75-85 = normal (most games)
+        90-120 = wide/"quake pro" style
+
+Example: set_camera_fov(scene_id, fov=90.0) for wide angle""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "fov": {"type": "number", "default": 75.0},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_vertical_look_limits",
+        description="""Configure how far up and down the player can look.
+
+Args:
+    scene_id: ID of the scene (required)
+    min_pitch: Min angle in degrees, looking down (default: -89)
+    max_pitch: Max angle in degrees, looking up (default: 89)
+
+Example: set_vertical_look_limits(scene_id, min_pitch=-45, max_pitch=45) for restricted""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "min_pitch": {"type": "number", "default": -89.0},
+                "max_pitch": {"type": "number", "default": 89.0},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="get_player_config",
+        description="""Get the current player controller configuration.
+
+Args:
+    scene_id: ID of the scene (required)
+
+Returns: All player settings (speed, jump, gravity, dimensions, etc.)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+]
+
+RENDERING_TOOLS = [
+    Tool(
+        name="add_light",
+        description="""Add a new light source to the scene.
+
+Args:
+    scene_id: Scene to modify (required)
+    light_type: "ambient", "directional", "point", or "spot" (required)
+    name: Unique identifier like "Torch1", "MainLight" (required)
+    color: Hex color code (default: "#ffffff")
+    intensity: Brightness 0.0-2.0 (default: 1.0)
+    position: {x, y, z} for directional/point/spot lights
+    target: {x, y, z} where directional/spot lights point
+    cast_shadow: Enable shadows (default: false)
+    spot_angle: Cone angle in degrees for spot lights (default: 45)
+
+Examples:
+    add_light(scene_id, "point", "Torch", "#ff6600", 1.5, {x:2, y:3, z:0})
+    add_light(scene_id, "ambient", "Fill", "#aaaaaa", 0.3)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "light_type": {
+                    "type": "string",
+                    "enum": ["ambient", "directional", "point", "spot"]
+                },
+                "name": {"type": "string"},
+                "color": {"type": "string", "default": "#ffffff"},
+                "intensity": {"type": "number", "default": 1.0},
+                "position": {
+                    "type": "object",
+                    "properties": {
+                        "x": {"type": "number"},
+                        "y": {"type": "number"},
+                        "z": {"type": "number"},
+                    }
+                },
+                "target": {
+                    "type": "object",
+                    "properties": {
+                        "x": {"type": "number"},
+                        "y": {"type": "number"},
+                        "z": {"type": "number"},
+                    }
+                },
+                "cast_shadow": {"type": "boolean", "default": False},
+                "spot_angle": {"type": "number", "default": 45.0},
+            },
+            "required": ["scene_id", "light_type", "name"],
+        },
+    ),
+    Tool(
+        name="remove_light",
+        description="""Remove a light from the scene.
+
+Args:
+    scene_id: Scene to modify (required)
+    light_name: Name of the light to remove (required)
+
+Example: remove_light(scene_id, "Torch1")""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "light_name": {"type": "string"},
+            },
+            "required": ["scene_id", "light_name"],
+        },
+    ),
+    Tool(
+        name="update_light",
+        description="""Update existing light properties.
+
+Args:
+    scene_id: Scene to modify (required)
+    light_name: Name of light to update (required)
+    color: New hex color (optional)
+    intensity: New brightness 0.0-2.0 (optional)
+    position: New {x, y, z} position (optional)
+    cast_shadow: Enable/disable shadows (optional)
+
+Example: update_light(scene_id, "Sun", color="#ffaa00", intensity=0.8)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "light_name": {"type": "string"},
+                "color": {"type": "string"},
+                "intensity": {"type": "number"},
+                "position": {
+                    "type": "object",
+                    "properties": {
+                        "x": {"type": "number"},
+                        "y": {"type": "number"},
+                        "z": {"type": "number"},
+                    }
+                },
+                "cast_shadow": {"type": "boolean"},
+            },
+            "required": ["scene_id", "light_name"],
+        },
+    ),
+    Tool(
+        name="get_lights",
+        description="""Get all lights in the scene.
+
+Args:
+    scene_id: Scene to query (required)
+
+Returns: List of all lights with their properties""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="update_object_material",
+        description="""Update an object's material properties.
+
+Args:
+    scene_id: Scene to modify (required)
+    object_id: ID of object to update (required)
+    color: Hex color code (optional)
+    metalness: 0.0 (matte) to 1.0 (metal) (optional)
+    roughness: 0.0 (shiny) to 1.0 (rough) (optional)
+    opacity: 0.0 (invisible) to 1.0 (solid) (optional)
+    emissive: Hex color for self-glow (optional)
+    emissive_intensity: Glow brightness 0.0-1.0 (optional)
+
+Examples:
+    update_object_material(scene_id, object_id, color="#ff0000")
+    update_object_material(scene_id, object_id, metalness=0.9, roughness=0.1)
+    update_object_material(scene_id, object_id, emissive="#00ffff", emissive_intensity=0.8)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "object_id": {"type": "string"},
+                "color": {"type": "string"},
+                "metalness": {"type": "number"},
+                "roughness": {"type": "number"},
+                "opacity": {"type": "number"},
+                "emissive": {"type": "string"},
+                "emissive_intensity": {"type": "number"},
+            },
+            "required": ["scene_id", "object_id"],
+        },
+    ),
+    Tool(
+        name="set_background_color",
+        description="""Set scene background color or gradient.
+
+Args:
+    scene_id: Scene to modify (required)
+    color: Hex color for solid background
+    bg_type: "solid" or "gradient" (default: "solid")
+    gradient_top: Top hex color for gradient
+    gradient_bottom: Bottom hex color for gradient
+
+Examples:
+    set_background_color(scene_id, color="#000000")  # Black
+    set_background_color(scene_id, bg_type="gradient", gradient_top="#87CEEB", gradient_bottom="#FFE4B5")""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "color": {"type": "string"},
+                "bg_type": {
+                    "type": "string",
+                    "enum": ["solid", "gradient"],
+                    "default": "solid"
+                },
+                "gradient_top": {"type": "string"},
+                "gradient_bottom": {"type": "string"},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+    Tool(
+        name="set_fog",
+        description="""Add atmospheric fog to the scene.
+
+Args:
+    scene_id: Scene to modify (required)
+    enabled: Enable or disable fog (required)
+    color: Hex color of fog (default: "#aaaaaa")
+    near: Start distance for linear fog
+    far: End distance for linear fog
+    density: Density for exponential fog (overrides near/far)
+
+Examples:
+    set_fog(scene_id, enabled=True, color="#aaaaaa", near=10, far=50)
+    set_fog(scene_id, enabled=True, density=0.05)  # Exponential
+    set_fog(scene_id, enabled=False)  # Disable""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "enabled": {"type": "boolean"},
+                "color": {"type": "string", "default": "#aaaaaa"},
+                "near": {"type": "number"},
+                "far": {"type": "number"},
+                "density": {"type": "number"},
+            },
+            "required": ["scene_id", "enabled"],
+        },
+    ),
+]
+
+POST_PROCESSING_TOOLS = [
+    Tool(
+        name="set_bloom",
+        description="""Configure bloom (glow) post-processing effect.
+
+Args:
+    scene_id: Scene to modify (required)
+    enabled: Enable/disable bloom (required)
+    strength: Bloom intensity 0.0-3.0 (default: 1.0)
+    radius: Bloom spread/blur radius 0.0-1.0 (default: 0.4)
+    threshold: Brightness threshold to trigger bloom 0.0-1.0 (default: 0.8)
+
+Example: set_bloom(scene_id, enabled=True, strength=1.5, threshold=0.6)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "enabled": {"type": "boolean"},
+                "strength": {"type": "number", "default": 1.0},
+                "radius": {"type": "number", "default": 0.4},
+                "threshold": {"type": "number", "default": 0.8},
+            },
+            "required": ["scene_id", "enabled"],
+        },
+    ),
+    Tool(
+        name="set_ssao",
+        description="""Configure Screen Space Ambient Occlusion (SSAO).
+
+Adds soft shadows in corners and crevices for depth and realism.
+
+Args:
+    scene_id: Scene to modify (required)
+    enabled: Enable/disable SSAO (required)
+    radius: Sample radius in world units 0.1-2.0 (default: 0.5)
+    intensity: Shadow intensity 0.0-2.0 (default: 1.0)
+    bias: Depth bias to prevent self-occlusion 0.001-0.1 (default: 0.025)
+
+Example: set_ssao(scene_id, enabled=True, intensity=1.5)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "enabled": {"type": "boolean"},
+                "radius": {"type": "number", "default": 0.5},
+                "intensity": {"type": "number", "default": 1.0},
+                "bias": {"type": "number", "default": 0.025},
+            },
+            "required": ["scene_id", "enabled"],
+        },
+    ),
+    Tool(
+        name="set_color_grading",
+        description="""Configure color grading post-processing.
+
+Adjust overall image colors for cinematic looks or stylized effects.
+
+Args:
+    scene_id: Scene to modify (required)
+    enabled: Enable/disable color grading (required)
+    brightness: Brightness adjustment -1.0 to 1.0 (default: 0.0)
+    contrast: Contrast multiplier 0.0-2.0 (default: 1.0)
+    saturation: Color saturation 0.0-2.0 (default: 1.0)
+    hue: Hue shift in degrees -180 to 180 (default: 0)
+    exposure: Exposure adjustment 0.0-3.0 (default: 1.0)
+    gamma: Gamma correction 0.5-2.5 (default: 1.0)
+
+Example: set_color_grading(scene_id, enabled=True, saturation=0.5) for desaturated look""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "enabled": {"type": "boolean"},
+                "brightness": {"type": "number", "default": 0.0},
+                "contrast": {"type": "number", "default": 1.0},
+                "saturation": {"type": "number", "default": 1.0},
+                "hue": {"type": "number", "default": 0.0},
+                "exposure": {"type": "number", "default": 1.0},
+                "gamma": {"type": "number", "default": 1.0},
+            },
+            "required": ["scene_id", "enabled"],
+        },
+    ),
+    Tool(
+        name="set_vignette",
+        description="""Configure vignette effect (darkened edges).
+
+Darkens corners and edges of the screen, drawing focus to the center.
+
+Args:
+    scene_id: Scene to modify (required)
+    enabled: Enable/disable vignette (required)
+    intensity: Darkness of the vignette 0.0-1.0 (default: 0.5)
+    smoothness: Softness of the vignette edge 0.0-1.0 (default: 0.5)
+
+Example: set_vignette(scene_id, enabled=True, intensity=0.7)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "enabled": {"type": "boolean"},
+                "intensity": {"type": "number", "default": 0.5},
+                "smoothness": {"type": "number", "default": 0.5},
+            },
+            "required": ["scene_id", "enabled"],
+        },
+    ),
+    Tool(
+        name="get_post_processing",
+        description="""Get all post-processing settings for the scene.
+
+Args:
+    scene_id: Scene to query (required)
+
+Returns: All post-processing settings (bloom, SSAO, color grading, vignette)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+]
+
+CAMERA_EFFECTS_TOOLS = [
+    Tool(
+        name="set_depth_of_field",
+        description="""Configure depth of field (DoF) camera effect.
+
+Blurs objects that are not at the focus distance, simulating real camera lenses.
+
+Args:
+    scene_id: Scene to modify (required)
+    enabled: Enable/disable depth of field (required)
+    focus_distance: Distance to the focal plane in units (default: 10.0)
+    aperture: Aperture size, affects blur amount 0.001-0.1 (default: 0.025)
+    max_blur: Maximum blur strength 0.0-0.05 (default: 0.01)
+
+Example: set_depth_of_field(scene_id, enabled=True, focus_distance=5.0)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "enabled": {"type": "boolean"},
+                "focus_distance": {"type": "number", "default": 10.0},
+                "aperture": {"type": "number", "default": 0.025},
+                "max_blur": {"type": "number", "default": 0.01},
+            },
+            "required": ["scene_id", "enabled"],
+        },
+    ),
+    Tool(
+        name="set_motion_blur",
+        description="""Configure motion blur camera effect.
+
+Adds blur in the direction of camera or object movement.
+
+Args:
+    scene_id: Scene to modify (required)
+    enabled: Enable/disable motion blur (required)
+    intensity: Blur intensity 0.0-2.0 (default: 0.5)
+    samples: Quality samples for blur 4-32 (default: 8)
+
+Example: set_motion_blur(scene_id, enabled=True, intensity=0.8)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "enabled": {"type": "boolean"},
+                "intensity": {"type": "number", "default": 0.5},
+                "samples": {"type": "integer", "default": 8},
+            },
+            "required": ["scene_id", "enabled"],
+        },
+    ),
+    Tool(
+        name="set_chromatic_aberration",
+        description="""Configure chromatic aberration effect.
+
+Simulates lens imperfection by separating color channels at the edges.
+
+Args:
+    scene_id: Scene to modify (required)
+    enabled: Enable/disable chromatic aberration (required)
+    intensity: Effect strength 0.0-0.05 (default: 0.005)
+
+Example: set_chromatic_aberration(scene_id, enabled=True, intensity=0.01)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+                "enabled": {"type": "boolean"},
+                "intensity": {"type": "number", "default": 0.005},
+            },
+            "required": ["scene_id", "enabled"],
+        },
+    ),
+    Tool(
+        name="get_camera_effects",
+        description="""Get all camera effects settings for the scene.
+
+Args:
+    scene_id: Scene to query (required)
+
+Returns: All camera effects settings (depth of field, motion blur, chromatic aberration)""",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "scene_id": {"type": "string"},
+            },
+            "required": ["scene_id"],
+        },
+    ),
+]
+
+# Combine all tools
+ALL_TOOLS = SCENE_TOOLS + PLAYER_TOOLS + RENDERING_TOOLS + POST_PROCESSING_TOOLS + CAMERA_EFFECTS_TOOLS
+
+
+# =============================================================================
+# MCP Handlers
+# =============================================================================
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    """Return all available GCP tools."""
+    return ALL_TOOLS
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    """Handle tool calls from MCP clients."""
+    try:
+        result = await _execute_tool(name, arguments)
+        return [TextContent(type="text", text=str(result))]
+    except Exception as e:
+        return [TextContent(type="text", text=f"Error: {str(e)}")]
+
+
+async def _execute_tool(name: str, args: dict) -> Any:
+    """Route tool calls to their implementations."""
+
+    # Scene tools
+    if name == "create_scene":
+        return create_game_scene(
+            name=args.get("name", "New Scene"),
+            description=args.get("description"),
+            world_width=args.get("world_width", 100.0),
+            world_height=args.get("world_height", 100.0),
+            world_depth=args.get("world_depth", 100.0),
+            lighting_preset=args.get("lighting_preset", "day"),
+            base_url=BASE_URL,
+        )
+
+    elif name == "add_object":
+        return add_game_object(
+            scene_id=args["scene_id"],
+            object_type=args.get("object_type", "cube"),
+            name=args.get("name"),
+            position=create_vector3(
+                args.get("x", 0.0),
+                args.get("y", 0.0),
+                args.get("z", 0.0)
+            ),
+            rotation=create_vector3(
+                args.get("rotation_x", 0.0),
+                args.get("rotation_y", 0.0),
+                args.get("rotation_z", 0.0)
+            ),
+            scale=create_vector3(
+                args.get("scale_x", 1.0),
+                args.get("scale_y", 1.0),
+                args.get("scale_z", 1.0)
+            ),
+            material=create_material(color=args.get("color", "#ffffff")),
+            base_url=BASE_URL,
+        )
+
+    elif name == "remove_object":
+        return remove_game_object(
+            scene_id=args["scene_id"],
+            object_id=args["object_id"],
+            base_url=BASE_URL,
+        )
+
+    elif name == "set_lighting":
+        return set_scene_lighting(
+            scene_id=args["scene_id"],
+            preset=args.get("preset", "day"),
+            base_url=BASE_URL,
+        )
+
+    elif name == "get_scene_info":
+        return get_scene_info(args["scene_id"], BASE_URL)
+
+    # Player tools
+    elif name == "set_player_speed":
+        return set_player_speed(
+            args["scene_id"],
+            args.get("walk_speed", 5.0)
+        )
+
+    elif name == "set_jump_force":
+        return set_jump_force(
+            args["scene_id"],
+            args.get("jump_force", 5.0)
+        )
+
+    elif name == "set_mouse_sensitivity":
+        return set_mouse_sensitivity(
+            args["scene_id"],
+            args.get("sensitivity", 0.002),
+            args.get("invert_y", False)
+        )
+
+    elif name == "set_gravity":
+        return set_gravity(
+            args["scene_id"],
+            args.get("gravity", -9.82)
+        )
+
+    elif name == "set_player_dimensions":
+        return set_player_dimensions(
+            args["scene_id"],
+            args.get("height", 1.7),
+            args.get("radius", 0.3),
+            args.get("eye_height")
+        )
+
+    elif name == "set_movement_acceleration":
+        return set_movement_acceleration(
+            args["scene_id"],
+            args.get("acceleration", 0.0),
+            args.get("damping", 0.9)
+        )
+
+    elif name == "set_air_control":
+        return set_air_control(
+            args["scene_id"],
+            args.get("air_control_factor", 1.0)
+        )
+
+    elif name == "set_camera_fov":
+        return set_camera_fov(
+            args["scene_id"],
+            args.get("fov", 75.0)
+        )
+
+    elif name == "set_vertical_look_limits":
+        return set_vertical_look_limits(
+            args["scene_id"],
+            args.get("min_pitch", -89.0),
+            args.get("max_pitch", 89.0)
+        )
+
+    elif name == "get_player_config":
+        return get_player_config(args["scene_id"])
+
+    # Rendering tools
+    elif name == "add_light":
+        return add_light(
+            args["scene_id"],
+            args["light_type"],
+            args["name"],
+            args.get("color", "#ffffff"),
+            args.get("intensity", 1.0),
+            args.get("position"),
+            args.get("target"),
+            args.get("cast_shadow", False),
+            args.get("spot_angle")
+        )
+
+    elif name == "remove_light":
+        return remove_light(
+            args["scene_id"],
+            args["light_name"]
+        )
+
+    elif name == "update_light":
+        return update_light(
+            args["scene_id"],
+            args["light_name"],
+            args.get("color"),
+            args.get("intensity"),
+            args.get("position"),
+            args.get("cast_shadow")
+        )
+
+    elif name == "get_lights":
+        return get_lights(args["scene_id"])
+
+    elif name == "update_object_material":
+        return update_object_material(
+            args["scene_id"],
+            args["object_id"],
+            args.get("color"),
+            args.get("metalness"),
+            args.get("roughness"),
+            args.get("opacity"),
+            args.get("emissive"),
+            args.get("emissive_intensity")
+        )
+
+    elif name == "set_background_color":
+        return set_background_color(
+            args["scene_id"],
+            args.get("color"),
+            args.get("bg_type", "solid"),
+            args.get("gradient_top"),
+            args.get("gradient_bottom")
+        )
+
+    elif name == "set_fog":
+        return set_fog(
+            args["scene_id"],
+            args["enabled"],
+            args.get("color"),
+            args.get("near"),
+            args.get("far"),
+            args.get("density")
+        )
+
+    # Post-processing tools
+    elif name == "set_bloom":
+        return set_bloom(
+            args["scene_id"],
+            args["enabled"],
+            args.get("strength", 1.0),
+            args.get("radius", 0.4),
+            args.get("threshold", 0.8)
+        )
+
+    elif name == "set_ssao":
+        return set_ssao(
+            args["scene_id"],
+            args["enabled"],
+            args.get("radius", 0.5),
+            args.get("intensity", 1.0),
+            args.get("bias", 0.025)
+        )
+
+    elif name == "set_color_grading":
+        return set_color_grading(
+            args["scene_id"],
+            args["enabled"],
+            args.get("brightness", 0.0),
+            args.get("contrast", 1.0),
+            args.get("saturation", 1.0),
+            args.get("hue", 0.0),
+            args.get("exposure", 1.0),
+            args.get("gamma", 1.0)
+        )
+
+    elif name == "set_vignette":
+        return set_vignette(
+            args["scene_id"],
+            args["enabled"],
+            args.get("intensity", 0.5),
+            args.get("smoothness", 0.5)
+        )
+
+    elif name == "get_post_processing":
+        return get_post_processing(args["scene_id"])
+
+    # Camera effects tools
+    elif name == "set_depth_of_field":
+        return set_depth_of_field(
+            args["scene_id"],
+            args["enabled"],
+            args.get("focus_distance", 10.0),
+            args.get("aperture", 0.025),
+            args.get("max_blur", 0.01)
+        )
+
+    elif name == "set_motion_blur":
+        return set_motion_blur(
+            args["scene_id"],
+            args["enabled"],
+            args.get("intensity", 0.5),
+            args.get("samples", 8)
+        )
+
+    elif name == "set_chromatic_aberration":
+        return set_chromatic_aberration(
+            args["scene_id"],
+            args["enabled"],
+            args.get("intensity", 0.005)
+        )
+
+    elif name == "get_camera_effects":
+        return get_camera_effects(args["scene_id"])
+
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+
+# =============================================================================
+# Server runner (for standalone MCP mode)
+# =============================================================================
+
+async def run_stdio():
+    """Run the MCP server using stdio transport."""
+    from mcp.server.stdio import stdio_server
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options()
+        )
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(run_stdio())

backend/storage.py

@@ -0,0 +1,101 @@
+"""
+In-memory storage for game scenes
+"""
+from typing import Dict, Optional, Any
+from datetime import datetime
+
+
+class Storage:
+    """Simple in-memory storage for game scenes using plain dictionaries"""
+
+    def __init__(self):
+        self._scenes: Dict[str, Dict[str, Any]] = {}
+
+    def save(self, scene: Dict[str, Any]) -> Dict[str, Any]:
+        """Save or update a scene"""
+        if not isinstance(scene, dict):
+            raise ValueError("Scene must be a dictionary")
+
+        if "scene_id" not in scene:
+            raise ValueError("Scene must have a 'scene_id' key")
+
+        # Update timestamp
+        scene["updated_at"] = datetime.utcnow().isoformat()
+
+        self._scenes[scene["scene_id"]] = scene
+        return scene
+
+    def get(self, scene_id: str) -> Optional[Dict[str, Any]]:
+        """Retrieve a scene by ID"""
+        return self._scenes.get(scene_id)
+
+    def delete(self, scene_id: str) -> bool:
+        """Delete a scene"""
+        if scene_id in self._scenes:
+            del self._scenes[scene_id]
+            return True
+        return False
+
+    def list_all(self) -> list[Dict[str, Any]]:
+        """List all scenes"""
+        return list(self._scenes.values())
+
+    def exists(self, scene_id: str) -> bool:
+        """Check if scene exists"""
+        return scene_id in self._scenes
+
+
+# Global storage instance
+storage = Storage()
+
+
+# Initialize with a clean default Welcome Scene for HuggingFace Spaces
+def initialize_default_scene():
+    """Create a clean default Welcome Scene on startup"""
+    from backend.game_models import create_scene, create_light, create_environment, create_vector3
+
+    # Create lights for day preset
+    lights = [
+        create_light(
+            name="Sun",
+            light_type="directional",
+            color="#ffffff",
+            intensity=1.0,
+            position=create_vector3(50, 50, 50),
+        ),
+        create_light(
+            name="Ambient",
+            light_type="ambient",
+            color="#ffffff",
+            intensity=0.5,
+        ),
+    ]
+
+    # Create environment
+    env = create_environment(lighting_preset="day")
+
+    # Create clean scene with NO default objects
+    # Ground plane and walls are created by physics system in viewer
+    scene = create_scene(
+        name="Welcome Scene",
+        description="Clean 10x10 FPS world with physics - Ready to explore!",
+        world_width=10,
+        world_height=10,
+        world_depth=10,
+        lights=lights,
+        environment=env,
+    )
+
+    # Use a predictable scene ID for easy linking
+    scene["scene_id"] = "welcome"
+
+    # Save to storage
+    storage.save(scene)
+    print(f"✓ Initialized default Welcome Scene (ID: welcome)")
+    print(f"  - 10x10 world with FPS physics controller")
+    print(f"  - Ground plane + boundary walls (created by viewer)")
+    print(f"  - Player spawn at (0, 1, 0)")
+
+
+# Initialize on module load
+initialize_default_scene()

backend/tools/__init__.py

@@ -0,0 +1,89 @@
+"""
+GCP Tools - Game Context Protocol Tool Implementations
+
+Organized by domain:
+- scene_tools: Create, modify, and query 3D scenes
+- player_tools: Configure FPS player controller
+- rendering_tools: Lights, materials, backgrounds, fog
+"""
+
+from backend.tools.scene_tools import (
+    create_game_scene,
+    add_game_object,
+    remove_game_object,
+    set_scene_lighting,
+    get_scene_info,
+)
+
+from backend.tools.player_tools import (
+    set_player_speed,
+    set_jump_force,
+    set_mouse_sensitivity,
+    set_gravity,
+    set_player_dimensions,
+    set_movement_acceleration,
+    set_air_control,
+    set_camera_fov,
+    set_vertical_look_limits,
+    get_player_config,
+)
+
+from backend.tools.rendering_tools import (
+    add_light,
+    remove_light,
+    update_light,
+    get_lights,
+    update_object_material,
+    set_background_color,
+    set_fog,
+    # Post-processing
+    set_bloom,
+    set_ssao,
+    set_color_grading,
+    set_vignette,
+    get_post_processing,
+    # Camera effects
+    set_depth_of_field,
+    set_motion_blur,
+    set_chromatic_aberration,
+    get_camera_effects,
+)
+
+__all__ = [
+    # Scene tools
+    "create_game_scene",
+    "add_game_object",
+    "remove_game_object",
+    "set_scene_lighting",
+    "get_scene_info",
+    # Player tools
+    "set_player_speed",
+    "set_jump_force",
+    "set_mouse_sensitivity",
+    "set_gravity",
+    "set_player_dimensions",
+    "set_movement_acceleration",
+    "set_air_control",
+    "set_camera_fov",
+    "set_vertical_look_limits",
+    "get_player_config",
+    # Rendering tools
+    "add_light",
+    "remove_light",
+    "update_light",
+    "get_lights",
+    "update_object_material",
+    "set_background_color",
+    "set_fog",
+    # Post-processing tools
+    "set_bloom",
+    "set_ssao",
+    "set_color_grading",
+    "set_vignette",
+    "get_post_processing",
+    # Camera effects tools
+    "set_depth_of_field",
+    "set_motion_blur",
+    "set_chromatic_aberration",
+    "get_camera_effects",
+]

backend/tools/player_tools.py

@@ -0,0 +1,347 @@
+"""
+Player Controller Tools
+Configure first-person character movement, physics, and camera settings
+"""
+from typing import Dict, Any, Optional
+from backend.storage import storage
+
+
+def set_player_speed(scene_id: str, walk_speed: float) -> Dict[str, Any]:
+    """
+    Implementation: Set player walking/movement speed
+
+    Args:
+        scene_id: ID of the scene
+        walk_speed: Movement speed in units/second
+
+    Returns:
+        Dictionary with updated speed and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    # Initialize player_config if it doesn't exist
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    scene["player_config"]["move_speed"] = walk_speed
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": f"Set player movement speed to {walk_speed} units/sec",
+        "move_speed": walk_speed,
+    }
+
+
+def set_jump_force(scene_id: str, jump_force: float) -> Dict[str, Any]:
+    """
+    Implementation: Configure jump height via initial upward velocity
+
+    Args:
+        scene_id: ID of the scene
+        jump_force: Initial jump velocity in m/s (higher = higher jumps)
+
+    Returns:
+        Dictionary with updated jump force and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    scene["player_config"]["jump_force"] = jump_force
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": f"Set jump force to {jump_force} m/s",
+        "jump_force": jump_force,
+    }
+
+
+def set_mouse_sensitivity(
+    scene_id: str,
+    sensitivity: float,
+    invert_y: bool
+) -> Dict[str, Any]:
+    """
+    Implementation: Configure mouse look sensitivity and Y-axis inversion
+
+    Args:
+        scene_id: ID of the scene
+        sensitivity: Mouse sensitivity multiplier (lower = slower/more precise)
+        invert_y: Whether to invert vertical look (flight sim style)
+
+    Returns:
+        Dictionary with updated settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    scene["player_config"]["mouse_sensitivity"] = sensitivity
+    scene["player_config"]["invert_y"] = invert_y
+    storage.save(scene)
+
+    invert_msg = "enabled" if invert_y else "disabled"
+    return {
+        "scene_id": scene_id,
+        "message": f"Set mouse sensitivity to {sensitivity}, Y-invert {invert_msg}",
+        "mouse_sensitivity": sensitivity,
+        "invert_y": invert_y,
+    }
+
+
+def set_gravity(scene_id: str, gravity: float) -> Dict[str, Any]:
+    """
+    Implementation: Set world gravity strength
+
+    Args:
+        scene_id: ID of the scene
+        gravity: Gravity acceleration in m/s² (negative = downward, -9.82 = Earth)
+
+    Returns:
+        Dictionary with updated gravity and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    scene["player_config"]["gravity"] = gravity
+    storage.save(scene)
+
+    gravity_desc = "Earth-like" if abs(gravity + 9.82) < 0.1 else "custom"
+    return {
+        "scene_id": scene_id,
+        "message": f"Set gravity to {gravity} m/s² ({gravity_desc})",
+        "gravity": gravity,
+    }
+
+
+def set_player_dimensions(
+    scene_id: str,
+    height: float,
+    radius: float,
+    eye_height: Optional[float] = None
+) -> Dict[str, Any]:
+    """
+    Implementation: Configure player collision capsule dimensions
+
+    Args:
+        scene_id: ID of the scene
+        height: Player height in meters (affects collision capsule)
+        radius: Player radius in meters (affects collision capsule width)
+        eye_height: Camera height from feet (defaults to height - 0.1m if not specified)
+
+    Returns:
+        Dictionary with updated dimensions and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    # Default eye height to slightly below top of head
+    if eye_height is None:
+        eye_height = height - 0.1
+
+    scene["player_config"]["player_height"] = height
+    scene["player_config"]["player_radius"] = radius
+    scene["player_config"]["eye_height"] = eye_height
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": f"Set player dimensions: height={height}m, radius={radius}m, eye_height={eye_height}m",
+        "player_height": height,
+        "player_radius": radius,
+        "eye_height": eye_height,
+    }
+
+
+def set_movement_acceleration(
+    scene_id: str,
+    acceleration: float,
+    damping: float
+) -> Dict[str, Any]:
+    """
+    Implementation: Configure movement acceleration and damping
+
+    Args:
+        scene_id: ID of the scene
+        acceleration: How quickly player reaches max speed (0.0=instant, higher=slower)
+        damping: Linear damping/air resistance (0.0-1.0, higher=more friction)
+
+    Returns:
+        Dictionary with updated settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    scene["player_config"]["movement_acceleration"] = acceleration
+    scene["player_config"]["linear_damping"] = damping
+    storage.save(scene)
+
+    feel = "instant" if acceleration < 0.1 else ("snappy" if acceleration < 0.5 else "sliding")
+    return {
+        "scene_id": scene_id,
+        "message": f"Set movement acceleration={acceleration}, damping={damping} ({feel} feel)",
+        "movement_acceleration": acceleration,
+        "linear_damping": damping,
+    }
+
+
+def set_air_control(scene_id: str, air_control_factor: float) -> Dict[str, Any]:
+    """
+    Implementation: Configure movement control while airborne
+
+    Args:
+        scene_id: ID of the scene
+        air_control_factor: Movement control while airborne (0.0-1.0)
+                          1.0 = full control, 0.0 = no air steering
+
+    Returns:
+        Dictionary with updated setting and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    # Clamp between 0 and 1
+    air_control_factor = max(0.0, min(1.0, air_control_factor))
+
+    scene["player_config"]["air_control"] = air_control_factor
+    storage.save(scene)
+
+    control_desc = "full" if air_control_factor >= 0.9 else ("limited" if air_control_factor >= 0.3 else "none")
+    return {
+        "scene_id": scene_id,
+        "message": f"Set air control to {air_control_factor} ({control_desc} control)",
+        "air_control": air_control_factor,
+    }
+
+
+def set_camera_fov(scene_id: str, fov: float) -> Dict[str, Any]:
+    """
+    Implementation: Set camera field of view
+
+    Args:
+        scene_id: ID of the scene
+        fov: Field of view in degrees (typical: 60-90, default: 75)
+
+    Returns:
+        Dictionary with updated FOV and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    # Clamp FOV to reasonable range
+    fov = max(30.0, min(120.0, fov))
+
+    scene["player_config"]["camera_fov"] = fov
+    storage.save(scene)
+
+    style = "narrow" if fov < 70 else ("normal" if fov < 90 else "wide")
+    return {
+        "scene_id": scene_id,
+        "message": f"Set camera FOV to {fov}° ({style})",
+        "camera_fov": fov,
+    }
+
+
+def set_vertical_look_limits(
+    scene_id: str,
+    min_pitch: float,
+    max_pitch: float
+) -> Dict[str, Any]:
+    """
+    Implementation: Configure vertical look angle limits
+
+    Args:
+        scene_id: ID of the scene
+        min_pitch: Minimum pitch angle in degrees (looking down, negative)
+        max_pitch: Maximum pitch angle in degrees (looking up, positive)
+
+    Returns:
+        Dictionary with updated limits and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "player_config" not in scene:
+        scene["player_config"] = {}
+
+    scene["player_config"]["min_pitch"] = min_pitch
+    scene["player_config"]["max_pitch"] = max_pitch
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": f"Set vertical look limits: {min_pitch}° to {max_pitch}°",
+        "min_pitch": min_pitch,
+        "max_pitch": max_pitch,
+    }
+
+
+def get_player_config(scene_id: str) -> Dict[str, Any]:
+    """
+    Implementation: Get current player configuration
+
+    Args:
+        scene_id: ID of the scene
+
+    Returns:
+        Dictionary with all player config values
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    player_config = scene.get("player_config", {})
+
+    # Return with defaults if not set
+    return {
+        "scene_id": scene_id,
+        "player_config": {
+            # Phase 1
+            "move_speed": player_config.get("move_speed", 5.0),
+            "jump_force": player_config.get("jump_force", 5.0),
+            "mouse_sensitivity": player_config.get("mouse_sensitivity", 0.002),
+            "invert_y": player_config.get("invert_y", False),
+            "gravity": player_config.get("gravity", -9.82),
+            "player_height": player_config.get("player_height", 1.7),
+            "player_radius": player_config.get("player_radius", 0.3),
+            "eye_height": player_config.get("eye_height", 1.6),
+            # Phase 2
+            "movement_acceleration": player_config.get("movement_acceleration", 0.0),
+            "linear_damping": player_config.get("linear_damping", 0.9),
+            "air_control": player_config.get("air_control", 1.0),
+            "camera_fov": player_config.get("camera_fov", 75.0),
+            "min_pitch": player_config.get("min_pitch", -89.0),
+            "max_pitch": player_config.get("max_pitch", 89.0),
+        }
+    }

backend/tools/rendering_tools.py

@@ -0,0 +1,848 @@
+"""
+Rendering & Lighting Tools
+Fine-grained control over scene lighting, materials, background, fog,
+post-processing effects, and camera effects.
+"""
+from typing import Dict, Any, Optional
+from backend.storage import storage
+
+
+def add_light(
+    scene_id: str,
+    light_type: str,
+    name: str,
+    color: str = "#ffffff",
+    intensity: float = 1.0,
+    position: Optional[Dict[str, float]] = None,
+    target: Optional[Dict[str, float]] = None,
+    cast_shadow: bool = False,
+    spot_angle: Optional[float] = None
+) -> Dict[str, Any]:
+    """
+    Implementation: Add a new light source to the scene
+
+    Args:
+        scene_id: ID of the scene
+        light_type: "ambient" | "directional" | "point" | "spot"
+        name: Light identifier (e.g., "Torch1", "MainLight")
+        color: Hex color (default: "#ffffff")
+        intensity: Brightness 0.0-2.0 (default: 1.0)
+        position: Position for directional/point/spot lights
+        target: Target position for directional/spot lights
+        cast_shadow: Enable shadows (default: False)
+        spot_angle: Cone angle in degrees (spot lights only)
+
+    Returns:
+        Dictionary with light details and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    # Validate light type
+    valid_types = ["ambient", "directional", "point", "spot"]
+    if light_type not in valid_types:
+        raise ValueError(f"Invalid light_type '{light_type}'. Must be one of: {valid_types}")
+
+    # Check for duplicate name
+    if "lights" not in scene:
+        scene["lights"] = []
+
+    for light in scene["lights"]:
+        if light.get("name") == name:
+            raise ValueError(f"Light with name '{name}' already exists. Use update_light() to modify it.")
+
+    # Create light object
+    light_obj = {
+        "name": name,
+        "light_type": light_type,
+        "color": color,
+        "intensity": intensity,
+        "cast_shadow": cast_shadow
+    }
+
+    # Add position for non-ambient lights
+    if light_type != "ambient":
+        if position:
+            light_obj["position"] = position
+        else:
+            # Default positions
+            defaults = {
+                "directional": {"x": 50, "y": 50, "z": 50},
+                "point": {"x": 0, "y": 5, "z": 0},
+                "spot": {"x": 0, "y": 5, "z": 0}
+            }
+            light_obj["position"] = defaults.get(light_type, {"x": 0, "y": 5, "z": 0})
+
+    # Add target for directional/spot lights
+    if light_type in ["directional", "spot"] and target:
+        light_obj["target"] = target
+
+    # Add spot angle for spot lights
+    if light_type == "spot":
+        light_obj["spot_angle"] = spot_angle if spot_angle else 45.0
+
+    scene["lights"].append(light_obj)
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": f"Added {light_type} light '{name}' to scene",
+        "light": light_obj
+    }
+
+
+def remove_light(scene_id: str, light_name: str) -> Dict[str, Any]:
+    """
+    Implementation: Remove a light from the scene
+
+    Args:
+        scene_id: ID of the scene
+        light_name: Name of light to remove
+
+    Returns:
+        Dictionary with confirmation message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "lights" not in scene or not scene["lights"]:
+        raise ValueError(f"Scene has no lights to remove")
+
+    # Find and remove light
+    original_count = len(scene["lights"])
+    scene["lights"] = [light for light in scene["lights"] if light.get("name") != light_name]
+
+    if len(scene["lights"]) == original_count:
+        raise ValueError(f"Light '{light_name}' not found in scene")
+
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": f"Removed light '{light_name}' from scene",
+        "light_name": light_name
+    }
+
+
+def update_light(
+    scene_id: str,
+    light_name: str,
+    color: Optional[str] = None,
+    intensity: Optional[float] = None,
+    position: Optional[Dict[str, float]] = None,
+    cast_shadow: Optional[bool] = None
+) -> Dict[str, Any]:
+    """
+    Implementation: Update existing light properties
+
+    Args:
+        scene_id: ID of the scene
+        light_name: Name of light to update
+        color: New color (optional)
+        intensity: New intensity (optional)
+        position: New position (optional)
+        cast_shadow: Enable/disable shadows (optional)
+
+    Returns:
+        Dictionary with updated light and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "lights" not in scene or not scene["lights"]:
+        raise ValueError(f"Scene has no lights")
+
+    # Find light
+    light = None
+    for l in scene["lights"]:
+        if l.get("name") == light_name:
+            light = l
+            break
+
+    if not light:
+        raise ValueError(f"Light '{light_name}' not found in scene")
+
+    # Update properties
+    updated_props = []
+    if color is not None:
+        light["color"] = color
+        updated_props.append(f"color={color}")
+
+    if intensity is not None:
+        light["intensity"] = intensity
+        updated_props.append(f"intensity={intensity}")
+
+    if position is not None:
+        light["position"] = position
+        updated_props.append(f"position={position}")
+
+    if cast_shadow is not None:
+        light["cast_shadow"] = cast_shadow
+        updated_props.append(f"shadows={'on' if cast_shadow else 'off'}")
+
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": f"Updated light '{light_name}': {', '.join(updated_props)}",
+        "light": light
+    }
+
+
+def get_lights(scene_id: str) -> Dict[str, Any]:
+    """
+    Implementation: Get all lights in the scene
+
+    Args:
+        scene_id: ID of the scene
+
+    Returns:
+        Dictionary with list of all lights
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    lights = scene.get("lights", [])
+
+    return {
+        "scene_id": scene_id,
+        "lights": lights,
+        "count": len(lights)
+    }
+
+
+def update_object_material(
+    scene_id: str,
+    object_id: str,
+    color: Optional[str] = None,
+    metalness: Optional[float] = None,
+    roughness: Optional[float] = None,
+    opacity: Optional[float] = None,
+    emissive: Optional[str] = None,
+    emissive_intensity: Optional[float] = None
+) -> Dict[str, Any]:
+    """
+    Implementation: Update an object's material properties
+
+    Args:
+        scene_id: ID of the scene
+        object_id: Object to update
+        color: Hex color (optional)
+        metalness: 0.0-1.0 (optional)
+        roughness: 0.0-1.0 (optional)
+        opacity: 0.0-1.0 (optional)
+        emissive: Emissive color for glow (optional)
+        emissive_intensity: Glow strength (optional)
+
+    Returns:
+        Dictionary with updated material and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "objects" not in scene or not scene["objects"]:
+        raise ValueError(f"Scene has no objects")
+
+    # Find object
+    obj = None
+    for o in scene["objects"]:
+        if o.get("object_id") == object_id:
+            obj = o
+            break
+
+    if not obj:
+        raise ValueError(f"Object '{object_id}' not found in scene")
+
+    # Ensure material exists
+    if "material" not in obj:
+        obj["material"] = {}
+
+    # Update material properties
+    updated_props = []
+
+    if color is not None:
+        obj["material"]["color"] = color
+        updated_props.append(f"color={color}")
+
+    if metalness is not None:
+        obj["material"]["metalness"] = max(0.0, min(1.0, metalness))
+        updated_props.append(f"metalness={metalness}")
+
+    if roughness is not None:
+        obj["material"]["roughness"] = max(0.0, min(1.0, roughness))
+        updated_props.append(f"roughness={roughness}")
+
+    if opacity is not None:
+        obj["material"]["opacity"] = max(0.0, min(1.0, opacity))
+        updated_props.append(f"opacity={opacity}")
+
+    if emissive is not None:
+        obj["material"]["emissive"] = emissive
+        updated_props.append(f"emissive={emissive}")
+
+    if emissive_intensity is not None:
+        obj["material"]["emissive_intensity"] = emissive_intensity
+        updated_props.append(f"emissive_intensity={emissive_intensity}")
+
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "object_id": object_id,
+        "message": f"Updated material: {', '.join(updated_props)}",
+        "material": obj["material"]
+    }
+
+
+def set_background_color(
+    scene_id: str,
+    color: Optional[str] = None,
+    bg_type: str = "solid",
+    gradient_top: Optional[str] = None,
+    gradient_bottom: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Implementation: Set scene background color
+
+    Args:
+        scene_id: ID of the scene
+        color: Hex color for solid background
+        bg_type: "solid" | "gradient"
+        gradient_top: Top color for gradient
+        gradient_bottom: Bottom color for gradient
+
+    Returns:
+        Dictionary with background settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "environment" not in scene:
+        scene["environment"] = {}
+
+    if bg_type == "gradient":
+        if not gradient_top or not gradient_bottom:
+            raise ValueError("gradient_top and gradient_bottom are required for gradient backgrounds")
+
+        scene["environment"]["background_type"] = "gradient"
+        scene["environment"]["background_gradient_top"] = gradient_top
+        scene["environment"]["background_gradient_bottom"] = gradient_bottom
+
+        message = f"Set background to gradient: {gradient_top} → {gradient_bottom}"
+    else:
+        if not color:
+            raise ValueError("color is required for solid backgrounds")
+
+        scene["environment"]["background_type"] = "solid"
+        scene["environment"]["background_color"] = color
+
+        message = f"Set background to {color}"
+
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "background": scene["environment"]
+    }
+
+
+def set_fog(
+    scene_id: str,
+    enabled: bool,
+    color: Optional[str] = None,
+    near: Optional[float] = None,
+    far: Optional[float] = None,
+    density: Optional[float] = None
+) -> Dict[str, Any]:
+    """
+    Implementation: Set atmospheric fog
+
+    Args:
+        scene_id: ID of the scene
+        enabled: Enable/disable fog
+        color: Fog color (default: "#aaaaaa")
+        near: Start distance for linear fog
+        far: End distance for linear fog
+        density: Density for exponential fog
+
+    Returns:
+        Dictionary with fog settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "environment" not in scene:
+        scene["environment"] = {}
+
+    if "fog" not in scene["environment"]:
+        scene["environment"]["fog"] = {}
+
+    fog = scene["environment"]["fog"]
+    fog["enabled"] = enabled
+
+    if enabled:
+        fog["color"] = color if color else "#aaaaaa"
+
+        # Determine fog type
+        if density is not None:
+            fog["type"] = "exponential"
+            fog["density"] = density
+            message = f"Enabled exponential fog (density={density}, color={fog['color']})"
+        elif near is not None and far is not None:
+            fog["type"] = "linear"
+            fog["near"] = near
+            fog["far"] = far
+            message = f"Enabled linear fog (near={near}, far={far}, color={fog['color']})"
+        else:
+            # Default linear fog
+            fog["type"] = "linear"
+            fog["near"] = 10
+            fog["far"] = 50
+            message = f"Enabled linear fog (near=10, far=50, color={fog['color']})"
+    else:
+        message = "Disabled fog"
+
+    storage.save(scene)
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "fog": fog
+    }
+
+
+# =============================================================================
+# Post-Processing Tools
+# =============================================================================
+
+def set_bloom(
+    scene_id: str,
+    enabled: bool,
+    strength: float = 1.0,
+    radius: float = 0.4,
+    threshold: float = 0.8
+) -> Dict[str, Any]:
+    """
+    Configure bloom (glow) post-processing effect.
+
+    Bloom creates a glow effect around bright areas of the scene,
+    simulating how cameras capture bright light sources.
+
+    Args:
+        scene_id: ID of the scene
+        enabled: Enable/disable bloom
+        strength: Bloom intensity (0.0-3.0, default: 1.0)
+        radius: Bloom spread/blur radius (0.0-1.0, default: 0.4)
+        threshold: Brightness threshold to trigger bloom (0.0-1.0, default: 0.8)
+
+    Returns:
+        Dictionary with bloom settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "post_processing" not in scene:
+        scene["post_processing"] = {}
+
+    bloom = {
+        "enabled": enabled,
+        "strength": max(0.0, min(3.0, strength)),
+        "radius": max(0.0, min(1.0, radius)),
+        "threshold": max(0.0, min(1.0, threshold))
+    }
+    scene["post_processing"]["bloom"] = bloom
+
+    storage.save(scene)
+
+    if enabled:
+        message = f"Enabled bloom (strength={strength}, radius={radius}, threshold={threshold})"
+    else:
+        message = "Disabled bloom"
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "bloom": bloom
+    }
+
+
+def set_ssao(
+    scene_id: str,
+    enabled: bool,
+    radius: float = 0.5,
+    intensity: float = 1.0,
+    bias: float = 0.025
+) -> Dict[str, Any]:
+    """
+    Configure Screen Space Ambient Occlusion (SSAO).
+
+    SSAO adds soft shadows in corners and crevices where ambient light
+    would naturally be occluded, adding depth and realism.
+
+    Args:
+        scene_id: ID of the scene
+        enabled: Enable/disable SSAO
+        radius: Sample radius in world units (0.1-2.0, default: 0.5)
+        intensity: Shadow intensity (0.0-2.0, default: 1.0)
+        bias: Depth bias to prevent self-occlusion (0.001-0.1, default: 0.025)
+
+    Returns:
+        Dictionary with SSAO settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "post_processing" not in scene:
+        scene["post_processing"] = {}
+
+    ssao = {
+        "enabled": enabled,
+        "radius": max(0.1, min(2.0, radius)),
+        "intensity": max(0.0, min(2.0, intensity)),
+        "bias": max(0.001, min(0.1, bias))
+    }
+    scene["post_processing"]["ssao"] = ssao
+
+    storage.save(scene)
+
+    if enabled:
+        message = f"Enabled SSAO (radius={radius}, intensity={intensity})"
+    else:
+        message = "Disabled SSAO"
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "ssao": ssao
+    }
+
+
+def set_color_grading(
+    scene_id: str,
+    enabled: bool,
+    brightness: float = 0.0,
+    contrast: float = 1.0,
+    saturation: float = 1.0,
+    hue: float = 0.0,
+    exposure: float = 1.0,
+    gamma: float = 1.0
+) -> Dict[str, Any]:
+    """
+    Configure color grading post-processing.
+
+    Adjust overall image colors for cinematic looks or stylized effects.
+
+    Args:
+        scene_id: ID of the scene
+        enabled: Enable/disable color grading
+        brightness: Brightness adjustment (-1.0 to 1.0, default: 0.0)
+        contrast: Contrast multiplier (0.0-2.0, default: 1.0)
+        saturation: Color saturation (0.0=grayscale, 1.0=normal, 2.0=vivid)
+        hue: Hue shift in degrees (-180 to 180, default: 0)
+        exposure: Exposure adjustment (0.0-3.0, default: 1.0)
+        gamma: Gamma correction (0.5-2.5, default: 1.0)
+
+    Returns:
+        Dictionary with color grading settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "post_processing" not in scene:
+        scene["post_processing"] = {}
+
+    color_grading = {
+        "enabled": enabled,
+        "brightness": max(-1.0, min(1.0, brightness)),
+        "contrast": max(0.0, min(2.0, contrast)),
+        "saturation": max(0.0, min(2.0, saturation)),
+        "hue": max(-180, min(180, hue)),
+        "exposure": max(0.0, min(3.0, exposure)),
+        "gamma": max(0.5, min(2.5, gamma))
+    }
+    scene["post_processing"]["color_grading"] = color_grading
+
+    storage.save(scene)
+
+    if enabled:
+        adjustments = []
+        if brightness != 0.0:
+            adjustments.append(f"brightness={brightness}")
+        if contrast != 1.0:
+            adjustments.append(f"contrast={contrast}")
+        if saturation != 1.0:
+            adjustments.append(f"saturation={saturation}")
+        if hue != 0.0:
+            adjustments.append(f"hue={hue}°")
+        if exposure != 1.0:
+            adjustments.append(f"exposure={exposure}")
+        if gamma != 1.0:
+            adjustments.append(f"gamma={gamma}")
+
+        if adjustments:
+            message = f"Enabled color grading ({', '.join(adjustments)})"
+        else:
+            message = "Enabled color grading (default settings)"
+    else:
+        message = "Disabled color grading"
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "color_grading": color_grading
+    }
+
+
+def set_vignette(
+    scene_id: str,
+    enabled: bool,
+    intensity: float = 0.5,
+    smoothness: float = 0.5
+) -> Dict[str, Any]:
+    """
+    Configure vignette effect (darkened edges).
+
+    Vignette darkens the corners and edges of the screen,
+    drawing focus to the center of the image.
+
+    Args:
+        scene_id: ID of the scene
+        enabled: Enable/disable vignette
+        intensity: Darkness of the vignette (0.0-1.0, default: 0.5)
+        smoothness: Softness of the vignette edge (0.0-1.0, default: 0.5)
+
+    Returns:
+        Dictionary with vignette settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "post_processing" not in scene:
+        scene["post_processing"] = {}
+
+    vignette = {
+        "enabled": enabled,
+        "intensity": max(0.0, min(1.0, intensity)),
+        "smoothness": max(0.0, min(1.0, smoothness))
+    }
+    scene["post_processing"]["vignette"] = vignette
+
+    storage.save(scene)
+
+    if enabled:
+        message = f"Enabled vignette (intensity={intensity}, smoothness={smoothness})"
+    else:
+        message = "Disabled vignette"
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "vignette": vignette
+    }
+
+
+def get_post_processing(scene_id: str) -> Dict[str, Any]:
+    """
+    Get all post-processing settings for the scene.
+
+    Args:
+        scene_id: ID of the scene
+
+    Returns:
+        Dictionary with all post-processing settings
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    post_processing = scene.get("post_processing", {})
+
+    return {
+        "scene_id": scene_id,
+        "post_processing": post_processing
+    }
+
+
+# =============================================================================
+# Camera Effects Tools
+# =============================================================================
+
+def set_depth_of_field(
+    scene_id: str,
+    enabled: bool,
+    focus_distance: float = 10.0,
+    aperture: float = 0.025,
+    max_blur: float = 0.01
+) -> Dict[str, Any]:
+    """
+    Configure depth of field (DoF) camera effect.
+
+    Depth of field blurs objects that are not at the focus distance,
+    simulating how real camera lenses focus on a specific plane.
+
+    Args:
+        scene_id: ID of the scene
+        enabled: Enable/disable depth of field
+        focus_distance: Distance to the focal plane in units (default: 10.0)
+        aperture: Aperture size, affects blur amount (0.001-0.1, default: 0.025)
+        max_blur: Maximum blur strength (0.0-0.05, default: 0.01)
+
+    Returns:
+        Dictionary with DoF settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "camera_effects" not in scene:
+        scene["camera_effects"] = {}
+
+    dof = {
+        "enabled": enabled,
+        "focus_distance": max(0.1, focus_distance),
+        "aperture": max(0.001, min(0.1, aperture)),
+        "max_blur": max(0.0, min(0.05, max_blur))
+    }
+    scene["camera_effects"]["depth_of_field"] = dof
+
+    storage.save(scene)
+
+    if enabled:
+        message = f"Enabled depth of field (focus={focus_distance}m, aperture={aperture})"
+    else:
+        message = "Disabled depth of field"
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "depth_of_field": dof
+    }
+
+
+def set_motion_blur(
+    scene_id: str,
+    enabled: bool,
+    intensity: float = 0.5,
+    samples: int = 8
+) -> Dict[str, Any]:
+    """
+    Configure motion blur camera effect.
+
+    Motion blur adds blur in the direction of camera or object movement,
+    creating a sense of speed and smooth motion.
+
+    Args:
+        scene_id: ID of the scene
+        enabled: Enable/disable motion blur
+        intensity: Blur intensity (0.0-2.0, default: 0.5)
+        samples: Quality samples for blur (4-32, default: 8)
+
+    Returns:
+        Dictionary with motion blur settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "camera_effects" not in scene:
+        scene["camera_effects"] = {}
+
+    motion_blur = {
+        "enabled": enabled,
+        "intensity": max(0.0, min(2.0, intensity)),
+        "samples": max(4, min(32, samples))
+    }
+    scene["camera_effects"]["motion_blur"] = motion_blur
+
+    storage.save(scene)
+
+    if enabled:
+        message = f"Enabled motion blur (intensity={intensity}, samples={samples})"
+    else:
+        message = "Disabled motion blur"
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "motion_blur": motion_blur
+    }
+
+
+def set_chromatic_aberration(
+    scene_id: str,
+    enabled: bool,
+    intensity: float = 0.005
+) -> Dict[str, Any]:
+    """
+    Configure chromatic aberration effect.
+
+    Chromatic aberration simulates lens imperfection by separating
+    color channels at the edges of the screen.
+
+    Args:
+        scene_id: ID of the scene
+        enabled: Enable/disable chromatic aberration
+        intensity: Effect strength (0.0-0.05, default: 0.005)
+
+    Returns:
+        Dictionary with chromatic aberration settings and message
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    if "camera_effects" not in scene:
+        scene["camera_effects"] = {}
+
+    chromatic = {
+        "enabled": enabled,
+        "intensity": max(0.0, min(0.05, intensity))
+    }
+    scene["camera_effects"]["chromatic_aberration"] = chromatic
+
+    storage.save(scene)
+
+    if enabled:
+        message = f"Enabled chromatic aberration (intensity={intensity})"
+    else:
+        message = "Disabled chromatic aberration"
+
+    return {
+        "scene_id": scene_id,
+        "message": message,
+        "chromatic_aberration": chromatic
+    }
+
+
+def get_camera_effects(scene_id: str) -> Dict[str, Any]:
+    """
+    Get all camera effects settings for the scene.
+
+    Args:
+        scene_id: ID of the scene
+
+    Returns:
+        Dictionary with all camera effects settings
+    """
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene '{scene_id}' not found")
+
+    camera_effects = scene.get("camera_effects", {})
+
+    return {
+        "scene_id": scene_id,
+        "camera_effects": camera_effects
+    }

backend/tools/scene_tools.py

@@ -0,0 +1,362 @@
+"""
+Scene Tools
+Create, modify, and query 3D scenes
+"""
+from typing import Optional, Dict, Any
+from backend.game_models import (
+    create_scene,
+    create_game_object,
+    create_light,
+    create_environment,
+    create_vector3,
+    create_material,
+)
+from backend.storage import storage
+
+
+def generate_viewer_url(scene_id: str, base_url: str = "http://localhost:8000") -> str:
+    """Generate viewer URL for a scene"""
+    return f"{base_url}/view/scene/{scene_id}"
+
+
+def create_game_scene(
+    name: str = "New Scene",
+    description: Optional[str] = None,
+    world_width: float = 100.0,
+    world_height: float = 100.0,
+    world_depth: float = 100.0,
+    lighting_preset: str = "day",
+    base_url: str = "http://localhost:8000"
+) -> Dict[str, Any]:
+    """
+    Create a new 3D scene
+
+    Args:
+        name: Scene name
+        description: Scene description
+        world_width: Width of the world
+        world_height: Height of the world
+        world_depth: Depth of the world
+        lighting_preset: Lighting preset (day, night, sunset, studio)
+        base_url: Base URL for the deployed space
+
+    Returns:
+        Dict with scene_id, viewer_url, and message
+    """
+    # Create default lights based on preset
+    lights = []
+    if lighting_preset == "day":
+        lights = [
+            create_light(
+                name="Sun",
+                light_type="directional",
+                color="#ffffff",
+                intensity=1.0,
+                position=create_vector3(50, 50, 50),
+            ),
+            create_light(
+                name="Ambient",
+                light_type="ambient",
+                color="#ffffff",
+                intensity=0.5,
+            ),
+        ]
+    elif lighting_preset == "night":
+        lights = [
+            create_light(
+                name="Moon",
+                light_type="directional",
+                color="#6699cc",
+                intensity=0.3,
+                position=create_vector3(-50, 50, -50),
+            ),
+            create_light(
+                name="Ambient",
+                light_type="ambient",
+                color="#1a1a3a",
+                intensity=0.2,
+            ),
+        ]
+
+    # Create environment
+    env = create_environment(lighting_preset=lighting_preset)
+    if lighting_preset == "night":
+        env["background_color"] = "#0a0a1a"
+    elif lighting_preset == "sunset":
+        env["background_color"] = "#ff6b35"
+
+    # Create scene
+    scene = create_scene(
+        name=name,
+        description=description,
+        world_width=world_width,
+        world_height=world_height,
+        world_depth=world_depth,
+        lights=lights,
+        environment=env,
+    )
+
+    # Save to storage
+    storage.save(scene)
+
+    # Generate viewer URL
+    viewer_url = generate_viewer_url(scene["scene_id"], base_url)
+
+    return {
+        "scene_id": scene["scene_id"],
+        "viewer_url": viewer_url,
+        "message": f"Created scene '{scene['name']}' with 10x10 world (white ground plane and boundary walls)",
+    }
+
+
+def add_game_object(
+    scene_id: str,
+    object_type: str = "cube",
+    name: Optional[str] = None,
+    position: Optional[Dict[str, float]] = None,
+    rotation: Optional[Dict[str, float]] = None,
+    scale: Optional[Dict[str, float]] = None,
+    material: Optional[Dict[str, Any]] = None,
+    model_path: Optional[str] = None,
+    base_url: str = "http://localhost:8000"
+) -> Dict[str, Any]:
+    """
+    Add an object to the scene
+
+    Args:
+        scene_id: ID of the scene
+        object_type: Type of object (cube, sphere, cylinder, etc.)
+        name: Object name
+        position: Position vector {x, y, z}
+        rotation: Rotation vector {x, y, z}
+        scale: Scale vector {x, y, z}
+        material: Material properties dict
+        model_path: Path to 3D model file
+        base_url: Base URL for the deployed space
+
+    Returns:
+        Dict with object_id, scene_id, viewer_url, and message
+    """
+    # Get existing scene
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene with ID '{scene_id}' not found")
+
+    # Validate position is within 10x10 world bounds (-5 to 5 in X and Z)
+    if position:
+        x = position.get('x', 0)
+        z = position.get('z', 0)
+        WORLD_HALF = 5.0
+        if abs(x) > WORLD_HALF or abs(z) > WORLD_HALF:
+            raise ValueError(
+                f"Object position ({x}, {z}) is outside the 10x10 world bounds. "
+                f"X and Z must be between -{WORLD_HALF} and {WORLD_HALF}."
+            )
+
+    # Create game object
+    obj = create_game_object(
+        object_type=object_type,
+        name=name or f"{object_type}_{len(scene['objects'])}",
+        position=position,
+        rotation=rotation,
+        scale=scale,
+        material=material,
+        model_path=model_path,
+    )
+
+    # Add to scene
+    scene["objects"].append(obj)
+
+    # Save updated scene
+    storage.save(scene)
+
+    # Generate viewer URL
+    viewer_url = generate_viewer_url(scene["scene_id"], base_url)
+
+    pos = obj["position"]
+    return {
+        "object_id": obj["id"],
+        "scene_id": scene["scene_id"],
+        "viewer_url": viewer_url,
+        "message": f"Added {obj['name']} ({object_type}) at position ({pos['x']}, {pos['y']}, {pos['z']})",
+    }
+
+
+def remove_game_object(
+    scene_id: str,
+    object_id: str,
+    base_url: str = "http://localhost:8000"
+) -> Dict[str, Any]:
+    """
+    Remove an object from the scene
+
+    Args:
+        scene_id: ID of the scene
+        object_id: ID of the object to remove
+        base_url: Base URL for the deployed space
+
+    Returns:
+        Dict with scene_id, viewer_url, and message
+    """
+    # Get existing scene
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene with ID '{scene_id}' not found")
+
+    # Find and remove object
+    original_count = len(scene["objects"])
+    scene["objects"] = [obj for obj in scene["objects"] if obj["id"] != object_id]
+
+    if len(scene["objects"]) == original_count:
+        raise ValueError(f"Object with ID '{object_id}' not found in scene")
+
+    # Save updated scene
+    storage.save(scene)
+
+    # Generate viewer URL
+    viewer_url = generate_viewer_url(scene["scene_id"], base_url)
+
+    return {
+        "scene_id": scene["scene_id"],
+        "viewer_url": viewer_url,
+        "message": f"Removed object {object_id}",
+    }
+
+
+def set_scene_lighting(
+    scene_id: str,
+    preset: str = "day",
+    base_url: str = "http://localhost:8000"
+) -> Dict[str, Any]:
+    """
+    Set lighting preset for the scene
+
+    Args:
+        scene_id: ID of the scene
+        preset: Lighting preset (day, night, sunset, studio)
+        base_url: Base URL for the deployed space
+
+    Returns:
+        Dict with scene_id, viewer_url, and message
+    """
+    # Get existing scene
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene with ID '{scene_id}' not found")
+
+    # Update lighting preset
+    scene["environment"]["lighting_preset"] = preset
+
+    # Update lights based on preset
+    if preset == "day":
+        scene["lights"] = [
+            create_light(
+                name="Sun",
+                light_type="directional",
+                color="#ffffff",
+                intensity=1.0,
+                position=create_vector3(50, 50, 50),
+            ),
+            create_light(
+                name="Ambient",
+                light_type="ambient",
+                color="#ffffff",
+                intensity=0.5,
+            ),
+        ]
+        scene["environment"]["background_color"] = "#87CEEB"
+    elif preset == "night":
+        scene["lights"] = [
+            create_light(
+                name="Moon",
+                light_type="directional",
+                color="#6699cc",
+                intensity=0.3,
+                position=create_vector3(-50, 50, -50),
+            ),
+            create_light(
+                name="Ambient",
+                light_type="ambient",
+                color="#1a1a3a",
+                intensity=0.2,
+            ),
+        ]
+        scene["environment"]["background_color"] = "#0a0a1a"
+    elif preset == "sunset":
+        scene["lights"] = [
+            create_light(
+                name="Sun",
+                light_type="directional",
+                color="#ff6b35",
+                intensity=0.8,
+                position=create_vector3(100, 20, 50),
+            ),
+            create_light(
+                name="Ambient",
+                light_type="ambient",
+                color="#ff9966",
+                intensity=0.4,
+            ),
+        ]
+        scene["environment"]["background_color"] = "#ff6b35"
+
+    # Save updated scene
+    storage.save(scene)
+
+    # Generate viewer URL
+    viewer_url = generate_viewer_url(scene["scene_id"], base_url)
+
+    return {
+        "scene_id": scene["scene_id"],
+        "viewer_url": viewer_url,
+        "message": f"Set lighting to {preset}",
+    }
+
+
+def get_scene_info(
+    scene_id: str,
+    base_url: str = "http://localhost:8000"
+) -> Dict[str, Any]:
+    """
+    Get information about a scene
+
+    Args:
+        scene_id: ID of the scene to retrieve
+        base_url: Base URL for the deployed space
+
+    Returns:
+        Dict with scene details including objects and lights
+    """
+    # Get scene
+    scene = storage.get(scene_id)
+    if not scene:
+        raise ValueError(f"Scene with ID '{scene_id}' not found")
+
+    # Generate viewer URL
+    viewer_url = generate_viewer_url(scene["scene_id"], base_url)
+
+    # Format object list
+    objects_info = [
+        {
+            "id": obj["id"],
+            "name": obj["name"],
+            "type": obj["type"],
+            "position": obj["position"],
+            "color": obj["material"]["color"],
+        }
+        for obj in scene["objects"]
+    ]
+
+    return {
+        "scene_id": scene["scene_id"],
+        "name": scene["name"],
+        "viewer_url": viewer_url,
+        "object_count": len(scene["objects"]),
+        "light_count": len(scene["lights"]),
+        "world_bounds": {
+            "width": scene["world_width"],
+            "height": scene["world_height"],
+            "depth": scene["world_depth"],
+        },
+        "objects": objects_info,
+    }

chat_client.py

@@ -0,0 +1,918 @@
+"""
+GPT-powered Chat Client for GCP (Game Context Protocol)
+
+This module provides an intelligent chat interface that uses OpenAI's GPT
+with function calling to interact with the GCP tools.
+"""
+import os
+import json
+from typing import Optional, Dict, Any, List
+
+# Load .env file if present
+from dotenv import load_dotenv
+load_dotenv()
+
+from openai import OpenAI
+
+# Import GCP tools
+from backend.tools.scene_tools import (
+    create_game_scene,
+    add_game_object,
+    remove_game_object,
+    set_scene_lighting,
+    get_scene_info,
+)
+from backend.tools.player_tools import (
+    set_player_speed,
+    set_jump_force,
+    set_mouse_sensitivity,
+    set_gravity,
+    set_player_dimensions,
+    set_movement_acceleration,
+    set_air_control,
+    set_camera_fov,
+    set_vertical_look_limits,
+    get_player_config,
+)
+from backend.tools.rendering_tools import (
+    add_light,
+    remove_light,
+    update_light,
+    get_lights,
+    update_object_material,
+    set_background_color,
+    set_fog,
+    # Post-processing
+    set_bloom,
+    set_ssao,
+    set_color_grading,
+    set_vignette,
+    get_post_processing,
+    # Camera effects
+    set_depth_of_field,
+    set_motion_blur,
+    set_chromatic_aberration,
+    get_camera_effects,
+)
+from backend.game_models import create_vector3, create_material
+
+
+# Tool definitions for OpenAI function calling
+TOOLS = [
+    # Scene Tools
+    {
+        "type": "function",
+        "function": {
+            "name": "create_scene",
+            "description": "Create a new 3D scene/level",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string", "description": "Name of the scene"},
+                    "description": {"type": "string", "description": "Description of the scene"},
+                    "world_width": {"type": "number", "description": "Width of the world in units (default: 100)"},
+                    "world_height": {"type": "number", "description": "Height of the world in units (default: 100)"},
+                    "world_depth": {"type": "number", "description": "Depth of the world in units (default: 100)"},
+                    "lighting_preset": {"type": "string", "enum": ["day", "night", "sunset", "studio"], "description": "Lighting preset"},
+                },
+                "required": []
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "add_object",
+            "description": "Add a 3D object to the scene",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "object_type": {"type": "string", "enum": ["cube", "sphere", "cylinder", "plane", "cone", "torus"], "description": "Type of object"},
+                    "name": {"type": "string", "description": "Name for the object"},
+                    "x": {"type": "number", "description": "X position"},
+                    "y": {"type": "number", "description": "Y position"},
+                    "z": {"type": "number", "description": "Z position"},
+                    "scale_x": {"type": "number", "description": "X scale (default: 1)"},
+                    "scale_y": {"type": "number", "description": "Y scale (default: 1)"},
+                    "scale_z": {"type": "number", "description": "Z scale (default: 1)"},
+                    "color": {"type": "string", "description": "Hex color code (e.g., #ff0000 for red)"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "remove_object",
+            "description": "Remove an object from the scene",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "object_id": {"type": "string", "description": "ID of the object to remove"},
+                },
+                "required": ["scene_id", "object_id"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_lighting",
+            "description": "Set the lighting preset for the scene",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "preset": {"type": "string", "enum": ["day", "night", "sunset", "studio"], "description": "Lighting preset"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_scene_info",
+            "description": "Get detailed information about a scene including all objects and settings",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    # Player Tools
+    {
+        "type": "function",
+        "function": {
+            "name": "set_player_speed",
+            "description": "Set the player's movement speed in units per second",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "walk_speed": {"type": "number", "description": "Movement speed in units/second"},
+                },
+                "required": ["scene_id", "walk_speed"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_jump_force",
+            "description": "Set the player's jump force (initial upward velocity)",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "jump_force": {"type": "number", "description": "Jump force in m/s"},
+                },
+                "required": ["scene_id", "jump_force"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_mouse_sensitivity",
+            "description": "Set mouse look sensitivity and Y-axis inversion",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "sensitivity": {"type": "number", "description": "Mouse sensitivity multiplier"},
+                    "invert_y": {"type": "boolean", "description": "Invert Y-axis"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_gravity",
+            "description": "Set the world's gravity strength",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "gravity": {"type": "number", "description": "Gravity in m/s² (negative = downward, e.g., -9.82 for Earth)"},
+                },
+                "required": ["scene_id", "gravity"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_player_dimensions",
+            "description": "Set player collision capsule dimensions",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "height": {"type": "number", "description": "Player height in meters"},
+                    "radius": {"type": "number", "description": "Player radius in meters"},
+                    "eye_height": {"type": "number", "description": "Camera height from feet"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_camera_fov",
+            "description": "Set camera field of view",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "fov": {"type": "number", "description": "Field of view in degrees (60-120)"},
+                },
+                "required": ["scene_id", "fov"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_player_config",
+            "description": "Get current player configuration including speed, jump force, gravity, dimensions, etc.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    # Rendering Tools
+    {
+        "type": "function",
+        "function": {
+            "name": "add_light",
+            "description": "Add a light source to the scene",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "light_type": {"type": "string", "enum": ["ambient", "directional", "point", "spot"], "description": "Type of light"},
+                    "name": {"type": "string", "description": "Unique name for the light"},
+                    "color": {"type": "string", "description": "Hex color code"},
+                    "intensity": {"type": "number", "description": "Light intensity (0-2)"},
+                    "x": {"type": "number", "description": "X position"},
+                    "y": {"type": "number", "description": "Y position"},
+                    "z": {"type": "number", "description": "Z position"},
+                    "cast_shadow": {"type": "boolean", "description": "Enable shadows"},
+                },
+                "required": ["scene_id", "light_type", "name"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "remove_light",
+            "description": "Remove a light from the scene",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "light_name": {"type": "string", "description": "Name of the light to remove"},
+                },
+                "required": ["scene_id", "light_name"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_lights",
+            "description": "Get all lights in the scene",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "update_object_material",
+            "description": "Update an object's material properties (color, metalness, roughness, opacity, emissive glow)",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "object_id": {"type": "string", "description": "ID of the object"},
+                    "color": {"type": "string", "description": "Hex color code"},
+                    "metalness": {"type": "number", "description": "Metalness (0=matte, 1=metal)"},
+                    "roughness": {"type": "number", "description": "Roughness (0=shiny, 1=rough)"},
+                    "opacity": {"type": "number", "description": "Opacity (0=invisible, 1=solid)"},
+                    "emissive": {"type": "string", "description": "Emissive color for glow"},
+                    "emissive_intensity": {"type": "number", "description": "Emissive intensity (0-1)"},
+                },
+                "required": ["scene_id", "object_id"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_background_color",
+            "description": "Set scene background color or gradient",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "color": {"type": "string", "description": "Hex color for solid background"},
+                    "bg_type": {"type": "string", "enum": ["solid", "gradient"], "description": "Background type"},
+                    "gradient_top": {"type": "string", "description": "Top color for gradient"},
+                    "gradient_bottom": {"type": "string", "description": "Bottom color for gradient"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_fog",
+            "description": "Add or remove atmospheric fog",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "enabled": {"type": "boolean", "description": "Enable or disable fog"},
+                    "color": {"type": "string", "description": "Fog color"},
+                    "near": {"type": "number", "description": "Fog start distance"},
+                    "far": {"type": "number", "description": "Fog end distance"},
+                    "density": {"type": "number", "description": "Fog density (for exponential fog)"},
+                },
+                "required": ["scene_id", "enabled"]
+            }
+        }
+    },
+    # Post-processing Tools
+    {
+        "type": "function",
+        "function": {
+            "name": "set_bloom",
+            "description": "Configure bloom (glow) post-processing effect. Creates glow around bright areas.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "enabled": {"type": "boolean", "description": "Enable or disable bloom"},
+                    "strength": {"type": "number", "description": "Bloom intensity (0-3, default: 1)"},
+                    "radius": {"type": "number", "description": "Bloom spread radius (0-1, default: 0.4)"},
+                    "threshold": {"type": "number", "description": "Brightness threshold (0-1, default: 0.8)"},
+                },
+                "required": ["scene_id", "enabled"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_ssao",
+            "description": "Configure Screen Space Ambient Occlusion (SSAO). Adds soft shadows in corners for depth.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "enabled": {"type": "boolean", "description": "Enable or disable SSAO"},
+                    "radius": {"type": "number", "description": "Sample radius (0.1-2, default: 0.5)"},
+                    "intensity": {"type": "number", "description": "Shadow intensity (0-2, default: 1)"},
+                    "bias": {"type": "number", "description": "Depth bias (0.001-0.1, default: 0.025)"},
+                },
+                "required": ["scene_id", "enabled"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_color_grading",
+            "description": "Configure color grading for cinematic looks. Adjust brightness, contrast, saturation, etc.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "enabled": {"type": "boolean", "description": "Enable or disable color grading"},
+                    "brightness": {"type": "number", "description": "Brightness (-1 to 1, default: 0)"},
+                    "contrast": {"type": "number", "description": "Contrast (0-2, default: 1)"},
+                    "saturation": {"type": "number", "description": "Color saturation (0-2, default: 1)"},
+                    "hue": {"type": "number", "description": "Hue shift in degrees (-180 to 180, default: 0)"},
+                    "exposure": {"type": "number", "description": "Exposure (0-3, default: 1)"},
+                    "gamma": {"type": "number", "description": "Gamma correction (0.5-2.5, default: 1)"},
+                },
+                "required": ["scene_id", "enabled"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_vignette",
+            "description": "Configure vignette effect (darkened edges) to focus attention on center.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "enabled": {"type": "boolean", "description": "Enable or disable vignette"},
+                    "intensity": {"type": "number", "description": "Darkness (0-1, default: 0.5)"},
+                    "smoothness": {"type": "number", "description": "Edge softness (0-1, default: 0.5)"},
+                },
+                "required": ["scene_id", "enabled"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_post_processing",
+            "description": "Get all post-processing settings (bloom, SSAO, color grading, vignette)",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+    # Camera Effects Tools
+    {
+        "type": "function",
+        "function": {
+            "name": "set_depth_of_field",
+            "description": "Configure depth of field (DoF). Blurs objects not at the focus distance.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "enabled": {"type": "boolean", "description": "Enable or disable DoF"},
+                    "focus_distance": {"type": "number", "description": "Distance to focal plane (default: 10)"},
+                    "aperture": {"type": "number", "description": "Aperture size (0.001-0.1, default: 0.025)"},
+                    "max_blur": {"type": "number", "description": "Maximum blur (0-0.05, default: 0.01)"},
+                },
+                "required": ["scene_id", "enabled"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_motion_blur",
+            "description": "Configure motion blur effect for sense of speed and smooth motion.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "enabled": {"type": "boolean", "description": "Enable or disable motion blur"},
+                    "intensity": {"type": "number", "description": "Blur intensity (0-2, default: 0.5)"},
+                    "samples": {"type": "integer", "description": "Quality samples (4-32, default: 8)"},
+                },
+                "required": ["scene_id", "enabled"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "set_chromatic_aberration",
+            "description": "Configure chromatic aberration. Simulates lens color separation at edges.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                    "enabled": {"type": "boolean", "description": "Enable or disable effect"},
+                    "intensity": {"type": "number", "description": "Effect strength (0-0.05, default: 0.005)"},
+                },
+                "required": ["scene_id", "enabled"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_camera_effects",
+            "description": "Get all camera effects settings (depth of field, motion blur, chromatic aberration)",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "scene_id": {"type": "string", "description": "ID of the scene"},
+                },
+                "required": ["scene_id"]
+            }
+        }
+    },
+]
+
+
+class GCPChatClient:
+    """GPT-powered chat client for GCP"""
+
+    def __init__(self, scene_id: str, base_url: str = "http://localhost:8000"):
+        self.client = OpenAI()  # Uses OPENAI_API_KEY env var
+        self.scene_id = scene_id
+        self.base_url = base_url
+        self.conversation_history: List[Dict[str, Any]] = []
+
+        # System prompt
+        self.system_prompt = f"""You are a helpful assistant for GCP (Game Context Protocol), a 3D scene building system.
+
+You help users create and modify 3D scenes using natural language. You have access to tools for:
+- Creating scenes and adding/removing objects (cubes, spheres, cylinders, etc.)
+- Configuring player movement (speed, jump, gravity, dimensions)
+- Managing lights (ambient, directional, point, spot)
+- Updating materials (color, metalness, roughness, opacity, glow)
+- Setting backgrounds and fog effects
+- Post-processing effects (bloom, SSAO, color grading, vignette)
+- Camera effects (depth of field, motion blur, chromatic aberration)
+
+The current scene ID is: {scene_id}
+
+When users ask to modify something relatively (like "half the speed" or "make it twice as big"),
+ALWAYS first get the current state using the appropriate get_* function, then calculate the new value,
+then apply it.
+
+Be concise but helpful. After making changes, briefly confirm what was done."""
+
+    def execute_tool(self, name: str, args: Dict[str, Any]) -> Any:
+        """Execute a GCP tool and return the result"""
+
+        # Inject scene_id if not provided
+        if "scene_id" not in args:
+            args["scene_id"] = self.scene_id
+
+        # Scene tools
+        if name == "create_scene":
+            return create_game_scene(
+                name=args.get("name", "New Scene"),
+                description=args.get("description"),
+                world_width=args.get("world_width", 100.0),
+                world_height=args.get("world_height", 100.0),
+                world_depth=args.get("world_depth", 100.0),
+                lighting_preset=args.get("lighting_preset", "day"),
+                base_url=self.base_url,
+            )
+
+        elif name == "add_object":
+            position = create_vector3(
+                args.get("x", 0),
+                args.get("y", 0),
+                args.get("z", 0)
+            )
+            scale = create_vector3(
+                args.get("scale_x", 1),
+                args.get("scale_y", 1),
+                args.get("scale_z", 1)
+            )
+            material = create_material(color=args.get("color", "#ffffff"))
+            return add_game_object(
+                scene_id=args["scene_id"],
+                object_type=args.get("object_type", "cube"),
+                name=args.get("name"),
+                position=position,
+                scale=scale,
+                material=material,
+                base_url=self.base_url,
+            )
+
+        elif name == "remove_object":
+            return remove_game_object(
+                scene_id=args["scene_id"],
+                object_id=args["object_id"],
+                base_url=self.base_url,
+            )
+
+        elif name == "set_lighting":
+            return set_scene_lighting(
+                scene_id=args["scene_id"],
+                preset=args.get("preset", "day"),
+                base_url=self.base_url,
+            )
+
+        elif name == "get_scene_info":
+            return get_scene_info(args["scene_id"], self.base_url)
+
+        # Player tools
+        elif name == "set_player_speed":
+            return set_player_speed(args["scene_id"], args["walk_speed"])
+
+        elif name == "set_jump_force":
+            return set_jump_force(args["scene_id"], args["jump_force"])
+
+        elif name == "set_mouse_sensitivity":
+            return set_mouse_sensitivity(
+                args["scene_id"],
+                args.get("sensitivity", 0.002),
+                args.get("invert_y", False)
+            )
+
+        elif name == "set_gravity":
+            return set_gravity(args["scene_id"], args["gravity"])
+
+        elif name == "set_player_dimensions":
+            return set_player_dimensions(
+                args["scene_id"],
+                args.get("height", 1.7),
+                args.get("radius", 0.3),
+                args.get("eye_height")
+            )
+
+        elif name == "set_camera_fov":
+            return set_camera_fov(args["scene_id"], args["fov"])
+
+        elif name == "get_player_config":
+            return get_player_config(args["scene_id"])
+
+        # Rendering tools
+        elif name == "add_light":
+            position = None
+            if "x" in args or "y" in args or "z" in args:
+                position = {"x": args.get("x", 0), "y": args.get("y", 5), "z": args.get("z", 0)}
+            return add_light(
+                args["scene_id"],
+                args["light_type"],
+                args["name"],
+                args.get("color", "#ffffff"),
+                args.get("intensity", 1.0),
+                position,
+                None,  # target
+                args.get("cast_shadow", False),
+                None   # spot_angle
+            )
+
+        elif name == "remove_light":
+            return remove_light(args["scene_id"], args["light_name"])
+
+        elif name == "get_lights":
+            return get_lights(args["scene_id"])
+
+        elif name == "update_object_material":
+            return update_object_material(
+                args["scene_id"],
+                args["object_id"],
+                args.get("color"),
+                args.get("metalness"),
+                args.get("roughness"),
+                args.get("opacity"),
+                args.get("emissive"),
+                args.get("emissive_intensity")
+            )
+
+        elif name == "set_background_color":
+            return set_background_color(
+                args["scene_id"],
+                args.get("color"),
+                args.get("bg_type", "solid"),
+                args.get("gradient_top"),
+                args.get("gradient_bottom")
+            )
+
+        elif name == "set_fog":
+            return set_fog(
+                args["scene_id"],
+                args["enabled"],
+                args.get("color"),
+                args.get("near"),
+                args.get("far"),
+                args.get("density")
+            )
+
+        # Post-processing tools
+        elif name == "set_bloom":
+            return set_bloom(
+                args["scene_id"],
+                args["enabled"],
+                args.get("strength", 1.0),
+                args.get("radius", 0.4),
+                args.get("threshold", 0.8)
+            )
+
+        elif name == "set_ssao":
+            return set_ssao(
+                args["scene_id"],
+                args["enabled"],
+                args.get("radius", 0.5),
+                args.get("intensity", 1.0),
+                args.get("bias", 0.025)
+            )
+
+        elif name == "set_color_grading":
+            return set_color_grading(
+                args["scene_id"],
+                args["enabled"],
+                args.get("brightness", 0.0),
+                args.get("contrast", 1.0),
+                args.get("saturation", 1.0),
+                args.get("hue", 0.0),
+                args.get("exposure", 1.0),
+                args.get("gamma", 1.0)
+            )
+
+        elif name == "set_vignette":
+            return set_vignette(
+                args["scene_id"],
+                args["enabled"],
+                args.get("intensity", 0.5),
+                args.get("smoothness", 0.5)
+            )
+
+        elif name == "get_post_processing":
+            return get_post_processing(args["scene_id"])
+
+        # Camera effects tools
+        elif name == "set_depth_of_field":
+            return set_depth_of_field(
+                args["scene_id"],
+                args["enabled"],
+                args.get("focus_distance", 10.0),
+                args.get("aperture", 0.025),
+                args.get("max_blur", 0.01)
+            )
+
+        elif name == "set_motion_blur":
+            return set_motion_blur(
+                args["scene_id"],
+                args["enabled"],
+                args.get("intensity", 0.5),
+                args.get("samples", 8)
+            )
+
+        elif name == "set_chromatic_aberration":
+            return set_chromatic_aberration(
+                args["scene_id"],
+                args["enabled"],
+                args.get("intensity", 0.005)
+            )
+
+        elif name == "get_camera_effects":
+            return get_camera_effects(args["scene_id"])
+
+        else:
+            return {"error": f"Unknown tool: {name}"}
+
+    def chat(self, user_message: str) -> tuple[str, Optional[Dict[str, Any]]]:
+        """
+        Process a user message and return the response.
+
+        Returns:
+            tuple: (response_text, action_data)
+            - response_text: The assistant's response
+            - action_data: Optional dict with action info for the frontend
+        """
+        # Add user message to history
+        self.conversation_history.append({
+            "role": "user",
+            "content": user_message
+        })
+
+        # Build messages with system prompt
+        messages = [{"role": "system", "content": self.system_prompt}] + self.conversation_history
+
+        # Track actions for frontend
+        actions = []
+
+        # Call GPT with tools
+        while True:
+            response = self.client.chat.completions.create(
+                model="gpt-4o-mini",  # or "gpt-4o" for better reasoning
+                messages=messages,
+                tools=TOOLS,
+                tool_choice="auto"
+            )
+
+            assistant_message = response.choices[0].message
+
+            # Check if there are tool calls
+            if assistant_message.tool_calls:
+                # Add assistant message with tool calls to history
+                messages.append({
+                    "role": "assistant",
+                    "content": assistant_message.content,
+                    "tool_calls": [
+                        {
+                            "id": tc.id,
+                            "type": "function",
+                            "function": {
+                                "name": tc.function.name,
+                                "arguments": tc.function.arguments
+                            }
+                        }
+                        for tc in assistant_message.tool_calls
+                    ]
+                })
+
+                # Execute each tool call
+                for tool_call in assistant_message.tool_calls:
+                    function_name = tool_call.function.name
+                    function_args = json.loads(tool_call.function.arguments)
+
+                    # Execute the tool
+                    try:
+                        result = self.execute_tool(function_name, function_args)
+                        actions.append({
+                            "tool": function_name,
+                            "args": function_args,
+                            "result": result
+                        })
+                        result_str = json.dumps(result)
+                    except Exception as e:
+                        result_str = json.dumps({"error": str(e)})
+
+                    # Add tool result to messages
+                    messages.append({
+                        "role": "tool",
+                        "tool_call_id": tool_call.id,
+                        "content": result_str
+                    })
+            else:
+                # No more tool calls, we have the final response
+                final_response = assistant_message.content or "Done!"
+
+                # Add to conversation history
+                self.conversation_history.append({
+                    "role": "assistant",
+                    "content": final_response
+                })
+
+                # Build action data for frontend
+                action_data = None
+                if actions:
+                    # Return the last significant action for the frontend
+                    last_action = actions[-1]
+                    action_data = self._build_frontend_action(last_action)
+
+                return final_response, action_data
+
+    def _build_frontend_action(self, action: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Convert tool result to frontend action"""
+        tool = action["tool"]
+        result = action["result"]
+
+        # Map tool names to frontend actions
+        if tool == "add_object":
+            from backend.storage import storage
+            scene = storage.get(self.scene_id)
+            if scene and scene.get("objects"):
+                return {"action": "addObject", "data": scene["objects"][-1]}
+
+        elif tool == "set_lighting":
+            from backend.storage import storage
+            scene = storage.get(self.scene_id)
+            if scene and scene.get("lighting"):
+                return {"action": "setLighting", "data": scene["lighting"]}
+
+        elif tool in ["set_player_speed", "set_jump_force", "set_gravity",
+                      "set_camera_fov", "set_player_dimensions"]:
+            return {"action": "reload", "url": f"{self.base_url}/view/scene/{self.scene_id}"}
+
+        elif tool == "add_light":
+            return {"action": "addLight", "data": result.get("light")}
+
+        elif tool == "remove_light":
+            return {"action": "removeLight", "data": {"light_name": action["args"].get("light_name")}}
+
+        elif tool == "update_object_material":
+            return {"action": "updateMaterial", "data": result}
+
+        elif tool == "set_background_color":
+            return {"action": "setBackground", "data": result.get("background")}
+
+        elif tool == "set_fog":
+            return {"action": "setFog", "data": result.get("fog")}
+
+        # Post-processing effects (require reload for now)
+        elif tool in ["set_bloom", "set_ssao", "set_color_grading", "set_vignette"]:
+            return {"action": "reload", "url": f"{self.base_url}/view/scene/{self.scene_id}"}
+
+        # Camera effects (require reload for now)
+        elif tool in ["set_depth_of_field", "set_motion_blur", "set_chromatic_aberration"]:
+            return {"action": "reload", "url": f"{self.base_url}/view/scene/{self.scene_id}"}
+
+        return None
+
+    def clear_history(self):
+        """Clear conversation history"""
+        self.conversation_history = []
+
+
+# Convenience function for simple usage
+def create_chat_client(scene_id: str = "welcome", base_url: str = "http://localhost:8000") -> GCPChatClient:
+    """Create a new GCP chat client"""
+    return GCPChatClient(scene_id, base_url)

frontend/game_viewer.html

@@ -0,0 +1,1515 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>3D Game Viewer</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+            overflow: hidden;
+            background: #0a0a0a;
+        }
+
+        #viewer-container {
+            width: 100vw;
+            height: 100vh;
+            position: relative;
+        }
+
+        /* Crosshair for FPS mode */
+        #crosshair {
+            position: absolute;
+            top: 50%;
+            left: 50%;
+            transform: translate(-50%, -50%);
+            width: 6px;
+            height: 6px;
+            background: #000000;
+            border-radius: 50%;
+            pointer-events: none;
+            display: none; /* Show only in FPS mode */
+            z-index: 100;
+            box-shadow: 0 0 2px rgba(255, 255, 255, 0.5);
+        }
+    </style>
+</head>
+<body>
+    <div id="viewer-container">
+        <div id="crosshair"></div>
+    </div>
+
+    <script type="importmap">
+    {
+        "imports": {
+            "three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js",
+            "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/",
+            "cannon-es": "https://cdn.jsdelivr.net/npm/cannon-es@0.20.0/dist/cannon-es.js"
+        }
+    }
+    </script>
+
+    <!-- Stats library for FPS counter -->
+    <script src="https://cdn.jsdelivr.net/npm/stats.js@0.17.0/build/stats.min.js"></script>
+
+    <script type="module">
+        import * as THREE from 'three';
+        import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+        import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+        import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
+        import { OutlinePass } from 'three/addons/postprocessing/OutlinePass.js';
+        import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
+        import * as CANNON from 'cannon-es';
+
+        // Get scene ID from URL
+        const sceneId = window.location.pathname.split('/').pop();
+        const baseUrl = window.location.origin;
+
+        // Check for control mode in URL params
+        const urlParams = new URLSearchParams(window.location.search);
+        const initialMode = urlParams.get('mode') || 'fps'; // Default to FPS mode
+
+        console.log('3D Game Viewer - Initializing...');
+        console.log('Scene ID:', sceneId);
+        console.log('Fetch URL:', `${baseUrl}/api/scenes/${sceneId}`);
+        console.log('Initial control mode:', initialMode);
+
+        let scene, camera, renderer;
+        let orbitControls;
+        let controlMode = initialMode;
+        let sceneData = null;
+
+        // Postprocessing for outlines
+        let composer, outlinePass;
+
+        // Scene controls
+        let gridHelper = null;
+        let stats = null;
+        let wireframeEnabled = false;
+
+        // Object selection system (FPS mode)
+        let raycaster = new THREE.Raycaster();
+        let mouse = new THREE.Vector2();
+        let selectedObject = null;
+        let selectedObjectId = null;
+        const MAX_SELECT_DISTANCE = 10; // Max raycast distance for selection
+
+        // FPS movement and look variables (configurable via player_config)
+        let moveSpeed = 5.0;
+        const velocity = new THREE.Vector3();
+        let isMouseLocked = false;
+        let cameraRotationX = 0; // Pitch (up/down)
+        let cameraRotationY = 0; // Yaw (left/right)
+        let mouseSensitivity = 0.002;
+        let invertY = false;
+        let movementAcceleration = 0.0;  // Phase 2
+        let airControl = 1.0;             // Phase 2
+        let cameraFOV = 75.0;             // Phase 2
+        let minPitch = -89.0;             // Phase 2
+        let maxPitch = 89.0;              // Phase 2
+
+        // Physics variables (configurable via player_config)
+        let physicsWorld;
+        let playerBody;
+        let groundBody;
+        let wallBodies = [];
+        let objectBodies = new Map(); // Maps object IDs to physics bodies
+        let PLAYER_HEIGHT = 1.7;
+        let PLAYER_RADIUS = 0.3;
+        let EYE_HEIGHT = 1.6; // Eye level for camera
+        let JUMP_FORCE = 5.0;
+        let GRAVITY = -9.82;
+        let PLAYER_MASS = 80.0;
+        let LINEAR_DAMPING = 0.9;
+        const WORLD_SIZE = 10; // 10x10 world (fixed)
+        const WORLD_HALF = WORLD_SIZE / 2; // -5 to 5 (fixed)
+        let isGrounded = false;
+        let canJump = true;
+
+        // Movement direction and keyboard state
+        const direction = new THREE.Vector3();
+        const moveForward = { value: false };
+        const moveBackward = { value: false };
+        const moveLeft = { value: false };
+        const moveRight = { value: false };
+        const moveUp = { value: false };
+        const moveDown = { value: false };
+        let prevTime = performance.now();
+
+        function applyPlayerConfig() {
+            /**
+             * Apply player configuration from scene data to runtime variables
+             * Allows MCP tools to customize player controller behavior
+             */
+            if (!sceneData || !sceneData.player_config) {
+                console.log('No player_config in scene data, using defaults');
+                return;
+            }
+
+            const config = sceneData.player_config;
+
+            // Apply movement settings
+            if (config.move_speed !== undefined) {
+                moveSpeed = config.move_speed;
+                console.log(`Applied player speed: ${moveSpeed} units/sec`);
+            }
+
+            if (config.jump_force !== undefined) {
+                JUMP_FORCE = config.jump_force;
+                console.log(`Applied jump force: ${JUMP_FORCE} m/s`);
+            }
+
+            // Apply camera settings
+            if (config.mouse_sensitivity !== undefined) {
+                mouseSensitivity = config.mouse_sensitivity;
+                console.log(`Applied mouse sensitivity: ${mouseSensitivity}`);
+            }
+
+            if (config.invert_y !== undefined) {
+                invertY = config.invert_y;
+                console.log(`Applied Y-axis inversion: ${invertY}`);
+            }
+
+            // Apply physics settings
+            if (config.gravity !== undefined) {
+                GRAVITY = config.gravity;
+                console.log(`Applied gravity: ${GRAVITY} m/s²`);
+            }
+
+            // Apply player dimensions
+            if (config.player_height !== undefined) {
+                PLAYER_HEIGHT = config.player_height;
+                console.log(`Applied player height: ${PLAYER_HEIGHT}m`);
+            }
+
+            if (config.player_radius !== undefined) {
+                PLAYER_RADIUS = config.player_radius;
+                console.log(`Applied player radius: ${PLAYER_RADIUS}m`);
+            }
+
+            if (config.eye_height !== undefined) {
+                EYE_HEIGHT = config.eye_height;
+                console.log(`Applied eye height: ${EYE_HEIGHT}m`);
+            }
+
+            if (config.player_mass !== undefined) {
+                PLAYER_MASS = config.player_mass;
+                console.log(`Applied player mass: ${PLAYER_MASS}kg`);
+            }
+
+            if (config.linear_damping !== undefined) {
+                LINEAR_DAMPING = config.linear_damping;
+                console.log(`Applied linear damping: ${LINEAR_DAMPING}`);
+            }
+
+            // Apply Phase 2 settings
+            if (config.movement_acceleration !== undefined) {
+                movementAcceleration = config.movement_acceleration;
+                console.log(`Applied movement acceleration: ${movementAcceleration}`);
+            }
+
+            if (config.air_control !== undefined) {
+                airControl = config.air_control;
+                console.log(`Applied air control: ${airControl}`);
+            }
+
+            if (config.camera_fov !== undefined) {
+                cameraFOV = config.camera_fov;
+                console.log(`Applied camera FOV: ${cameraFOV}°`);
+            }
+
+            if (config.min_pitch !== undefined) {
+                minPitch = config.min_pitch;
+                console.log(`Applied min pitch: ${minPitch}°`);
+            }
+
+            if (config.max_pitch !== undefined) {
+                maxPitch = config.max_pitch;
+                console.log(`Applied max pitch: ${maxPitch}°`);
+            }
+
+            console.log('✅ Player configuration applied successfully');
+        }
+
+        async function init() {
+            try {
+                // Fetch scene data
+                console.log('Fetching scene data...');
+                const response = await fetch(`${baseUrl}/api/scenes/${sceneId}`);
+                console.log('Response status:', response.status);
+
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    console.error('Failed to fetch scene:', errorText);
+                    throw new Error(`Scene not found (${response.status}): ${errorText}`);
+                }
+                sceneData = await response.json();
+                console.log('Scene data loaded:', sceneData);
+
+                // Apply player configuration from scene data
+                applyPlayerConfig();
+
+                // Setup Three.js scene
+                setupScene();
+
+                // Setup physics world
+                setupPhysics();
+
+                // Render all game objects
+                renderGameObjects();
+
+                // Start animation loop
+                animate();
+
+            } catch (error) {
+                console.error('Error initializing viewer:', error);
+            }
+        }
+
+        function setupScene() {
+            // Create scene
+            scene = new THREE.Scene();
+            const bgColor = sceneData.environment?.background_color || '#87CEEB';
+            scene.background = new THREE.Color(bgColor);
+
+            // Create camera (FOV from player_config)
+            camera = new THREE.PerspectiveCamera(
+                cameraFOV,
+                window.innerWidth / window.innerHeight,
+                0.1,
+                1000
+            );
+
+            // Position camera at player eye height (will be synced with physics in animate loop)
+            camera.position.set(0, EYE_HEIGHT, 0);
+
+            // Create renderer
+            renderer = new THREE.WebGLRenderer({ antialias: true });
+            renderer.setSize(window.innerWidth, window.innerHeight);
+            renderer.setPixelRatio(window.devicePixelRatio);
+            document.getElementById('viewer-container').appendChild(renderer.domElement);
+
+            // Setup postprocessing for object outlines
+            composer = new EffectComposer(renderer);
+
+            const renderPass = new RenderPass(scene, camera);
+            composer.addPass(renderPass);
+
+            outlinePass = new OutlinePass(new THREE.Vector2(window.innerWidth, window.innerHeight), scene, camera);
+            outlinePass.edgeStrength = 5.0;  // Increased for better visibility
+            outlinePass.edgeGlow = 1.0;      // Increased glow
+            outlinePass.edgeThickness = 3.0; // Thicker edge
+            outlinePass.pulsePeriod = 0;     // No pulsing
+            outlinePass.visibleEdgeColor.set('#ff8800'); // Orange outline
+            outlinePass.hiddenEdgeColor.set('#ff4400');  // Darker orange for hidden edges
+            composer.addPass(outlinePass);
+
+            console.log('OutlinePass configured - orange outline ready');
+
+            const outputPass = new OutputPass();
+            composer.addPass(outputPass);
+
+            console.log('PostProcessing composer initialized with OutlinePass');
+
+            // Add lights from scene data
+            sceneData.lights.forEach(lightData => {
+                let light;
+
+                if (lightData.type === 'ambient') {
+                    light = new THREE.AmbientLight(lightData.color, lightData.intensity);
+                } else if (lightData.type === 'directional') {
+                    light = new THREE.DirectionalLight(lightData.color, lightData.intensity);
+                    light.position.set(lightData.position.x, lightData.position.y, lightData.position.z);
+                    // Directional lights need their target in the scene to work properly
+                    light.target.position.set(0, 0, 0);
+                    scene.add(light.target);
+                    if (lightData.cast_shadow) {
+                        light.castShadow = true;
+                    }
+                } else if (lightData.type === 'point') {
+                    light = new THREE.PointLight(lightData.color, lightData.intensity);
+                    light.position.set(lightData.position.x, lightData.position.y, lightData.position.z);
+                }
+
+                if (light) {
+                    scene.add(light);
+                    console.log('Added light:', lightData.type, lightData.name, 'at', lightData.position || 'default');
+                }
+            });
+
+            // Add grid (initially hidden, can be toggled)
+            const gridSize = sceneData.grid_size || 100;
+            const divisions = sceneData.grid_divisions || 20;
+            gridHelper = new THREE.GridHelper(gridSize, divisions, 0x444444, 0x222222);
+            gridHelper.visible = sceneData.show_grid || false;
+            scene.add(gridHelper);
+
+            // Initialize stats (FPS counter) - initially hidden
+            if (typeof Stats !== 'undefined') {
+                stats = new Stats();
+                stats.dom.style.position = 'absolute';
+                stats.dom.style.top = '0px';
+                stats.dom.style.left = '0px';
+                stats.dom.style.display = 'none'; // Hidden by default
+                document.getElementById('viewer-container').appendChild(stats.dom);
+            }
+
+            // Setup Orbit controls
+            orbitControls = new OrbitControls(camera, renderer.domElement);
+            orbitControls.enableDamping = true;
+            orbitControls.dampingFactor = 0.05;
+
+            // Setup FPS mouse-look controls
+            setupFPSControls();
+
+            // Click handler for object inspection in orbit mode
+            renderer.domElement.addEventListener('click', (event) => {
+                // In orbit mode, allow object inspection
+                if (controlMode === 'orbit') {
+                    onObjectClick(event);
+                }
+            });
+
+            // Keyboard controls for FPS movement
+            const onKeyDown = (event) => {
+                switch (event.code) {
+                    case 'KeyW': moveForward.value = true; break;
+                    case 'KeyA': moveLeft.value = true; break;
+                    case 'KeyS': moveBackward.value = true; break;
+                    case 'KeyD': moveRight.value = true; break;
+                    case 'Space':
+                        event.preventDefault(); // Prevent page scroll
+                        if (canJump && isGrounded && playerBody) {
+                            playerBody.velocity.y = JUMP_FORCE;
+                            canJump = false;
+                            isGrounded = false;
+                        }
+                        break;
+                    case 'KeyC': toggleControlMode(); break;
+                }
+            };
+
+            const onKeyUp = (event) => {
+                switch (event.code) {
+                    case 'KeyW': moveForward.value = false; break;
+                    case 'KeyA': moveLeft.value = false; break;
+                    case 'KeyS': moveBackward.value = false; break;
+                    case 'KeyD': moveRight.value = false; break;
+                }
+            };
+
+            document.addEventListener('keydown', onKeyDown);
+            document.addEventListener('keyup', onKeyUp);
+
+            // Set initial control mode
+            setControlMode(controlMode);
+
+            // Handle window resize
+            window.addEventListener('resize', onWindowResize);
+        }
+
+        function setupFPSControls() {
+            // Mouse-look controls for FPS mode
+            renderer.domElement.addEventListener('mousedown', (event) => {
+                if (controlMode === 'fps' && event.button === 0) {
+                    isMouseLocked = true;
+                    renderer.domElement.requestPointerLock();
+                }
+            });
+
+            renderer.domElement.addEventListener('mouseup', () => {
+                // Keep mouse locked until Escape is pressed
+            });
+
+            // Mouse movement for camera rotation
+            document.addEventListener('mousemove', (event) => {
+                if (!isMouseLocked || controlMode !== 'fps') return;
+
+                const movementX = event.movementX || 0;
+                const movementY = event.movementY || 0;
+
+                // Update rotation (yaw and pitch)
+                cameraRotationY -= movementX * mouseSensitivity; // Yaw (left/right)
+                const pitchMultiplier = invertY ? 1 : -1; // Invert Y if configured
+                cameraRotationX += movementY * mouseSensitivity * pitchMultiplier; // Pitch (up/down)
+
+                // Clamp vertical rotation to configured limits
+                const minPitchRad = THREE.MathUtils.degToRad(minPitch);
+                const maxPitchRad = THREE.MathUtils.degToRad(maxPitch);
+                cameraRotationX = Math.max(minPitchRad, Math.min(maxPitchRad, cameraRotationX));
+            });
+
+            // Handle pointer lock changes
+            document.addEventListener('pointerlockchange', () => {
+                isMouseLocked = document.pointerLockElement === renderer.domElement;
+            });
+
+            document.addEventListener('pointerlockerror', () => {
+                console.error('Pointer lock failed');
+                isMouseLocked = false;
+            });
+
+            console.log('FPS controls initialized - click in viewer to enable mouse-look');
+        }
+
+        function setupPhysics() {
+            console.log('Setting up physics world...');
+
+            // Create physics world
+            physicsWorld = new CANNON.World();
+            physicsWorld.gravity.set(0, GRAVITY, 0);
+
+            // Set up collision materials for better physics response
+            const defaultMaterial = new CANNON.Material('default');
+            const defaultContactMaterial = new CANNON.ContactMaterial(
+                defaultMaterial,
+                defaultMaterial,
+                {
+                    friction: 0.3,
+                    restitution: 0.0, // No bounce
+                }
+            );
+            physicsWorld.addContactMaterial(defaultContactMaterial);
+            physicsWorld.defaultContactMaterial = defaultContactMaterial;
+
+            // Create ground plane (10x10 centered at origin)
+            const groundGeometry = new THREE.PlaneGeometry(WORLD_SIZE, WORLD_SIZE);
+            const groundMaterial = new THREE.MeshStandardMaterial({
+                color: 0xffffff,
+                roughness: 0.8,
+                metalness: 0.2
+            });
+            const groundMesh = new THREE.Mesh(groundGeometry, groundMaterial);
+            groundMesh.rotation.x = -Math.PI / 2; // Rotate to be horizontal
+            groundMesh.position.y = 0;
+            groundMesh.receiveShadow = true;
+            groundMesh.userData = { isGround: true };
+            scene.add(groundMesh);
+
+            // Ground physics body
+            const groundShape = new CANNON.Plane();
+            groundBody = new CANNON.Body({ mass: 0, material: defaultMaterial });
+            groundBody.addShape(groundShape);
+            groundBody.quaternion.setFromEuler(-Math.PI / 2, 0, 0);
+            physicsWorld.addBody(groundBody);
+
+            // Create 4 boundary walls (white cubes, 5 units high, 0.5 thick)
+            const wallHeight = 5;
+            const wallThickness = 0.5;
+            const wallMaterial = new THREE.MeshStandardMaterial({
+                color: 0xffffff,
+                roughness: 0.7,
+                metalness: 0.1
+            });
+
+            // North wall (z = 5)
+            const northWallGeometry = new THREE.BoxGeometry(WORLD_SIZE + wallThickness * 2, wallHeight, wallThickness);
+            const northWallMesh = new THREE.Mesh(northWallGeometry, wallMaterial);
+            northWallMesh.position.set(0, wallHeight / 2, WORLD_HALF);
+            northWallMesh.userData = { isWall: true };
+            scene.add(northWallMesh);
+
+            const northWallShape = new CANNON.Box(new CANNON.Vec3((WORLD_SIZE + wallThickness * 2) / 2, wallHeight / 2, wallThickness / 2));
+            const northWallBody = new CANNON.Body({ mass: 0, material: defaultMaterial });
+            northWallBody.addShape(northWallShape);
+            northWallBody.position.copy(northWallMesh.position);
+            physicsWorld.addBody(northWallBody);
+            wallBodies.push(northWallBody);
+
+            // South wall (z = -5)
+            const southWallMesh = new THREE.Mesh(northWallGeometry, wallMaterial);
+            southWallMesh.position.set(0, wallHeight / 2, -WORLD_HALF);
+            southWallMesh.userData = { isWall: true };
+            scene.add(southWallMesh);
+
+            const southWallBody = new CANNON.Body({ mass: 0, material: defaultMaterial });
+            southWallBody.addShape(northWallShape);
+            southWallBody.position.copy(southWallMesh.position);
+            physicsWorld.addBody(southWallBody);
+            wallBodies.push(southWallBody);
+
+            // East wall (x = 5)
+            const eastWallGeometry = new THREE.BoxGeometry(wallThickness, wallHeight, WORLD_SIZE);
+            const eastWallMesh = new THREE.Mesh(eastWallGeometry, wallMaterial);
+            eastWallMesh.position.set(WORLD_HALF, wallHeight / 2, 0);
+            eastWallMesh.userData = { isWall: true };
+            scene.add(eastWallMesh);
+
+            const eastWallShape = new CANNON.Box(new CANNON.Vec3(wallThickness / 2, wallHeight / 2, WORLD_SIZE / 2));
+            const eastWallBody = new CANNON.Body({ mass: 0, material: defaultMaterial });
+            eastWallBody.addShape(eastWallShape);
+            eastWallBody.position.copy(eastWallMesh.position);
+            physicsWorld.addBody(eastWallBody);
+            wallBodies.push(eastWallBody);
+
+            // West wall (x = -5)
+            const westWallMesh = new THREE.Mesh(eastWallGeometry, wallMaterial);
+            westWallMesh.position.set(-WORLD_HALF, wallHeight / 2, 0);
+            westWallMesh.userData = { isWall: true };
+            scene.add(westWallMesh);
+
+            const westWallBody = new CANNON.Body({ mass: 0, material: defaultMaterial });
+            westWallBody.addShape(eastWallShape);
+            westWallBody.position.copy(westWallMesh.position);
+            physicsWorld.addBody(westWallBody);
+            wallBodies.push(westWallBody);
+
+            // Create player physics body (capsule approximated with cylinder)
+            const playerShape = new CANNON.Cylinder(PLAYER_RADIUS, PLAYER_RADIUS, PLAYER_HEIGHT, 8);
+            playerBody = new CANNON.Body({
+                mass: PLAYER_MASS, // kg (configurable via player_config)
+                material: defaultMaterial,
+                fixedRotation: true, // Prevent player from tipping over
+                linearDamping: LINEAR_DAMPING, // Air resistance for movement (configurable)
+            });
+            playerBody.addShape(playerShape);
+
+            // Set player starting position (0, 1, 0) - y=1 means feet at y=1, top at y=2.7
+            playerBody.position.set(0, 1 + PLAYER_HEIGHT / 2, 0);
+            physicsWorld.addBody(playerBody);
+
+            // Add collision detection for grounded check
+            playerBody.addEventListener('collide', (e) => {
+                // Check if colliding with ground
+                if (e.body === groundBody) {
+                    isGrounded = true;
+                    canJump = true;
+                }
+            });
+
+            console.log('Physics world created with ground, walls, and player');
+        }
+
+        function toggleControlMode() {
+            const newMode = controlMode === 'orbit' ? 'fps' : 'orbit';
+            setControlMode(newMode);
+        }
+
+        function setControlMode(mode) {
+            controlMode = mode;
+            const crosshair = document.getElementById('crosshair');
+
+            if (mode === 'fps') {
+                // Switch to FPS
+                orbitControls.enabled = false;
+                // Exit pointer lock if active
+                if (document.pointerLockElement) {
+                    document.exitPointerLock();
+                }
+                isMouseLocked = false;
+
+                // Show crosshair
+                if (crosshair) crosshair.style.display = 'block';
+
+                console.log('Switched to FPS controls - click in viewer to enable mouse-look, WASD to move');
+            } else {
+                // Switch to Orbit
+                if (document.pointerLockElement) {
+                    document.exitPointerLock();
+                }
+                isMouseLocked = false;
+                orbitControls.enabled = true;
+
+                // Hide crosshair
+                if (crosshair) crosshair.style.display = 'none';
+
+                // Clear selection
+                if (outlinePass) outlinePass.selectedObjects = [];
+                selectedObject = null;
+                selectedObjectId = null;
+
+                console.log('Switched to Orbit controls');
+            }
+        }
+
+        function createPhysicsShape(objType, scale) {
+            // Create Cannon.js physics shape based on object type
+            switch (objType) {
+                case 'cube':
+                    return new CANNON.Box(new CANNON.Vec3(scale.x / 2, scale.y / 2, scale.z / 2));
+                case 'sphere':
+                    return new CANNON.Sphere(scale.x);
+                case 'cylinder':
+                    return new CANNON.Cylinder(scale.x, scale.x, scale.y, 8);
+                case 'plane':
+                    // For planes, create a thin box
+                    return new CANNON.Box(new CANNON.Vec3(scale.x / 2, 0.01, scale.y / 2));
+                case 'cone':
+                    // Approximate cone with cylinder (Cannon doesn't have cone shape)
+                    return new CANNON.Cylinder(0, scale.x, scale.y, 8);
+                case 'torus':
+                    // Approximate torus with sphere
+                    return new CANNON.Sphere(scale.x);
+                default:
+                    // Default to box
+                    return new CANNON.Box(new CANNON.Vec3(scale.x / 2, scale.y / 2, scale.z / 2));
+            }
+        }
+
+        function renderGameObjects() {
+            console.log('Rendering', sceneData.objects.length, 'game objects...');
+
+            sceneData.objects.forEach(obj => {
+                // Validate object is within bounds
+                if (Math.abs(obj.position.x) > WORLD_HALF || Math.abs(obj.position.z) > WORLD_HALF) {
+                    console.warn(`Object ${obj.name} at (${obj.position.x}, ${obj.position.z}) is outside 10x10 world bounds - skipping`);
+                    return;
+                }
+                let geometry, mesh;
+
+                // Create geometry based on type
+                switch (obj.type) {
+                    case 'cube':
+                        geometry = new THREE.BoxGeometry(
+                            obj.scale.x,
+                            obj.scale.y,
+                            obj.scale.z
+                        );
+                        break;
+                    case 'sphere':
+                        geometry = new THREE.SphereGeometry(obj.scale.x, 32, 32);
+                        break;
+                    case 'cylinder':
+                        geometry = new THREE.CylinderGeometry(
+                            obj.scale.x,
+                            obj.scale.x,
+                            obj.scale.y,
+                            32
+                        );
+                        break;
+                    case 'plane':
+                        geometry = new THREE.PlaneGeometry(obj.scale.x, obj.scale.y);
+                        break;
+                    case 'cone':
+                        geometry = new THREE.ConeGeometry(obj.scale.x, obj.scale.y, 32);
+                        break;
+                    case 'torus':
+                        geometry = new THREE.TorusGeometry(obj.scale.x, obj.scale.x * 0.4, 16, 100);
+                        break;
+                    default:
+                        console.warn('Unknown object type:', obj.type);
+                        return;
+                }
+
+                // Create material
+                const material = new THREE.MeshStandardMaterial({
+                    color: obj.material.color,
+                    metalness: obj.material.metalness || 0.5,
+                    roughness: obj.material.roughness || 0.5,
+                    opacity: obj.material.opacity || 1.0,
+                    transparent: obj.material.opacity < 1.0,
+                    wireframe: obj.material.wireframe || false,
+                });
+
+                // Create mesh
+                mesh = new THREE.Mesh(geometry, material);
+
+                // Set position
+                mesh.position.set(obj.position.x, obj.position.y, obj.position.z);
+
+                // Set rotation (convert degrees to radians)
+                mesh.rotation.set(
+                    THREE.MathUtils.degToRad(obj.rotation.x),
+                    THREE.MathUtils.degToRad(obj.rotation.y),
+                    THREE.MathUtils.degToRad(obj.rotation.z)
+                );
+
+                // Store metadata
+                mesh.userData = {
+                    id: obj.id,
+                    name: obj.name,
+                    type: obj.type,
+                    isSceneObject: true,
+                };
+
+                scene.add(mesh);
+
+                // Create physics body for collision
+                const physicsShape = createPhysicsShape(obj.type, obj.scale);
+                const physicsBody = new CANNON.Body({
+                    mass: 0, // Static objects
+                    position: new CANNON.Vec3(obj.position.x, obj.position.y, obj.position.z),
+                });
+                physicsBody.addShape(physicsShape);
+
+                // Apply rotation to physics body
+                const quaternion = new CANNON.Quaternion();
+                quaternion.setFromEuler(
+                    THREE.MathUtils.degToRad(obj.rotation.x),
+                    THREE.MathUtils.degToRad(obj.rotation.y),
+                    THREE.MathUtils.degToRad(obj.rotation.z),
+                    'XYZ'
+                );
+                physicsBody.quaternion.copy(quaternion);
+
+                physicsWorld.addBody(physicsBody);
+                objectBodies.set(obj.id, physicsBody);
+
+                console.log('Added object:', obj.name || obj.id, obj.type, 'with physics collider');
+            });
+
+            // Camera position is managed by physics system in FPS mode
+            console.log('Scene objects loaded. Camera controlled by player physics body.');
+        }
+
+        function onWindowResize() {
+            camera.aspect = window.innerWidth / window.innerHeight;
+            camera.updateProjectionMatrix();
+            renderer.setSize(window.innerWidth, window.innerHeight);
+
+            // Update composer
+            if (composer) {
+                composer.setSize(window.innerWidth, window.innerHeight);
+            }
+        }
+
+        function updateLookedAtObject() {
+            if (controlMode !== 'fps') {
+                if (selectedObject) {
+                    outlinePass.selectedObjects = [];
+                    selectedObject = null;
+                    selectedObjectId = null;
+                }
+                return;
+            }
+
+            // Raycast from camera center (crosshair position)
+            const raycaster = new THREE.Raycaster();
+            raycaster.setFromCamera(new THREE.Vector2(0, 0), camera); // Center of screen
+
+            const selectableObjects = scene.children.filter(obj => obj.userData.isSceneObject && obj.userData.id);
+            const intersects = raycaster.intersectObjects(selectableObjects);
+
+            if (intersects.length > 0 && intersects[0].distance < MAX_SELECT_DISTANCE) {
+                const newSelected = intersects[0].object;
+                if (newSelected !== selectedObject) {
+                    selectedObject = newSelected;
+                    selectedObjectId = newSelected.userData.id;
+                    outlinePass.selectedObjects = [selectedObject];
+
+                    console.log('🎯 Object selected:', selectedObjectId, newSelected.userData.type,
+                                `distance: ${intersects[0].distance.toFixed(2)}m`,
+                                `outline array length: ${outlinePass.selectedObjects.length}`);
+
+                    // Send selection to parent (for chat commands)
+                    if (window.parent) {
+                        window.parent.postMessage({
+                            action: 'objectSelected',
+                            data: {
+                                object_id: selectedObjectId,
+                                object_type: newSelected.userData.type,
+                                distance: intersects[0].distance.toFixed(2)
+                            }
+                        }, '*');
+                    }
+                }
+            } else {
+                // No object in view
+                if (selectedObject) {
+                    console.log('🎯 Object deselected');
+                    outlinePass.selectedObjects = [];
+                    selectedObject = null;
+                    selectedObjectId = null;
+
+                    // Notify deselection
+                    if (window.parent) {
+                        window.parent.postMessage({
+                            action: 'objectDeselected',
+                            data: {}
+                        }, '*');
+                    }
+                }
+            }
+        }
+
+        function animate() {
+            requestAnimationFrame(animate);
+
+            // Update stats
+            if (stats) stats.begin();
+
+            const time = performance.now();
+            const delta = (time - prevTime) / 1000;
+
+            // Step physics simulation
+            if (physicsWorld) {
+                physicsWorld.step(1/60, delta, 3);
+            }
+
+            if (controlMode === 'fps' && playerBody) {
+                // Apply camera rotation from mouse-look
+                camera.rotation.order = 'YXZ'; // Ensure correct rotation order
+                camera.rotation.y = cameraRotationY;
+                camera.rotation.x = cameraRotationX;
+                camera.rotation.z = 0;
+
+                // Get input direction from keyboard
+                direction.z = Number(moveForward.value) - Number(moveBackward.value);
+                direction.x = Number(moveRight.value) - Number(moveLeft.value);
+                direction.y = 0; // No vertical movement from input
+                direction.normalize();
+
+                // Calculate movement direction relative to camera orientation
+                const forward = new THREE.Vector3(0, 0, -1);
+                const right = new THREE.Vector3(1, 0, 0);
+
+                // Apply camera rotation to get movement direction
+                forward.applyQuaternion(camera.quaternion);
+                right.applyQuaternion(camera.quaternion);
+
+                // Project to horizontal plane
+                forward.y = 0;
+                right.y = 0;
+                forward.normalize();
+                right.normalize();
+
+                // Apply movement to physics body (keep current Y velocity for gravity/jump)
+                // Reduce effectiveness when airborne based on air control setting
+                const controlFactor = isGrounded ? 1.0 : airControl;
+                const moveX = (direction.x * right.x + direction.z * forward.x) * moveSpeed * controlFactor;
+                const moveZ = (direction.x * right.z + direction.z * forward.z) * moveSpeed * controlFactor;
+
+                playerBody.velocity.x = moveX;
+                playerBody.velocity.z = moveZ;
+                // Don't modify playerBody.velocity.y - let physics handle gravity and jumping
+
+                // Check if grounded using a small raycast downward
+                const groundRaycaster = new THREE.Raycaster(
+                    new THREE.Vector3(playerBody.position.x, playerBody.position.y, playerBody.position.z),
+                    new THREE.Vector3(0, -1, 0),
+                    0,
+                    PLAYER_HEIGHT / 2 + 0.1
+                );
+                const groundIntersects = groundRaycaster.intersectObjects(
+                    scene.children.filter(obj => obj.userData.isGround || obj.userData.isWall || obj.userData.isSceneObject)
+                );
+                if (groundIntersects.length > 0) {
+                    isGrounded = true;
+                    canJump = true;
+                } else {
+                    isGrounded = false;
+                }
+
+                // Sync camera position to physics body (at eye height)
+                camera.position.x = playerBody.position.x;
+                camera.position.y = playerBody.position.y - PLAYER_HEIGHT / 2 + EYE_HEIGHT;
+                camera.position.z = playerBody.position.z;
+
+                prevTime = time;
+            } else if (controlMode === 'orbit') {
+                // Orbit controls
+                orbitControls.update();
+            }
+
+            // Update looked-at object (FPS mode only)
+            updateLookedAtObject();
+
+            // Render using composer (for outlines) instead of direct renderer
+            if (composer) {
+                composer.render();
+            } else {
+                renderer.render(scene, camera);
+            }
+
+            // End stats measurement
+            if (stats) stats.end();
+        }
+
+        // ==================== Scene Control Functions ====================
+
+        /**
+         * Toggle grid helper visibility
+         */
+        function toggleGrid(enabled) {
+            if (gridHelper) {
+                gridHelper.visible = enabled;
+                console.log('Grid helper:', enabled ? 'enabled' : 'disabled');
+            }
+        }
+
+        /**
+         * Toggle wireframe mode for all objects
+         */
+        function toggleWireframe(enabled) {
+            wireframeEnabled = enabled;
+            scene.traverse((object) => {
+                if (object.isMesh && object.material) {
+                    object.material.wireframe = enabled;
+                }
+            });
+            console.log('Wireframe mode:', enabled ? 'enabled' : 'disabled');
+        }
+
+        /**
+         * Toggle stats (FPS counter) display
+         */
+        function toggleStats(enabled) {
+            if (stats) {
+                stats.dom.style.display = enabled ? 'block' : 'none';
+                console.log('Stats:', enabled ? 'enabled' : 'disabled');
+            }
+        }
+
+        /**
+         * Capture screenshot of the current scene
+         */
+        function captureScreenshot() {
+            if (!renderer) {
+                console.error('Renderer not initialized');
+                return;
+            }
+
+            // Render one more frame to ensure we have the latest scene
+            renderer.render(scene, camera);
+
+            // Get the canvas data as PNG
+            const dataURL = renderer.domElement.toDataURL('image/png');
+
+            // Send screenshot data back to parent window
+            window.parent.postMessage({
+                action: 'screenshot',
+                data: {
+                    dataURL: dataURL,
+                    timestamp: Date.now(),
+                    sceneName: sceneData?.name || 'scene'
+                }
+            }, '*');
+
+            console.log('Screenshot captured and sent to parent window');
+        }
+
+        /**
+         * Handle object click for inspection
+         */
+        function onObjectClick(event) {
+            // Calculate mouse position in normalized device coordinates (-1 to +1)
+            const rect = renderer.domElement.getBoundingClientRect();
+            mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+            mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+
+            // Update raycaster
+            raycaster.setFromCamera(mouse, camera);
+
+            // Find intersections (only check mesh objects, not lights or helpers)
+            const intersects = raycaster.intersectObjects(scene.children.filter(obj => obj.isMesh));
+
+            if (intersects.length > 0) {
+                const clickedObject = intersects[0].object;
+
+                // Deselect previous object
+                if (selectedObject && selectedObject !== clickedObject) {
+                    if (selectedObject.userData.originalColor) {
+                        selectedObject.material.emissive.copy(selectedObject.userData.originalColor);
+                        selectedObject.material.emissiveIntensity = 0;
+                    }
+                }
+
+                // Select new object
+                selectedObject = clickedObject;
+
+                // Highlight selected object with persistent glow
+                if (!selectedObject.userData.originalColor) {
+                    selectedObject.userData.originalColor = selectedObject.material.emissive.clone();
+                }
+                selectedObject.material.emissive = new THREE.Color(0x4444ff);
+                selectedObject.material.emissiveIntensity = 0.3;
+
+                // Get object properties
+                const objectInfo = {
+                    id: clickedObject.userData.id,
+                    name: clickedObject.userData.name || 'Unnamed Object',
+                    type: clickedObject.userData.type || 'unknown',
+                    position: {
+                        x: clickedObject.position.x.toFixed(2),
+                        y: clickedObject.position.y.toFixed(2),
+                        z: clickedObject.position.z.toFixed(2)
+                    },
+                    rotation: {
+                        x: THREE.MathUtils.radToDeg(clickedObject.rotation.x).toFixed(2),
+                        y: THREE.MathUtils.radToDeg(clickedObject.rotation.y).toFixed(2),
+                        z: THREE.MathUtils.radToDeg(clickedObject.rotation.z).toFixed(2)
+                    },
+                    scale: {
+                        x: clickedObject.scale.x.toFixed(2),
+                        y: clickedObject.scale.y.toFixed(2),
+                        z: clickedObject.scale.z.toFixed(2)
+                    },
+                    color: '#' + clickedObject.material.color.getHexString()
+                };
+
+                // Send object info to parent window
+                window.parent.postMessage({
+                    action: 'objectInspect',
+                    data: objectInfo
+                }, '*');
+
+                console.log('Object selected:', objectInfo);
+            }
+        }
+
+        // ==================== PostMessage API for Dynamic Updates ====================
+
+        /**
+         * Listen for messages from parent window (Gradio) to update scene dynamically
+         * This eliminates the need for iframe reloads
+         */
+        window.addEventListener('message', (event) => {
+            // Security: verify origin in production
+            // if (event.origin !== window.location.origin) return;
+
+            const { action, data } = event.data;
+            console.log('📨 Received postMessage:', action, data);
+
+            switch (action) {
+                case 'addObject':
+                    handleAddObject(data);
+                    break;
+                case 'removeObject':
+                    handleRemoveObject(data);
+                    break;
+                case 'setLighting':
+                    handleSetLighting(data);
+                    break;
+                case 'updateScene':
+                    handleUpdateScene(data);
+                    break;
+                case 'setControlMode':
+                    setControlMode(data.mode);
+                    break;
+                case 'toggleGrid':
+                    toggleGrid(data.enabled);
+                    break;
+                case 'toggleWireframe':
+                    toggleWireframe(data.enabled);
+                    break;
+                case 'toggleStats':
+                    toggleStats(data.enabled);
+                    break;
+                case 'takeScreenshot':
+                    captureScreenshot();
+                    break;
+                case 'addLight':
+                    addLightToScene(data);
+                    break;
+                case 'removeLight':
+                    removeLightFromScene(data.light_name);
+                    break;
+                case 'updateLight':
+                    updateSceneLight(data.light_name, data);
+                    break;
+                case 'updateMaterial':
+                    updateObjectMaterial(data.object_id, data);
+                    break;
+                case 'setBackground':
+                    setSceneBackground(data);
+                    break;
+                case 'setFog':
+                    setSceneFog(data);
+                    break;
+                default:
+                    console.warn('Unknown postMessage action:', action);
+            }
+        });
+
+        /**
+         * Dynamically add an object to the scene
+         */
+        function handleAddObject(objData) {
+            if (!scene || !sceneData) {
+                console.error('Scene not initialized yet');
+                return;
+            }
+
+            // Validate object is within bounds
+            if (Math.abs(objData.position.x) > WORLD_HALF || Math.abs(objData.position.z) > WORLD_HALF) {
+                console.error(`Cannot add object at (${objData.position.x}, ${objData.position.z}) - outside 10x10 world bounds`);
+                return;
+            }
+
+            // Add to scene data
+            sceneData.objects.push(objData);
+
+            // Create and add to Three.js scene
+            let geometry;
+            switch (objData.type) {
+                case 'cube':
+                    geometry = new THREE.BoxGeometry(objData.scale.x, objData.scale.y, objData.scale.z);
+                    break;
+                case 'sphere':
+                    geometry = new THREE.SphereGeometry(objData.scale.x, 32, 32);
+                    break;
+                case 'cylinder':
+                    geometry = new THREE.CylinderGeometry(objData.scale.x, objData.scale.x, objData.scale.y, 32);
+                    break;
+                case 'plane':
+                    geometry = new THREE.PlaneGeometry(objData.scale.x, objData.scale.y);
+                    break;
+                case 'cone':
+                    geometry = new THREE.ConeGeometry(objData.scale.x, objData.scale.y, 32);
+                    break;
+                case 'torus':
+                    geometry = new THREE.TorusGeometry(objData.scale.x, objData.scale.x * 0.4, 16, 100);
+                    break;
+                default:
+                    console.warn('Unknown object type:', objData.type);
+                    return;
+            }
+
+            const material = new THREE.MeshStandardMaterial({
+                color: objData.material.color,
+                metalness: objData.material.metalness || 0.5,
+                roughness: objData.material.roughness || 0.5,
+                opacity: objData.material.opacity || 1.0,
+                transparent: objData.material.opacity < 1.0,
+                wireframe: wireframeEnabled || objData.material.wireframe || false,
+            });
+
+            const mesh = new THREE.Mesh(geometry, material);
+            mesh.position.set(objData.position.x, objData.position.y, objData.position.z);
+            mesh.rotation.set(
+                THREE.MathUtils.degToRad(objData.rotation.x),
+                THREE.MathUtils.degToRad(objData.rotation.y),
+                THREE.MathUtils.degToRad(objData.rotation.z)
+            );
+            mesh.userData = {
+                id: objData.id,
+                name: objData.name,
+                type: objData.type,
+                isSceneObject: true,
+            };
+
+            scene.add(mesh);
+
+            // Create physics body for collision
+            const physicsShape = createPhysicsShape(objData.type, objData.scale);
+            const physicsBody = new CANNON.Body({
+                mass: 0, // Static objects
+                position: new CANNON.Vec3(objData.position.x, objData.position.y, objData.position.z),
+            });
+            physicsBody.addShape(physicsShape);
+
+            // Apply rotation to physics body
+            const quaternion = new CANNON.Quaternion();
+            quaternion.setFromEuler(
+                THREE.MathUtils.degToRad(objData.rotation.x),
+                THREE.MathUtils.degToRad(objData.rotation.y),
+                THREE.MathUtils.degToRad(objData.rotation.z),
+                'XYZ'
+            );
+            physicsBody.quaternion.copy(quaternion);
+
+            physicsWorld.addBody(physicsBody);
+            objectBodies.set(objData.id, physicsBody);
+
+            // Add highlight effect
+            animateObjectHighlight(mesh);
+
+            console.log('Added object dynamically:', objData.name || objData.id);
+        }
+
+        /**
+         * Dynamically remove an object from the scene
+         */
+        function handleRemoveObject(data) {
+            if (!scene || !sceneData) {
+                console.error('Scene not initialized yet');
+                return;
+            }
+
+            const { object_id } = data;
+
+            // Remove from Three.js scene
+            const objectToRemove = scene.children.find(obj => obj.userData && obj.userData.id === object_id);
+            if (objectToRemove) {
+                scene.remove(objectToRemove);
+                if (objectToRemove.geometry) objectToRemove.geometry.dispose();
+                if (objectToRemove.material) objectToRemove.material.dispose();
+            }
+
+            // Remove physics body
+            const physicsBody = objectBodies.get(object_id);
+            if (physicsBody) {
+                physicsWorld.removeBody(physicsBody);
+                objectBodies.delete(object_id);
+            }
+
+            // Remove from scene data
+            sceneData.objects = sceneData.objects.filter(obj => obj.id !== object_id);
+
+            console.log('Removed object dynamically:', object_id);
+        }
+
+        /**
+         * Dynamically update lighting
+         */
+        function handleSetLighting(data) {
+            if (!scene || !sceneData) {
+                console.error('Scene not initialized yet');
+                return;
+            }
+
+            const { lights } = data;
+
+            // Remove all existing lights
+            const lightsToRemove = scene.children.filter(obj => obj.isLight);
+            lightsToRemove.forEach(light => scene.remove(light));
+
+            // Add new lights
+            lights.forEach(lightData => {
+                let light;
+
+                if (lightData.type === 'ambient') {
+                    light = new THREE.AmbientLight(lightData.color, lightData.intensity);
+                } else if (lightData.type === 'directional') {
+                    light = new THREE.DirectionalLight(lightData.color, lightData.intensity);
+                    light.position.set(lightData.position.x, lightData.position.y, lightData.position.z);
+                    light.target.position.set(0, 0, 0);
+                    scene.add(light.target);
+                    if (lightData.cast_shadow) {
+                        light.castShadow = true;
+                    }
+                } else if (lightData.type === 'point') {
+                    light = new THREE.PointLight(lightData.color, lightData.intensity);
+                    light.position.set(lightData.position.x, lightData.position.y, lightData.position.z);
+                }
+
+                if (light) {
+                    scene.add(light);
+                }
+            });
+
+            // Update scene data
+            sceneData.lights = lights;
+
+            console.log('Updated lighting dynamically');
+        }
+
+        /**
+         * Fully reload the scene from new data
+         */
+        function handleUpdateScene(data) {
+            // For major updates, we can reload the entire scene
+            // This is a fallback for complex changes
+            location.reload();
+        }
+
+        /**
+         * Animate object highlight with enhanced color pulse and scale effect
+         */
+        function animateObjectHighlight(mesh) {
+            const originalColor = mesh.material.color.clone();
+            const originalScale = mesh.scale.clone();
+
+            // Color pulse sequence: yellow -> cyan -> yellow
+            const pulseColors = [
+                new THREE.Color(0xffff00), // Yellow
+                new THREE.Color(0x00ffff), // Cyan
+                new THREE.Color(0xffff00), // Yellow
+            ];
+
+            let progress = 0;
+            const duration = 90; // frames (1.5 seconds at 60fps)
+            const pulseIntensity = 0.6; // How much to mix highlight colors
+
+            function animateHighlight() {
+                if (progress < duration) {
+                    // Calculate normalized progress (0 to 1)
+                    const t = progress / duration;
+
+                    // Color animation - cycle through pulse colors
+                    const colorPhase = t * (pulseColors.length - 1);
+                    const colorIndex = Math.floor(colorPhase);
+                    const colorBlend = colorPhase - colorIndex;
+
+                    if (colorIndex < pulseColors.length - 1) {
+                        const color1 = pulseColors[colorIndex];
+                        const color2 = pulseColors[colorIndex + 1];
+                        const blendedColor = color1.clone().lerp(color2, colorBlend);
+
+                        // Mix with original color using sine wave for smooth pulse
+                        const pulseMix = Math.sin(t * Math.PI) * pulseIntensity;
+                        mesh.material.color.lerpColors(originalColor, blendedColor, pulseMix);
+                    }
+
+                    // Scale animation - subtle "pop" effect
+                    const scaleAmount = 1.0 + Math.sin(t * Math.PI) * 0.15; // 15% scale increase
+                    mesh.scale.copy(originalScale).multiplyScalar(scaleAmount);
+
+                    // Increase emissive for glow effect
+                    if (mesh.material.emissive) {
+                        const emissiveIntensity = Math.sin(t * Math.PI * 2) * 0.3;
+                        mesh.material.emissiveIntensity = emissiveIntensity;
+                    }
+
+                    progress++;
+                    requestAnimationFrame(animateHighlight);
+                } else {
+                    // Reset to original state
+                    mesh.material.color.copy(originalColor);
+                    mesh.scale.copy(originalScale);
+                    if (mesh.material.emissive) {
+                        mesh.material.emissiveIntensity = 0;
+                    }
+                }
+            }
+
+            // Enable emissive if not already set
+            if (!mesh.material.emissive) {
+                mesh.material.emissive = new THREE.Color(originalColor);
+                mesh.material.emissiveIntensity = 0;
+            }
+
+            animateHighlight();
+        }
+
+        // ==================== Rendering & Lighting Handler Functions ====================
+
+        function addLightToScene(lightData) {
+            console.log('💡 addLightToScene called with:', lightData);
+            let light;
+
+            if (lightData.light_type === 'ambient') {
+                light = new THREE.AmbientLight(lightData.color, lightData.intensity);
+            } else if (lightData.light_type === 'directional') {
+                light = new THREE.DirectionalLight(lightData.color, lightData.intensity);
+                light.position.set(lightData.position.x, lightData.position.y, lightData.position.z);
+                if (lightData.target) {
+                    light.target.position.set(lightData.target.x, lightData.target.y, lightData.target.z);
+                    scene.add(light.target);
+                }
+            } else if (lightData.light_type === 'point') {
+                light = new THREE.PointLight(lightData.color, lightData.intensity);
+                light.position.set(lightData.position.x, lightData.position.y, lightData.position.z);
+            } else if (lightData.light_type === 'spot') {
+                light = new THREE.SpotLight(lightData.color, lightData.intensity);
+                light.position.set(lightData.position.x, lightData.position.y, lightData.position.z);
+                light.angle = THREE.MathUtils.degToRad(lightData.spot_angle || 45);
+                if (lightData.target) {
+                    light.target.position.set(lightData.target.x, lightData.target.y, lightData.target.z);
+                    scene.add(light.target);
+                }
+            }
+
+            if (light) {
+                light.name = lightData.name;
+                if (lightData.cast_shadow) light.castShadow = true;
+                scene.add(light);
+                console.log('💡 Light added to scene:', lightData.name, 'type:', lightData.light_type);
+            } else {
+                console.error('❌ Failed to create light:', lightData);
+            }
+        }
+
+        function removeLightFromScene(lightName) {
+            const light = scene.getObjectByName(lightName);
+            if (light) {
+                scene.remove(light);
+                console.log('Removed light:', lightName);
+            }
+        }
+
+        function updateSceneLight(lightName, updates) {
+            const light = scene.getObjectByName(lightName);
+            if (!light) return;
+
+            if (updates.color) light.color.set(updates.color);
+            if (updates.intensity !== undefined) light.intensity = updates.intensity;
+            if (updates.position) {
+                light.position.set(updates.position.x, updates.position.y, updates.position.z);
+            }
+            if (updates.cast_shadow !== undefined) light.castShadow = updates.cast_shadow;
+
+            console.log('Updated light:', lightName);
+        }
+
+        function updateObjectMaterial(objectId, materialData) {
+            console.log('updateObjectMaterial called with:', objectId, materialData);
+            const obj = scene.children.find(child => child.userData.id === objectId);
+            if (!obj || !obj.material) {
+                console.error('Object not found or has no material:', objectId);
+                return;
+            }
+
+            console.log('Found object:', obj.userData.name, 'Current color:', obj.material.color.getHexString());
+
+            if (materialData.color) {
+                obj.material.color.set(materialData.color);
+                console.log('Set color to:', materialData.color);
+            }
+            if (materialData.metalness !== undefined) {
+                obj.material.metalness = materialData.metalness;
+                console.log('Set metalness to:', materialData.metalness);
+            }
+            if (materialData.roughness !== undefined) {
+                obj.material.roughness = materialData.roughness;
+                console.log('Set roughness to:', materialData.roughness);
+            }
+            if (materialData.opacity !== undefined) {
+                obj.material.opacity = materialData.opacity;
+                obj.material.transparent = materialData.opacity < 1.0;
+                console.log('Set opacity to:', materialData.opacity);
+            }
+            if (materialData.emissive) {
+                obj.material.emissive = new THREE.Color(materialData.emissive);
+                console.log('Set emissive to:', materialData.emissive);
+            }
+            if (materialData.emissive_intensity !== undefined) {
+                obj.material.emissiveIntensity = materialData.emissive_intensity;
+                console.log('Set emissive intensity to:', materialData.emissive_intensity);
+            }
+
+            obj.material.needsUpdate = true;
+            console.log('Material updated successfully! New color:', obj.material.color.getHexString());
+        }
+
+        function setSceneBackground(bgData) {
+            if (bgData.background_type === 'gradient') {
+                // Create gradient canvas
+                const canvas = document.createElement('canvas');
+                canvas.width = 2;
+                canvas.height = 256;
+                const ctx = canvas.getContext('2d');
+                const gradient = ctx.createLinearGradient(0, 0, 0, 256);
+                gradient.addColorStop(0, bgData.background_gradient_top);
+                gradient.addColorStop(1, bgData.background_gradient_bottom);
+                ctx.fillStyle = gradient;
+                ctx.fillRect(0, 0, 2, 256);
+
+                const texture = new THREE.CanvasTexture(canvas);
+                scene.background = texture;
+            } else {
+                scene.background = new THREE.Color(bgData.background_color);
+            }
+
+            console.log('Updated background');
+        }
+
+        function setSceneFog(fogData) {
+            if (!fogData.enabled) {
+                scene.fog = null;
+                console.log('Fog disabled');
+                return;
+            }
+
+            const color = new THREE.Color(fogData.color);
+
+            if (fogData.type === 'exponential') {
+                scene.fog = new THREE.FogExp2(color, fogData.density);
+            } else {
+                scene.fog = new THREE.Fog(color, fogData.near, fogData.far);
+            }
+
+            console.log('Fog enabled:', fogData.type);
+        }
+
+        // Start the application
+        init();
+    </script>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,14 @@
+# Core Backend
+fastapi
+uvicorn[standard]
+requests
+
+# MCP Server (official Anthropic SDK)
+mcp>=1.0.0
+
+# Chat Interface
+gradio
+
+# LLM
+openai
+python-dotenv