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