From 1c6b904e9c6f9d6bf5e41171557dbb6c30b05fdd Mon Sep 17 00:00:00 2001 From: fOuttaMyPaint Date: Sun, 26 Apr 2026 15:42:04 -0400 Subject: [PATCH] fix: backfill CONTRIBUTING.md and CLAUDE.md per ecosystem standards Tracks DTD#48 (expanded scope: original issue noted CONTRIBUTING.md only; CLAUDE.md absence surfaced during DTD#47 work). Identical surgery to CFX-Developer-Tools (DTD#48 canary, merged previously). CONTRIBUTING.md follows the Plaid pattern with the verbatim DCO grant from standards/licensing.md. CLAUDE.md includes the standards-version marker and `**Version:**` convention so release-doc-sync can reconcile version markers on future releases (which DTD#51 just fixed at the runner level). Made-with: Cursor --- CLAUDE.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 143 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 295 insertions(+) create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a9b95a1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,152 @@ + + +# CLAUDE.md + +Project documentation for Claude Code and AI assistants working on this repository. + +## Project Overview + +Unity Developer Tools is a Cursor IDE plugin for Unity game development. It includes 18 skills, 8 rules, 20 code snippets across C# / HLSL / Visual Scripting, 5 starter templates, and a companion Python MCP server with 4 tools for script scaffolding, Unity API lookup, shader patterns, and platform information. + +**Works with:** Cursor (plugin), Claude Code (terminal and in-editor), and any MCP-compatible client. + +This is a monorepo. Skills, rules, snippets, templates, and the companion MCP server live in the same repository because Unity development crosses all of those layers in a single workflow. + +**Version:** 1.4.3 +**License:** CC-BY-NC-ND-4.0 +**Author:** TMHSDigital + +## Plugin Architecture + +``` +Unity-Developer-Tools/ + .cursor-plugin/ + plugin.json # Plugin manifest (version, skills, rules) + skills/ + / + SKILL.md # One skill per directory (kebab-case) + rules/ + .mdc # Cursor rule files + snippets/ + csharp/ # C# patterns and examples + shaders/ # HLSL / ShaderLab patterns + visual-scripting/ # Visual Scripting graphs and notes + templates/ # Starter project archetypes + mcp-server/ + server.py # MCP server entry point (Python, FastMCP) + data/ # API reference, deprecated patterns, shader props, platform defines + requirements.txt + docs/ # MkDocs Material site (ARCHITECTURE, ROADMAP, GETTING-STARTED) + .github/ + workflows/ # CI / release / docs / drift-check automation +``` + +## Skills (18) + +| Skill | Description | +|-------|-------------| +| `project-setup` | Folder structure, assembly definitions, version control, and package management for Unity projects | +| `monobehaviour-patterns` | MonoBehaviour lifecycle, async patterns with Awaitable, and common Unity design patterns | +| `scriptableobjects` | Data-driven design with ScriptableObjects (events, variables, runtime sets, configuration) | +| `physics-2d-3d` | Collision, raycasting, layers, and rigidbody management for 2D and 3D projects | +| `ui-development` | UI Toolkit (primary) and Canvas/UGUI, including data binding, styling, responsive layouts | +| `shader-development` | Shader Graph, HLSL, and ShaderLab for URP and HDRP projects | +| `animation-systems` | Animator Controller, Timeline, DOTween, and sprite animation for 2D | +| `audio-systems` | AudioSource, AudioMixer, spatial audio, and audio management patterns | +| `input-systems` | New Input System package and migration guidance from the legacy Input Manager | +| `networking` | Multiplayer networking with Netcode for GameObjects, Netcode for Entities, Mirror, Photon Fusion | +| `editor-scripting` | Custom inspectors, editor windows, property drawers, gizmos, Scene View overlays via UI Toolkit | +| `performance-optimization` | CPU, GPU, memory, and profiling tools (Profiler, Memory Profiler, Frame Debugger) | +| `render-pipeline-detection` | Detect and adapt to URP, HDRP, or Built-in pipelines | +| `ecs-dots` | Entity Component System with Unity Entities, Jobs, and Burst | +| `visual-scripting` | Script Graphs, State Graphs, Subgraphs, and custom units | +| `testing` | Unity Test Framework 2.x with Edit Mode and Play Mode tests, async Awaitable support | +| `addressables-assets` | Async loading, memory management, and remote content delivery via Addressables | +| `platform-targeting` | Scripting defines, build settings, and cross-platform considerations | + +## Rules (8) + +| Rule | Scope | Description | +|------|-------|-------------| +| `csharp-unity-conventions.mdc` | `**/*.cs` | C# coding conventions for Unity development | +| `monobehaviour-lifecycle.mdc` | `**/*.cs` | Correct usage of MonoBehaviour lifecycle methods | +| `performance-rules.mdc` | `**/*.cs` | Performance optimization rules (allocations, FindObject, tight loops) | +| `naming-conventions.mdc` | `**/*.cs` | Naming conventions for Unity C# code | +| `serialization-rules.mdc` | `**/*.cs` | Unity serialization best practices (`[SerializeField]`, ISerializationCallbackReceiver) | +| `shader-conventions.mdc` | `**/*.shader`, `**/*.hlsl`, `**/*.cginc`, `**/*.shadergraph` | Conventions for Unity shader development (HLSLPROGRAM, SRP Batcher) | +| `visual-scripting-conventions.mdc` | `**/*.asset` | Best practices for Unity Visual Scripting graphs | +| `security-and-builds.mdc` | `**/*.cs`, `**/*.json`, `**/*.asset` | Security and build configuration rules (no hardcoded secrets, build target hygiene) | + +## MCP Server (4 tools) + +The companion MCP server is Python-based (FastMCP). It exposes Unity-aware tools that read from local data files (`mcp-server/data/`) and accept agent-supplied parameters. + +| Tool | Description | +|------|-------------| +| `scaffold_script` | Generate a structured C# script (MonoBehaviour, ScriptableObject, EditorWindow, custom inspector, property drawer, interface, state machine, test) with recommended folder placement | +| `lookup_api` | Search the Unity API reference (name, namespace, signature, examples) with optional category filter and deprecated-pattern warnings | +| `shader_helper` | Fetch shader patterns and property setups for common effects (dissolve, outline, toon, water, hologram, fresnel) per render pipeline | +| `platform_info` | Get platform-specific scripting defines, capabilities, limitations, and recommendations (Windows, macOS, Linux, Android, iOS, WebGL, PS5, Xbox, Switch) | + +## Development Workflow + +### Plugin development (symlink) + +**macOS / Linux:** +```bash +ln -s "$(pwd)" ~/.cursor/plugins/unity-developer-tools +``` + +**Windows (PowerShell as Admin):** +```powershell +New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.cursor\plugins\unity-developer-tools" -Target (Get-Location) +``` + +### MCP server development + +```bash +cd mcp-server +pip install -r requirements.txt +python server.py +``` + +### Running validation + +```bash +# JSON schema and content-count checks (run by CI) +python .github/scripts/validate_plugin.py +``` + +## Release Workflow + +Releases are automated. The `release.yml` workflow: + +1. Reads conventional commits since the last tag. +2. Computes the next semver bump (PATCH for `fix:`, MINOR for `feat:`, MAJOR for `BREAKING CHANGE`). +3. Updates `plugin.json` `version` and the README version badge. +4. Creates the tag, the GitHub Release, and floating major / minor tags. +5. Invokes `release-doc-sync` to update `**Version:**` in this file and prepend a CHANGELOG entry. + +Do not hand-edit `plugin.json` `version`, the README badge, or the `**Version:**` line above. The release pipeline owns them. + +## Key Conventions + +- **No em dashes.** Use regular dashes (`-`) or rewrite the sentence. CI flags em and en dashes in markdown. +- **No hardcoded credentials.** Use environment variables, `EditorUserSettings`, or a secrets store. CI flags suspicious patterns. +- **Skill frontmatter:** `title`, `description`, `globs` (when path-scoped), and `standards-version`. +- **Rule frontmatter:** `title`, `description`, `globs`, `alwaysApply`, and `standards-version`. +- **Snippets:** must compile against Unity 6.x and use modern APIs (Awaitable, `FindFirstObjectByType`, UI Toolkit). No placeholder credentials. +- **Templates:** every template needs a top-level `README.md` describing usage, scripts, and any project setup notes (assembly definitions, package dependencies). +- **MCP tool naming:** snake_case Python functions decorated with `@mcp.tool()`. + +## Unity Reference Quick Links + +| Resource | Use | +|----------|-----| +| `docs.unity3d.com/Manual/index.html` | Authoritative Unity manual | +| `docs.unity3d.com/ScriptReference/index.html` | Scripting API reference | +| `docs.unity3d.com/Packages/` | Package-specific manuals (URP, HDRP, Input System, Netcode, Entities) | +| `mcp-server/data/unity_api_common.json` | Local Unity API quick-reference index | +| `mcp-server/data/deprecated_patterns.json` | Deprecation map (legacy -> replacement) | +| `mcp-server/data/shader_properties.json` | Shader effect patterns and property setups | +| `mcp-server/data/platform_defines.json` | Platform scripting defines and capabilities | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6f8cf77 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,143 @@ +# Contributing to Unity Developer Tools + +Thanks for helping improve this plugin. This document describes how to set up locally, extend skills and rules, and submit changes. + +## Getting Started + +1. **Fork** the repository on GitHub. +2. **Clone** your fork: + + ```bash + git clone https://github.com//Unity-Developer-Tools.git + cd Unity-Developer-Tools + ``` + +3. **Create a branch** for your work: + + ```bash + git checkout -b your-feature-name + ``` + +## Local Development + +Install the plugin from your working copy so Cursor loads your changes. + +Symlink the repo into the local plugins directory: `~/.cursor/plugins/local/unity-developer-tools/` (create parent folders if needed). + +**Windows (PowerShell):** + +```powershell +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools" | Out-Null +cmd /c mklink /J "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools\Unity-Developer-Tools" (Get-Location) +``` + +Adjust the final path if your clone lives elsewhere. + +**macOS / Linux:** + +```bash +mkdir -p ~/.cursor/plugins/local/unity-developer-tools +ln -s "$(pwd)" ~/.cursor/plugins/local/unity-developer-tools/Unity-Developer-Tools +``` + +Restart Cursor after linking so it picks up the plugin. + +## Plugin Structure + +The repo is organized as a Cursor plugin with **18 skills** and **8 rules**, plus snippets, templates, and a companion MCP server. + +```text +.cursor-plugin/ + plugin.json +skills/ + / + SKILL.md +rules/ + .mdc +snippets/ + csharp/ + shaders/ + visual-scripting/ +templates/ +mcp-server/ + server.py + data/ +docs/ +.github/ + workflows/ +``` + +- **`plugin.json`** - manifest (name, version, paths to skills/rules). +- **`skills/`** - one directory per skill; each contains `SKILL.md`. +- **`rules/`** - Cursor rules as `.mdc` files with YAML frontmatter. +- **`snippets/`** - C#, HLSL/ShaderLab, and Visual Scripting examples organized by language. +- **`templates/`** - starter project archetypes (2D platformer, 3D FPS, UI menu, ScriptableObject architecture, editor tool). +- **`mcp-server/`** - Python MCP server exposing Unity-aware tools (script scaffolding, API lookup, shader patterns, platform info). + +## Adding a Skill + +1. Add a **kebab-case** directory under `skills/`, e.g. `skills/unity-example-flow/`. +2. Create **`SKILL.md`** with YAML frontmatter including at least `title`, `description`, and `globs` (path-scoped patterns where applicable, e.g. `["**/*.cs"]`, `["**/*.shader", "**/*.hlsl"]`). +3. In the body, include sections (use `##` headings) such as: + - **Overview / Why** - when the skill applies and what problem it solves. + - **Required Inputs** - what the agent or user must provide. + - **Workflow** - step-by-step guidance. + - **Key References** - Unity manual links, package names, or repo paths. + - **Example Interaction** - short example prompt/response pattern. + - **MCP Usage** - when to use the companion MCP server, if relevant. + - **Common Pitfalls** - mistakes to avoid (deprecated APIs, render-pipeline confusion, MonoBehaviour lifecycle traps, etc.). + - **See Also** - links to related skills or rules. + +Match tone, formatting, and frontmatter style of existing skills in this repo. + +## Adding a Rule + +1. Add a **`.mdc`** file under `rules/`, e.g. `rules/unity-example.mdc`. +2. Start with YAML **frontmatter**: + - `title` - one-line summary. + - `description` - longer description for humans and tooling. + - `globs` - glob patterns scoping the rule (e.g. `["**/*.cs"]`, `["**/*.shader", "**/*.hlsl", "**/*.cginc", "**/*.shadergraph"]`). + - `alwaysApply` - `true` or `false` depending on whether the rule should apply globally. + +3. Below the frontmatter, write the rule content in Markdown (constraints, patterns, anti-patterns). + +Keep rules focused; prefer linking to a skill for long workflows. + +## Adding a Snippet or Template + +1. Snippets live under `snippets/` grouped by language (`csharp/`, `shaders/`, `visual-scripting/`). Each file should be self-contained, target Unity 6.x APIs (Awaitable, `FindFirstObjectByType`, UI Toolkit), and free of hardcoded credentials. +2. Templates live under `templates/`. A new template needs at least a top-level `README.md` describing usage, the canonical scripts, and any project setup notes (assembly definitions, package dependencies, scripting defines). +3. Run the validators before opening a PR; CI checks JSON validity, plugin manifest completeness, file count consistency, em/en dash detection, and credential scanning. + +## Pull Request Process + +1. **Update docs** if you change behavior, skill lists, snippet counts, or versioning (`README.md`, `CLAUDE.md`, `CHANGELOG.md`, `docs/ROADMAP.md` as appropriate). +2. **Run validation** locally where possible. CI runs JSON schema checks, kebab-case enforcement, em/en dash detection, deprecated-API scans, and Python syntax checks for `mcp-server/`. +3. **Open a PR** against `main` with a clear title and summary of changes. Use a conventional commit prefix (`feat:`, `fix:`, `docs:`, `chore:`). +4. **Respond to review** feedback; CI must pass before merge. + +## Developer Certificate of Origin and Inbound License Grant + +This project uses CC-BY-NC-ND-4.0 as its outbound license, which forbids derivatives. Every pull request is a derivative. Contributions are accepted inbound under a broader grant via the Developer Certificate of Origin (DCO), which resolves the conflict so the project can accept and redistribute contributions. + +### Required grant + +By submitting a contribution to this repository, you certify that you have the right to do so under the Developer Certificate of Origin (DCO) 1.1, and you grant TMHSDigital a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute your contribution under the project's current license (CC-BY-NC-ND-4.0) or any successor license chosen by the project. + +### DCO sign-off + +Every commit in a pull request must have a `Signed-off-by:` trailer matching the commit author: + +``` +Signed-off-by: Jane Developer +``` + +Signing is done at commit time: + +```bash +git commit -s -m "feat: add new skill" +``` + +The GitHub DCO App enforces this on every PR. + +For the full inbound/outbound model and rationale, see [`standards/licensing.md`](https://github.com/TMHSDigital/Developer-Tools-Directory/blob/main/standards/licensing.md) in the Developer-Tools-Directory meta-repo.