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.