Skip to content

CLAUDE.md

Latest commit

 

History

History
157 lines (123 loc) · 8.63 KB

CLAUDE.md

File metadata and controls

157 lines (123 loc) · 8.63 KB
Raw

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 5 tools for script scaffolding, Unity API lookup, shader patterns, platform information, and project analysis.

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.5.0 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-name>/
      SKILL.md               # One skill per directory (kebab-case)
  rules/
    <rule-name>.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 (5 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)
analyze_project Read a Unity project from disk (editor version, render pipeline, packages, input handling, scripting backend, define symbols, asmdefs) so advice matches the actual project

Development Workflow

Plugin development (local plugin folder)

Cursor loads local plugins from ~/.cursor/plugins/local/<name> and skips symlinks that point outside that folder, so clone the repo there and work in that clone:

macOS / Linux:

git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git ~/.cursor/plugins/local/unity-developer-tools

Windows (PowerShell):

git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools"

Run Developer: Reload Window after changing the manifest, rules, skills, or mcp.json.

MCP server development

cd mcp-server
pip install -r requirements.txt
python server.py

Running validation

# 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