gamedev-skills/awesome-gamedev-agent-skills / skills/unity/unity-csharp-scripting
unity-csharp-scripting
FlaggedWrites and fixes Unity 6.3 LTS C# gameplay scripts: MonoBehaviour lifecycle, serialization, .meta/GUID discipline and command-line tests. Use for new or renamed .cs files, "Missing script" or a field missing from the Inspector. Not for physics (`unity-physics`), input (`unity-input-system`), data assets (`unity-scriptableobjects`) or builds (`unity-build-pipeline`).
Unity C# Scripting (MonoBehaviour)
Write correct gameplay scripts for Unity 6.3 LTS (6000.3), C# 9 on .NET Standard 2.1, keep the
project's .meta files intact, and prove the result compiles and behaves without opening the
Editor by hand.
When to use
- Authoring or fixing a
MonoBehaviour: lifecycle callbacks, component references, serialized fields, coroutines,asyncwithAwaitable. - Creating, moving, renaming or deleting scripts and assets from the file system.
- Compiling or testing a Unity project from a terminal or CI, for any Unity skill.
- The project has
Assets/,ProjectSettings/and*.csfiles.
When not to use: rigidbodies and collision response → unity-physics; reading player
input → unity-input-system; shared data assets and config → unity-scriptableobjects;
Animator parameters → unity-animation; building players → unity-build-pipeline.
Workflow
- Read the project's versions first.
ProjectSettings/ProjectVersion.txtgives the Editor version;Packages/manifest.jsonthe packages; any*.asmdeffiles tell you which assembly a new script lands in. Keep the project's version unless asked to upgrade. - Pick the callback by purpose.
Awakecaches references to its own components;OnEnable/OnDisablesubscribe and unsubscribe;Startwires things that depend on other objects'Awake;FixedUpdateis physics;LateUpdatefollows movement (cameras). - Expose tunables with
[SerializeField] privateso designers can edit them and other code cannot. A plain class needs[System.Serializable]to show up. - Move every file with its
.meta. A.metaholds the asset's GUID; a new.metameans a new GUID and every reference to the old one shows "Missing script". A brand-new file needs no.meta: Unity writes one on the next import. Keep eachMonoBehaviourorScriptableObjectclass in a file of the same name. - Run the checker:
python scripts/check_unity_project.py <project-dir>(--jsonfor machine-readable output). Fix everyERROR(duplicate or malformed GUIDs, files moved without their.meta, missing script references) and re-run until it exits 0. Run it from this skill's directory or resolve the installed path first; it needs Python 3.10+ only, reads text-serialized assets and never writes.--helplists the checks and exit codes. - Compile. With the Unity CLI and a ready Editor,
unity recompile --project-path <project>; otherwise a batch-mode import andgrep -E "error CS[0-9]{4}"on its log. - Prove the behavior with an EditMode or PlayMode test, or by reading the value back from
the running Editor with
unity command script eval. Readreferences/agent-checks.mdfor the exact commands, the test.asmdefand how to read the results. Report which checks ran and which could not.
Patterns
1. Serialized fields that survive refactors
using UnityEngine;
using UnityEngine.Serialization;
public class Turret : MonoBehaviour
{
[SerializeField, Range(0.1f, 5f)] private float fireInterval = 0.5f;
// Renamed from "range": without this attribute every scene and prefab loses the value.
[FormerlySerializedAs("range")]
[SerializeField] private float maxRange = 12f;
[System.Serializable]
public class Stats { public int hp = 100; public int armor = 0; }
[SerializeField] private Stats stats = new();
}
2. A coroutine you can stop exactly
private Coroutine _spawnLoop;
private void OnEnable() => _spawnLoop = StartCoroutine(SpawnLoop());
private void OnDisable() { if (_spawnLoop != null) StopCoroutine(_spawnLoop); }
private System.Collections.IEnumerator SpawnLoop()
{
var wait = new WaitForSeconds(1f); // allocate once, reuse
while (true) { Spawn(); yield return wait; }
}
private void Spawn() { }
For async/await with Awaitable, the full execution order and custom yield
instructions, read references/lifecycle-and-coroutines.md.
Gotchas
?.and??on a destroyed object. Unity overrides==so a destroyed object equalsnull, but?.,??andis nullskip that override and see a live reference. Useif (target)ortarget == nullfor anything derived fromUnityEngine.Object.- Renaming a serialized field wipes its saved values. Add
[FormerlySerializedAs("old")](namespaceUnityEngine.Serialization) when you rename. - "Missing script" after a refactor. The
.metastayed behind, was regenerated, or the class name no longer matches the file name. The checker reports all three. - Physics in
Update. Forces orMovePositionoutsideFixedUpdatejitter and depend on frame rate. Read input inUpdate, apply it inFixedUpdate. - Order between objects. All
Awakecalls finish before anyStart, but the order amongAwakes (and amongStarts) is undefined unless Script Execution Order is set. Do cross-object wiring inStart. - Coroutines stop when the GameObject is deactivated.
SetActive(false)kills them; setting only the component'senabled = falsedoes not. Restart inOnEnableif needed. - An
asyncmethod keeps running after its object is destroyed. PassdestroyCancellationTokentoAwaitablewaits (they then throwOperationCanceledException), and await eachAwaitableinstance only once: they are pooled. - Obsolete warnings on
FindObjectOfType/FindObjectsOfType. UseFindAnyObjectByTypeorFindObjectsByType(FindObjectsSortMode.None)on 6.3. From 6.4,FindFirstObjectByTypeand theFindObjectsSortModeoverload are obsolete too: useFindAnyObjectByTypeandFindObjectsByType<T>(). All of them scan the scene; cache the result. - Repeated
GetComponentin hot paths. Cache stable references inAwake, and profile before treating an occasional lookup as the bottleneck. - The first
Updatecan run in the same frame asStart. Guard fields that other objects set later.
References
- Read
references/agent-checks.mdbefore compiling or testing a project from the command line: Unity CLI commands, batch-mode commands, test assembly files, log locations and how to read NUnit results. - Read
references/lifecycle-and-coroutines.mdwhen ordering matters across callbacks, or for coroutine yield instructions,CustomYieldInstructionand theAwaitableequivalents of coroutine waits. scripts/check_unity_project.py: run it (step 5); treat it as a black box and use--helpinstead of reading the source.
Related skills
unity-physics:Rigidbody, collisions andFixedUpdatemotion.unity-input-system: reading player input into these scripts.unity-scriptableobjects: sharing data between scripts without singletons.
Version notes
Last verified: 2026-11-11, against Unity 6000.3.28f1.
FindObjectsOfTypeis obsolete in 6.3;FindFirstObjectByTypeandFindObjectsByType(FindObjectsSortMode)become obsolete in 6.4. Source: Unity C# reference source,Runtime/Export/Scripting/UnityEngineObject.bindings.csat tags 6000.3.28f1 and 6000.4.12f1 (https://github.com/Unity-Technologies/UnityCsReference).?./??caveat: Scripting APIObjectpage (https://docs.unity.com/en-us/engine/6000.3/script-reference/unityengine/object).- Event order: https://docs.unity.com/en-us/engine/6000.3/manual/scripting/managing-update-order/execution-order
- Unity CLI 1.0.0-beta.17 and
com.unity.pipeline1.0.0-pre.1 are pre-release. Exit codes: https://docs.unity.com/en-us/unity-cli/reference/output-formats. Commands: https://docs.unity3d.com/Packages/com.unity.pipeline@1.0/manual/index.html - Test runner command line (
-runTestsdoes not support-quit): https://docs.unity.com/en-us/engine/6000.3/manual/programming-environment/test-framework-introduction/reference-command-line
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| webapp-testinganthropics/skillsToolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| browser-testing-with-devtoolsaddyosmani/agent-skillsTests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| ci-cd-and-automationaddyosmani/agent-skillsAutomates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |