Unity

Unity + C# (Unity 6 LTS)

Idiomatic C# for the current Unity engine — 2D and 3D. Owns engine-side patterns (components, lifecycle, prefabs, scenes, data, input, async, builds). Not Godot (godot) or Unreal (unreal); stops at the netcode wire (gamedev-multiplayer).

Version contract — read first

Target: Unity 6 LTS, versioned 6000.x. Current LTS at authoring is Unity 6.3 LTS (6000.3) (supported to Dec 2027); Unity 6.0 LTS (6000.0) to Oct 2026. Unity 6 dropped the year-based names (2020/2021/2022 LTS) for the 6000.x scheme. Confirm the project version in ProjectSettings/ProjectVersion.txt before assuming an API exists.

Ban-list — never emit these; use the modern replacement:

Prefer the new Input System even for single-player prototypes. Keep Debug.Log out of hot loops and strip it from ships.

1. GameObject / Component model & Transform hierarchy

A GameObject is an empty container; behaviour comes from Components you attach (Transform, Rigidbody, MeshRenderer, and your MonoBehaviour scripts). Every GameObject has exactly one Transform (or RectTransform under a Canvas) giving position/rotation/scale.

• Get components: TryGetComponent(out var rb) (no-alloc, preferred), GetComponent<T>(), GetComponentInChildren/InParent<T>(). Cache in Awake — GetComponent in Update is a perf sink.
• Hierarchy: transform.parent, transform.SetParent(newParent, worldPositionStays: true), transform.childCount, foreach (Transform child in transform). Child world = parent × local.
• Same object model for 2D and 3D: 2D uses Rigidbody2D/Collider2D/SpriteRenderer; 3D uses Rigidbody/Collider/MeshRenderer. Never mix 2D and 3D physics components on one body.

[RequireComponent(typeof(Rigidbody))]
public sealed class Mover : MonoBehaviour
{
    Rigidbody _rb;
    void Awake() => _rb = GetComponent<Rigidbody>(); // cache once
}

2. Prefabs & prefab variants; instantiation

A Prefab is a reusable GameObject template (an asset). A Prefab Variant inherits from a base prefab and overrides selected properties/children — like subclassing for assets (e.g. Enemy base → EnemyFast variant). Edit the base and variants inherit the change unless they override that value.

• Spawn with Instantiate(prefab, position, rotation, parent); it returns the concrete type (var e = Instantiate(_enemyPrefab); with [SerializeField] Enemy _enemyPrefab;). Store the serialized reference; do not Resources.Load it.
• Destroy with Destroy(gameObject) (end of frame) or Destroy(obj, delay). Never DestroyImmediate at runtime. For frequently spawned objects (bullets, VFX) pool them (UnityEngine.Pool.ObjectPool<T>) instead of Instantiate/Destroy churn.
• Editor-only prefab authoring uses PrefabUtility (wrap in #if UNITY_EDITOR); absent in builds.

3. Scenes & scene management (additive loading)

A Scene holds a set of GameObjects. Register scenes in Build Profiles → Scene List (Unity 6; formerly Build Settings) so they can load by index or name.

using UnityEngine.SceneManagement;

// Additive: keep the current scene, layer another on top (e.g. UI, a level chunk).
var op = SceneManager.LoadSceneAsync("Level_02", LoadSceneMode.Additive);
op.completed += _ => Debug.Log("Level_02 loaded");
await op; // Unity 6: AsyncOperation is awaitable

// Unload just that scene later:
await SceneManager.UnloadSceneAsync("Level_02");

• LoadSceneMode.Single (default) unloads everything first; Additive composes scenes — the basis of streaming worlds, persistent manager scenes, and separate UI scenes.
• SceneManager.MoveGameObjectToScene moves an object between loaded scenes; DontDestroyOnLoad objects survive Single loads (use for a bootstrap/services scene). Prefer LoadSceneAsync to avoid a hitch.

4. MonoBehaviour lifecycle

Order per frame and where each concern belongs (full ordering in references/lifecycle-deep-dive.md):

Rules that bite:

• Physics goes in FixedUpdate, never Update. Reading input in FixedUpdate drops events — read input in Update, cache intent, apply forces in FixedUpdate.
• Frame-rate independence: multiply per-frame movement by Time.deltaTime (Update) — but FixedUpdate already runs at a fixed Time.fixedDeltaTime.
• Awake runs even on inactive objects; Start does not run until the object is active. Cross-object references belong in Start, not Awake.
• Every OnEnable subscription needs a matching OnDisable unsubscription or you leak and get double-fires after re-enable.

5. ScriptableObjects for data/config; serialization

A ScriptableObject is a data asset that lives outside any scene — ideal for config, tuning tables, enemy/item definitions, and event channels. One asset is shared by reference (no per-instance copy), so it saves memory and lets designers tweak values without touching code.

[CreateAssetMenu(fileName = "WeaponDef", menuName = "Game/Weapon Definition")]
public sealed class WeaponDefinition : ScriptableObject
{
    [SerializeField] float _damage = 10f;
    [SerializeField] float _fireRate = 2f;
    public float Damage => _damage;      // expose read-only
    public float FireRate => _fireRate;
}

[SerializeField] private vs public: default to [SerializeField] private + a public property/method. It shows in the Inspector and survives serialization without letting arbitrary code mutate the field — encapsulation intact. Use bare public only for genuine data bags.

Serialization rules (they trip everyone):

• Unity serializes: public or [SerializeField] fields of supported types (primitives, string, Unity types, enums, arrays/List<T> of those, and [Serializable] plain classes/structs).
• Unity does not serialize: properties (use [field: SerializeField] public float X { get; private set; }), static, readonly, const, Dictionary<,> (use two lists or a serializable wrapper), or polymorphic references — for interface/abstract fields use [SerializeReference].
• Do not hold runtime mutable state on a shared ScriptableObject expecting it to reset — it persists in the Editor between play sessions. Keep SOs for config; put mutable per-instance state on MonoBehaviours.

6. Input System (new) — with a legacy contrast

The new Input System (com.unity.inputsystem) is enabled by default in Unity 6 and is device-agnostic and event-driven. Define an Input Action Asset with Action Maps (e.g. "Player", "UI") and Actions (e.g. "Move" = Value/Vector2, "Jump" = Button). Generate a C# wrapper or use the PlayerInput component. Full setup, PlayerInput, and rebinding in references/input-system.md.

// New Input System — subscribe to the generated actions (no per-frame polling).
using UnityEngine.InputSystem;

public sealed class PlayerController : MonoBehaviour
{
    InputSystem_Actions _controls;   // generated C# class from the .inputactions asset
    Vector2 _move;

    void Awake() => _controls = new InputSystem_Actions();
    void OnEnable()
    {
        _controls.Player.Enable();
        _controls.Player.Move.performed += ctx => _move = ctx.ReadValue<Vector2>();
        _controls.Player.Move.canceled  += _  => _move = Vector2.zero;
        _controls.Player.Jump.performed += _  => Jump();
    }
    void OnDisable() => _controls.Player.Disable();
}

Legacy contrast (do not write this in new code):

// LEGACY Input Manager — string axes, per-frame polling, device-blind. Avoid.
float x = Input.GetAxis("Horizontal");
if (Input.GetButtonDown("Jump")) Jump();

The new system also polls if you prefer: _controls.Player.Move.ReadValue<Vector2>() in Update.

7. Coroutines vs async/await vs Awaitable

// Coroutine — classic, MonoBehaviour-bound, stops when the object disables/destroys.
IEnumerator SpawnWave()
{
    yield return new WaitForSeconds(1f);
    Instantiate(_enemyPrefab);
}
void Start() => StartCoroutine(SpawnWave());

// Awaitable (Unity 6) — the modern replacement. Cancels automatically on destroy.
async Awaitable SpawnWaveAsync()
{
    await Awaitable.WaitForSecondsAsync(1f, destroyCancellationToken);
    await Awaitable.NextFrameAsync(destroyCancellationToken);
    Instantiate(_enemyPrefab);
}

Rules:

• Coroutines run only while the MonoBehaviour is enabled; they die silently on disable. No return value; exceptions across yield are awkward.
• Awaitable: never await the same instance twice (pooled → undefined behavior). Pass destroyCancellationToken so it stops when the object is destroyed. Switch threads with Awaitable.BackgroundThreadAsync() / Awaitable.MainThreadAsync().
• Task: does not auto-cancel on destroy — thread a CancellationToken yourself, and never touch Unity API off the main thread (it throws). Prefer Awaitable in Unity 6 unless you need Task.

8. Addressables (intro) + the Resources anti-pattern

Addressables (com.unity.addressables) is the modern content-loading system: assets get string addresses, load asynchronously, and can ship in the build or from a remote CDN with dependency tracking and memory-managed release.

using UnityEngine.AddressableAssets;

var handle = Addressables.InstantiateAsync("Prefabs/Boss");
GameObject boss = await handle.Task;      // or handle.Completed += ...
// when done: Addressables.ReleaseInstance(boss);  // release to free memory

Resources/ is an anti-pattern for game content: everything under it is forced into the build, loaded synchronously, bloats size/startup, and can't be patched or streamed. Reserve it for tiny always-needed defaults; migrate real content to Addressables.

9. Build settings, platforms & player settings

• Build Profiles (Unity 6, File → Build Profiles) supersede the old Build Settings window: per-platform scene list, target platform, and overridable player settings.
• Scripting backend: IL2CPP (AOT — required for iOS/consoles/WebGL, faster, harder to reverse) vs Mono (JIT, Editor/desktop, faster iteration). Set per platform in Player Settings.
• Player Settings: product/company name, bundle identifier, icons, orientation, API compatibility level (.NET Standard 2.1 default), managed stripping. 2D vs 3D is a template choice, not a different build path.
• WebGL/mobile specifics and the shipping checklist: references/build-and-platforms.md + gamedev-shipping.

Guardrails / gotchas

• ==/!= null on a destroyed UnityEngine.Object works (overloaded), but ?. and cached refs treat a destroyed object as non-null. Re-check with if (obj) after possible destruction.
• Don't mix input systems: with PlayerInput, don't also Input.GetKey — in "New" mode legacy calls throw.
• One Rigidbody per body (child colliders fine); non-uniform scale breaks physics bodies.
• Coroutines/InvokeRepeating stop on SetActive(false); async Tasks keep running unless cancelled.
• No allocation (new, LINQ, boxing) in Update/FixedUpdate hot paths.

Related skills

• gamedev-multiplayer — networking/netcode (Netcode for GameObjects); this skill hands off the wire.
• gamedev-physics — deep physics tuning (joints, solver, determinism) beyond "put it in FixedUpdate".
• gamedev-shaders — Shader Graph / HLSL, URP/HDRP materials and rendering.
• gamedev-pathing — NavMesh, agents, steering, path solving.
• gamedev-shipping — store builds, signing, size budgets, platform certification.
• godot / unreal — the other engines; route Godot/GDScript and Unreal/Blueprint/C++ there.

Checklist

• Confirmed the project's Unity version (ProjectVersion.txt); no year-based-LTS assumptions.
• No banned API emitted (Input.GetAxis, UnityEngine.Networking, Resources.Load for content, FindObjectOfType, WWW, runtime OnGUI).
• GetComponent results cached in Awake; no string Find in Update.
• Physics in FixedUpdate; input read in Update; camera/tracking in LateUpdate.
• Every OnEnable subscription has a matching OnDisable unsubscription.
• [SerializeField] private + property used instead of bare public where encapsulation matters.
• New Input System used (actions/maps), not legacy polling; systems not mixed.
• Async uses Awaitable (or coroutine) with destroyCancellationToken; no double-await.
• Content via Addressables, not Resources/.
• Scenes registered in Build Profiles; async/additive loading where it avoids a hitch.