# Pathrule Pattern: Unity Game Development (1.0.0) # ::pathrule:package:unity-game-development ### [RULE] Keep hot frame paths allocation-free and bounded (path: /Assets/Scripts) A small allocation or hierarchy search multiplied by every object and every frame becomes visible as garbage collection or CPU spikes. Hot paths need explicit budgets and stable ownership. - Cache required components during initialization and inject cross-object references through serialized fields or a composition boundary; do not call hierarchy-wide find APIs inside `Update`. - Avoid LINQ, string formatting, closure creation, and temporary collections in per-frame code unless profiling proves the allocation is absent or acceptable. - Run work only when state changes where possible. For periodic checks, schedule or stagger them instead of polling every object on every frame. - Profile representative device builds, not only the editor, and capture main-thread time, allocations, rendering, and job activity around the exact gameplay event. See /Assets/Tests for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Mutate physics on the physics clock (path: /Assets/Scripts) Rendering and physics advance on different clocks. Applying forces from a variable-rate update makes behavior depend on frame rate, while reading transient input only during a fixed step can miss events. - Sample player input at the render or input-system boundary, store intent, and consume that intent during the fixed physics step. - Move Rigidbody objects through physics APIs instead of writing Transform directly, which bypasses collision resolution and interpolation assumptions. - Use elapsed time appropriate to the active loop and do not multiply a physics force mode by time unless that mode's contract requires it. - Keep collision callbacks lightweight and defer expensive effects, object creation, and domain transitions to a controlled queue after the physics step. See /Assets/Scripts for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] MonoBehaviours adapt engine events to plain gameplay logic (path: /Assets/Scripts) MonoBehaviour is the bridge to Unity lifecycle and serialization, not the only place gameplay logic can live. Pure rules trapped inside callbacks require scene setup to test and accumulate hidden dependencies on active objects. - Use the component to translate engine callbacks, references, and time into explicit method calls on a gameplay object. - Keep plain gameplay objects free of scene searches and static global access so edit-mode tests can construct them with deterministic dependencies. - Own subscriptions in the same component that owns the subscriber and detach them when disabled or destroyed, matching the intended pause behavior. - Use interfaces or narrow references for services such as audio, spawning, saves, and analytics rather than a universal service locator reachable from every script. See /Assets/Tests for the rule or workflow that puts this decision into practice. --- ### [MEMORY] ScriptableObjects hold authored configuration, not live session state (path: /Assets/Scripts) ScriptableObjects are assets shared by every consumer and can retain changes unexpectedly in editor workflows. Using them as mutable global variables hides session boundaries and makes scene reloads or tests depend on prior execution. - Store designer-authored constants, curves, tables, and references in assets, then copy required values into a runtime state owner at session start. - Do not place player health, current inventory, active quest progress, or other per-session mutations directly on a shared asset. - When a runtime clone is intentional, create and destroy it through a clear owner and prevent callers from accidentally editing the source asset. - Serialize saved game data into stable domain identifiers and values; engine object references and scene instance IDs are not durable save formats. See /Assets/Scenes for the rule or workflow that puts this decision into practice. --- ### [SKILL] capture-unity-performance-regression (path: /) --- name: capture-unity-performance-regression description: Investigate a Unity performance regression on representative target hardware. --- # Capture Unity Performance Regression Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result. 1. Create a deterministic capture scene or replay that reaches the affected event with the same assets, entity counts, camera, and quality settings. 2. Capture a development build on target hardware and mark the event so CPU, GPU, allocation, rendering, physics, and asset-loading timelines align. 3. Identify the limiting frame and expand its call stacks or markers; separate steady-state cost from one-time warmup, compilation, or asset activation. 4. Change one suspected source, repeat the same capture, and compare percentile frame times and allocation rather than a single editor observation. 5. Keep the capture instructions and budget beside the system so later content growth can be measured against the same scenario. ## Exit criteria The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.