From e46f78f94b75d2e3267e546db711ab04e4280189 Mon Sep 17 00:00:00 2001 From: wxm <18854896936@163.com> Date: Tue, 19 May 2026 01:29:15 -0700 Subject: [PATCH] =?UTF-8?q?=E8=BF=81=E7=A7=BBsetup-engine=E5=B7=A5?= =?UTF-8?q?=E4=BD=9C=E6=B5=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codex-plugin/plugin.json | 9 +- README.md | 16 +- project-template/AGENTS.md | 76 +- project-template/technical-preferences.md | 87 ++ references/engine-reference/README.md | 63 ++ references/engine-reference/godot/VERSION.md | 31 + .../godot/breaking-changes.md | 70 ++ .../godot/current-best-practices.md | 107 +++ .../engine-reference/godot/deprecated-apis.md | 43 + .../godot/modules/animation.md | 76 ++ .../engine-reference/godot/modules/audio.md | 79 ++ .../engine-reference/godot/modules/input.md | 72 ++ .../godot/modules/navigation.md | 101 +++ .../godot/modules/networking.md | 76 ++ .../engine-reference/godot/modules/physics.md | 76 ++ .../godot/modules/rendering.md | 59 ++ .../engine-reference/godot/modules/ui.md | 82 ++ references/engine-reference/unity/PLUGINS.md | 250 ++++++ references/engine-reference/unity/VERSION.md | 57 ++ .../unity/breaking-changes.md | 154 ++++ .../unity/current-best-practices.md | 334 ++++++++ .../engine-reference/unity/deprecated-apis.md | 156 ++++ .../unity/modules/animation.md | 289 +++++++ .../engine-reference/unity/modules/audio.md | 284 +++++++ .../engine-reference/unity/modules/input.md | 356 ++++++++ .../unity/modules/navigation.md | 330 +++++++ .../unity/modules/networking.md | 351 ++++++++ .../engine-reference/unity/modules/physics.md | 268 ++++++ .../unity/modules/rendering.md | 238 ++++++ .../engine-reference/unity/modules/ui.md | 377 ++++++++ .../unity/plugins/addressables.md | 378 +++++++++ .../unity/plugins/cinemachine.md | 348 ++++++++ .../unity/plugins/dots-entities.md | 420 +++++++++ references/engine-reference/unreal/PLUGINS.md | 210 +++++ references/engine-reference/unreal/VERSION.md | 54 ++ .../unreal/breaking-changes.md | 150 ++++ .../unreal/current-best-practices.md | 340 ++++++++ .../unreal/deprecated-apis.md | 170 ++++ .../unreal/modules/animation.md | 292 +++++++ .../engine-reference/unreal/modules/audio.md | 289 +++++++ .../engine-reference/unreal/modules/input.md | 288 +++++++ .../unreal/modules/navigation.md | 338 ++++++++ .../unreal/modules/networking.md | 409 +++++++++ .../unreal/modules/physics.md | 283 ++++++ .../unreal/modules/rendering.md | 297 +++++++ .../engine-reference/unreal/modules/ui.md | 353 ++++++++ .../unreal/plugins/common-ui.md | 389 +++++++++ .../unreal/plugins/gameplay-ability-system.md | 386 +++++++++ .../unreal/plugins/gameplay-camera-system.md | 321 +++++++ .../engine-reference/unreal/plugins/pcg.md | 356 ++++++++ .../studio-docs/templates/game-concept.md | 2 +- .../templates/technical-preferences.md | 87 ++ runtime/agents/godot-csharp-specialist.toml | 404 +++++++++ .../agents/godot-gdextension-specialist.toml | 314 +++++++ runtime/agents/godot-gdscript-specialist.toml | 269 ++++++ runtime/agents/godot-shader-specialist.toml | 262 ++++++ runtime/agents/godot-specialist.toml | 187 ++++ runtime/agents/ue-blueprint-specialist.toml | 156 ++++ runtime/agents/ue-gas-specialist.toml | 139 +++ runtime/agents/ue-replication-specialist.toml | 149 ++++ runtime/agents/ue-umg-specialist.toml | 156 ++++ .../agents/unity-addressables-specialist.toml | 171 ++++ runtime/agents/unity-dots-specialist.toml | 154 ++++ runtime/agents/unity-shader-specialist.toml | 184 ++++ runtime/agents/unity-specialist.toml | 186 ++++ runtime/agents/unity-ui-specialist.toml | 223 +++++ runtime/agents/unreal-specialist.toml | 174 ++++ scripts/install_codex_runtime.py | 5 +- scripts/validate_plugin.py | 259 ++++++ skills/brainstorm/DETAILS.md | 16 +- skills/brainstorm/SKILL.md | 10 +- skills/setup-engine/DETAILS.md | 802 ++++++++++++++++++ skills/setup-engine/SKILL.md | 44 + skills/setup-engine/agents/openai.yaml | 4 + 74 files changed, 14945 insertions(+), 50 deletions(-) create mode 100644 project-template/technical-preferences.md create mode 100644 references/engine-reference/README.md create mode 100644 references/engine-reference/godot/VERSION.md create mode 100644 references/engine-reference/godot/breaking-changes.md create mode 100644 references/engine-reference/godot/current-best-practices.md create mode 100644 references/engine-reference/godot/deprecated-apis.md create mode 100644 references/engine-reference/godot/modules/animation.md create mode 100644 references/engine-reference/godot/modules/audio.md create mode 100644 references/engine-reference/godot/modules/input.md create mode 100644 references/engine-reference/godot/modules/navigation.md create mode 100644 references/engine-reference/godot/modules/networking.md create mode 100644 references/engine-reference/godot/modules/physics.md create mode 100644 references/engine-reference/godot/modules/rendering.md create mode 100644 references/engine-reference/godot/modules/ui.md create mode 100644 references/engine-reference/unity/PLUGINS.md create mode 100644 references/engine-reference/unity/VERSION.md create mode 100644 references/engine-reference/unity/breaking-changes.md create mode 100644 references/engine-reference/unity/current-best-practices.md create mode 100644 references/engine-reference/unity/deprecated-apis.md create mode 100644 references/engine-reference/unity/modules/animation.md create mode 100644 references/engine-reference/unity/modules/audio.md create mode 100644 references/engine-reference/unity/modules/input.md create mode 100644 references/engine-reference/unity/modules/navigation.md create mode 100644 references/engine-reference/unity/modules/networking.md create mode 100644 references/engine-reference/unity/modules/physics.md create mode 100644 references/engine-reference/unity/modules/rendering.md create mode 100644 references/engine-reference/unity/modules/ui.md create mode 100644 references/engine-reference/unity/plugins/addressables.md create mode 100644 references/engine-reference/unity/plugins/cinemachine.md create mode 100644 references/engine-reference/unity/plugins/dots-entities.md create mode 100644 references/engine-reference/unreal/PLUGINS.md create mode 100644 references/engine-reference/unreal/VERSION.md create mode 100644 references/engine-reference/unreal/breaking-changes.md create mode 100644 references/engine-reference/unreal/current-best-practices.md create mode 100644 references/engine-reference/unreal/deprecated-apis.md create mode 100644 references/engine-reference/unreal/modules/animation.md create mode 100644 references/engine-reference/unreal/modules/audio.md create mode 100644 references/engine-reference/unreal/modules/input.md create mode 100644 references/engine-reference/unreal/modules/navigation.md create mode 100644 references/engine-reference/unreal/modules/networking.md create mode 100644 references/engine-reference/unreal/modules/physics.md create mode 100644 references/engine-reference/unreal/modules/rendering.md create mode 100644 references/engine-reference/unreal/modules/ui.md create mode 100644 references/engine-reference/unreal/plugins/common-ui.md create mode 100644 references/engine-reference/unreal/plugins/gameplay-ability-system.md create mode 100644 references/engine-reference/unreal/plugins/gameplay-camera-system.md create mode 100644 references/engine-reference/unreal/plugins/pcg.md create mode 100644 references/studio-docs/templates/technical-preferences.md create mode 100644 runtime/agents/godot-csharp-specialist.toml create mode 100644 runtime/agents/godot-gdextension-specialist.toml create mode 100644 runtime/agents/godot-gdscript-specialist.toml create mode 100644 runtime/agents/godot-shader-specialist.toml create mode 100644 runtime/agents/godot-specialist.toml create mode 100644 runtime/agents/ue-blueprint-specialist.toml create mode 100644 runtime/agents/ue-gas-specialist.toml create mode 100644 runtime/agents/ue-replication-specialist.toml create mode 100644 runtime/agents/ue-umg-specialist.toml create mode 100644 runtime/agents/unity-addressables-specialist.toml create mode 100644 runtime/agents/unity-dots-specialist.toml create mode 100644 runtime/agents/unity-shader-specialist.toml create mode 100644 runtime/agents/unity-specialist.toml create mode 100644 runtime/agents/unity-ui-specialist.toml create mode 100644 runtime/agents/unreal-specialist.toml create mode 100644 skills/setup-engine/DETAILS.md create mode 100644 skills/setup-engine/SKILL.md create mode 100644 skills/setup-engine/agents/openai.yaml diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index ed26bcd..c4f9b94 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "codex-game-studios", "version": "0.2.0", - "description": "A Codex plugin for game-production workflows and guided game concept brainstorming.", + "description": "A Codex plugin for game-production workflows, concept brainstorming, and engine setup.", "author": { "name": "wxm", "email": "18854896936@163.com", @@ -15,13 +15,15 @@ "game-development", "studio-workflow", "brainstorm", + "setup-engine", + "game-engine", "gdd" ], "skills": "./skills/", "interface": { "displayName": "Codex Game Studios", "shortDescription": "Game-production workflows for Codex", - "longDescription": "Codex Game Studios exposes plugin-native skills for guided game concept ideation and structured game design documentation.", + "longDescription": "Codex Game Studios exposes plugin-native skills for guided game concept ideation, engine/version setup, technical preferences, and structured game design documentation.", "developerName": "wxm", "category": "Coding", "capabilities": [ @@ -33,7 +35,8 @@ "privacyPolicyURL": "https://gitea.wuxianming.ac.cn/wxm/codex-game-studios", "termsOfServiceURL": "https://gitea.wuxianming.ac.cn/wxm/codex-game-studios", "defaultPrompt": [ - "Use $brainstorm to shape my game concept." + "Use $brainstorm to shape my game concept.", + "Use $setup-engine to configure my game engine." ], "brandColor": "#0F766E", "composerIcon": "./assets/codex-game-studio.svg", diff --git a/README.md b/README.md index 5e1eadd..06a7912 100644 --- a/README.md +++ b/README.md @@ -9,14 +9,23 @@ skills expose the runtime workflows directly. Do not use a global - Skills: - `$brainstorm` guides game concept ideation into `design/gdd/game-concept.md`. -- Runtime agents: `creative-director`, `art-director`, `technical-director`, `producer` + - `$setup-engine` configures engine/version, technical preferences, engine reference docs, and specialist routing. +- Runtime agents: + - Director agents: `creative-director`, `art-director`, `technical-director`, `producer` + - Godot specialists: `godot-specialist`, `godot-gdscript-specialist`, `godot-csharp-specialist`, `godot-shader-specialist`, `godot-gdextension-specialist` + - Unity specialists: `unity-specialist`, `unity-dots-specialist`, `unity-shader-specialist`, `unity-addressables-specialist`, `unity-ui-specialist` + - Unreal specialists: `unreal-specialist`, `ue-blueprint-specialist`, `ue-gas-specialist`, `ue-replication-specialist`, `ue-umg-specialist` - Runtime source: `runtime/agents/` - Project guide template: `project-template/AGENTS.md` -- References: `references/studio-docs/director-gates.md`, `references/studio-docs/templates/game-concept.md`, `references/studio-docs/templates/game-pillars.md` +- References: `references/studio-docs/director-gates.md`, `references/studio-docs/templates/game-concept.md`, `references/studio-docs/templates/game-pillars.md`, `references/studio-docs/templates/technical-preferences.md`, `references/engine-reference/` - Standards: `standards/design-docs.md` - Marketplace: `.agents/plugins/marketplace.json` - No hooks, rules, MCP servers, or app integrations yet +`$setup-engine` is the next technical step after `$brainstorm`: it pins the +engine version, writes the Technology Stack section in `AGENTS.md`, creates +`docs/technical-preferences.md`, and seeds `docs/engine-reference//`. + ## Review Intensity `production/review-mode.txt` controls review-gate intensity: @@ -34,7 +43,8 @@ directly: python3 scripts/install_codex_runtime.py /path/to/game-project ``` -The installer writes custom agents and the project guide to: +The installer writes all bundled director and engine specialist agents plus the +project guide to: ```text /path/to/game-project/.codex/agents/ diff --git a/project-template/AGENTS.md b/project-template/AGENTS.md index 07060fb..7832a1b 100644 --- a/project-template/AGENTS.md +++ b/project-template/AGENTS.md @@ -12,8 +12,19 @@ game-production workflows. - **Build System**: [SPECIFY after choosing engine] - **Asset Pipeline**: [SPECIFY after choosing engine] -> Engine-specialist agents will be added later. For now, use the four bundled -> director agents only when a workflow explicitly asks for them. +Run `$setup-engine` after `$brainstorm` or whenever the project needs its engine, +version, language, and specialist routing initialized. + +## Engine Version Reference + +Pinned engine/version reference is created by `$setup-engine`: + +```text +docs/engine-reference//VERSION.md +``` + +When the file exists, read it before giving engine-specific implementation +guidance. ## Runtime Agents @@ -23,15 +34,26 @@ Bundled custom agents are installed into: .codex/agents/ ``` -Current bundled agents: +Bundled director agents: - `creative-director` - `art-director` - `technical-director` - `producer` -These agents are primarily used by director / lead review gates. They are not a -replacement for user decisions. +Bundled engine specialist agents: + +- Godot: `godot-specialist`, `godot-gdscript-specialist`, + `godot-csharp-specialist`, `godot-shader-specialist`, + `godot-gdextension-specialist` +- Unity: `unity-specialist`, `unity-dots-specialist`, + `unity-shader-specialist`, `unity-addressables-specialist`, + `unity-ui-specialist` +- Unreal: `unreal-specialist`, `ue-blueprint-specialist`, + `ue-gas-specialist`, `ue-replication-specialist`, `ue-umg-specialist` + +Director agents are used by review gates. Engine specialists are routed through +`docs/technical-preferences.md`. They are not replacements for user decisions. ## Review Intensity @@ -44,7 +66,7 @@ production/review-mode.txt Allowed values: - `full` — all gates active; every workflow step is reviewed. -- `lean` — PHASE-GATEs only (`/gate-check`); per-skill gates are skipped. +- `lean` — phase-level gates only; ordinary per-skill gates are skipped. - `solo` — no director gates anywhere. Default when the file is missing: `lean`. @@ -67,44 +89,42 @@ Question -> Options -> Decision -> Draft -> Approval ## Current Workflow Surface -The current plugin build exposes only the migrated `/brainstorm` workflow. +The current plugin build exposes these workflows: -`/brainstorm` produces: +- `$brainstorm` guides concept ideation and produces: ```text design/gdd/game-concept.md ``` -Game pillars and anti-pillars are defined during `/brainstorm` and recorded +Game pillars and anti-pillars are defined during `$brainstorm` and recorded inside `design/gdd/game-concept.md`. A separate `design/gdd/game-pillars.md` may be created later from the template if the project needs a standalone pillar source of truth. -## Design Documents - -Use these project paths: +- `$setup-engine` configures the project technology stack and produces or + updates: ```text -design/gdd/ -design/ux/ -docs/architecture/ -production/ +AGENTS.md +docs/technical-preferences.md +docs/engine-reference//VERSION.md ``` -`design/gdd/game-concept.md`, optional `design/gdd/game-pillars.md`, and -`design/gdd/systems-index.md` are top-level design documents. They are not -per-system GDDs. +## Project Documents -Per-system GDDs under `design/gdd/` should include: +Current workflows use these project paths: -1. Overview -2. Player Fantasy -3. Detailed Rules -4. Formulas -5. Edge Cases -6. Dependencies -7. Tuning Knobs -8. Acceptance Criteria +```text +design/gdd/game-concept.md +docs/technical-preferences.md +docs/engine-reference//VERSION.md +production/review-mode.txt +``` + +`docs/technical-preferences.md` records engine/language conventions, platform +targets, performance budgets, approved libraries, and engine specialist routing. +Do not assume workflows beyond the current plugin surface are available. ## Context Management diff --git a/project-template/technical-preferences.md b/project-template/technical-preferences.md new file mode 100644 index 0000000..c180b36 --- /dev/null +++ b/project-template/technical-preferences.md @@ -0,0 +1,87 @@ +# Technical Preferences + + + + +## Engine & Language + +- **Engine**: [TO BE CONFIGURED — run $setup-engine] +- **Language**: [TO BE CONFIGURED] +- **Rendering**: [TO BE CONFIGURED] +- **Physics**: [TO BE CONFIGURED] + +## Input & Platform + + + + +- **Target Platforms**: [TO BE CONFIGURED — e.g., PC, Console, Mobile, Web] +- **Input Methods**: [TO BE CONFIGURED — e.g., Keyboard/Mouse, Gamepad, Touch, Mixed] +- **Primary Input**: [TO BE CONFIGURED — the dominant input for this game] +- **Gamepad Support**: [TO BE CONFIGURED — Full / Partial / None] +- **Touch Support**: [TO BE CONFIGURED — Full / Partial / None] +- **Platform Notes**: [TO BE CONFIGURED — any platform-specific UX constraints] + +## Naming Conventions + +- **Classes**: [TO BE CONFIGURED] +- **Variables**: [TO BE CONFIGURED] +- **Signals/Events**: [TO BE CONFIGURED] +- **Files**: [TO BE CONFIGURED] +- **Scenes/Prefabs**: [TO BE CONFIGURED] +- **Constants**: [TO BE CONFIGURED] + +## Performance Budgets + +- **Target Framerate**: [TO BE CONFIGURED] +- **Frame Budget**: [TO BE CONFIGURED] +- **Draw Calls**: [TO BE CONFIGURED] +- **Memory Ceiling**: [TO BE CONFIGURED] + +## Testing + +- **Framework**: [TO BE CONFIGURED] +- **Minimum Coverage**: [TO BE CONFIGURED] +- **Required Tests**: Balance formulas, gameplay systems, networking (if applicable) + +## Forbidden Patterns + + +- [None configured yet — add as architectural decisions are made] + +## Allowed Libraries / Addons + + +- [None configured yet — add as dependencies are approved] + +## Architecture Decisions Log + + +- [No ADRs yet] + +## Engine Specialists + + + + + +- **Primary**: [TO BE CONFIGURED — run $setup-engine] +- **Language/Code Specialist**: [TO BE CONFIGURED] +- **Shader Specialist**: [TO BE CONFIGURED] +- **UI Specialist**: [TO BE CONFIGURED] +- **Additional Specialists**: [TO BE CONFIGURED] +- **Routing Notes**: [TO BE CONFIGURED] + +### File Extension Routing + + + + +| File Extension / Type | Specialist to Spawn | +|-----------------------|---------------------| +| Game code (primary language) | [TO BE CONFIGURED] | +| Shader / material files | [TO BE CONFIGURED] | +| UI / screen files | [TO BE CONFIGURED] | +| Scene / prefab / level files | [TO BE CONFIGURED] | +| Native extension / plugin files | [TO BE CONFIGURED] | +| General architecture review | Primary | diff --git a/references/engine-reference/README.md b/references/engine-reference/README.md new file mode 100644 index 0000000..c13ca5e --- /dev/null +++ b/references/engine-reference/README.md @@ -0,0 +1,63 @@ +# Engine Reference Documentation + +This directory contains curated, version-pinned documentation snapshots for the +game engine(s) used in this project. These files exist because **LLM knowledge +has a cutoff date** and game engines update frequently. + +## Why This Exists + +The model's training data has a knowledge cutoff (currently May 2025). Game engines +like Godot, Unity, and Unreal ship updates that introduce breaking API changes, +new features, and deprecated patterns. Without these reference files, agents will +suggest outdated code. + +## Structure + +Each engine gets its own directory: + +``` +/ +├── VERSION.md # Pinned version, verification date, knowledge gap window +├── breaking-changes.md # API changes between versions, organized by risk level +├── deprecated-apis.md # "Don't use X → Use Y" lookup tables +├── current-best-practices.md # New practices not in model training data +└── modules/ # Per-subsystem quick references (~150 lines max each) + ├── rendering.md + ├── physics.md + └── ... +``` + +## How Agents Use These Files + +Engine-specialist agents are instructed to: + +1. Read `VERSION.md` to confirm the current engine version +2. Check `deprecated-apis.md` before suggesting any engine API +3. Consult `breaking-changes.md` for version-specific concerns +4. Read relevant `modules/*.md` for subsystem-specific work + +## Maintenance + +### When to Update + +- After upgrading the engine version +- When the LLM model is updated (new knowledge cutoff) +- After running `/refresh-docs` (if available) +- When you discover an API the model gets wrong + +### How to Update + +1. Update `VERSION.md` with the new engine version and date +2. Add new entries to `breaking-changes.md` for the version transition +3. Move newly deprecated APIs into `deprecated-apis.md` +4. Update `current-best-practices.md` with new patterns +5. Update relevant `modules/*.md` with API changes +6. Set "Last verified" dates on all modified files + +### Quality Rules + +- Every file must have a "Last verified: YYYY-MM-DD" date +- Keep module files under 150 lines (context budget) +- Include code examples showing correct/incorrect patterns +- Link to official documentation URLs for verification +- Only document things that differ from the model's training data diff --git a/references/engine-reference/godot/VERSION.md b/references/engine-reference/godot/VERSION.md new file mode 100644 index 0000000..b008a9b --- /dev/null +++ b/references/engine-reference/godot/VERSION.md @@ -0,0 +1,31 @@ +# Godot Engine — Version Reference + +| Field | Value | +|-------|-------| +| **Engine Version** | Godot 4.6 | +| **Release Date** | January 2026 | +| **Project Pinned** | 2026-02-12 | +| **Last Docs Verified** | 2026-02-12 | +| **LLM Knowledge Cutoff** | May 2025 | + +## Knowledge Gap Warning + +The LLM's training data likely covers Godot up to ~4.3. Versions 4.4, 4.5, +and 4.6 introduced significant changes that the model does NOT know about. +Always cross-reference this directory before suggesting Godot API calls. + +## Post-Cutoff Version Timeline + +| Version | Release | Risk Level | Key Theme | +|---------|---------|------------|-----------| +| 4.4 | ~Mid 2025 | MEDIUM | Jolt physics option, FileAccess return types, shader texture type changes | +| 4.5 | ~Late 2025 | HIGH | Accessibility (AccessKit), variadic args, @abstract, shader baker, SMAA | +| 4.6 | Jan 2026 | HIGH | Jolt default, glow rework, D3D12 default on Windows, IK restored | + +## Verified Sources + +- Official docs: https://docs.godotengine.org/en/stable/ +- 4.5→4.6 migration: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.6.html +- 4.4→4.5 migration: https://docs.godotengine.org/en/stable/tutorials/migrating/upgrading_to_godot_4.5.html +- Changelog: https://github.com/godotengine/godot/blob/master/CHANGELOG.md +- Release notes: https://godotengine.org/releases/4.6/ diff --git a/references/engine-reference/godot/breaking-changes.md b/references/engine-reference/godot/breaking-changes.md new file mode 100644 index 0000000..64e4f79 --- /dev/null +++ b/references/engine-reference/godot/breaking-changes.md @@ -0,0 +1,70 @@ +# Godot — Breaking Changes + +Last verified: 2026-02-12 + +Changes between Godot versions, focused on post-LLM-cutoff changes (4.4+). + +## 4.5 → 4.6 (Jan 2026 — POST-CUTOFF, HIGH RISK) + +| Subsystem | Change | Details | +|-----------|--------|---------| +| Physics | Jolt is now the DEFAULT 3D physics engine | New projects use Jolt automatically. Existing projects keep their setting. Some HingeJoint3D properties (like `damp`) only work with GodotPhysics. | +| Rendering | Glow processes BEFORE tonemapping | Was after tonemapping. Scenes with glow will look different. Adjust intensity/blend in WorldEnvironment. | +| Rendering | D3D12 default on Windows | Was Vulkan. For better driver compatibility. | +| Rendering | AgX tonemapper new controls | White point and contrast parameters added. | +| Core | Quaternion initializes to identity | Was zero. Unlikely to affect most code but technically breaking. | +| UI | Dual-focus system | Mouse/touch focus now separate from keyboard/gamepad focus. Visual feedback differs by input method. | +| Animation | IK system fully restored | CCDIK, FABRIK, Jacobian IK, Spline IK, TwoBoneIK via SkeletonModifier3D nodes. | +| Editor | New "Modern" theme default | Grayscale replaces blue-tint. Restore: Editor Settings → Interface → Theme → Style: Classic | +| Editor | "Select Mode" keybind changed | New "Select Mode" (v key) prevents accidental transforms. Old mode renamed "Transform Mode" (q key). | +| 2D | TileMapLayer scene tile rotation | Scene tiles can now be rotated like atlas tiles. | +| Localization | CSV plural form support | No longer requires Gettext for plurals. Context columns added. | +| C# | Automatic string extraction | Translation strings auto-extracted from C# code. | +| Plugins | New EditorDock class | Specialized container for plugin docks with layout control. | + +## 4.4 → 4.5 (Late 2025 — POST-CUTOFF, HIGH RISK) + +| Subsystem | Change | Details | +|-----------|--------|---------| +| GDScript | Variadic arguments added | Functions can accept `...` arbitrary params — new language feature | +| GDScript | `@abstract` decorator | Abstract classes and methods now enforceable | +| GDScript | Script backtracing | Detailed call stacks available even in Release builds | +| Rendering | Stencil buffer support | New capability for advanced visual effects | +| Rendering | SMAA 1x antialiasing | New post-processing AA option | +| Rendering | Shader Baker | Pre-compiles shaders — reportedly 20x faster startup on some demos | +| Rendering | Bent normal maps, specular occlusion | New material features | +| Accessibility | Screen reader support | Control nodes work with accessibility tools via AccessKit | +| Editor | Live translation preview | Test GUI layouts in different languages in-editor | +| Physics | 3D interpolation rearchitected | Moved from RenderingServer to SceneTree. API unchanged but internals differ. | +| Animation | BoneConstraint3D | New: AimModifier3D, CopyTransformModifier3D, ConvertTransformModifier3D | +| Resources | `duplicate_deep()` added | New explicit method for deep duplication of nested resources | +| Navigation | Dedicated 2D navigation server | No longer a proxy to 3D navigation; smaller export for 2D games | +| UI | FoldableContainer node | New accordion-style container for collapsible UI sections | +| UI | Recursive Control behavior | Disable mouse/focus interactions across entire node hierarchies | +| Platform | visionOS export support | New platform target | +| Platform | SDL3 gamepad driver | Delegated gamepad handling to SDL library | +| Platform | Android 16KB page support | Required for Google Play targeting Android 15+ | + +## 4.3 → 4.4 (Mid 2025 — NEAR CUTOFF, VERIFY) + +| Subsystem | Change | Details | +|-----------|--------|---------| +| Core | `FileAccess.store_*` return `bool` | Was `void`. Methods: `store_8`, `store_16`, `store_32`, `store_64`, `store_buffer`, `store_csv_line`, `store_double`, `store_float`, `store_half`, `store_line`, `store_pascal_string`, `store_real`, `store_string`, `store_var` | +| Core | `OS.execute_with_pipe` | Added optional `blocking` parameter | +| Core | `RegEx.compile/create_from_string` | Added optional `show_error` parameter | +| Rendering | `RenderingDevice.draw_list_begin` | Many parameters removed; `breadcrumb` parameter added | +| Rendering | Shader texture types | Parameter/return types changed from `Texture2D` to `Texture` | +| Particles | `.restart()` method | Added optional `keep_seed` parameter (CPU/GPU 2D/3D) | +| GUI | `RichTextLabel.push_meta` | Added optional `tooltip` parameter | +| GUI | `GraphEdit.connect_node` | Added optional `keep_alive` parameter | + +## 4.2 → 4.3 (In Training Data — LOW RISK) + +| Subsystem | Change | Details | +|-----------|--------|---------| +| Animation | `Skeleton3D.add_bone` returns `int32` | Was `void` | +| Animation | `bone_pose_updated` signal | Replaced by `skeleton_updated` | +| TileMap | `TileMapLayer` replaces `TileMap` | One node per layer instead of multi-layer single node | +| Navigation | `NavigationRegion2D` | Removed `avoidance_layers`, `constrain_avoidance` properties | +| Editor | `EditorSceneFormatImporterFBX` | Renamed to `EditorSceneFormatImporterFBX2GLTF` | +| Animation | AnimationMixer base class | AnimationPlayer and AnimationTree now extend AnimationMixer | diff --git a/references/engine-reference/godot/current-best-practices.md b/references/engine-reference/godot/current-best-practices.md new file mode 100644 index 0000000..421ffa3 --- /dev/null +++ b/references/engine-reference/godot/current-best-practices.md @@ -0,0 +1,107 @@ +# Godot — Current Best Practices + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +Practices that are **new or changed** since the model's training data (~4.3). +This supplements (not replaces) the agent's built-in knowledge. + +## GDScript (4.5+) + +- **Variadic arguments**: Functions can accept arbitrary parameter counts + ```gdscript + func log_values(prefix: String, values: Variant...) -> void: + for v in values: + print(prefix, ": ", v) + ``` + +- **Abstract classes and methods**: Use `@abstract` to enforce inheritance + ```gdscript + @abstract + class_name BaseEnemy extends CharacterBody3D + + @abstract + func get_attack_pattern() -> Array[Attack]: + pass # Subclasses MUST override + ``` + +- **Script backtracing**: Detailed call stacks available even in Release builds + +## Physics (4.6) + +- **Jolt Physics is the default 3D engine** for new projects + - Better determinism and stability than GodotPhysics3D + - Some HingeJoint3D properties (`damp`) only work with GodotPhysics + - Switch: Project Settings → Physics → 3D → Physics Engine + - 2D physics unchanged (still Godot Physics 2D) + +## Rendering (4.6) + +- **D3D12 is the default backend on Windows** (was Vulkan) — for better driver compatibility +- **Glow now processes before tonemapping** with screen blending mode — existing glow setups may look different +- **SSR overhauled** — significant improvement in realism, stability, and performance +- **AgX tonemapper** — new white point and contrast controls + +## Rendering (4.5) + +- **Shader Baker**: Pre-compile shaders to eliminate startup hitching +- **SMAA 1x**: New AA option — sharper than FXAA, cheaper than TAA +- **Stencil buffer**: Available for advanced masking/portal effects +- **Bent normal maps**: Directional occlusion in normal map textures +- **Specular occlusion**: Ambient occlusion now affects reflections + +## Accessibility (4.5+) + +- **Screen reader support**: Control nodes integrate with accessibility tools via AccessKit +- **Live translation preview**: Test GUI layouts in different languages directly in-editor +- **FoldableContainer**: New accordion-style UI node for collapsible sections +- **Recursive Control disable**: Disable mouse/focus interactions for entire node hierarchies with a single property + +## Animation (4.5+) + +- **BoneConstraint3D**: Bind bones to other bones with modifiers + - AimModifier3D, CopyTransformModifier3D, ConvertTransformModifier3D + +## Animation (4.6) + +- **IK system fully restored**: Complete inverse kinematics reintroduced for 3D + - Available modifiers: CCDIK, FABRIK, Jacobian IK, Spline IK, TwoBoneIK + - Applied via `SkeletonModifier3D` nodes + +## Resources (4.5+) + +- **`duplicate_deep()`**: Explicit deep duplication for nested resource trees + - Old `duplicate()` behavior retained for backward compatibility + - Use `duplicate_deep()` when you need per-instance copies of nested resources + +## Navigation (4.5+) + +- **Dedicated 2D navigation server**: No longer proxied through 3D NavigationServer + - Reduces export binary size for 2D-only games + +## UI (4.6) + +- **Dual-focus system**: Mouse/touch focus is now separate from keyboard/gamepad focus + - Visual feedback differs depending on input method + - Consider this when designing custom focus behavior + +## Editor Workflow (4.6) + +- Flexible dock drag-and-drop with blue outline preview (including bottom panel) +- Most panels support floating windows (except Debugger) +- New keyboard shortcuts: Alt+O (Output), Alt+S (Shader) +- Export variable auto-generation: drag resource from FileSystem into script editor +- Live preview in Quick Open dialog when "Live Preview" enabled +- New "Select Mode" (v key) prevents accidental transforms; old mode renamed "Transform Mode" (q key) + +## Tooling + +- **ripgrep has no `gdscript` type**: `*.gd` is registered under `gap` (GAP programming language). + `rg --type gdscript` is a hard error — the search never executes. + Always use `rg --glob "*.gd"` (shell) or `glob: "*.gd"` (Search tool) to filter GDScript files. + +## Platform (4.5+) + +- **visionOS export**: First new platform since open-sourcing (windowed app mode) +- **SDL3 gamepad driver**: Better cross-platform gamepad support +- **Android**: Edge-to-edge display, camera feed access, 16KB page support (Android 15+) +- **Linux**: Wayland subwindow support for multi-window capability diff --git a/references/engine-reference/godot/deprecated-apis.md b/references/engine-reference/godot/deprecated-apis.md new file mode 100644 index 0000000..fbd7e4a --- /dev/null +++ b/references/engine-reference/godot/deprecated-apis.md @@ -0,0 +1,43 @@ +# Godot — Deprecated APIs + +Last verified: 2026-02-12 + +If an agent suggests any API in the "Deprecated" column, it MUST be replaced +with the "Use Instead" column. + +## Nodes & Classes + +| Deprecated | Use Instead | Since | Notes | +|------------|-------------|-------|-------| +| `TileMap` | `TileMapLayer` | 4.3 | One node per layer instead of multi-layer node | +| `VisibilityNotifier2D` | `VisibleOnScreenNotifier2D` | 4.0 | Renamed for clarity | +| `VisibilityNotifier3D` | `VisibleOnScreenNotifier3D` | 4.0 | Renamed for clarity | +| `YSort` | `Node2D.y_sort_enabled` | 4.0 | Property on Node2D, not a separate node | +| `Navigation2D` / `Navigation3D` | `NavigationServer2D` / `NavigationServer3D` | 4.0 | Server-based API | +| `EditorSceneFormatImporterFBX` | `EditorSceneFormatImporterFBX2GLTF` | 4.3 | Renamed | + +## Methods & Properties + +| Deprecated | Use Instead | Since | Notes | +|------------|-------------|-------|-------| +| `yield()` | `await signal` | 4.0 | GDScript 2.0 coroutine syntax | +| `connect("signal", obj, "method")` | `signal.connect(callable)` | 4.0 | Callable-based connections | +| `instance()` | `instantiate()` | 4.0 | Renamed | +| `PackedScene.instance()` | `PackedScene.instantiate()` | 4.0 | Renamed | +| `get_world()` | `get_world_3d()` | 4.0 | Explicit 2D/3D split | +| `OS.get_ticks_msec()` | `Time.get_ticks_msec()` | 4.0 | Time singleton preferred | +| `duplicate()` for nested resources | `duplicate_deep()` | 4.5 | Explicit deep copy control | +| `Skeleton3D` signal `bone_pose_updated` | `skeleton_updated` | 4.3 | Renamed | +| `AnimationPlayer.method_call_mode` | `AnimationMixer.callback_mode_method` | 4.3 | Moved to base class | +| `AnimationPlayer.playback_active` | `AnimationMixer.active` | 4.3 | Moved to base class | + +## Patterns (Not Just APIs) + +| Deprecated Pattern | Use Instead | Why | +|--------------------|-------------|-----| +| String-based `connect()` | Typed signal connections | Type-safe, refactor-friendly | +| `$NodePath` in `_process()` | `@onready var` cached reference | Performance: path lookup every frame | +| Untyped `Array` / `Dictionary` | `Array[Type]`, typed variables | GDScript compiler optimizations | +| `Texture2D` in shader parameters | `Texture` base type | Changed in 4.4 | +| Manual post-process viewport chains | `Compositor` + `CompositorEffect` | Structured post-processing (4.3+) | +| GodotPhysics3D for new projects | Jolt Physics 3D | Default since 4.6; better stability | diff --git a/references/engine-reference/godot/modules/animation.md b/references/engine-reference/godot/modules/animation.md new file mode 100644 index 0000000..25a4cbb --- /dev/null +++ b/references/engine-reference/godot/modules/animation.md @@ -0,0 +1,76 @@ +# Godot Animation — Quick Reference + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +## What Changed Since ~4.3 (LLM Cutoff) + +### 4.6 Changes +- **IK system fully restored**: Complete inverse kinematics for 3D skeletons + - CCDIK, FABRIK, Jacobian IK, Spline IK, TwoBoneIK + - Applied via `SkeletonModifier3D` nodes (not the old IK approach) +- **Animation editor QoL**: Solo/hide/lock/delete for Bezier node groups; draggable timeline + +### 4.5 Changes +- **BoneConstraint3D**: Bind bones to other bones with modifiers + - `AimModifier3D`, `CopyTransformModifier3D`, `ConvertTransformModifier3D` + +### 4.3 Changes (in training data) +- **AnimationMixer**: Base class for both AnimationPlayer and AnimationTree + - `method_call_mode` → `callback_mode_method` + - `playback_active` → `active` + - `bone_pose_updated` signal → `skeleton_updated` +- **`Skeleton3D.add_bone()`**: Now returns `int32` (was `void`) + +## Current API Patterns + +### AnimationPlayer (unchanged API, new base class) +```gdscript +@onready var anim_player: AnimationPlayer = %AnimationPlayer + +func play_attack() -> void: + anim_player.play(&"attack") + await anim_player.animation_finished +``` + +### IK Setup (4.6 — NEW) +```gdscript +# Add SkeletonModifier3D-based IK nodes as children of Skeleton3D +# Available types: +# - SkeletonModifier3D (base) +# - TwoBoneIK (arms, legs) +# - FABRIK (chains, tentacles) +# - CCDIK (tails, spines) +# - Jacobian IK (complex multi-joint) +# - Spline IK (along curves) + +# Configure in editor or code: +# 1. Add IK modifier node as child of Skeleton3D +# 2. Set target bone and tip bone +# 3. Add a Marker3D as the IK target +# 4. IK solver runs automatically each frame +``` + +### BoneConstraint3D (4.5 — NEW) +```gdscript +# Add as child of Skeleton3D +# Types: +# - AimModifier3D: Point bone at target +# - CopyTransformModifier3D: Mirror another bone's transform +# - ConvertTransformModifier3D: Remap transform values +``` + +### AnimationTree (base class changed in 4.3) +```gdscript +# AnimationTree now extends AnimationMixer (not Node directly) +# Use AnimationMixer properties: +@onready var anim_tree: AnimationTree = %AnimationTree + +func _ready() -> void: + anim_tree.active = true # NOT playback_active (deprecated 4.3) +``` + +## Common Mistakes +- Using `playback_active` instead of `active` (deprecated since 4.3) +- Using `bone_pose_updated` signal instead of `skeleton_updated` (renamed in 4.3) +- Using old IK approach instead of SkeletonModifier3D system (restored in 4.6) +- Not checking `is AnimationMixer` when type-checking animation nodes diff --git a/references/engine-reference/godot/modules/audio.md b/references/engine-reference/godot/modules/audio.md new file mode 100644 index 0000000..2924588 --- /dev/null +++ b/references/engine-reference/godot/modules/audio.md @@ -0,0 +1,79 @@ +# Godot Audio — Quick Reference + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +## What Changed Since ~4.3 (LLM Cutoff) + +No major breaking changes to the audio API in 4.4–4.6. The core audio system +remains stable. Key updates are workflow improvements: + +### 4.6 Changes +- **No audio-specific breaking changes** in this release + +### 4.5 Changes +- **No audio-specific breaking changes** in this release + +## Current API Patterns + +### Playing Audio +```gdscript +@onready var sfx_player: AudioStreamPlayer = %SFXPlayer +@onready var music_player: AudioStreamPlayer = %MusicPlayer + +func play_sfx(stream: AudioStream) -> void: + sfx_player.stream = stream + sfx_player.play() + +func play_music(stream: AudioStream, fade_time: float = 1.0) -> void: + var tween: Tween = create_tween() + tween.tween_property(music_player, "volume_db", -80.0, fade_time) + await tween.finished + music_player.stream = stream + music_player.volume_db = 0.0 + music_player.play() +``` + +### 3D Spatial Audio +```gdscript +@onready var audio_3d: AudioStreamPlayer3D = %AudioPlayer3D + +func _ready() -> void: + audio_3d.max_distance = 50.0 + audio_3d.attenuation_model = AudioStreamPlayer3D.ATTENUATION_INVERSE_DISTANCE + audio_3d.unit_size = 10.0 +``` + +### Audio Buses +```gdscript +# Set bus volumes +AudioServer.set_bus_volume_db(AudioServer.get_bus_index(&"Music"), volume_db) +AudioServer.set_bus_volume_db(AudioServer.get_bus_index(&"SFX"), volume_db) + +# Mute a bus +AudioServer.set_bus_mute(AudioServer.get_bus_index(&"Music"), true) +``` + +### Object Pooling for SFX +```gdscript +# Pre-create multiple AudioStreamPlayer nodes for concurrent sounds +var _sfx_pool: Array[AudioStreamPlayer] = [] + +func _ready() -> void: + for i in range(8): + var player := AudioStreamPlayer.new() + player.bus = &"SFX" + add_child(player) + _sfx_pool.append(player) + +func play_pooled(stream: AudioStream) -> void: + for player in _sfx_pool: + if not player.playing: + player.stream = stream + player.play() + return +``` + +## Common Mistakes +- Creating new AudioStreamPlayer nodes at runtime instead of pooling +- Not using audio buses for volume categories (Music, SFX, UI, Voice) +- Using `_process()` for audio timing instead of signals (`finished`) diff --git a/references/engine-reference/godot/modules/input.md b/references/engine-reference/godot/modules/input.md new file mode 100644 index 0000000..9b03a10 --- /dev/null +++ b/references/engine-reference/godot/modules/input.md @@ -0,0 +1,72 @@ +# Godot Input — Quick Reference + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +## What Changed Since ~4.3 (LLM Cutoff) + +### 4.6 Changes +- **Dual-focus system**: Mouse/touch focus is now separate from keyboard/gamepad focus + - Visual feedback differs by input method + - Custom focus implementations may need updating +- **Select Mode keybind changed**: "Select Mode" is now `v` key; old mode renamed "Transform Mode" (`q` key) + +### 4.5 Changes +- **SDL3 gamepad driver**: Gamepad handling delegated to SDL library for better cross-platform support +- **Recursive Control disable**: Single property disables mouse/focus for entire node hierarchies + +### 4.3 Changes (in training data) +- **InputEventShortcut**: Dedicated event type for menu shortcuts (optional) + +## Current API Patterns + +### Input Actions (unchanged) +```gdscript +func _physics_process(delta: float) -> void: + var input_dir: Vector2 = Input.get_vector( + &"move_left", &"move_right", &"move_forward", &"move_back" + ) + if Input.is_action_just_pressed(&"jump"): + jump() +``` + +### Input Events (unchanged) +```gdscript +func _unhandled_input(event: InputEvent) -> void: + if event is InputEventMouseButton: + if event.button_index == MOUSE_BUTTON_LEFT and event.pressed: + handle_click(event.position) + elif event is InputEventKey: + if event.keycode == KEY_ESCAPE and event.pressed: + toggle_pause() +``` + +### Focus Management (4.6 — CHANGED) +```gdscript +# Mouse/touch and keyboard/gamepad focus are now SEPARATE +# Visual styles may differ depending on which input method is active +# If you have custom focus drawing, test with both input methods + +# Standard approach still works: +func _ready() -> void: + %StartButton.grab_focus() # Keyboard/gamepad focus + +# But be aware: mouse hover focus != keyboard focus in 4.6 +``` + +### Gamepad (4.5+ — SDL3 backend) +```gdscript +# API unchanged, but SDL3 provides: +# - Better device detection across platforms +# - Improved rumble support +# - More consistent button mapping + +func _input(event: InputEvent) -> void: + if event is InputEventJoypadButton: + if event.button_index == JOY_BUTTON_A and event.pressed: + confirm_selection() +``` + +## Common Mistakes +- Not testing both mouse and keyboard focus paths (dual-focus in 4.6) +- Assuming `grab_focus()` affects mouse focus (it only affects keyboard/gamepad in 4.6) +- Using string literals instead of `StringName` (`&"action"`) for action names in hot paths diff --git a/references/engine-reference/godot/modules/navigation.md b/references/engine-reference/godot/modules/navigation.md new file mode 100644 index 0000000..4dd35d5 --- /dev/null +++ b/references/engine-reference/godot/modules/navigation.md @@ -0,0 +1,101 @@ +# Godot Navigation — Quick Reference + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +## What Changed Since ~4.3 (LLM Cutoff) + +### 4.5 Changes +- **Dedicated 2D navigation server**: No longer a proxy to 3D NavigationServer + - Reduces export binary size for 2D-only games + - API remains the same for both 2D and 3D + +### 4.3 Changes (in training data) +- **`NavigationRegion2D`**: Removed `avoidance_layers` and `constrain_avoidance` properties + +## Current API Patterns + +### NavigationAgent3D (Preferred for Most Cases) +```gdscript +@onready var nav_agent: NavigationAgent3D = %NavigationAgent3D + +func _ready() -> void: + nav_agent.path_desired_distance = 0.5 + nav_agent.target_desired_distance = 1.0 + nav_agent.velocity_computed.connect(_on_velocity_computed) + +func navigate_to(target: Vector3) -> void: + nav_agent.target_position = target + +func _physics_process(delta: float) -> void: + if nav_agent.is_navigation_finished(): + return + var next_pos: Vector3 = nav_agent.get_next_path_position() + var direction: Vector3 = global_position.direction_to(next_pos) + nav_agent.velocity = direction * move_speed + +func _on_velocity_computed(safe_velocity: Vector3) -> void: + velocity = safe_velocity + move_and_slide() +``` + +### NavigationAgent2D +```gdscript +@onready var nav_agent: NavigationAgent2D = %NavigationAgent2D + +func navigate_to(target: Vector2) -> void: + nav_agent.target_position = target + +func _physics_process(delta: float) -> void: + if nav_agent.is_navigation_finished(): + return + var next_pos: Vector2 = nav_agent.get_next_path_position() + var direction: Vector2 = global_position.direction_to(next_pos) + velocity = direction * move_speed + move_and_slide() +``` + +### Low-Level Path Query (3D) +```gdscript +# Direct server query for custom pathfinding logic +var query := NavigationPathQueryParameters3D.new() +query.map = get_world_3d().navigation_map +query.start_position = global_position +query.target_position = target_pos +query.navigation_layers = navigation_layers + +var result := NavigationPathQueryResult3D.new() +NavigationServer3D.query_path(query, result) +var path: PackedVector3Array = result.path +``` + +### Avoidance +```gdscript +# Enable RVO2-based local avoidance +nav_agent.avoidance_enabled = true +nav_agent.radius = 0.5 +nav_agent.max_speed = move_speed +nav_agent.neighbor_distance = 10.0 + +# Use velocity_computed signal for avoidance-safe movement +nav_agent.velocity_computed.connect(_on_velocity_computed) + +# Set velocity each frame (avoidance needs this) +nav_agent.velocity = desired_velocity +``` + +### Navigation Layers +```gdscript +# Use layers to separate walkable areas by agent type +# Layer 1: Ground units +# Layer 2: Flying units +# Layer 3: Swimming units +nav_agent.navigation_layers = 1 # Ground only +nav_agent.navigation_layers = 1 | 2 # Ground + Flying +``` + +## Common Mistakes +- Calling `get_next_path_position()` without checking `is_navigation_finished()` +- Not setting `velocity` on the agent when avoidance is enabled (required for RVO2) +- Using `NavigationRegion2D.avoidance_layers` (removed in 4.3) +- Forgetting to bake navigation mesh after modifying geometry +- Not setting `navigation_layers` (defaults to all layers) diff --git a/references/engine-reference/godot/modules/networking.md b/references/engine-reference/godot/modules/networking.md new file mode 100644 index 0000000..287a547 --- /dev/null +++ b/references/engine-reference/godot/modules/networking.md @@ -0,0 +1,76 @@ +# Godot Networking — Quick Reference + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +## What Changed Since ~4.3 (LLM Cutoff) + +### 4.6 Changes +- **Networking section in breaking changes**: See the official migration guide for + specifics at the 4.5→4.6 level + +### 4.5 Changes +- **No major networking API breaks** — core multiplayer API remains stable + +## Current API Patterns + +### High-Level Multiplayer +```gdscript +# Server +func host_game(port: int = 9999) -> void: + var peer := ENetMultiplayerPeer.new() + peer.create_server(port) + multiplayer.multiplayer_peer = peer + multiplayer.peer_connected.connect(_on_peer_connected) + multiplayer.peer_disconnected.connect(_on_peer_disconnected) + +# Client +func join_game(address: String, port: int = 9999) -> void: + var peer := ENetMultiplayerPeer.new() + peer.create_client(address, port) + multiplayer.multiplayer_peer = peer +``` + +### RPCs +```gdscript +# Server-authoritative pattern +@rpc("any_peer", "call_local", "reliable") +func request_action(action_data: Dictionary) -> void: + if not multiplayer.is_server(): + return + # Validate on server, then broadcast + _execute_action.rpc(action_data) + +@rpc("authority", "call_local", "reliable") +func _execute_action(action_data: Dictionary) -> void: + # All peers execute the validated action + pass +``` + +### MultiplayerSpawner and MultiplayerSynchronizer +```gdscript +# Use MultiplayerSpawner for automatic node replication +# Use MultiplayerSynchronizer for property synchronization + +# MultiplayerSynchronizer setup: +# 1. Add as child of the node to sync +# 2. Configure replication properties in editor +# 3. Set visibility filters for relevancy +``` + +### SceneMultiplayer Configuration +```gdscript +func _ready() -> void: + var scene_mp := multiplayer as SceneMultiplayer + scene_mp.auth_callback = _authenticate_peer + scene_mp.server_relay = false # Direct peer connections + +func _authenticate_peer(id: int, data: PackedByteArray) -> void: + # Custom authentication logic + pass +``` + +## Common Mistakes +- Not using `"any_peer"` for client-to-server RPCs (defaults to authority only) +- Trusting client data without server-side validation +- Using `"unreliable"` for game state changes (use for position updates only) +- Not setting multiplayer authority (`set_multiplayer_authority()`) on spawned nodes diff --git a/references/engine-reference/godot/modules/physics.md b/references/engine-reference/godot/modules/physics.md new file mode 100644 index 0000000..e790a47 --- /dev/null +++ b/references/engine-reference/godot/modules/physics.md @@ -0,0 +1,76 @@ +# Godot Physics — Quick Reference + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +## What Changed Since ~4.3 (LLM Cutoff) + +### 4.6 Changes +- **Jolt Physics is the DEFAULT 3D engine** for new projects + - Existing projects keep their current physics engine setting + - Better determinism, stability, and performance than GodotPhysics3D + - Some HingeJoint3D properties (`damp`) only work with GodotPhysics3D + - 2D physics UNCHANGED (still Godot Physics 2D) + +### 4.5 Changes +- **3D physics interpolation rearchitected**: Moved from RenderingServer to SceneTree + - User-facing API unchanged, but internal behavior may differ in edge cases + +## Physics Engine Selection (4.6) + +``` +Project Settings → Physics → 3D → Physics Engine: +- Jolt Physics (DEFAULT for new projects) +- GodotPhysics3D (legacy, still available) +``` + +### Jolt vs GodotPhysics3D + +| Feature | Jolt (default) | GodotPhysics3D | +|---------|---------------|----------------| +| Determinism | Better | Inconsistent | +| Stability | Better | Adequate | +| Performance | Better for complex scenes | Adequate | +| HingeJoint3D `damp` | NOT supported | Supported | +| Runtime warnings | Yes, for unsupported properties | No | +| Collision margins | May behave differently | Original behavior | + +## Current API Patterns + +### Basic Physics Setup (unchanged) +```gdscript +# CharacterBody3D movement — API unchanged across engines +extends CharacterBody3D + +@export var speed: float = 5.0 +@export var jump_velocity: float = 4.5 + +func _physics_process(delta: float) -> void: + if not is_on_floor(): + velocity += get_gravity() * delta + + if Input.is_action_just_pressed("jump") and is_on_floor(): + velocity.y = jump_velocity + + var input_dir: Vector2 = Input.get_vector("left", "right", "forward", "back") + var direction: Vector3 = (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized() + velocity.x = direction.x * speed + velocity.z = direction.z * speed + + move_and_slide() +``` + +### Raycasting (unchanged) +```gdscript +var space_state: PhysicsDirectSpaceState3D = get_world_3d().direct_space_state +var query := PhysicsRayQueryParameters3D.create(from, to) +query.collision_mask = collision_mask +var result: Dictionary = space_state.intersect_ray(query) +if result: + var hit_point: Vector3 = result.position + var hit_normal: Vector3 = result.normal +``` + +## Common Mistakes +- Assuming GodotPhysics3D is the default (Jolt since 4.6) +- Using HingeJoint3D `damp` property without checking physics engine (Jolt ignores it) +- Not testing collision edge cases when switching between physics engines diff --git a/references/engine-reference/godot/modules/rendering.md b/references/engine-reference/godot/modules/rendering.md new file mode 100644 index 0000000..f725535 --- /dev/null +++ b/references/engine-reference/godot/modules/rendering.md @@ -0,0 +1,59 @@ +# Godot Rendering — Quick Reference + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +## What Changed Since ~4.3 (LLM Cutoff) + +### 4.6 Changes +- **D3D12 is the default rendering backend on Windows** (was Vulkan) +- **Glow processes before tonemapping** (was after) — uses screen blending mode +- **AgX tonemapper**: new white point and contrast controls +- **SSR overhauled**: better realism, visual stability, and performance + +### 4.5 Changes +- **Shader Baker**: Pre-compiles shaders to reduce startup time +- **SMAA 1x**: New anti-aliasing option (sharper than FXAA, cheaper than TAA) +- **Stencil buffer support**: Enables selective geometry masking/portal effects +- **Bent normal maps**: Directional occlusion encoded in normal map textures +- **Specular occlusion**: Ambient occlusion now correctly affects reflections + +### 4.4 Changes +- **`RenderingDevice.draw_list_begin`**: Many parameters removed; optional `breadcrumb` added +- **Shader texture types**: Changed from `Texture2D` to `Texture` base type +- **Particles `.restart()`**: Added optional `keep_seed` parameter + +### 4.3 Changes (in training data) +- **Compositor node**: `Compositor` + `CompositorEffect` for post-processing chains + +## Current API Patterns + +### Post-Processing (4.3+) +```gdscript +# Use Compositor node — NOT manual viewport shader chains +# Add Compositor as child of WorldEnvironment or Camera3D +# Create CompositorEffect resources for each post-process step +``` + +### Anti-Aliasing Options (4.6) +``` +Project Settings → Rendering → Anti Aliasing: +- MSAA 2D/3D: Hardware MSAA (quality but expensive) +- Screen Space AA: FXAA (fast, blurry) or SMAA (sharp, moderate cost) # SMAA new in 4.5 +- TAA: Temporal (best quality, ghosting on fast motion) +``` + +### Rendering Backend Selection (4.6) +``` +Project Settings → Rendering → Renderer: +- Forward+ (default): Full featured, desktop-focused +- Mobile: Optimized for mobile/low-end, limited features +- Compatibility: OpenGL 3.3 / WebGL 2, broadest hardware support + +Windows default backend: D3D12 (was Vulkan pre-4.6) +``` + +## Common Mistakes +- Assuming Vulkan is the default backend on Windows (D3D12 since 4.6) +- Using manual viewport chains instead of Compositor for post-processing +- Using `Texture2D` in shader uniform types (use `Texture` since 4.4) +- Not using Shader Baker for projects with many shader variants diff --git a/references/engine-reference/godot/modules/ui.md b/references/engine-reference/godot/modules/ui.md new file mode 100644 index 0000000..2c23781 --- /dev/null +++ b/references/engine-reference/godot/modules/ui.md @@ -0,0 +1,82 @@ +# Godot UI — Quick Reference + +Last verified: 2026-02-12 | Engine: Godot 4.6 + +## What Changed Since ~4.3 (LLM Cutoff) + +### 4.6 Changes +- **Dual-focus system**: Mouse/touch focus is now SEPARATE from keyboard/gamepad focus + - Visual feedback differs by input method + - Custom focus implementations may need updating +- **TabContainer**: Tab properties editable directly in Inspector +- **TileMapLayer scene tile rotation**: Scene tiles can be rotated like atlas tiles + +### 4.5 Changes +- **FoldableContainer**: New accordion-style UI node for collapsible sections +- **Recursive Control behavior**: Disable mouse/focus for entire node hierarchies + with a single property +- **Screen reader support**: Control nodes work with AccessKit +- **Live translation preview**: Test different locales in-editor +- **`RichTextLabel.push_meta`**: Added optional `tooltip` parameter (from 4.4) + +### 4.4 Changes +- **`GraphEdit.connect_node`**: Added optional `keep_alive` parameter + +## Current API Patterns + +### Theme and Style (4.6) +```gdscript +# Editor uses new "Modern" theme by default +# For game UI, use custom themes as before: +var theme := Theme.new() +theme.set_color(&"font_color", &"Label", Color.WHITE) +theme.set_font_size(&"font_size", &"Label", 24) +``` + +### Focus Management (4.6 — CHANGED) +```gdscript +# Keyboard/gamepad focus (grab_focus still works) +func _ready() -> void: + %StartButton.grab_focus() + +# IMPORTANT: In 4.6, mouse hover is separate from keyboard focus +# Both can be active simultaneously on different controls +# Test your UI with BOTH mouse and keyboard/gamepad + +# Focus neighbors (unchanged) +%Button1.focus_neighbor_bottom = %Button2.get_path() +%Button1.focus_neighbor_right = %Button3.get_path() +``` + +### FoldableContainer (4.5 — NEW) +```gdscript +# Accordion-style collapsible container +# Add as parent of content you want to make collapsible +# Children show/hide when header is clicked +# Configure via editor properties or code +``` + +### Recursive Disable (4.5 — NEW) +```gdscript +# Disable all mouse/focus interactions for a hierarchy +# Useful for disabling entire menu sections +%SettingsPanel.mouse_filter = Control.MOUSE_FILTER_IGNORE +# In 4.5+, this can propagate recursively to children +``` + +### Localization-Ready UI (best practice) +```gdscript +# Use tr() for all visible strings +label.text = tr("MENU_START_GAME") + +# Use auto-wrap for labels (text length varies by language) +label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + +# Test with live translation preview in editor (4.5+) +``` + +## Common Mistakes +- Assuming `grab_focus()` affects mouse focus (keyboard/gamepad only in 4.6) +- Not testing UI with both mouse and gamepad after upgrading to 4.6 +- Hardcoding strings instead of using `tr()` for localization +- Not using `FoldableContainer` for collapsible UI (new in 4.5, cleaner than custom) diff --git a/references/engine-reference/unity/PLUGINS.md b/references/engine-reference/unity/PLUGINS.md new file mode 100644 index 0000000..d00025f --- /dev/null +++ b/references/engine-reference/unity/PLUGINS.md @@ -0,0 +1,250 @@ +# Unity 6.3 LTS — Optional Packages & Systems + +**Last verified:** 2026-02-13 + +This document indexes **optional packages and systems** available in Unity 6.3 LTS. +These are NOT part of the core engine but are commonly used for specific game types. + +--- + +## How to Use This Guide + +**✅ Detailed Documentation Available** - See `plugins/` directory for comprehensive guides +**🟡 Brief Overview Only** - Links to official docs, use official web search for details +**⚠️ Preview** - May have breaking changes in future versions +**📦 Package Required** - Install via Package Manager + +--- + +## Production-Ready Packages (Detailed Docs Available) + +### ✅ Cinemachine +- **Purpose:** Virtual camera system (dynamic cameras, cutscenes, camera blending) +- **When to use:** 3rd person games, cinematics, complex camera behavior +- **Knowledge Gap:** Cinemachine 3.0+ (Unity 6) has major API changes vs 2.x +- **Status:** Production-Ready +- **Package:** `com.unity.cinemachine` (Package Manager) +- **Detailed Docs:** [plugins/cinemachine.md](plugins/cinemachine.md) +- **Official:** https://docs.unity3d.com/Packages/com.unity.cinemachine@3.0/manual/index.html + +--- + +### ✅ Addressables +- **Purpose:** Advanced asset management (async loading, remote content, memory control) +- **When to use:** Large projects, DLC, remote content delivery +- **Knowledge Gap:** Unity 6 improvements, better performance +- **Status:** Production-Ready +- **Package:** `com.unity.addressables` (Package Manager) +- **Detailed Docs:** [plugins/addressables.md](plugins/addressables.md) +- **Official:** https://docs.unity3d.com/Packages/com.unity.addressables@2.0/manual/index.html + +--- + +### ✅ DOTS / Entities (ECS) +- **Purpose:** Data-Oriented Technology Stack (high-performance ECS for massive scale) +- **When to use:** Games with 1000s of entities, RTS, simulations +- **Knowledge Gap:** Entities 1.3+ (Unity 6) is production-ready, major rewrite from 0.x +- **Status:** Production-Ready (as of Unity 6.3 LTS) +- **Package:** `com.unity.entities` (Package Manager) +- **Detailed Docs:** [plugins/dots-entities.md](plugins/dots-entities.md) +- **Official:** https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/index.html + +--- + +## Other Production-Ready Packages (Brief Overview) + +### 🟡 Input System (Already Covered) +- **Purpose:** Modern input handling (rebindable, cross-platform) +- **Status:** Production-Ready (default in Unity 6) +- **Package:** `com.unity.inputsystem` +- **Docs:** See [modules/input.md](../modules/input.md) +- **Official:** https://docs.unity3d.com/Packages/com.unity.inputsystem@1.11/manual/index.html + +--- + +### 🟡 UI Toolkit (Already Covered) +- **Purpose:** Modern runtime UI (HTML/CSS-like, performant) +- **Status:** Production-Ready (Unity 6) +- **Package:** Built-in +- **Docs:** See [modules/ui.md](../modules/ui.md) +- **Official:** https://docs.unity3d.com/Packages/com.unity.ui@2.0/manual/index.html + +--- + +### 🟡 Visual Effect Graph (VFX Graph) +- **Purpose:** GPU-accelerated particle system (millions of particles) +- **When to use:** Large-scale VFX, fire, smoke, magic, explosions +- **Status:** Production-Ready +- **Package:** `com.unity.visualeffectgraph` (URP/HDRP only) +- **Official:** https://docs.unity3d.com/Packages/com.unity.visualeffectgraph@17.0/manual/index.html + +--- + +### 🟡 Shader Graph +- **Purpose:** Visual shader editor (node-based shader creation) +- **When to use:** Custom shaders without HLSL coding +- **Status:** Production-Ready +- **Package:** `com.unity.shadergraph` (URP/HDRP) +- **Official:** https://docs.unity3d.com/Packages/com.unity.shadergraph@17.0/manual/index.html + +--- + +### 🟡 Timeline +- **Purpose:** Cinematic sequencing (cutscenes, scripted events) +- **When to use:** Story-driven games, cinematics, scripted sequences +- **Status:** Production-Ready +- **Package:** `com.unity.timeline` (built-in) +- **Official:** https://docs.unity3d.com/Packages/com.unity.timeline@1.8/manual/index.html + +--- + +### 🟡 Animation Rigging +- **Purpose:** Runtime IK, procedural animation +- **When to use:** Foot IK, aim offsets, procedural limb placement +- **Status:** Production-Ready (Unity 6) +- **Package:** `com.unity.animation.rigging` +- **Official:** https://docs.unity3d.com/Packages/com.unity.animation.rigging@1.3/manual/index.html + +--- + +### 🟡 ProBuilder +- **Purpose:** In-editor 3D modeling (level prototyping, greyboxing) +- **When to use:** Rapid prototyping, level blockout +- **Status:** Production-Ready +- **Package:** `com.unity.probuilder` +- **Official:** https://docs.unity3d.com/Packages/com.unity.probuilder@6.0/manual/index.html + +--- + +### 🟡 Netcode for GameObjects +- **Purpose:** Official Unity multiplayer networking +- **When to use:** Multiplayer games (client-server architecture) +- **Status:** Production-Ready +- **Package:** `com.unity.netcode.gameobjects` +- **Official:** https://docs-multiplayer.unity3d.com/netcode/current/about/ + +--- + +### 🟡 Burst Compiler +- **Purpose:** LLVM-based compiler for C# Jobs (massive performance boost) +- **When to use:** Performance-critical code, DOTS, Jobs System +- **Status:** Production-Ready +- **Package:** `com.unity.burst` (auto-installed with DOTS) +- **Official:** https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/index.html + +--- + +### 🟡 Jobs System +- **Purpose:** Multi-threaded job scheduling (CPU parallelism) +- **When to use:** Performance optimization, parallel processing +- **Status:** Production-Ready +- **Package:** Built-in +- **Official:** https://docs.unity3d.com/Manual/JobSystem.html + +--- + +### 🟡 Mathematics +- **Purpose:** SIMD math library (optimized for Burst) +- **When to use:** DOTS, high-performance math +- **Status:** Production-Ready +- **Package:** `com.unity.mathematics` +- **Official:** https://docs.unity3d.com/Packages/com.unity.mathematics@1.3/manual/index.html + +--- + +### 🟡 ML-Agents (Machine Learning) +- **Purpose:** Train AI with reinforcement learning +- **When to use:** Advanced AI training, procedural behavior +- **Status:** Production-Ready +- **Package:** `com.unity.ml-agents` +- **Official:** https://github.com/Unity-Technologies/ml-agents + +--- + +### 🟡 Recorder +- **Purpose:** Capture gameplay footage, screenshots, animation clips +- **When to use:** Trailers, replays, debug recording +- **Status:** Production-Ready +- **Package:** `com.unity.recorder` +- **Official:** https://docs.unity3d.com/Packages/com.unity.recorder@5.0/manual/index.html + +--- + +## Preview/Experimental Packages (Use with Caution) + +### ⚠️ Splines +- **Purpose:** Runtime spline creation and editing +- **When to use:** Roads, paths, procedural content +- **Status:** Production-Ready (Unity 6) +- **Package:** `com.unity.splines` +- **Official:** https://docs.unity3d.com/Packages/com.unity.splines@2.6/manual/index.html + +--- + +### ⚠️ Muse (AI Assistant) +- **Purpose:** AI-powered asset creation (textures, sprites, animations) +- **Status:** Preview (Unity 6) +- **Package:** `com.unity.muse.*` +- **Official:** https://unity.com/products/muse + +--- + +### ⚠️ Sentis (Neural Network Inference) +- **Purpose:** Run neural networks in Unity (AI inference) +- **Status:** Preview +- **Package:** `com.unity.sentis` +- **Official:** https://docs.unity3d.com/Packages/com.unity.sentis@2.0/manual/index.html + +--- + +## Deprecated Packages (Avoid for New Projects) + +### ❌ UGUI (Canvas UI) +- **Deprecated:** Still supported, but UI Toolkit recommended +- **Use Instead:** UI Toolkit + +--- + +### ❌ Legacy Particle System +- **Deprecated:** Use Visual Effect Graph (VFX Graph) +- **Use Instead:** VFX Graph + +--- + +### ❌ Legacy Animation +- **Deprecated:** Use Animator (Mecanim) +- **Use Instead:** Animator Controller + +--- + +## On-Demand official web search Strategy + +For packages NOT listed above, use the following approach when users ask: + +1. **official web search** for latest documentation: `"Unity 6.3 [package name]"` +2. Verify if package is: + - Post-cutoff (beyond May 2025 training data) + - Preview vs Production-Ready + - Still supported in Unity 6.3 LTS +3. Optionally cache findings in `plugins/[package-name].md` for future reference + +--- + +## Quick Decision Guide + +**I need virtual cameras** → **Cinemachine** +**I need async asset loading / DLC** → **Addressables** +**I need 1000s of entities (RTS, sim)** → **DOTS/Entities** +**I need modern input** → **Input System** (see modules/input.md) +**I need GPU particles** → **Visual Effect Graph** +**I need visual shaders** → **Shader Graph** +**I need cinematics** → **Timeline** +**I need runtime IK** → **Animation Rigging** +**I need level prototyping** → **ProBuilder** +**I need multiplayer** → **Netcode for GameObjects** + +--- + +**Last Updated:** 2026-02-13 +**Engine Version:** Unity 6.3 LTS +**LLM Knowledge Cutoff:** May 2025 diff --git a/references/engine-reference/unity/VERSION.md b/references/engine-reference/unity/VERSION.md new file mode 100644 index 0000000..2ba702d --- /dev/null +++ b/references/engine-reference/unity/VERSION.md @@ -0,0 +1,57 @@ +# Unity Engine — Version Reference + +| Field | Value | +|-------|-------| +| **Engine Version** | Unity 6.3 LTS | +| **Release Date** | December 2025 | +| **Project Pinned** | 2026-02-13 | +| **Last Docs Verified** | 2026-02-13 | +| **LLM Knowledge Cutoff** | May 2025 | + +## Knowledge Gap Warning + +The LLM's training data likely covers Unity up to ~2022 LTS (2022.3). The entire +Unity 6 release series (formerly Unity 2023 Tech Stream) introduced significant +changes that the model does NOT know about. Always cross-reference this directory +before suggesting Unity API calls. + +## Post-Cutoff Version Timeline + +| Version | Release | Risk Level | Key Theme | +|---------|---------|------------|-----------| +| 6.0 | Oct 2024 | HIGH | Unity 6 rebrand, new rendering features, Entities 1.3, DOTS improvements | +| 6.1 | Nov 2024 | MEDIUM | Bug fixes, stability improvements | +| 6.2 | Dec 2024 | MEDIUM | Performance optimizations, new input system improvements | +| 6.3 LTS | Dec 2025 | HIGH | First LTS since 6.0, production-ready DOTS, enhanced graphics features | + +## Major Changes from 2022 LTS to Unity 6.3 LTS + +### Breaking Changes +- **Entities/DOTS**: Major API overhaul in Entities 1.0+, complete redesign of ECS patterns +- **Input System**: Legacy Input Manager deprecated, new Input System is default +- **Rendering**: URP/HDRP significant upgrades, SRP Batcher improvements +- **Addressables**: Asset management workflow changes +- **Scripting**: C# 9 support, new API patterns + +### New Features (Post-Cutoff) +- **DOTS**: Production-ready Entity Component System (Entities 1.3+) +- **Graphics**: Enhanced URP/HDRP pipelines, GPU Resident Drawer +- **Multiplayer**: Netcode for GameObjects improvements +- **UI Toolkit**: Production-ready for runtime UI (replaces UGUI for new projects) +- **Async Asset Loading**: Improved Addressables performance +- **Web**: WebGPU support + +### Deprecated Systems +- **Legacy Input Manager**: Use new Input System package +- **Legacy Particle System**: Use Visual Effect Graph +- **UGUI**: Still supported, but UI Toolkit recommended for new projects +- **Old ECS (GameObjectEntity)**: Replaced by modern DOTS/Entities + +## Verified Sources + +- Official docs: https://docs.unity3d.com/6000.0/Documentation/Manual/index.html +- Unity 6 release: https://unity.com/releases/unity-6 +- Unity 6.3 LTS announcement: https://unity.com/blog/unity-6-3-lts-is-now-available +- Migration guide: https://docs.unity3d.com/6000.0/Documentation/Manual/upgrade-guides.html +- Unity 6 support: https://unity.com/releases/unity-6/support +- C# API reference: https://docs.unity3d.com/6000.0/Documentation/ScriptReference/index.html diff --git a/references/engine-reference/unity/breaking-changes.md b/references/engine-reference/unity/breaking-changes.md new file mode 100644 index 0000000..fb4b916 --- /dev/null +++ b/references/engine-reference/unity/breaking-changes.md @@ -0,0 +1,154 @@ +# Unity 6.3 LTS — Breaking Changes + +**Last verified:** 2026-02-13 + +This document tracks breaking API changes and behavioral differences between Unity 2022 LTS +(likely in model training) and Unity 6.3 LTS (current version). Organized by risk level. + +## HIGH RISK — Will Break Existing Code + +### Entities/DOTS API Complete Overhaul +**Versions:** Entities 1.0+ (Unity 6.0+) + +```csharp +// ❌ OLD (pre-Unity 6, GameObjectEntity pattern) +public class HealthComponent : ComponentData { + public float Value; +} + +// ✅ NEW (Unity 6+, IComponentData) +public struct HealthComponent : IComponentData { + public float Value; +} + +// ❌ OLD: ComponentSystem +public class DamageSystem : ComponentSystem { } + +// ✅ NEW: ISystem (unmanaged, Burst-compatible) +public partial struct DamageSystem : ISystem { + public void OnCreate(ref SystemState state) { } + public void OnUpdate(ref SystemState state) { } +} +``` + +**Migration:** Follow Unity's ECS migration guide. Major architectural changes required. + +--- + +### Input System — Legacy Input Deprecated +**Versions:** Unity 6.0+ + +```csharp +// ❌ OLD: Input class (deprecated) +if (Input.GetKeyDown(KeyCode.Space)) { } + +// ✅ NEW: Input System package +using UnityEngine.InputSystem; +if (Keyboard.current.spaceKey.wasPressedThisFrame) { } +``` + +**Migration:** Install Input System package, replace all `Input.*` calls with new API. + +--- + +### URP/HDRP Renderer Feature API Changes +**Versions:** Unity 6.0+ + +```csharp +// ❌ OLD: ScriptableRenderPass.Execute signature +public override void Execute(ScriptableRenderContext context, ref RenderingData data) + +// ✅ NEW: Uses RenderGraph API +public override void RecordRenderGraph(RenderGraph renderGraph, ContextContainer frameData) +``` + +**Migration:** Update custom render passes to use RenderGraph API. + +--- + +## MEDIUM RISK — Behavioral Changes + +### Addressables — Asset Loading Returns +**Versions:** Unity 6.2+ + +Asset loading failures now throw exceptions by default instead of returning null. +Add proper exception handling or use `TryLoad` variants. + +```csharp +// ❌ OLD: Silent null on failure +var handle = Addressables.LoadAssetAsync("key"); +var sprite = handle.Result; // null if failed + +// ✅ NEW: Throws on failure, use try/catch or TryLoad +try { + var handle = Addressables.LoadAssetAsync("key"); + var sprite = await handle.Task; +} catch (Exception e) { + Debug.LogError($"Failed to load: {e}"); +} +``` + +--- + +### Physics — Default Solver Iterations Changed +**Versions:** Unity 6.0+ + +Default solver iterations increased for better stability. +Check `Physics.defaultSolverIterations` if you rely on old behavior. + +--- + +## LOW RISK — Deprecations (Still Functional) + +### UGUI (Legacy UI) +**Status:** Deprecated but supported +**Replacement:** UI Toolkit + +UGUI still works but UI Toolkit is recommended for new projects. + +--- + +### Legacy Particle System +**Status:** Deprecated +**Replacement:** Visual Effect Graph (VFX Graph) + +--- + +### Old Animation System +**Status:** Deprecated +**Replacement:** Animator Controller (Mecanim) + +--- + +## Platform-Specific Breaking Changes + +### WebGL +- **Unity 6.0+**: WebGPU is now the default (WebGL 2.0 fallback available) +- Update shaders for WebGPU compatibility + +### Android +- **Unity 6.0+**: Minimum API level raised to 24 (Android 7.0) + +### iOS +- **Unity 6.0+**: Minimum deployment target raised to iOS 13 + +--- + +## Migration Checklist + +When upgrading from 2022 LTS to Unity 6.3 LTS: + +- [ ] Audit all DOTS/ECS code (complete rewrite likely needed) +- [ ] Replace `Input` class with Input System package +- [ ] Update custom render passes to RenderGraph API +- [ ] Add exception handling to Addressables calls +- [ ] Test physics behavior (solver iterations changed) +- [ ] Consider migrating UGUI to UI Toolkit for new UI +- [ ] Update WebGL shaders for WebGPU +- [ ] Verify minimum platform versions (Android/iOS) + +--- + +**Sources:** +- https://docs.unity3d.com/6000.0/Documentation/Manual/upgrade-guides.html +- https://docs.unity3d.com/Packages/com.unity.entities@1.3/manual/upgrade-guide.html diff --git a/references/engine-reference/unity/current-best-practices.md b/references/engine-reference/unity/current-best-practices.md new file mode 100644 index 0000000..34fd68a --- /dev/null +++ b/references/engine-reference/unity/current-best-practices.md @@ -0,0 +1,334 @@ +# Unity 6.3 LTS — Current Best Practices + +**Last verified:** 2026-02-13 + +Modern Unity 6 patterns that may not be in the LLM's training data. +These are production-ready recommendations as of Unity 6.3 LTS. + +--- + +## Project Setup + +### Use Unity 6.3 LTS for Production +- **Tech Stream** (6.4+): Latest features, less stable +- **LTS** (6.3): Production-ready, 2-year support (until Dec 2027) + +### Choose the Right Render Pipeline +- **URP (Universal)**: Mobile, cross-platform, good performance ✅ Recommended for most games +- **HDRP (High Definition)**: High-end PC/console, photorealistic +- **Built-in**: Deprecated, avoid for new projects + +--- + +## Scripting + +### Use C# 9+ Features (Unity 6 Supports C# 9) + +```csharp +// ✅ Record types for data +public record PlayerData(string Name, int Level, float Health); + +// ✅ Init-only properties +public class Config { + public string GameMode { get; init; } +} + +// ✅ Pattern matching +var result = enemy switch { + Boss boss => boss.Enrage(), + Minion minion => minion.Flee(), + _ => null +}; +``` + +### Async/Await for Asset Loading + +```csharp +// ✅ Modern async pattern +public async Task LoadEnemyAsync(string key) { + var handle = Addressables.LoadAssetAsync(key); + return await handle.Task; +} +``` + +### Use Source Generators for Serialization (Unity 6+) + +```csharp +// ✅ Source-generated serialization (faster, less reflection) +[GenerateSerializer] +public partial struct PlayerStats : IComponentData { + public int Health; + public int Mana; +} +``` + +--- + +## DOTS/ECS (Production-Ready in Unity 6.3 LTS) + +### Use ISystem (Not ComponentSystem) + +```csharp +// ✅ Modern unmanaged ISystem (Burst-compatible) +public partial struct MovementSystem : ISystem { + public void OnCreate(ref SystemState state) { } + + public void OnUpdate(ref SystemState state) { + foreach (var (transform, speed) in + SystemAPI.Query, RefRO>()) { + transform.ValueRW.Position += speed.ValueRO.Value * SystemAPI.Time.DeltaTime; + } + } +} +``` + +### Use IJobEntity for Parallel Jobs + +```csharp +// ✅ IJobEntity (replaces IJobForEach) +[BurstCompile] +public partial struct DamageJob : IJobEntity { + public float DeltaTime; + + void Execute(ref Health health, in DamageOverTime dot) { + health.Value -= dot.DamagePerSecond * DeltaTime; + } +} + +// Schedule it +var job = new DamageJob { DeltaTime = SystemAPI.Time.DeltaTime }; +job.ScheduleParallel(); +``` + +--- + +## Input + +### Use Input System Package (Not Legacy Input) + +```csharp +// ✅ Input Actions (rebindable, cross-platform) +using UnityEngine.InputSystem; + +public class PlayerInput : MonoBehaviour { + private PlayerControls controls; + + void Awake() { + controls = new PlayerControls(); + controls.Gameplay.Jump.performed += ctx => Jump(); + } + + void OnEnable() => controls.Enable(); + void OnDisable() => controls.Disable(); +} +``` + +Create Input Actions asset in editor, generate C# class via inspector. + +--- + +## UI + +### Use UI Toolkit for Runtime UI (Production-Ready in Unity 6) + +```csharp +// ✅ UI Toolkit (replaces UGUI for new projects) +using UnityEngine.UIElements; + +public class MainMenu : MonoBehaviour { + void OnEnable() { + var root = GetComponent().rootVisualElement; + + var playButton = root.Q