Unity Game Development

Pathrule2 Rules • 2 Memories • 1 Skill

Unity scripts run inside engine-managed frame, physics, scene, serialization, and asset lifecycles, so ordinary application patterns such as per-frame allocation, hidden singleton state, and asynchronous scene mutation create stutter or nondeterministic behavior. This pattern constrains hot-loop allocation and physics changes, records component and scene ownership, separates runtime state from serialized configuration, and supplies a repeatable performance capture workflow. It opens a game-development segment the catalog does not cover and focuses on Unity's engine lifecycle rather than generic C# or application-service architecture.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

capture-unity-performance-regression

Assets/

Scripts/

Keep hot frame paths allocation-free and bounded

Mutate physics on the physics clock

MonoBehaviours adapt engine events to plain gameplay logic

ScriptableObjects hold authored configuration, not live session state

Rules

Keep hot frame paths allocation-free and bounded/Assets/ScriptshighstrictCache component references, avoid repeated scene searches, and move variable-cost work off every Update invocation.

1	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.
2
3	- 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`.
4	- Avoid LINQ, string formatting, closure creation, and temporary collections in per-frame code unless profiling proves the allocation is absent or acceptable.
5	- Run work only when state changes where possible. For periodic checks, schedule or stagger them instead of polling every object on every frame.
6	- Profile representative device builds, not only the editor, and capture main-thread time, allocations, rendering, and job activity around the exact gameplay event.
7
8	See /Assets/Tests for the adjacent decision or procedure that completes this constraint.

Mutate physics on the physics clock/Assets/ScriptshighstrictApply Rigidbody forces and physics movement in fixed-step code while reading input and presenting visuals at render cadence.

1	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.
2
3	- Sample player input at the render or input-system boundary, store intent, and consume that intent during the fixed physics step.
4	- Move Rigidbody objects through physics APIs instead of writing Transform directly, which bypasses collision resolution and interpolation assumptions.
5	- 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.
6	- Keep collision callbacks lightweight and defer expensive effects, object creation, and domain transitions to a controlled queue after the physics step.
7
8	See /Assets/Scripts for the adjacent decision or procedure that completes this constraint.

Memories

MonoBehaviours adapt engine events to plain gameplay logic/Assets/ScriptsKeep engine callbacks thin and move testable rules into plain C# objects with explicit inputs and ownership.

1	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.
2
3	- Use the component to translate engine callbacks, references, and time into explicit method calls on a gameplay object.
4	- Keep plain gameplay objects free of scene searches and static global access so edit-mode tests can construct them with deterministic dependencies.
5	- Own subscriptions in the same component that owns the subscriber and detach them when disabled or destroyed, matching the intended pause behavior.
6	- Use interfaces or narrow references for services such as audio, spawning, saves, and analytics rather than a universal service locator reachable from every script.
7
8	See /Assets/Tests for the rule or workflow that puts this decision into practice.

ScriptableObjects hold authored configuration, not live session state/Assets/ScriptsTreat shared assets as immutable configuration and create runtime state instances with explicit reset and save behavior.

1	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.
2
3	- Store designer-authored constants, curves, tables, and references in assets, then copy required values into a runtime state owner at session start.
4	- Do not place player health, current inventory, active quest progress, or other per-session mutations directly on a shared asset.
5	- When a runtime clone is intentional, create and destroy it through a clear owner and prevent callers from accidentally editing the source asset.
6	- Serialize saved game data into stable domain identifiers and values; engine object references and scene instance IDs are not durable save formats.
7
8	See /Assets/Scenes for the rule or workflow that puts this decision into practice.

Skills

capture-unity-performance-regression/rootProfile a reproducible gameplay segment and compare frame time, allocation, rendering, physics, and loading evidence.

1	---
2	name: capture-unity-performance-regression
3	description: Investigate a Unity performance regression on representative target hardware.
4	---
5
6	# Capture Unity Performance Regression
7
8	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.
9
10	1. Create a deterministic capture scene or replay that reaches the affected event with the same assets, entity counts, camera, and quality settings.
11	2. Capture a development build on target hardware and mark the event so CPU, GPU, allocation, rendering, physics, and asset-loading timelines align.
12	3. Identify the limiting frame and expand its call stacks or markers; separate steady-state cost from one-time warmup, compilation, or asset activation.
13	4. Change one suspected source, repeat the same capture, and compare percentile frame times and allocation rather than a single editor observation.
14	5. Keep the capture instructions and budget beside the system so later content growth can be measured against the same scenario.
15
16	## Exit criteria
17
18	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.

Why this pattern

AI agents often allocate or search in Update, move physics bodies on the render clock, keep mutable state in ScriptableObjects, or let scene changes destroy an in-flight asynchronous operation.

Built for Unity teams shipping gameplay systems across desktop, mobile, console, or immersive targets.

Keeps your assistant from:

Creating garbage and frame spikes in per-frame code
Applying physics mutations at render-dependent timing
Leaking mutable play-session state through shared assets
Saving engine object references that cannot be restored

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25