Metadata-Version: 2.4
Name: codex-unity-bridge
Version: 0.3.0
Summary: Control Unity Editor from Codex
License: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"

---
name: unity
description: Execute Unity Editor commands through Codex Unity Bridge. Requires the com.prodfact.codex-bridge Unity package in the current project and a running Unity Editor.
---

# Unity Bridge Skill

Use this skill when Codex needs to interact with a live Unity Editor from the project workspace.

## Overview

Codex Unity Bridge uses a deterministic Python CLI instead of ad-hoc in-context file handling. The CLI owns:

- UUID generation
- atomic command writes
- polling and timeout handling
- response parsing
- cleanup of stale files
- skill installation

That keeps Unity interactions stable across sessions and avoids re-implementing the file protocol each time.

## Requirements

1. The Unity project has `com.prodfact.codex-bridge` installed
2. Unity Editor is open with that project loaded
3. The project root contains `.codex-unity-bridge/` after the package initializes
4. The CLI is installed: `codex-unity-bridge`

## Runtime Files

- Command file: `.codex-unity-bridge/command.json`
- Response files: `.codex-unity-bridge/response-{id}.json`

This is intentionally separate from the original Claude bridge runtime directory so both bridges can coexist in the same Unity project.

## Basic Usage

Run the CLI directly:

```bash
codex-unity-bridge [command] [options]
```

Common commands:

```bash
codex-unity-bridge run-tests --mode EditMode
codex-unity-bridge compile
codex-unity-bridge refresh
codex-unity-bridge get-status
codex-unity-bridge get-console-logs --limit 20 --filter Error
codex-unity-bridge play
codex-unity-bridge pause
codex-unity-bridge step
codex-unity-bridge health-check
```

## Natural-Language Examples

Typical prompts that map well to this skill:

- `Run the Unity tests in EditMode`
- `Check whether Unity is compiling`
- `Show the last 10 Unity errors`
- `Refresh the Unity asset database`
- `Pause play mode and step one frame`

## Guidance

- Prefer the CLI over manual edits to bridge files
- Use `--timeout` for long-running test or compile operations
- Use `get-status` or `health-check` before assuming Unity is unavailable
- Use `get-console-logs --filter Error` before asking for a broad log dump

## Troubleshooting

If Codex cannot communicate with Unity:

1. Verify the Unity Editor is open with the intended project
2. Check that `.codex-unity-bridge/` exists at the project root
3. Run `codex-unity-bridge health-check`
4. Inspect the Unity Console for `[CodexBridge]` messages

If the CLI is not on `PATH`, run:

```bash
python -m codex_unity_bridge.cli install-skill
```

## References

- [Command Reference](references/COMMANDS.md)
- [Extending the Bridge](references/EXTENDING.md)
