diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 918bb39..976adbc 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -32,6 +32,11 @@ "name": "ralph-loop", "source": "ralph-loop", "description": "Iterative self-referential AI loops using the Ralph Wiggum technique." + }, + { + "name": "aether", + "source": "aether", + "description": "AI co-debugging for Unity. One-click install—your AI can see your game." } ] } diff --git a/aether/.cursor-plugin/plugin.json b/aether/.cursor-plugin/plugin.json new file mode 100644 index 0000000..29b8f25 --- /dev/null +++ b/aether/.cursor-plugin/plugin.json @@ -0,0 +1,33 @@ +{ + "name": "aether", + "displayName": "Aether", + "version": "0.4.9", + "description": "AI co-debugging for Unity. One-click install—your AI can see your game.", + "author": { + "name": "Finexma", + "email": "support@getaether.dev" + }, + "homepage": "https://getaether.dev", + "repository": "https://github.com/finexma-dev/aether", + "license": "MIT", + "logo": "assets/avatar.png", + "keywords": [ + "aether", + "unity", + "debugging", + "mcp", + "game-dev", + "gtml", + "live-inspector", + "replay" + ], + "category": "developer-tools", + "tags": [ + "unity", + "game-development", + "debugging", + "mcp", + "ai-assistant" + ], + "skills": "./skills/" +} diff --git a/aether/CHANGELOG.md b/aether/CHANGELOG.md new file mode 100644 index 0000000..fcb2ac6 --- /dev/null +++ b/aether/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog + +## v0.4.9 — Initial Cursor Marketplace release + +- MCP server via Aether Bridge local binary +- Unity SDK v0.4.9 support +- Compatible with Unity 2021.3 LTS and newer +- Aether debugging skill for gameplay, crash analysis, and verification diff --git a/aether/LICENSE b/aether/LICENSE new file mode 100644 index 0000000..ea87105 --- /dev/null +++ b/aether/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Aether + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/aether/README.md b/aether/README.md new file mode 100644 index 0000000..d3335b9 --- /dev/null +++ b/aether/README.md @@ -0,0 +1,85 @@ +# Aether + +**AI co-debugging for Unity.** Stop narrating your gameplay—your AI can see the game. + +Aether bridges your Unity game to Cursor, giving the AI complete context: live state, event history, crashes, and GTML snapshots. Two modes: **Live Inspector** (real-time object inspection) and **Replay Mode** (time-travel debugging after a bug). + +--- + +## Install + +```bash +/add-plugin aether +``` + +That's it. The bridge auto-downloads on first use. + +**First time in a Unity project?** Run this once from your project root: + +```bash +npx aether-init +``` + +Then reload Cursor (Ctrl+Shift+P → Reload Window), enter Play mode, and ask your AI: *"What's the state of my game?"* + +--- + +## Requirements + +Unity 2021.3+, Node.js 18+, Cursor with MCP + +--- + +## When the Agent Uses Aether + +The plugin includes a skill that guides the agent to use Aether when: + +- Debugging Unity gameplay behavior +- Analyzing crashes, NullReferenceExceptions, or runtime errors +- Inspecting object state during Play Mode +- Asking "what happened before this crash?" or "why is this object behaving wrong?" + +The agent will call tools like `aether_snapshot`, `aether_tail`, `aether_console`, and `aether_last_run_answer` to get live context from your game. + +--- + +## MCP Tools + +| Tool | Description | +|------|-------------| +| `aether_snapshot` | Current Unity state: selected object, scene, frame, recent events | +| `aether_tail` | Events + console + state over last N seconds | +| `aether_console` | Query Unity stdout logs with filters | +| `aether_last_run_answer` | Answer engine for the last run with receipts | +| `aether_mark` | Save a moment (clip) with context | +| `aether_docs` | Get authoritative tool documentation | + +See [Aether docs](https://docs.getaether.dev) for the full tool list. + +--- + +## Manual Setup + +Technical users or non-Cursor setups: see [getaether.dev](https://getaether.dev) for download links and manual MCP configuration. + +--- + +## Pro Trial + +Aether Pro includes proof clips, capsules, probes, and vision analysis. **14-day free trial, no credit card required.** See [getaether.dev](https://getaether.dev) for details. + +--- + +## Troubleshooting + +**MCP won't start / "script not found"** — Cursor runs the launcher from the plugin directory. If you see script path errors, ensure the plugin was installed correctly. You can still use Aether by running `npx aether-init`; it writes `.cursor/mcp.json` with the direct bridge path. + +## Windows SmartScreen + +On first run, Windows may show SmartScreen for the bridge binary. Choose "More info" → "Run anyway." The binary is signed; this is a one-time prompt. + +--- + +## License + +MIT diff --git a/aether/assets/README.md b/aether/assets/README.md new file mode 100644 index 0000000..480485d --- /dev/null +++ b/aether/assets/README.md @@ -0,0 +1,3 @@ +Add `avatar.png` here (128×128 or 256×256 recommended) for the plugin marketplace icon. + +The `plugin.json` references `assets/avatar.png`. If omitted, the plugin may still install but won't display an icon in the marketplace. diff --git a/aether/assets/avatar.png b/aether/assets/avatar.png new file mode 100644 index 0000000..59f9141 Binary files /dev/null and b/aether/assets/avatar.png differ diff --git a/aether/mcp.json b/aether/mcp.json new file mode 100644 index 0000000..7bf1065 --- /dev/null +++ b/aether/mcp.json @@ -0,0 +1,9 @@ +{ + "mcpServers": { + "aether": { + "command": "node", + "args": ["scripts/start-mcp.js"], + "env": {} + } + } +} diff --git a/aether/scripts/start-mcp.js b/aether/scripts/start-mcp.js new file mode 100644 index 0000000..41f33c1 --- /dev/null +++ b/aether/scripts/start-mcp.js @@ -0,0 +1,65 @@ +#!/usr/bin/env node + +/** + * Aether MCP launcher — OS-agnostic. + * Locates the bridge at ~/.aether/bin. If missing, auto-downloads via npx aether-init --bridge-only. + * Then spawns the bridge with --stdio. + */ + +const { spawn, execSync } = require("child_process"); +const { existsSync } = require("fs"); +const { homedir, platform, arch } = require("os"); +const { join } = require("path"); + +function detectPlatform() { + const os = platform(); + const cpu = arch(); + if (os === "win32") return { os: "windows", arch: "x64", ext: ".exe" }; + if (os === "darwin") return { os: "darwin", arch: cpu === "arm64" ? "arm64" : "x64", ext: "" }; + if (os === "linux") return { os: "linux", arch: "x64", ext: "" }; + throw new Error(`Unsupported platform: ${os}/${cpu}`); +} + +function getBinaryName(plat) { + return `aether-bridge-${plat.os}-${plat.arch}${plat.ext}`; +} + +const binDir = join(homedir(), ".aether", "bin"); +const plat = detectPlatform(); +const binaryName = getBinaryName(plat); +const bridgePath = join(binDir, binaryName); + +if (!existsSync(bridgePath)) { + try { + execSync("npx aether-init@latest --bridge-only", { + stdio: "ignore", + env: { ...process.env, npm_config_yes: "true" }, + }); + } catch (e) { + console.error( + "[Aether] Bridge not found and auto-download failed. Run manually from your Unity project root:\n npx aether-init\nThen reload Cursor (Ctrl+Shift+P → Reload Window)." + ); + process.exit(1); + } + if (!existsSync(bridgePath)) { + console.error("[Aether] Bridge download completed but binary not found. Try: npx aether-init"); + process.exit(1); + } +} + +const child = spawn(bridgePath, ["--stdio"], { + stdio: ["pipe", "pipe", "inherit"], +}); + +process.stdin.pipe(child.stdin); +child.stdout.pipe(process.stdout); + +child.on("error", (err) => { + console.error("[Aether] Failed to start bridge:", err.message); + process.exit(1); +}); + +child.on("exit", (code, signal) => { + if (code !== null) process.exit(code); + process.exit(signal === "SIGTERM" ? 143 : 1); +}); diff --git a/aether/skills/aether-debugging/SKILL.md b/aether/skills/aether-debugging/SKILL.md new file mode 100644 index 0000000..0db4da2 --- /dev/null +++ b/aether/skills/aether-debugging/SKILL.md @@ -0,0 +1,51 @@ +--- +name: aether-debugging +description: Use Aether MCP tools when debugging Unity gameplay behavior, analyzing runtime crashes, inspecting object state during Play Mode, or when the user asks what happened before a crash or why an object is misbehaving. +--- + +# Aether Unity Debugging + +## MCP Gate (Required First) + +**Before recommending any Aether tool calls:** Check whether Aether tools are available. If the user gets "tool not found," "aether_snapshot failed," or similar errors, or if you cannot invoke Aether tools: + +1. **Instruct the user to run** `npx aether-init` from their Unity project root. +2. **Tell them to reload Cursor** (Ctrl+Shift+P → "Reload Window"). +3. **Then retry** the Aether tool call. + +Only recommend tool calls (aether_snapshot, aether_tail, etc.) **after** confirming Aether is configured. Do not suggest tools the user cannot use. + +--- + +## When to Use + +- User mentions Unity, gameplay bug, crash, or runtime error +- User asks "what went wrong?", "what happened before this crash?", "why is this object falling through the floor?" +- User is debugging in Play Mode and needs object state or event history +- User references Aether tools or GTML + +## Prerequisites (for tool calls) + +1. User ran `npx aether-init` from their Unity project root +2. Unity is in Play Mode (for live data) or has recorded a session (for replay) + +## Key Tools + +| Tool | Use when | +|------|----------| +| `aether_snapshot` | Need current state of selected GameObject, scene, frame | +| `aether_tail` | Need recent events, console logs, state changes (last N seconds) | +| `aether_console` | Need to search/filter Unity stdout logs | +| `aether_last_run_answer` | Need causal answer for "what led to this?" with receipts | +| `aether_docs` | Need full tool documentation | + +## Workflow + +1. **Live Inspector**: User selects GameObject in Unity → ask for snapshot → analyze GTML for issues (disabled colliders, wrong velocity, etc.) +2. **Replay / Crash**: User hit a bug → ask "what happened before this crash?" → use `aether_tail` or `aether_last_run_answer` for timeline +3. **Console search**: Use `aether_console` with text/level filters to find relevant logs +4. **Verification**: After making code changes, ask the user to enter Play mode, then use Aether to verify the fix worked (snapshot, tail, or last_run_answer) + +## Output Format + +Aether returns GTML (Game Temporal Markup Language)—structured XML that LLMs parse well. Look for `[ISSUE: ...]` tags for detected problems.