# MooseRunner (Unity Git Submodule)

This project integrates **[MooseRunner](https://github.com/Valectric/MooseRunner)** as a Unity package using **Git submodules**.  
Unity detects it as an **embedded package** via its `package.json`.

---

## Quick start

Once the package is installed, run:

```
mooserunnerCli setup
```

and hand the printed runbook to your AI agent. It's a one-time, throwaway runbook (not saved) that
walks through prerequisites (clearly marking free vs paid), the testing / architecture guideline
docs, and importing the demo samples.

> When upgrading MooseRunner, delete the prior `Assets/Samples/com.valectric.mooserunner/<old-version>/`
> before re-importing the demo samples, to avoid duplicate-class warnings.

---

## Why use a submodule?

Instead of copying MooseRunner’s source code directly, we use a **Git submodule** because:

- Keeps MooseRunner’s history and version tracking intact  
- Easy to update to the latest changes (or pin to a specific commit)  
- Keeps your repository clean while still embedding MooseRunner as a Unity package  
- Works seamlessly with Unity’s Package Manager as an **embedded package**

---

## Adding MooseRunner

To add MooseRunner as a submodule in your Unity project:

```bash
git submodule add https://github.com/Valectric/MooseRunner.git Packages/MooseRunnerGit
git commit -m "Add MooseRunner as submodule in Packages/MooseRunnerGit"
```

Then manual add MooseRunner as a pakcage in packagemanager from disk by selecting 
the package.json in the subfolder MooseRunner

### Important: Enable Test Assemblies

When using MooseRunner as a package, you must add it to the `testables` array in your project's `Packages/manifest.json`:

```json
{
  "dependencies": {
    ...
  },
  "testables": [
    "com.valectric.mooserunner"
  ]
}
```

This ensures Unity includes MooseRunner's test assemblies, allowing the SelectMethod list to properly display all available tests.

---

## Cloning With Submodules

When cloning this repository fresh, make sure to fetch submodules:

```bash
git clone <your-repo-url>
cd <your-repo>
git submodule update --init --recursive
```

---

## Updating MooseRunner

Update MooseRunner to the latest version:

```bash
cd Packages/MooseRunnerGit
git pull origin main
```

Update all submodules in one go:

```bash
git submodule update --remote --merge
```

---

## Listing Submodules

Check the status of submodules (commit SHA and path):

```bash
git submodule status
```

List configured submodule URLs:

```bash
git config --file .gitmodules --get-regexp url
```

---

## Removing MooseRunner

To completely remove the MooseRunner submodule:

```bash
git submodule deinit -f Packages/MooseRunnerGit
git rm -f Packages/MooseRunnerGit
rm -rf .git/modules/Packages/MooseRunnerGit
git commit -m "Remove MooseRunner submodule"
```

---

With this setup, Unity treats MooseRunner as an **embedded package** while Git keeps it synced as a **submodule**.

---

## Claude Code Integration

MooseRunner includes skills for Claude Code that provide comprehensive documentation on writing and running tests.

### Available Skills

Skills are located in `MooseRunner/skills/`:

| Skill | Use Case |
|-------|----------|
| **play-mode-tester** | Isolated component tests with SetUp/TearDown |
| **e2e-tester** | E2E gameplay flow tests (chained, no setup between) |

### Installing Skills

Skills sync automatically via git hooks on checkout/merge.

#### Step 1: Create Hooks Folder

Create a `.githooks/` folder in your project root (tracked by git, unlike `.git/hooks/`):

```bash
mkdir .githooks
```

#### Step 2: Copy the Sync Script

```bash
cp Assets/MooseRunnerGit/MooseRunner/hooks/sync-mooserunner-skills.ps1 .githooks/
```

**Note:** If MooseRunner is in `Packages/` instead of `Assets/`, edit the script's `$SubmodulePath` parameter.

#### Step 3: Set Up Git Hooks

Copy or create `post-checkout` and `post-merge` in `.githooks/`:

```bash
cp Assets/MooseRunnerGit/MooseRunner/hooks/post-checkout .githooks/
cp Assets/MooseRunnerGit/MooseRunner/hooks/post-merge .githooks/
```

Or add this line to existing hooks:

```bash
powershell -NoProfile -ExecutionPolicy Bypass -File .githooks/sync-mooserunner-skills.ps1
```

#### Step 4: Configure Git to Use Tracked Hooks

```bash
git config core.hooksPath .githooks
```

> **Tip**: Add this to a setup script so new developers run it once after cloning.

#### Step 5: Run the Sync Script

```powershell
.\.githooks\sync-mooserunner-skills.ps1
```

#### Step 6: Update .gitignore

Add the junctioned folders to your `.gitignore`:

```gitignore
# Skills synced from MooseRunner submodule
.claude/skills/play-mode-tester/
.claude/skills/e2e-tester/
```

#### Step 7: Update settings.json (Optional)

To allow skills to run without permission prompts, add to `.claude/settings.json`:

```json
"Skill(play-mode-tester)",
"Skill(e2e-tester)"
```

### Windows Developer Mode

Junction creation requires Developer Mode on Windows:

**Settings > Update & Security > For developers > Developer Mode**

Without it, skills are copied instead of junctioned (won't auto-update with submodule).

### What the Skills Provide

- **Test Structure Guidelines**: Arrange – Act – Assert – Cleanup pattern
- **Scene Cleanup Methods**: `DoNotDestroyOnTeardown.CleanSceneImmediate()` and `CleanSceneSafeUsingUpdateAsync()`
- **MCP Integration**: How to run tests via MCP tools
- **E2E Test Patterns**: Dynamic loading rules, first-test-method setup, chained execution
- **Debugging Workflows**: Console analysis and debug logging patterns

### Recommended CLAUDE.md Settings

Add to your project's `CLAUDE.md`:

```markdown
## Critical Constraints
- For tests use the `play-mode-tester` skill (isolated tests) or `e2e-tester` skill (E2E gameplay flows). Never run the MCP run_play_mode_test yourself.

## MooseRunner Testing

Deny these MCP tools in `.claude/settings.json` to prevent direct test execution:
- `mcp__unityMCP__run_tests`
- `mcp__unityMCP__refresh_unity`
- `mcp__unityMCP__get_test_job`

Use the skills instead, which handle test execution properly via MooseRunner.
```

---

## Troubleshooting

### Skills Not Appearing in Claude Code
- Verify junctions exist: `ls .claude/skills/`
- Re-run sync script: `.\.git\hooks\sync-mooserunner-skills.ps1`
- Restart Claude Code after installation

### Junction Creation Failed
- Enable Developer Mode: Settings > Update & Security > For developers
- Without Developer Mode, skills are copied (won't auto-update)

### Hook Not Executing on Checkout
- Verify hook is executable (Git Bash): `chmod +x .git/hooks/post-checkout`
- Check hooks path: `git config core.hooksPath`

### PowerShell Execution Policy Error
- Run: `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`

---

## AI Installation Guide

If you are an AI assistant installing this for a user:

### Pre-Installation Checks (Silent)
1. Check if `.claude/skills/` directory exists
2. Check if hooks folder exists (`.git/hooks` or custom path via `git config core.hooksPath`)
3. Check if `sync-mooserunner-skills.ps1` already exists in hooks folder

### Installation Notes
- **Merging**: When updating settings.json, merge new permissions into existing `permissions.allow` array
- **Existing hooks**: Add sync line to existing post-checkout/post-merge, don't replace entire file
- **Verification**: After running sync script, verify junctions created with `ls .claude/skills/`

### Questions to Ask User
- "Do you have a custom hooks path configured?" (if unsure, run `git config core.hooksPath`)
- "Should I add these skills to your settings.json permissions?"

---

## Optional Components

MooseRunner includes optional utilities. Each component can be installed independently.

### A. MooseRunner Core (Skills + Test CLI)

**What it does:** Test skills for Claude Code + CLI script for long-running tests.

**Why useful:** Skills provide test documentation and patterns. CLI bypasses MCP timeout for long tests.

**Setup:** Follow "Installing Skills" section above.

**CLAUDE.md snippet:**
```markdown
## Critical Constraints
- For tests use the `play-mode-tester` skill (isolated tests) or `e2e-tester` skill (E2E gameplay flows).

## MooseRunner Testing
Script location: `Assets/MooseRunnerGit/MooseRunner/Editor/MCPForUnityTools/run-moose-test.py`

```bash
python run-moose-test.py --method Assembly Class Method
python run-moose-test.py --class Assembly Class
python run-moose-test.py --assembly Assembly
```
```

---

### B. Unity MCP CLI

**What it does:** Command-line interface for Unity MCP tools.

**Why useful:** Avoids MCP reconnection issues. When Unity restarts, MCP connection breaks and requires human `/mcp reconnect`. CLI works via HTTP - no persistent connection needed.

**Installation:**
```bash
cd Server  # In unity-mcp repo (https://github.com/CoplayDev/unity-mcp)
pip install -e .
```

**Prerequisite:** MCP HTTP server must be running. Use `restart-unity.ps1` from `General-Claude-Code-Skill-And-Agents/Unity_Control/` which handles this automatically.

**Setup:** Unity needs `AutoStartMcpSession` component to connect to MCP server.

**CLAUDE.md snippet:**
```markdown
## Unity MCP (CLI Mode)

We use Unity MCP via **CLI** instead of MCP server connection. This avoids reconnection issues when Unity restarts.

### Core Commands
```bash
unity-mcp instance list                    # List Unity instances
unity-mcp editor play|pause|stop           # Control play mode
unity-mcp editor console                   # Get console logs
unity-mcp scene hierarchy                  # Get scene hierarchy
unity-mcp gameobject find "Name"           # Find GameObject
unity-mcp raw tool_name 'JSON_params'      # Any tool via raw access
```

Full reference: https://github.com/CoplayDev/unity-mcp/blob/main/docs/guides/CLI_USAGE.md
```

---

### Why These Components Are Separate

| Component | Purpose | When to Install |
|-----------|---------|-----------------|
| **MooseRunner Core** | Test documentation + CLI | Always (for testing) |
| **Unity MCP CLI** | CLI instead of MCP connection | If Unity restarts break your workflow |

Each component solves a specific problem:
- **MooseRunner Core**: "How do I write and run tests?"
- **Unity MCP CLI**: "How do I avoid MCP reconnection issues?"

**Note:** Unity Control Scripts (start/stop/restart Unity) have moved to `General-Claude-Code-Skill-And-Agents/Unity_Control/`.

