Upload folder using huggingface_hub

teeunit_env/__init__.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2024 TeeUnit Project
+# SPDX-License-Identifier: MIT
+
+"""
+TeeUnit OpenEnv Environment
+
+An OpenEnv-compatible multi-agent arena environment wrapping the real Teeworlds 0.7.5 game
+for LLM-based reinforcement learning training.
+
+Example:
+    >>> from teeunit_env import TeeEnv
+    >>> 
+    >>> with TeeEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])
+    ...     # ['move', 'jump', 'aim', 'shoot', 'hook', 'get_status']
+    ...     
+    ...     # Get current game state
+    ...     status = env.call_tool("get_status")
+    ...     print(status)
+    ...     
+    ...     # Take actions
+    ...     env.call_tool("move", direction="right")
+    ...     env.call_tool("aim", x=500, y=300)
+    ...     env.call_tool("shoot", weapon=1)
+"""
+
+from .client import TeeEnv, TeeAction
+
+__all__ = ["TeeEnv", "TeeAction"]
+__version__ = "0.1.0"

teeunit_env/client.py

@@ -0,0 +1,251 @@
+# Copyright (c) 2024 TeeUnit Project
+# SPDX-License-Identifier: MIT
+
+"""
+TeeUnit Environment Client.
+
+This module provides the client for connecting to a TeeUnit Environment server.
+TeeEnv extends MCPToolClient to provide tool-calling style interactions.
+
+Example:
+    >>> with TeeEnv(base_url="http://localhost:8000") as env:
+    ...     env.reset()
+    ...
+    ...     # Discover tools
+    ...     tools = env.list_tools()
+    ...     print([t.name for t in tools])  # ['move', 'jump', 'aim', 'shoot', 'hook', 'get_status']
+    ...
+    ...     # Get game state
+    ...     status = env.call_tool("get_status")
+    ...     print(status)
+    ...
+    ...     # Take actions
+    ...     result = env.call_tool("move", direction="right")
+    ...     result = env.call_tool("shoot", weapon=2)
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Any, Dict
+
+# Support both in-repo and standalone imports
+try:
+    from openenv.core.mcp_client import MCPToolClient
+except ImportError:
+    # Fallback for development/testing without openenv installed
+    class MCPToolClient:
+        """Fallback MCPToolClient for development."""
+        
+        def __init__(self, base_url: str = "http://localhost:8000", **kwargs):
+            self.base_url = base_url
+            self._connected = False
+        
+        def __enter__(self):
+            self._connected = True
+            return self
+        
+        def __exit__(self, *args):
+            self._connected = False
+        
+        def reset(self, **kwargs):
+            pass
+        
+        def list_tools(self):
+            return []
+        
+        def call_tool(self, name: str, **kwargs):
+            return None
+        
+        def step(self, action):
+            return None
+        
+        def close(self):
+            self._connected = False
+        
+        @classmethod
+        def from_docker_image(cls, image: str, **kwargs):
+            return cls(**kwargs)
+        
+        @classmethod
+        def from_env(cls, env_id: str, **kwargs):
+            return cls(**kwargs)
+
+
+@dataclass
+class TeeAction:
+    """
+    Action for the TeeUnit environment.
+    
+    This is a convenience class for building actions to send to the environment.
+    The actual actions are sent via MCP tools (move, jump, aim, shoot, hook).
+    
+    Attributes:
+        tool_name: The MCP tool to call
+        arguments: Arguments for the tool
+    """
+    tool_name: str
+    arguments: Dict[str, Any]
+    
+    @classmethod
+    def move(cls, direction: str = "none") -> "TeeAction":
+        """Create a move action."""
+        return cls(tool_name="move", arguments={"direction": direction})
+    
+    @classmethod
+    def jump(cls) -> "TeeAction":
+        """Create a jump action."""
+        return cls(tool_name="jump", arguments={})
+    
+    @classmethod
+    def aim(cls, x: int, y: int) -> "TeeAction":
+        """Create an aim action."""
+        return cls(tool_name="aim", arguments={"x": x, "y": y})
+    
+    @classmethod
+    def shoot(cls, weapon: int = -1) -> "TeeAction":
+        """Create a shoot action."""
+        return cls(tool_name="shoot", arguments={"weapon": weapon})
+    
+    @classmethod
+    def hook(cls) -> "TeeAction":
+        """Create a hook action."""
+        return cls(tool_name="hook", arguments={})
+    
+    @classmethod
+    def get_status(cls) -> "TeeAction":
+        """Create a get_status action."""
+        return cls(tool_name="get_status", arguments={})
+
+
+class TeeEnv(MCPToolClient):
+    """
+    Client for the TeeUnit Environment.
+    
+    This client provides a simple interface for interacting with the TeeUnit
+    Environment via MCP tools. It inherits all functionality from MCPToolClient:
+    - `list_tools()`: Discover available tools
+    - `call_tool(name, **kwargs)`: Call a tool by name
+    - `reset(**kwargs)`: Reset the environment
+    - `step(action)`: Execute an action
+    
+    Available MCP Tools:
+    - `move(direction)`: Move left, right, or none
+    - `jump()`: Make the tee jump
+    - `aim(x, y)`: Aim at coordinates
+    - `shoot(weapon)`: Fire weapon (0-5 or -1 for current)
+    - `hook()`: Use grappling hook
+    - `get_status()`: Get game state as text
+    
+    Example:
+        >>> # Connect to a running server
+        >>> with TeeEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...
+        ...     # List available tools
+        ...     tools = env.list_tools()
+        ...     for tool in tools:
+        ...         print(f"{tool.name}: {tool.description}")
+        ...
+        ...     # Get game state
+        ...     status = env.call_tool("get_status")
+        ...     print(status)
+        ...
+        ...     # Take actions
+        ...     env.call_tool("move", direction="right")
+        ...     env.call_tool("aim", x=500, y=300)
+        ...     env.call_tool("shoot", weapon=2)
+    
+    Example with HuggingFace Space:
+        >>> # Connect to HuggingFace Space
+        >>> env = TeeEnv.from_env("ziadbc/teeunit-env")
+        >>> try:
+        ...     env.reset()
+        ...     status = env.call_tool("get_status")
+        ...     print(status)
+        ... finally:
+        ...     env.close()
+    
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> env = TeeEnv.from_docker_image("teeunit-env:latest")
+        >>> try:
+        ...     env.reset()
+        ...     env.call_tool("move", direction="right")
+        ... finally:
+        ...     env.close()
+    """
+    
+    def execute_action(self, action: TeeAction) -> Any:
+        """
+        Execute a TeeAction.
+        
+        Args:
+            action: TeeAction to execute
+            
+        Returns:
+            Result from the MCP tool call
+        """
+        return self.call_tool(action.tool_name, **action.arguments)
+    
+    def get_status(self) -> str:
+        """
+        Get the current game state as text.
+        
+        Returns:
+            Text description of game state
+        """
+        return self.call_tool("get_status")
+    
+    def move(self, direction: str = "none") -> str:
+        """
+        Move the tee.
+        
+        Args:
+            direction: "left", "right", or "none"
+            
+        Returns:
+            Result message
+        """
+        return self.call_tool("move", direction=direction)
+    
+    def jump(self) -> str:
+        """
+        Make the tee jump.
+        
+        Returns:
+            Result message
+        """
+        return self.call_tool("jump")
+    
+    def aim(self, x: int, y: int) -> str:
+        """
+        Aim at coordinates.
+        
+        Args:
+            x: Target X coordinate
+            y: Target Y coordinate
+            
+        Returns:
+            Result message
+        """
+        return self.call_tool("aim", x=x, y=y)
+    
+    def shoot(self, weapon: int = -1) -> str:
+        """
+        Fire weapon.
+        
+        Args:
+            weapon: Weapon ID (0-5) or -1 for current weapon
+            
+        Returns:
+            Result message
+        """
+        return self.call_tool("shoot", weapon=weapon)
+    
+    def hook(self) -> str:
+        """
+        Use grappling hook.
+        
+        Returns:
+            Result message
+        """
+        return self.call_tool("hook")

teeunit_env/openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: teeunit_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

teeunit_env/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "teeunit-env"
+version = "0.1.0"
+description = "OpenEnv-compatible Teeworlds arena environment for LLM RL training"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "TeeUnit Team", email = "ziadbc@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+keywords = ["openenv", "teeworlds", "reinforcement-learning", "llm", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "openenv-core>=0.2.1",
+    "fastmcp>=0.1.0",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.23.0",
+    "pydantic>=2.0.0",
+    "websockets>=11.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "httpx>=0.24",
+]
+
+[project.scripts]
+teeunit-server = "teeunit_env.server.app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["teeunit_env"]

teeunit_env/server/Dockerfile

@@ -0,0 +1,38 @@
+# TeeUnit OpenEnv Environment
+# Compatible with HuggingFace Spaces
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy environment files
+COPY teeunit_env/ ./teeunit_env/
+COPY teeunit_env/pyproject.toml ./
+
+# Install Python dependencies
+RUN pip install --no-cache-dir \
+    openenv-core>=0.2.1 \
+    fastmcp>=0.1.0 \
+    fastapi>=0.100.0 \
+    uvicorn>=0.23.0 \
+    pydantic>=2.0.0 \
+    websockets>=11.0
+
+# Expose port
+EXPOSE 8000
+
+# Set environment variables
+ENV PYTHONPATH=/app
+ENV PYTHONUNBUFFERED=1
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Run the server
+CMD ["uvicorn", "teeunit_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

teeunit_env/server/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2024 TeeUnit Project
+# SPDX-License-Identifier: MIT
+
+"""
+TeeUnit OpenEnv Server
+
+This module provides the server-side implementation of the TeeUnit environment,
+exposing Teeworlds game control through MCP tools.
+"""
+
+from .tee_environment import TeeEnvironment
+
+__all__ = ["TeeEnvironment"]

teeunit_env/server/app.py

@@ -0,0 +1,309 @@
+# Copyright (c) 2024 TeeUnit Project
+# SPDX-License-Identifier: MIT
+
+"""
+FastAPI application for the TeeUnit Environment.
+
+This module creates an HTTP server that exposes the TeeEnvironment
+over HTTP and WebSocket endpoints, compatible with MCPToolClient.
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn teeunit_env.server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn teeunit_env.server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m teeunit_env.server.app
+"""
+
+# Support both in-repo and standalone imports
+try:
+    from openenv.core.env_server.http_server import create_app
+    from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+    
+    from .tee_environment import TeeEnvironment
+    
+    # Create the app with web interface
+    # Pass the class (factory) instead of an instance for WebSocket session support
+    # Use MCP types for action/observation since this is a pure MCP environment
+    app = create_app(
+        TeeEnvironment, CallToolAction, CallToolObservation, env_name="teeunit_env"
+    )
+
+except ImportError:
+    # Fallback: Create a simple FastAPI app for development/testing
+    from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+    from fastapi.middleware.cors import CORSMiddleware
+    from pydantic import BaseModel
+    from typing import Optional, Dict, Any
+    import json
+    
+    # Import our environment
+    try:
+        from .tee_environment import TeeEnvironment
+    except ImportError:
+        from tee_environment import TeeEnvironment
+    
+    app = FastAPI(
+        title="TeeUnit OpenEnv",
+        description="OpenEnv-compatible Teeworlds arena environment for LLM RL training",
+        version="0.1.0",
+    )
+    
+    # Add CORS middleware
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    
+    # Store environment instances per session
+    _environments: Dict[str, TeeEnvironment] = {}
+    
+    class ResetRequest(BaseModel):
+        seed: Optional[int] = None
+        episode_id: Optional[str] = None
+    
+    class ResetResponse(BaseModel):
+        status: str
+        episode_id: str
+        message: str
+    
+    class ToolCallRequest(BaseModel):
+        tool_name: str
+        arguments: Dict[str, Any] = {}
+    
+    class ToolCallResponse(BaseModel):
+        result: Any
+        reward: float
+        done: bool
+        metadata: Dict[str, Any] = {}
+    
+    class ToolInfo(BaseModel):
+        name: str
+        description: str
+        parameters: Dict[str, Any] = {}
+    
+    @app.get("/")
+    async def root():
+        """Root endpoint with environment info."""
+        return {
+            "name": "TeeUnit OpenEnv",
+            "version": "0.1.0",
+            "description": "OpenEnv-compatible Teeworlds arena for LLM training",
+            "endpoints": {
+                "reset": "POST /reset",
+                "tools": "GET /tools",
+                "call_tool": "POST /call_tool",
+                "websocket": "WS /ws",
+            }
+        }
+    
+    @app.get("/health")
+    async def health():
+        """Health check endpoint."""
+        return {"status": "healthy"}
+    
+    @app.post("/reset", response_model=ResetResponse)
+    async def reset(request: ResetRequest):
+        """Reset the environment for a new episode."""
+        env = TeeEnvironment()
+        obs = env.reset(seed=request.seed, episode_id=request.episode_id)
+        
+        session_id = obs.metadata.get("episode_id", "default")
+        _environments[session_id] = env
+        
+        return ResetResponse(
+            status="ready",
+            episode_id=session_id,
+            message=obs.metadata.get("message", "Environment ready"),
+        )
+    
+    @app.get("/tools")
+    async def list_tools():
+        """List available MCP tools."""
+        return {
+            "tools": [
+                {
+                    "name": "move",
+                    "description": "Move the tee left, right, or none",
+                    "parameters": {"direction": {"type": "string", "enum": ["left", "right", "none"]}},
+                },
+                {
+                    "name": "jump",
+                    "description": "Make the tee jump",
+                    "parameters": {},
+                },
+                {
+                    "name": "aim",
+                    "description": "Aim at target coordinates",
+                    "parameters": {
+                        "x": {"type": "integer", "description": "Target X coordinate"},
+                        "y": {"type": "integer", "description": "Target Y coordinate"},
+                    },
+                },
+                {
+                    "name": "shoot",
+                    "description": "Fire the specified weapon",
+                    "parameters": {
+                        "weapon": {"type": "integer", "description": "Weapon ID (0-5) or -1 for current", "default": -1},
+                    },
+                },
+                {
+                    "name": "hook",
+                    "description": "Use the grappling hook",
+                    "parameters": {},
+                },
+                {
+                    "name": "get_status",
+                    "description": "Get current game state as text",
+                    "parameters": {},
+                },
+            ]
+        }
+    
+    @app.post("/call_tool", response_model=ToolCallResponse)
+    async def call_tool(request: ToolCallRequest, session_id: str = "default"):
+        """Call an MCP tool."""
+        env = _environments.get(session_id)
+        if env is None:
+            env = TeeEnvironment()
+            env.reset()
+            _environments[session_id] = env
+        
+        # Get the MCP server from environment
+        mcp = env._mcp
+        
+        # Call the tool
+        tool_name = request.tool_name
+        arguments = request.arguments
+        
+        try:
+            # Use FastMCP's async call_tool method
+            tool_result = await mcp.call_tool(tool_name, arguments)
+            
+            # Extract text result from ToolResult
+            if tool_result and tool_result.content:
+                result = tool_result.content[0].text if hasattr(tool_result.content[0], 'text') else str(tool_result.content[0])
+            else:
+                result = str(tool_result)
+            
+            # Simulate tick and get reward
+            env._simulate_tick()
+            reward = env._calculate_reward()
+            
+            # Check done
+            done = env._state.step_count >= env._max_steps
+            player = env._agents.get(env._current_agent_id)
+            if player and not player.is_alive:
+                done = True
+            
+            return ToolCallResponse(
+                result=result,
+                reward=reward,
+                done=done,
+                metadata={
+                    "step": env._state.step_count,
+                    "tick": env._tick,
+                },
+            )
+        except Exception as e:
+            return ToolCallResponse(
+                result=f"Error: {str(e)}",
+                reward=0.0,
+                done=False,
+                metadata={"error": str(e)},
+            )
+    
+    @app.websocket("/ws")
+    async def websocket_endpoint(websocket: WebSocket):
+        """WebSocket endpoint for real-time interaction."""
+        await websocket.accept()
+        
+        env = TeeEnvironment()
+        env.reset()
+        
+        try:
+            while True:
+                data = await websocket.receive_text()
+                message = json.loads(data)
+                
+                action_type = message.get("type", "call_tool")
+                
+                if action_type == "reset":
+                    obs = env.reset(
+                        seed=message.get("seed"),
+                        episode_id=message.get("episode_id"),
+                    )
+                    await websocket.send_json({
+                        "type": "reset",
+                        "status": "ready",
+                        "episode_id": obs.metadata.get("episode_id"),
+                        "message": obs.metadata.get("message"),
+                    })
+                
+                elif action_type == "list_tools":
+                    await websocket.send_json({
+                        "type": "tools",
+                        "tools": [
+                            {"name": "move", "description": "Move left/right/none"},
+                            {"name": "jump", "description": "Jump"},
+                            {"name": "aim", "description": "Aim at x,y"},
+                            {"name": "shoot", "description": "Fire weapon"},
+                            {"name": "hook", "description": "Use hook"},
+                            {"name": "get_status", "description": "Get game state"},
+                        ],
+                    })
+                
+                elif action_type == "call_tool":
+                    tool_name = message.get("tool_name")
+                    arguments = message.get("arguments", {})
+                    
+                    # Call tool using FastMCP's async call_tool method
+                    mcp = env._mcp
+                    try:
+                        tool_result = await mcp.call_tool(tool_name, arguments)
+                        if tool_result and tool_result.content:
+                            result = tool_result.content[0].text if hasattr(tool_result.content[0], 'text') else str(tool_result.content[0])
+                        else:
+                            result = str(tool_result)
+                    except Exception as e:
+                        result = f"Error: {str(e)}"
+                    
+                    # Simulate and get reward
+                    env._simulate_tick()
+                    reward = env._calculate_reward()
+                    done = env._state.step_count >= env._max_steps
+                    
+                    await websocket.send_json({
+                        "type": "tool_result",
+                        "tool_name": tool_name,
+                        "result": result,
+                        "reward": reward,
+                        "done": done,
+                        "step": env._state.step_count,
+                        "tick": env._tick,
+                    })
+        
+        except WebSocketDisconnect:
+            pass
+
+
+def main():
+    """
+    Entry point for direct execution.
+    
+    Usage:
+        python -m teeunit_env.server.app
+        uvicorn teeunit_env.server.app:app --host 0.0.0.0 --port 8000
+    """
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

teeunit_env/server/tee_environment.py

@@ -0,0 +1,682 @@
+# Copyright (c) 2024 TeeUnit Project
+# SPDX-License-Identifier: MIT
+
+"""
+TeeUnit Environment Implementation.
+
+A MCP environment that wraps the Teeworlds game for LLM-based RL training.
+All interactions happen through MCP tools that translate to game actions.
+
+MCP Tools:
+- `move(direction)`: Move the tee left, right, or none
+- `jump()`: Make the tee jump
+- `aim(x, y)`: Aim at target coordinates
+- `shoot(weapon)`: Fire the specified weapon
+- `hook()`: Use the grappling hook
+- `get_status()`: Get current game state as text
+
+Example:
+    >>> from openenv.core.env_server.mcp_types import ListToolsAction, CallToolAction
+    >>> env = TeeEnvironment()
+    >>> env.reset()
+    >>>
+    >>> # List available tools
+    >>> obs = env.step(ListToolsAction())
+    >>> print([t.name for t in obs.tools])  # ["move", "jump", "aim", "shoot", "hook", "get_status"]
+    >>>
+    >>> # Get game state
+    >>> obs = env.step(CallToolAction(tool_name="get_status", arguments={}))
+    >>> print(obs.result)
+"""
+
+from typing import Any, Optional, Dict, List
+from uuid import uuid4
+import random
+import math
+
+# Support both in-repo and standalone imports
+try:
+    from openenv.core.env_server.mcp_environment import MCPEnvironment
+    from openenv.core.env_server.types import Action, Observation, State
+except ImportError:
+    # Fallback for development/testing
+    from dataclasses import dataclass
+    
+    @dataclass
+    class State:
+        episode_id: str = ""
+        step_count: int = 0
+    
+    @dataclass
+    class Observation:
+        done: bool = False
+        reward: float = 0.0
+        metadata: dict = None
+        
+        def __post_init__(self):
+            if self.metadata is None:
+                self.metadata = {}
+    
+    class Action:
+        pass
+    
+    class MCPEnvironment:
+        def __init__(self, mcp):
+            self._mcp = mcp
+        
+        def step(self, action, **kwargs):
+            return Observation()
+
+from fastmcp import FastMCP
+
+
+# Weapon definitions
+WEAPONS = {
+    0: {"name": "hammer", "ammo": -1, "damage": 3},
+    1: {"name": "pistol", "ammo": 10, "damage": 1},
+    2: {"name": "shotgun", "ammo": 10, "damage": 3},
+    3: {"name": "grenade", "ammo": 10, "damage": 6},
+    4: {"name": "laser", "ammo": 10, "damage": 5},
+    5: {"name": "ninja", "ammo": -1, "damage": 9},
+}
+
+
+class GameAgent:
+    """Represents a player/bot in the game."""
+    
+    def __init__(self, agent_id: int):
+        self.agent_id = agent_id
+        self.x = 400.0 + random.uniform(-200, 200)
+        self.y = 300.0 + random.uniform(-100, 100)
+        self.vel_x = 0.0
+        self.vel_y = 0.0
+        self.health = 10
+        self.armor = 0
+        self.weapon = 1  # pistol
+        self.ammo = {w: WEAPONS[w]["ammo"] for w in WEAPONS}
+        self.direction = 1  # 1 = right, -1 = left
+        self.is_alive = True
+        self.score = 0
+        self.aim_x = self.x + 100
+        self.aim_y = self.y
+        self.is_hooking = False
+        self.is_grounded = True
+        
+    def respawn(self):
+        """Respawn at random location."""
+        self.x = 400.0 + random.uniform(-200, 200)
+        self.y = 300.0 + random.uniform(-100, 100)
+        self.vel_x = 0.0
+        self.vel_y = 0.0
+        self.health = 10
+        self.armor = 0
+        self.weapon = 1
+        self.ammo = {w: WEAPONS[w]["ammo"] for w in WEAPONS}
+        self.is_alive = True
+        self.is_hooking = False
+
+
+class TeeEnvironment(MCPEnvironment):
+    """
+    OpenEnv-compatible Teeworlds environment with MCP tool interface.
+    
+    This environment provides a text-based interface for LLM agents to play
+    Teeworlds. The LLM receives game state as natural language descriptions
+    and issues commands through MCP tools.
+    
+    For hackathon demo, this uses a simplified game simulation. For production,
+    it can be connected to the real Teeworlds server via bot_manager.
+    
+    Example:
+        >>> with TeeEnv(base_url="http://localhost:8000") as env:
+        ...     env.reset()
+        ...     status = env.call_tool("get_status")
+        ...     env.call_tool("move", direction="right")
+        ...     env.call_tool("shoot", weapon=2)
+    """
+    
+    def __init__(
+        self,
+        num_agents: int = 4,
+        max_steps: int = 1000,
+        use_real_server: bool = False,
+        server_host: str = "127.0.0.1",
+        server_port: int = 8303,
+    ):
+        """
+        Initialize the TeeUnit environment.
+        
+        Args:
+            num_agents: Number of agents in the arena
+            max_steps: Maximum steps per episode
+            use_real_server: If True, connect to real Teeworlds server
+            server_host: Teeworlds server host
+            server_port: Teeworlds server port
+        """
+        # Create MCP server and define tools inline
+        mcp = FastMCP("teeunit_env")
+        
+        # Store config
+        self._num_agents = num_agents
+        self._max_steps = max_steps
+        self._use_real_server = use_real_server
+        self._server_host = server_host
+        self._server_port = server_port
+        
+        # Game state
+        self._agents: Dict[int, GameAgent] = {}
+        self._tick = 0
+        self._kill_events: List[dict] = []
+        self._current_agent_id = 0  # LLM controls agent 0
+        
+        # Episode state
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        
+        # Real server connection (optional)
+        self._bot_manager = None
+        
+        # Define MCP tools
+        @mcp.tool
+        def move(direction: str) -> str:
+            """
+            Move the tee horizontally.
+            
+            Args:
+                direction: "left", "right", or "none"
+            
+            Returns:
+                Result message describing the action taken
+            """
+            agent = self._agents.get(self._current_agent_id)
+            if not agent or not agent.is_alive:
+                return "Cannot move: agent is dead"
+            
+            if direction == "left":
+                agent.direction = -1
+                agent.vel_x = max(agent.vel_x - 5, -15)
+                return f"Moving left. Velocity: ({agent.vel_x:.1f}, {agent.vel_y:.1f})"
+            elif direction == "right":
+                agent.direction = 1
+                agent.vel_x = min(agent.vel_x + 5, 15)
+                return f"Moving right. Velocity: ({agent.vel_x:.1f}, {agent.vel_y:.1f})"
+            else:
+                agent.vel_x *= 0.8  # friction
+                return f"Stopped. Velocity: ({agent.vel_x:.1f}, {agent.vel_y:.1f})"
+        
+        @mcp.tool
+        def jump() -> str:
+            """
+            Make the tee jump. Can double-jump in the air.
+            
+            Returns:
+                Result message describing the jump
+            """
+            agent = self._agents.get(self._current_agent_id)
+            if not agent or not agent.is_alive:
+                return "Cannot jump: agent is dead"
+            
+            if agent.is_grounded:
+                agent.vel_y = -12
+                agent.is_grounded = False
+                return f"Jumped! Velocity: ({agent.vel_x:.1f}, {agent.vel_y:.1f})"
+            else:
+                # Air jump (weaker)
+                agent.vel_y = -8
+                return f"Air jumped! Velocity: ({agent.vel_x:.1f}, {agent.vel_y:.1f})"
+        
+        @mcp.tool
+        def aim(x: int, y: int) -> str:
+            """
+            Aim at target coordinates.
+            
+            Args:
+                x: Target X coordinate
+                y: Target Y coordinate
+            
+            Returns:
+                Result message confirming aim direction
+            """
+            agent = self._agents.get(self._current_agent_id)
+            if not agent or not agent.is_alive:
+                return "Cannot aim: agent is dead"
+            
+            agent.aim_x = x
+            agent.aim_y = y
+            
+            # Calculate angle for display
+            dx = x - agent.x
+            dy = y - agent.y
+            angle = math.atan2(dy, dx) * 180 / math.pi
+            distance = math.sqrt(dx*dx + dy*dy)
+            
+            return f"Aiming at ({x}, {y}). Angle: {angle:.1f} deg, Distance: {distance:.1f} units"
+        
+        @mcp.tool
+        def shoot(weapon: int = -1) -> str:
+            """
+            Fire the current or specified weapon.
+            
+            Args:
+                weapon: Weapon ID (0=hammer, 1=pistol, 2=shotgun, 3=grenade, 4=laser, 5=ninja).
+                       Use -1 for current weapon.
+            
+            Returns:
+                Result message describing the shot and any hits
+            """
+            agent = self._agents.get(self._current_agent_id)
+            if not agent or not agent.is_alive:
+                return "Cannot shoot: agent is dead"
+            
+            # Switch weapon if specified
+            if weapon >= 0 and weapon <= 5:
+                agent.weapon = weapon
+            
+            wpn = WEAPONS[agent.weapon]
+            wpn_name = wpn["name"]
+            
+            # Check ammo
+            if wpn["ammo"] > 0 and agent.ammo[agent.weapon] <= 0:
+                return f"Out of ammo for {wpn_name}!"
+            
+            # Use ammo
+            if wpn["ammo"] > 0:
+                agent.ammo[agent.weapon] -= 1
+            
+            # Check for hits on other agents
+            hits = []
+            for other_id, other in self._agents.items():
+                if other_id == self._current_agent_id or not other.is_alive:
+                    continue
+                
+                # Simple hit detection based on aim
+                dx = other.x - agent.x
+                dy = other.y - agent.y
+                distance = math.sqrt(dx*dx + dy*dy)
+                
+                aim_dx = agent.aim_x - agent.x
+                aim_dy = agent.aim_y - agent.y
+                aim_dist = math.sqrt(aim_dx*aim_dx + aim_dy*aim_dy)
+                
+                if aim_dist > 0:
+                    # Check if enemy is roughly in line of fire
+                    dot = (dx * aim_dx + dy * aim_dy) / (aim_dist * max(distance, 1))
+                    
+                    # Hit probability based on weapon and distance
+                    hit_range = 400 if agent.weapon != 0 else 50  # hammer short range
+                    if distance < hit_range and dot > 0.8:
+                        # Hit!
+                        damage = wpn["damage"]
+                        other.health -= damage
+                        other.armor = max(0, other.armor - damage // 2)
+                        
+                        if other.health <= 0:
+                            other.is_alive = False
+                            agent.score += 1
+                            self._kill_events.append({
+                                "killer_id": self._current_agent_id,
+                                "victim_id": other_id,
+                                "weapon": agent.weapon,
+                                "tick": self._tick,
+                            })
+                            hits.append(f"KILLED Player {other_id} with {wpn_name}!")
+                        else:
+                            hits.append(f"Hit Player {other_id} for {damage} damage ({other.health}HP remaining)")
+            
+            ammo_str = f"({agent.ammo[agent.weapon]} ammo)" if wpn["ammo"] > 0 else ""
+            if hits:
+                return f"Fired {wpn_name} {ammo_str}. " + " ".join(hits)
+            else:
+                return f"Fired {wpn_name} {ammo_str}. No hits."
+        
+        @mcp.tool
+        def hook() -> str:
+            """
+            Use the grappling hook in the aim direction.
+            The hook can grab walls or enemies to pull yourself toward them.
+            
+            Returns:
+                Result message describing hook action
+            """
+            agent = self._agents.get(self._current_agent_id)
+            if not agent or not agent.is_alive:
+                return "Cannot hook: agent is dead"
+            
+            agent.is_hooking = not agent.is_hooking
+            
+            if agent.is_hooking:
+                # Pull toward aim point
+                dx = agent.aim_x - agent.x
+                dy = agent.aim_y - agent.y
+                dist = math.sqrt(dx*dx + dy*dy)
+                if dist > 0:
+                    agent.vel_x += (dx / dist) * 3
+                    agent.vel_y += (dy / dist) * 3
+                return f"Hook deployed! Pulling toward ({agent.aim_x}, {agent.aim_y})"
+            else:
+                return "Hook released."
+        
+        @mcp.tool
+        def get_status() -> str:
+            """
+            Get the current game state as a text description.
+            
+            Returns:
+                Detailed text description of current game state including:
+                - Your position, health, weapon, ammo
+                - Visible enemies with positions and health
+                - Recent events (kills, deaths)
+            """
+            agent = self._agents.get(self._current_agent_id)
+            
+            lines = []
+            lines.append(f"=== Teeworlds Game State (Tick {self._tick}) ===")
+            lines.append("")
+            
+            if not agent or not agent.is_alive:
+                lines.append("STATUS: DEAD - Waiting for respawn...")
+                lines.append("")
+            else:
+                lines.append(f"Position: ({agent.x:.0f}, {agent.y:.0f}) | Velocity: ({agent.vel_x:.1f}, {agent.vel_y:.1f})")
+                lines.append(f"Health: {agent.health}/10 | Armor: {agent.armor}/10")
+                
+                wpn = WEAPONS[agent.weapon]
+                ammo_str = str(agent.ammo[agent.weapon]) if wpn["ammo"] > 0 else "infinite"
+                lines.append(f"Weapon: {wpn['name']} ({ammo_str} ammo)")
+                lines.append(f"Score: {agent.score} kills")
+                lines.append(f"Aim: ({agent.aim_x:.0f}, {agent.aim_y:.0f})")
+                lines.append("")
+            
+            # Other players
+            enemies = []
+            for other_id, other in self._agents.items():
+                if other_id == self._current_agent_id:
+                    continue
+                    
+                if other.is_alive:
+                    dx = other.x - agent.x if agent else other.x
+                    dy = other.y - agent.y if agent else other.y
+                    dist = math.sqrt(dx*dx + dy*dy)
+                    wpn_name = WEAPONS[other.weapon]["name"]
+                    enemies.append(
+                        f"  - Player {other_id}: pos({other.x:.0f}, {other.y:.0f}), "
+                        f"{other.health}HP, {wpn_name}, {dist:.0f} units away"
+                    )
+                else:
+                    enemies.append(f"  - Player {other_id}: DEAD")
+            
+            if enemies:
+                lines.append("OTHER PLAYERS:")
+                lines.extend(enemies)
+            else:
+                lines.append("OTHER PLAYERS: None")
+            lines.append("")
+            
+            # Recent kills
+            recent = self._kill_events[-5:] if self._kill_events else []
+            if recent:
+                lines.append("RECENT EVENTS:")
+                for event in recent:
+                    killer = event["killer_id"]
+                    victim = event["victim_id"]
+                    wpn_name = WEAPONS[event["weapon"]]["name"]
+                    if killer == self._current_agent_id:
+                        lines.append(f"  - You killed Player {victim} with {wpn_name}")
+                    elif victim == self._current_agent_id:
+                        lines.append(f"  - Player {killer} killed you with {wpn_name}")
+                    else:
+                        lines.append(f"  - Player {killer} killed Player {victim} with {wpn_name}")
+                lines.append("")
+            
+            lines.append("AVAILABLE ACTIONS: move, jump, aim, shoot, hook, get_status")
+            
+            return "\n".join(lines)
+        
+        # Store MCP reference and pass to base class
+        self._mcp = mcp
+        super().__init__(mcp)
+    
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Reset the environment for a new episode.
+        
+        Args:
+            seed: Optional random seed
+            episode_id: Optional episode ID
+            **kwargs: Additional reset options
+        
+        Returns:
+            Observation indicating the environment is ready
+        """
+        if seed is not None:
+            random.seed(seed)
+        
+        # Reset episode state
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+        self._tick = 0
+        self._kill_events = []
+        
+        # Initialize agents
+        self._agents = {}
+        for i in range(self._num_agents):
+            self._agents[i] = GameAgent(i)
+        
+        # Get initial status
+        status = self._get_status_text()
+        
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "status": "ready",
+                "message": status,
+                "episode_id": self._state.episode_id,
+            },
+        )
+    
+    def _get_status_text(self) -> str:
+        """Generate current game status text."""
+        agent = self._agents.get(self._current_agent_id)
+        
+        lines = []
+        lines.append(f"=== Teeworlds Game State (Tick {self._tick}) ===")
+        
+        if agent and agent.is_alive:
+            lines.append(f"Position: ({agent.x:.0f}, {agent.y:.0f})")
+            lines.append(f"Health: {agent.health}/10 | Armor: {agent.armor}/10")
+            wpn = WEAPONS[agent.weapon]
+            lines.append(f"Weapon: {wpn['name']}")
+            lines.append(f"Score: {agent.score} kills")
+        else:
+            lines.append("STATUS: DEAD")
+        
+        return "\n".join(lines)
+    
+    def _simulate_tick(self):
+        """Simulate one game tick (physics, AI, etc.)."""
+        self._tick += 1
+        
+        for agent in self._agents.values():
+            if not agent.is_alive:
+                continue
+            
+            # Apply gravity
+            agent.vel_y += 0.5
+            
+            # Apply velocity
+            agent.x += agent.vel_x
+            agent.y += agent.vel_y
+            
+            # Ground collision (simple)
+            if agent.y > 500:
+                agent.y = 500
+                agent.vel_y = 0
+                agent.is_grounded = True
+            
+            # Wall collision
+            agent.x = max(50, min(750, agent.x))
+            
+            # Friction
+            agent.vel_x *= 0.95
+            
+            # Simple AI for non-player agents
+            if agent.agent_id != self._current_agent_id:
+                self._simple_ai(agent)
+    
+    def _simple_ai(self, agent: GameAgent):
+        """Simple AI behavior for non-player agents."""
+        # Random movement
+        if random.random() < 0.1:
+            agent.vel_x += random.uniform(-3, 3)
+        
+        # Random jump
+        if agent.is_grounded and random.random() < 0.05:
+            agent.vel_y = -10
+            agent.is_grounded = False
+        
+        # Aim at player
+        player = self._agents.get(self._current_agent_id)
+        if player and player.is_alive:
+            agent.aim_x = player.x
+            agent.aim_y = player.y
+            
+            # Occasionally shoot
+            if random.random() < 0.02:
+                dx = player.x - agent.x
+                dy = player.y - agent.y
+                dist = math.sqrt(dx*dx + dy*dy)
+                
+                if dist < 300:
+                    # Attack player
+                    wpn = WEAPONS[agent.weapon]
+                    if wpn["ammo"] < 0 or agent.ammo[agent.weapon] > 0:
+                        if wpn["ammo"] > 0:
+                            agent.ammo[agent.weapon] -= 1
+                        
+                        # Check hit (simplified)
+                        if dist < 200 and random.random() < 0.3:
+                            damage = wpn["damage"]
+                            player.health -= damage
+                            
+                            if player.health <= 0:
+                                player.is_alive = False
+                                agent.score += 1
+                                self._kill_events.append({
+                                    "killer_id": agent.agent_id,
+                                    "victim_id": self._current_agent_id,
+                                    "weapon": agent.weapon,
+                                    "tick": self._tick,
+                                })
+    
+    def _step_impl(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Handle non-MCP actions.
+        
+        Args:
+            action: The action to execute
+            timeout_s: Optional timeout
+            **kwargs: Additional arguments
+        
+        Returns:
+            Observation with error for unknown action types
+        """
+        return Observation(
+            done=False,
+            reward=0.0,
+            metadata={
+                "error": f"Unknown action type: {type(action).__name__}. "
+                "Use ListToolsAction or CallToolAction for MCP interactions."
+            },
+        )
+    
+    def step(
+        self,
+        action: Action,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> Observation:
+        """
+        Execute a step in the environment.
+        
+        Args:
+            action: The MCP action to execute
+            timeout_s: Optional timeout
+            **kwargs: Additional arguments
+        
+        Returns:
+            Observation from the action execution
+        """
+        # Increment step count
+        self._state.step_count += 1
+        
+        # Simulate game tick
+        self._simulate_tick()
+        
+        # Calculate reward
+        reward = self._calculate_reward()
+        
+        # Check done
+        done = self._state.step_count >= self._max_steps
+        
+        # Check if all enemies dead (win condition)
+        enemies_alive = sum(1 for a in self._agents.values() 
+                          if a.agent_id != self._current_agent_id and a.is_alive)
+        if enemies_alive == 0:
+            done = True
+            reward += 10.0  # Win bonus
+        
+        # Check if player dead
+        player = self._agents.get(self._current_agent_id)
+        if player and not player.is_alive:
+            done = True
+            reward -= 5.0  # Death penalty
+        
+        # Let the base class handle MCP actions
+        obs = super().step(action, timeout_s=timeout_s, **kwargs)
+        
+        # Update observation with reward and done
+        obs.reward = reward
+        obs.done = done
+        obs.metadata["step"] = self._state.step_count
+        obs.metadata["tick"] = self._tick
+        
+        return obs
+    
+    def _calculate_reward(self) -> float:
+        """Calculate reward for current step."""
+        reward = 0.0
+        
+        player = self._agents.get(self._current_agent_id)
+        if not player:
+            return reward
+        
+        # Survival bonus
+        if player.is_alive:
+            reward += 0.01
+        
+        # Kill bonus (from recent events)
+        for event in self._kill_events:
+            if event["tick"] == self._tick:
+                if event["killer_id"] == self._current_agent_id:
+                    reward += 1.0
+                elif event["victim_id"] == self._current_agent_id:
+                    reward -= 0.5
+        
+        return reward
+    
+    @property
+    def state(self) -> State:
+        """Get the current environment state."""
+        return self._state