mcpforunityserver 8.7.0__py3-none-any.whl → 9.1.0__py3-none-any.whl

cli/commands/vfx.py

@@ -0,0 +1,439 @@
+"""VFX CLI commands for managing Unity visual effects."""
+
+import sys
+import json
+import click
+from typing import Optional, Tuple, Any
+
+from cli.utils.config import get_config
+from cli.utils.output import format_output, print_error, print_success
+from cli.utils.connection import run_command, UnityConnectionError
+
+
+@click.group()
+def vfx():
+    """VFX operations - particle systems, line renderers, trails."""
+    pass
+
+
+# =============================================================================
+# Particle System Commands
+# =============================================================================
+
+@vfx.group()
+def particle():
+    """Particle system operations."""
+    pass
+
+
+@particle.command("info")
+@click.argument("target")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def particle_info(target: str, search_method: Optional[str]):
+    """Get particle system info.
+
+    \\b
+    Examples:
+        unity-mcp vfx particle info "Fire"
+        unity-mcp vfx particle info "-12345" --search-method by_id
+    """
+    config = get_config()
+    params: dict[str, Any] = {"action": "particle_get_info", "target": target}
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@particle.command("play")
+@click.argument("target")
+@click.option("--with-children", is_flag=True, help="Also play child particle systems.")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def particle_play(target: str, with_children: bool, search_method: Optional[str]):
+    """Play a particle system.
+
+    \\b
+    Examples:
+        unity-mcp vfx particle play "Fire"
+        unity-mcp vfx particle play "Effects" --with-children
+    """
+    config = get_config()
+    params: dict[str, Any] = {"action": "particle_play", "target": target}
+    if with_children:
+        params["withChildren"] = True
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+        if result.get("success"):
+            print_success(f"Playing particle system: {target}")
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@particle.command("stop")
+@click.argument("target")
+@click.option("--with-children", is_flag=True, help="Also stop child particle systems.")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def particle_stop(target: str, with_children: bool, search_method: Optional[str]):
+    """Stop a particle system."""
+    config = get_config()
+    params: dict[str, Any] = {"action": "particle_stop", "target": target}
+    if with_children:
+        params["withChildren"] = True
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+        if result.get("success"):
+            print_success(f"Stopped particle system: {target}")
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@particle.command("pause")
+@click.argument("target")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def particle_pause(target: str, search_method: Optional[str]):
+    """Pause a particle system."""
+    config = get_config()
+    params: dict[str, Any] = {"action": "particle_pause", "target": target}
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@particle.command("restart")
+@click.argument("target")
+@click.option("--with-children", is_flag=True)
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def particle_restart(target: str, with_children: bool, search_method: Optional[str]):
+    """Restart a particle system."""
+    config = get_config()
+    params: dict[str, Any] = {"action": "particle_restart", "target": target}
+    if with_children:
+        params["withChildren"] = True
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@particle.command("clear")
+@click.argument("target")
+@click.option("--with-children", is_flag=True)
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def particle_clear(target: str, with_children: bool, search_method: Optional[str]):
+    """Clear all particles from a particle system."""
+    config = get_config()
+    params: dict[str, Any] = {"action": "particle_clear", "target": target}
+    if with_children:
+        params["withChildren"] = True
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+# =============================================================================
+# Line Renderer Commands
+# =============================================================================
+
+@vfx.group()
+def line():
+    """Line renderer operations."""
+    pass
+
+
+@line.command("info")
+@click.argument("target")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def line_info(target: str, search_method: Optional[str]):
+    """Get line renderer info.
+
+    \\b
+    Examples:
+        unity-mcp vfx line info "LaserBeam"
+    """
+    config = get_config()
+    params: dict[str, Any] = {"action": "line_get_info", "target": target}
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@line.command("set-positions")
+@click.argument("target")
+@click.option("--positions", "-p", required=True, help='Positions as JSON array: [[0,0,0], [1,1,1], [2,0,0]]')
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def line_set_positions(target: str, positions: str, search_method: Optional[str]):
+    """Set all positions on a line renderer.
+
+    \\b
+    Examples:
+        unity-mcp vfx line set-positions "Line" --positions "[[0,0,0], [5,2,0], [10,0,0]]"
+    """
+    config = get_config()
+
+    try:
+        positions_list = json.loads(positions)
+    except json.JSONDecodeError as e:
+        print_error(f"Invalid JSON for positions: {e}")
+        sys.exit(1)
+
+    params: dict[str, Any] = {
+        "action": "line_set_positions",
+        "target": target,
+        "positions": positions_list,
+    }
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@line.command("create-line")
+@click.argument("target")
+@click.option("--start", nargs=3, type=float, required=True, help="Start point X Y Z")
+@click.option("--end", nargs=3, type=float, required=True, help="End point X Y Z")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def line_create_line(target: str, start: Tuple[float, float, float], end: Tuple[float, float, float], search_method: Optional[str]):
+    """Create a simple line between two points.
+
+    \\b
+    Examples:
+        unity-mcp vfx line create-line "MyLine" --start 0 0 0 --end 10 5 0
+    """
+    config = get_config()
+    params: dict[str, Any] = {
+        "action": "line_create_line",
+        "target": target,
+        "start": list(start),
+        "end": list(end),
+    }
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@line.command("create-circle")
+@click.argument("target")
+@click.option("--center", nargs=3, type=float, default=(0, 0, 0), help="Center point X Y Z")
+@click.option("--radius", type=float, required=True, help="Circle radius")
+@click.option("--segments", type=int, default=32, help="Number of segments")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def line_create_circle(target: str, center: Tuple[float, float, float], radius: float, segments: int, search_method: Optional[str]):
+    """Create a circle shape.
+
+    \\b
+    Examples:
+        unity-mcp vfx line create-circle "Circle" --radius 5 --segments 64
+        unity-mcp vfx line create-circle "Ring" --center 0 2 0 --radius 3
+    """
+    config = get_config()
+    params: dict[str, Any] = {
+        "action": "line_create_circle",
+        "target": target,
+        "center": list(center),
+        "radius": radius,
+        "segments": segments,
+    }
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@line.command("clear")
+@click.argument("target")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def line_clear(target: str, search_method: Optional[str]):
+    """Clear all positions from a line renderer."""
+    config = get_config()
+    params: dict[str, Any] = {"action": "line_clear", "target": target}
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+# =============================================================================
+# Trail Renderer Commands
+# =============================================================================
+
+@vfx.group()
+def trail():
+    """Trail renderer operations."""
+    pass
+
+
+@trail.command("info")
+@click.argument("target")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def trail_info(target: str, search_method: Optional[str]):
+    """Get trail renderer info."""
+    config = get_config()
+    params: dict[str, Any] = {"action": "trail_get_info", "target": target}
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@trail.command("set-time")
+@click.argument("target")
+@click.argument("duration", type=float)
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def trail_set_time(target: str, duration: float, search_method: Optional[str]):
+    """Set trail duration.
+
+    \\b
+    Examples:
+        unity-mcp vfx trail set-time "PlayerTrail" 2.0
+    """
+    config = get_config()
+    params: dict[str, Any] = {
+        "action": "trail_set_time",
+        "target": target,
+        "time": duration,
+    }
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@trail.command("clear")
+@click.argument("target")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def trail_clear(target: str, search_method: Optional[str]):
+    """Clear a trail renderer."""
+    config = get_config()
+    params: dict[str, Any] = {"action": "trail_clear", "target": target}
+    if search_method:
+        params["searchMethod"] = search_method
+
+    try:
+        result = run_command("manage_vfx", params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+# =============================================================================
+# Raw Command (escape hatch for all VFX actions)
+# =============================================================================
+
+@vfx.command("raw")
+@click.argument("action")
+@click.argument("target", required=False)
+@click.option("--params", "-p", default="{}", help="Additional parameters as JSON.")
+@click.option("--search-method", type=click.Choice(["by_name", "by_path", "by_id", "by_tag"]), default=None)
+def vfx_raw(action: str, target: Optional[str], params: str, search_method: Optional[str]):
+    """Execute any VFX action directly.
+
+    For advanced users who need access to all 60+ VFX actions.
+
+    \\b
+    Actions include:
+        particle_*: particle_set_main, particle_set_emission, particle_set_shape, ...
+        vfx_*: vfx_set_float, vfx_send_event, vfx_play, ...
+        line_*: line_create_arc, line_create_bezier, ...
+        trail_*: trail_set_width, trail_set_color, ...
+
+    \\b
+    Examples:
+        unity-mcp vfx raw particle_set_main "Fire" --params '{"duration": 5, "looping": true}'
+        unity-mcp vfx raw line_create_arc "Arc" --params '{"radius": 3, "startAngle": 0, "endAngle": 180}'
+        unity-mcp vfx raw vfx_send_event "Explosion" --params '{"eventName": "OnSpawn"}'
+    """
+    config = get_config()
+
+    try:
+        extra_params = json.loads(params)
+    except json.JSONDecodeError as e:
+        print_error(f"Invalid JSON for params: {e}")
+        sys.exit(1)
+    if not isinstance(extra_params, dict):
+        print_error("Invalid JSON for params: expected an object")
+        sys.exit(1)
+
+    request_params: dict[str, Any] = {"action": action}
+    if target:
+        request_params["target"] = target
+    if search_method:
+        request_params["searchMethod"] = search_method
+
+    # Merge extra params
+    request_params.update(extra_params)
+    try:
+        result = run_command("manage_vfx", request_params, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)

cli/main.py

@@ -0,0 +1,248 @@
+"""Unity MCP Command Line Interface - Main Entry Point."""
+
+import sys
+from importlib import import_module
+
+import click
+from typing import Optional
+
+from cli import __version__
+from cli.utils.config import CLIConfig, set_config, get_config
+from cli.utils.output import format_output, print_error, print_success, print_info
+from cli.utils.connection import (
+    run_command,
+    run_check_connection,
+    run_list_instances,
+    UnityConnectionError,
+    warn_if_remote_host,
+)
+
+
+# Context object to pass configuration between commands
+class Context:
+    def __init__(self):
+        self.config: Optional[CLIConfig] = None
+        self.verbose: bool = False
+
+
+pass_context = click.make_pass_decorator(Context, ensure=True)
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="unity-mcp")
+@click.option(
+    "--host", "-h",
+    default="127.0.0.1",
+    envvar="UNITY_MCP_HOST",
+    help="MCP server host address."
+)
+@click.option(
+    "--port", "-p",
+    default=8080,
+    type=int,
+    envvar="UNITY_MCP_HTTP_PORT",
+    help="MCP server port."
+)
+@click.option(
+    "--timeout", "-t",
+    default=30,
+    type=int,
+    envvar="UNITY_MCP_TIMEOUT",
+    help="Command timeout in seconds."
+)
+@click.option(
+    "--format", "-f",
+    type=click.Choice(["text", "json", "table"]),
+    default="text",
+    envvar="UNITY_MCP_FORMAT",
+    help="Output format."
+)
+@click.option(
+    "--instance", "-i",
+    default=None,
+    envvar="UNITY_MCP_INSTANCE",
+    help="Target Unity instance (hash or Name@hash)."
+)
+@click.option(
+    "--verbose", "-v",
+    is_flag=True,
+    help="Enable verbose output."
+)
+@pass_context
+def cli(ctx: Context, host: str, port: int, timeout: int, format: str, instance: Optional[str], verbose: bool):
+    """Unity MCP Command Line Interface.
+
+    Control Unity Editor directly from the command line using the Model Context Protocol.
+
+    \b
+    Examples:
+        unity-mcp status
+        unity-mcp gameobject find "Player"
+        unity-mcp scene hierarchy --format json
+        unity-mcp editor play
+
+    \b
+    Environment Variables:
+        UNITY_MCP_HOST      Server host (default: 127.0.0.1)
+        UNITY_MCP_HTTP_PORT Server port (default: 8080)
+        UNITY_MCP_TIMEOUT   Timeout in seconds (default: 30)
+        UNITY_MCP_FORMAT    Output format (default: text)
+        UNITY_MCP_INSTANCE  Target Unity instance
+    """
+    config = CLIConfig(
+        host=host,
+        port=port,
+        timeout=timeout,
+        format=format,
+        unity_instance=instance,
+    )
+
+    # Security warning for non-localhost connections
+    warn_if_remote_host(config)
+
+    set_config(config)
+    ctx.config = config
+    ctx.verbose = verbose
+
+
+@cli.command("status")
+@pass_context
+def status(ctx: Context):
+    """Check connection status to Unity MCP server."""
+    config = ctx.config or get_config()
+
+    click.echo(f"Checking connection to {config.host}:{config.port}...")
+
+    if run_check_connection(config):
+        print_success(
+            f"Connected to Unity MCP server at {config.host}:{config.port}")
+
+        # Try to get Unity instances
+        try:
+            result = run_list_instances(config)
+            instances = result.get("instances", []) if isinstance(
+                result, dict) else []
+            if instances:
+                click.echo("\nConnected Unity instances:")
+                for inst in instances:
+                    project = inst.get("project", "Unknown")
+                    version = inst.get("unity_version", "Unknown")
+                    hash_id = inst.get("hash", "")[:8]
+                    click.echo(f"  • {project} (Unity {version}) [{hash_id}]")
+            else:
+                print_info("No Unity instances currently connected")
+        except UnityConnectionError as e:
+            print_info(f"Could not retrieve Unity instances: {e}")
+    else:
+        print_error(
+            f"Cannot connect to Unity MCP server at {config.host}:{config.port}")
+        sys.exit(1)
+
+
+@cli.command("instances")
+@pass_context
+def list_instances(ctx: Context):
+    """List available Unity instances."""
+    config = ctx.config or get_config()
+
+    try:
+        instances = run_list_instances(config)
+        click.echo(format_output(instances, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+@cli.command("raw")
+@click.argument("command_type")
+@click.argument("params", required=False, default="{}")
+@pass_context
+def raw_command(ctx: Context, command_type: str, params: str):
+    """Send a raw command to Unity.
+
+    \b
+    Examples:
+        unity-mcp raw manage_scene '{"action": "get_hierarchy"}'
+        unity-mcp raw read_console '{"count": 10}'
+    """
+    import json
+    config = ctx.config or get_config()
+
+    try:
+        params_dict = json.loads(params)
+    except json.JSONDecodeError as e:
+        print_error(f"Invalid JSON params: {e}")
+        sys.exit(1)
+
+    try:
+        result = run_command(command_type, params_dict, config)
+        click.echo(format_output(result, config.format))
+    except UnityConnectionError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+
+# Import and register command groups
+# These will be implemented in subsequent TODOs
+def register_commands():
+    """Register all command groups."""
+    def register_optional_command(module_name: str, command_name: str) -> None:
+        try:
+            module = import_module(module_name)
+        except ModuleNotFoundError as e:
+            if e.name == module_name:
+                return
+            print_error(
+                f"Failed to load command module '{module_name}': {e}"
+            )
+            return
+        except Exception as e:
+            print_error(
+                f"Failed to load command module '{module_name}': {e}"
+            )
+            return
+
+        command = getattr(module, command_name, None)
+        if command is None:
+            print_error(
+                f"Command '{command_name}' not found in '{module_name}'"
+            )
+            return
+
+        cli.add_command(command)
+
+    optional_commands = [
+        ("cli.commands.gameobject", "gameobject"),
+        ("cli.commands.component", "component"),
+        ("cli.commands.scene", "scene"),
+        ("cli.commands.asset", "asset"),
+        ("cli.commands.script", "script"),
+        ("cli.commands.code", "code"),
+        ("cli.commands.editor", "editor"),
+        ("cli.commands.prefab", "prefab"),
+        ("cli.commands.material", "material"),
+        ("cli.commands.lighting", "lighting"),
+        ("cli.commands.animation", "animation"),
+        ("cli.commands.audio", "audio"),
+        ("cli.commands.ui", "ui"),
+        ("cli.commands.instance", "instance"),
+        ("cli.commands.shader", "shader"),
+        ("cli.commands.vfx", "vfx"),
+        ("cli.commands.batch", "batch"),
+    ]
+
+    for module_name, command_name in optional_commands:
+        register_optional_command(module_name, command_name)
+
+
+# Register commands on import
+register_commands()
+
+
+def main():
+    """Main entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()