# Unity — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Knowledge Base Index" type: index updated: 2026-07-17 unity_version: "6.0" --- # Knowledge Base Index Master catalog of all wiki pages. Every page in the wiki must have an entry here. ## Concepts | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [[concepts/animation]] | animation, foundational | high | 2026-07-17 | | [[concepts/coroutines]] | scripting, coroutines, foundational, intermediate | high | 2026-07-17 | | [[concepts/editor-and-projects]] | editor, foundational, beginner | high | 2026-07-17 | | [[concepts/event-lifecycle]] | scripting, gameobjects, foundational, intermediate | high | 2026-07-17 | | [[concepts/gameobjects-components-prefabs]] | gameobjects, editor, foundational, beginner | high | 2026-07-17 | | [[concepts/input-system]] | input, packages, foundational, intermediate | high | 2026-07-17 | | [[concepts/overview]] | editor, scripting, gameobjects, foundational, beginner | high | 2026-07-17 | | [[concepts/packages]] | packages, editor, foundational, beginner | high | 2026-07-17 | | [[concepts/performance-best-practices]] | performance, scripting, editor, intermediate | medium | 2026-07-17 | | [[concepts/physics]] | physics, foundational, intermediate | high | 2026-07-17 | | [[concepts/rendering-pipelines]] | rendering, editor, foundational | high | 2026-07-17 | | [[concepts/scriptableobjects]] | scripting, gameobjects, foundational, intermediate | high | 2026-07-17 | | [[concepts/scripting-model]] | scripting, gameobjects, foundational, beginner | high | 2026-07-17 | | [[concepts/ui-toolkit]] | ui, editor, foundational | high | 2026-07-17 | ## Entities | Page | Tags | Updated | |------|------|---------| | [[entities/unity-ecosystem]] | packages, scripting, ui, animation, foundational | 2026-07-17 | ## Summaries _This KB uses concept/entity/synthesis pages directly from the Unity 6 Manual; no per-source summary tier._ ## Syntheses | Page | Pages Compared | Created | |------|----------------|---------| | [[syntheses/common-gotchas]] | scripting, physics, gameobjects, performance, beginner, intermediate | 2026-07-17 | | [[syntheses/render-pipeline-picker]] | rendering, foundational | 2026-07-17 | ## XL Edition (Pro) Per-item reference depth beyond this edition, in the gated XL layer (14 pages): the Scripting API class surface (MonoBehaviour, Transform/GameObject, math types, physics/camera classes, Time/coroutines — 5 pages), the full Input System (Actions & assets, PlayerInput, Devices/Interactions — 3), physics component references (colliders, joints & collision — 2), the Animator system (Animator, state machines, clips — 3), and HDRP (1). Agents without Pro access should treat those areas as "covered in the XL edition" rather than out of scope. ## Statistics - **Total pages**: 17 - **Concepts**: 14 - **Entities**: 1 - **Summaries**: 0 - **Syntheses**: 2 - **Sources ingested**: 0 - **High confidence**: 15 - **Medium confidence**: 1 - **Low confidence**: 1 --- title: "Animation System" type: concept tags: [animation, foundational] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-animation.md"] unity_version: "6.0" confidence: high --- ## Definition Unity's **animation system** provides tools and processes to animate the properties of models and assets — for example, animating Transform properties to move and rotate a model, or animating a Light's intensity to make it dim. Unity 6 ships two animation systems with different capabilities: **Mecanim** (the modern, recommended system) and the **Legacy animation system** (retained for backward compatibility with old projects). ## How It Works Common building blocks across Unity's animation tooling: - **Importers** bring in animation and model data from external DCC tools. - **Editors** create and modify animation clips. - **State machines** determine, in real time, which animation plays and when — a state machine holds a set of states (e.g., idling, walking, running, jumping) plus transitions between them and a variable tracking the current state. **Mecanim** (the recommended animation system for most situations) is built around: - The **Animator component** — attached to a model, it references an **Animator Controller** asset that drives the animation. - The **Animation window** — for authoring/editing animation clips. - The **Animator window** — for visualizing and editing the Animator Controller's state machine and transitions. Mecanim provides better performance for complex character animation involving many **animation curves** (extra per-clip data tracks, e.g., driving a particle system's emission rate in sync with a character's animation) and **blending** between clips. It also includes specialized support for humanoid models — defining a humanoid rig lets you **retarget** animations between different models that share the same humanoid definition. **Legacy animation system** predates Mecanim and has a more limited feature set. It uses the **Animation component** (distinct from the Animator component) and requires the **Legacy** import option in the Rig tab of a model's Import Settings. It's simpler for basic animation needs but is primarily kept around for old-project compatibility rather than recommended for new work. ## Key Parameters - Which system is in use: **Animator + Animator Controller** (Mecanim) vs. **Animation component** (Legacy) — determined largely by the Rig import setting on the model. - **State machine** structure: states, transitions, and the parameters that drive transition conditions. - **Humanoid vs. generic** rig definition, which determines whether animation retargeting between models is possible. - **Animation curves**, used to synchronize auxiliary effects (particles, lights, audio cues) to a clip's timeline. ## When To Use - Use **Mecanim** for essentially all new character and complex-object animation work — it's Unity's recommended system and is required for humanoid retargeting and rich state-machine-driven blending. - Use the **Legacy** system only when maintaining an old project that already depends on it, or for very simple one-off animations where the overhead of setting up an Animator Controller isn't justified. - Consult the Animator's state machine (via the Animator window) whenever debugging "why did the wrong animation play" — the answer usually lives in a transition condition or parameter, not the clip itself. ## Risks & Pitfalls - Mixing Legacy and Mecanim workflows on the same model, or misconfiguring the Rig import tab, leads to animations silently failing to play or components not appearing where expected. - Retargeting only works cleanly between models that share the same humanoid rig definition — non-humanoid or mismatched rigs will not retarget correctly. - State-machine complexity can grow quickly; unclear transition conditions are a common source of "stuck" or unexpectedly-interrupted animations. - Animation-related MonoBehaviour callbacks (`OnAnimatorMove`, `OnAnimatorIK`) and StateMachineBehaviour callbacks (`OnStateEnter`, `OnStateExit`, etc.) execute at specific points in Unity's per-frame update order — see [[concepts/event-lifecycle]] for exactly where they fall relative to `Update`/`LateUpdate`/rendering. ## Related Concepts - [[concepts/event-lifecycle]] — where animation update callbacks fit into the frame execution order. - [[concepts/gameobjects-components-prefabs]] — the Animator/Animation component attaches to a GameObject. - [[concepts/scripting-model]] — StateMachineBehaviour and Animator scripting hooks. ## Sources - raw/web_community-unity-manual-animation.md --- title: "Coroutines" type: concept tags: [scripting, coroutines, foundational, intermediate] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-write-and-run-coroutines.md"] confidence: high unity_version: "6.0" --- ## Definition A coroutine is a method that can suspend its execution and resume later, letting Unity spread work across multiple frames instead of forcing it to complete within a single frame update. A coroutine is written as a method with an `IEnumerator` return type that contains at least one `yield return` statement — the point at which execution pauses. Coroutines are a core part of the [[concepts/scripting-model]] and interact closely with the [[concepts/event-lifecycle]]. ## How It Works A regular method runs to completion within one frame. A coroutine method, by contrast, returns `IEnumerator` and uses `yield return` to hand control back to Unity, which resumes the method at a later point determined by the yield instruction. You start a coroutine with `StartCoroutine(MethodName())`, typically called from inside an event function such as `Update`. The classic example is a fade effect: instead of looping through alpha values in a single frame (which produces no visible transition), the loop is rewritten as an `IEnumerator Fade()` method that does one iteration, then executes `yield return null`, then resumes on the next frame to do the next iteration. Variables and loop counters are preserved across `yield` statements for the lifetime of the coroutine. What a coroutine yields controls its timing relative to the update loop: - `yield return null` — resumes on the very next frame. This does not allocate. - `yield return new WaitForSeconds(.1f)` — resumes after a fixed real-time delay (here, 0.1 seconds), useful when you want the effect to run at a rate decoupled from the frame rate. - `yield return Awaitable.WaitForSecondsAsync(.1f)` — an alternative to `WaitForSeconds` that integrates with Unity's `Awaitable`/`async`/`await` support. - Other custom yield instructions (`WaitUntil`, `WaitWhile`, etc.) resume when a condition is met or at specific points in the Player loop. Important: coroutines are **not threads**. Synchronous code inside a coroutine still runs on the Unity main thread, so blocking operations inside a coroutine still block the main thread just as they would in any other script code. For true multi-threaded work, the Manual points to the job system or .NET `async`/`await` with `Awaitable`. To stop a coroutine, call `StopCoroutine` or `StopAllCoroutines`. A coroutine also stops automatically if `GameObject.activeSelf` becomes `false` for the GameObject it's attached to, or if the MonoBehaviour is destroyed via `Destroy`. Note: setting the MonoBehaviour's `enabled` to `false` does **not** stop its coroutines. Coroutines can also run in Edit mode if the script uses `[ExecuteInEditMode]` or `[ExecuteAlways]`, though the Edit-mode update loop is less fixed and regular than the Player loop; for coroutines designed specifically for Edit mode, Unity recommends the Editor coroutines package. Unity Test Framework Play mode tests marked `[UnityTest]` also run as coroutines. ## Key Parameters - **`IEnumerator`** — the required return type for any coroutine method. - **`yield return`** — the suspension statement; its argument determines resume timing (`null`, `WaitForSeconds`, `WaitForFixedUpdate`, `WaitUntil`, `WaitWhile`, an `Awaitable`, etc.). - **`StartCoroutine` / `StopCoroutine` / `StopAllCoroutines`** — the `MonoBehaviour` methods that control a coroutine's lifecycle. - **`WaitForSeconds`** — a real-time delay yield instruction; each `new WaitForSeconds(...)` allocates, so cache and reuse instances with fixed durations rather than constructing new ones repeatedly. ## When To Use Use coroutines for effects or operations that need to unfold over multiple frames or over time rather than instantly: gradual visual transitions (fades, movement tweens), staged sequences, polling loops that wait for a condition, and long-running asynchronous operations such as waiting on HTTP transfers, asset loads, or file I/O. ## Risks & Pitfalls - Confusing coroutines with real concurrency — they run on the main thread, so a blocking call inside one still stalls the frame. - Starting coroutines frequently (for example, once per frame) allocates a new `IEnumerator` state machine each time and adds GC overhead; prefer a long-lived coroutine that loops with `yield return null` instead of repeatedly starting new short ones. - Constructing `new WaitForSeconds(...)` repeatedly allocates; cache commonly reused instances instead. - Using lambdas inside `WaitUntil`/`WaitWhile` can cause delegate and closure-capture allocations — avoid where possible. - Disabling a script (`enabled = false`) does not stop its coroutines — only `StopCoroutine`/`StopAllCoroutines`, disabling the GameObject, or destroying the script does. - Coroutines retain references to their owner and any captured variables, which can cause objects to be kept alive longer than expected if the coroutine is never stopped — always ensure coroutines terminate or are explicitly stopped. - `yield return` on a generic `Awaitable` from a coroutine is not supported. ## Related Concepts - [[concepts/scripting-model]] - [[concepts/event-lifecycle]] - [[concepts/performance-best-practices]] - [[concepts/scriptableobjects]] ## Sources - raw/web_community-unity-manual-write-and-run-coroutines.md --- title: "Editor and Projects" type: concept tags: [editor, foundational, beginner] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-introduction-to-scenes.md"] confidence: high unity_version: "6.0" --- ## Definition The Unity Editor is the authoring application used to build Unity projects; a **project** is organized around **Scenes**, which are assets that contain all or part of a game or application — the unit of content you work in and load at runtime. This page covers the scene/project model and the editor workflow for creating and managing scenes. ## How It Works Scenes are where you work with content in Unity. A simple game might be built in a single scene, while a more complex game typically uses one scene per level, each with its own environments, characters, obstacles, decorations, and UI. A project can contain any number of scenes. When you create a new project and open it for the first time, Unity opens a default sample scene containing only a Camera and a Light. New scenes are created from **scene templates** — assets stored in the project that are designed to be copied rather than used directly. You open the **New Scene dialog** via `File > New Scene` or the `Ctrl/Cmd + N` shortcut. The dialog lets you search available templates by name, browse a list of all templates in the project, view template details, and use a command bar to create a scene from the selected template. Templates can be **pinned** so they appear at the top of the template list — either by clicking the pin icon in the New Scene dialog, or by enabling the **Pin in New Scene Dialog** option in the scene template's Inspector. Selecting a template in the New Scene dialog shows the path to that template in the details pane; from there you can use the **Locate** link to highlight it in the Project window, or the **Edit** link to open it in an Inspector window for editing its properties. Unity also supports **multi-scene editing** — opening multiple scenes for editing at the same time, which is useful for working on shared/persistent content (e.g., a UI or lighting scene) alongside a level scene. ## Key Parameters - **Scene** — an asset containing all or part of a game; the unit you load, save, and build from. - **Scene template** — an asset that acts as a starting point/blueprint for new scenes, copied rather than referenced directly. - **New Scene dialog** — accessed via `File > New Scene` or `Ctrl/Cmd + N`; has a search field, template list, template details pane, and command bar. - **Project window** — the window showing the contents of your `Assets` folder, used to locate templates and other assets. - **Multi-scene editing** — the ability to have more than one scene open in the Editor simultaneously. ## When To Use Split a project into multiple scenes when building anything beyond a trivial single-screen prototype — for example, one scene per level, plus persistent scenes (menus, a bootstrap/loader scene, or shared UI) loaded additively. Use scene templates when you want new scenes to start from a consistent baseline (e.g., a level template pre-populated with lighting and camera setup) rather than building every scene from scratch. Use multi-scene editing when a team needs to work on different parts of the same overall level in parallel, or when you want to compose a level from separately authored pieces (environment scene + gameplay scene + lighting scene). ## Risks & Pitfalls - Putting an entire game in one scene makes it harder to reason about, slower to iterate on, and harder for multiple people to work on simultaneously without merge conflicts. - Forgetting that scene templates are copied, not referenced — editing a template after scenes have already been created from it does not retroactively update those scenes. - Not realizing the default sample scene (Camera + Light only) is just a starting point with no gameplay content of its own — it's meant to be built on or replaced. - Losing track of which scenes are open during multi-scene editing and unintentionally saving or modifying a scene you didn't mean to touch. ## Related Concepts - [[concepts/overview]] — where scenes fit in the overall Unity mental model - [[concepts/gameobjects-components-prefabs]] — what a scene is actually made of - [[concepts/packages]] — packages can add project-level tooling and templates ## Sources - raw/web_community-unity-manual-introduction-to-scenes.md --- title: "MonoBehaviour Event Functions and Execution Order" type: concept tags: [scripting, gameobjects, foundational, intermediate] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-event-functions.md", "raw/web_community-unity-manual-event-function-execution-order.md"] confidence: high unity_version: "6.0" --- ## Definition **Event functions** are predefined callback methods that any `MonoBehaviour`-derived script component can implement, and which Unity's Editor and Engine invoke in response to events such as frame/physics updates, scene and object lifecycle changes, UI events, input events, and physics events. The **execution order** is the defined sequence in which these callbacks fire relative to each other and to the rest of the engine's Player loop. ## How It Works To react to a source event, you implement the corresponding method signature in your `MonoBehaviour`-derived class; the full list is documented under **Messages** in the `MonoBehaviour` API reference. Key groups: **Regular update events.** A running game continuously renders frames, and `Update()` is the main place to change position, state, and behavior just before each frame renders (`Update` is called before rendering and before animation calculation). The physics system updates on its own discrete time steps, and `FixedUpdate()` is called just before each physics update — physics code should live in `FixedUpdate`, not `Update`, since physics and frame updates don't run at the same frequency. `LateUpdate()` runs after `Update`/`FixedUpdate` have been called for all objects and after animations have been calculated — useful for logic that must react to where objects ended up this frame, such as a camera that must track a target only after the target has moved, or code that overrides an animation's effect (e.g., making a character's head look at a target). **Initialization events.** `Awake()` is called on every object in the scene at scene-load time; `Start()` is called before the first frame or physics update on that object. Although `Awake` and `Start` calls across different objects happen in an arbitrary relative order, Unity guarantees that **all** `Awake` calls finish before **any** `Start` call happens — so `Start` can safely rely on initialization performed during `Awake` on other objects. **GUI events.** `OnGUI()` is called periodically to draw and manage UI for the legacy IMGUI system; even an empty `OnGUI` adds IMGUI processing overhead to every frame, so only implement it if the project actually uses IMGUI (no longer recommended). **Input events.** The `OnMouse*` family (e.g. `OnMouseOver`, `OnMouseDown`) reacts to mouse input but only under the legacy Input Manager (no longer recommended) — see [[concepts/input-system]] for the modern approach. **Physics events.** `OnCollisionEnter`, `OnCollisionStay`, `OnCollisionExit` fire as solid-collider contact is made, held, and broken; the trigger-collider equivalents are `OnTriggerEnter`, `OnTriggerStay`, `OnTriggerExit`. See [[concepts/physics]]. **Full execution order.** The Manual's execution-order diagram traces the lifecycle sequence at a high level; the complete Player loop (all engine subsystems, in their default order) can be retrieved and customized via the `PlayerLoop` API. Some additional documented ordering facts: - `SceneManager.sceneLoaded` fires after `OnEnable` but before `Start` for all objects in a newly loaded scene; `SceneManager.sceneUnloaded` is the corresponding unload event. - Code can run on Editor launch without user action via the `[InitializeOnLoad]` attribute on a class with a static constructor, or `[InitializeOnLoadMethod]` on individual methods. - Code can run on runtime initialization via `[RuntimeInitializeOnLoadMethodAttribute]`, with an optional `RuntimeInitializeLoadType` parameter controlling where in the Player loop it executes. - Animation-related callbacks `MonoBehaviour.OnAnimatorMove` and `MonoBehaviour.OnAnimatorIK` fire during the internal animation update; `StateMachineBehaviour` scripts additionally receive `OnStateMachineEnter`, `OnStateMachineExit`, `OnStateEnter`, `OnStateUpdate`, `OnStateExit`, `OnStateMove`, `OnStateIK`. - Rendering-order callbacks (Built-in Render Pipeline only — see [[concepts/rendering-pipelines]] for URP/HDRP equivalents): `OnPreCull` (before camera culling), `OnBecameVisible`/`OnBecameInvisible`, `OnWillRenderObject` (once per camera if visible), `OnPreRender`, `OnRenderObject` (after regular rendering — use with the `GL` class or `Graphics.DrawMeshNow` for custom geometry), `OnPostRender`, `OnRenderImage` (post-processing), `OnGUI`, `OnDrawGizmos`. Note: `OnPreCull`, `OnPreRender`, `OnPostRender`, and `OnRenderImage` only fire on scripts attached to the same object as an enabled Camera component; to get equivalent callbacks on a script on a *different* object, use the lowercase delegate equivalents `Camera.onPreCull`, `Camera.onPreRender`, `Camera.onPostRender`. - Suspended coroutines resume at different points depending on their yield instruction — `WaitForEndOfFrame` resumes at end of frame, `WaitForFixedUpdate` resumes at the end of the fixed-update step (see [[concepts/coroutines]]). Regular .NET `Task`s and async methods resume during the `Update` phase; Unity's `Awaitable` class can resume at different points depending on the await method used, and the relative order between resuming coroutines and async tasks is not guaranteed (`Awaitable`s are grouped and executed in the order they were awaited). - When using the Entity Component System (ECS), ECS system group updates are merged into the Player update loop; the Entities Systems window shows their update order relative to the full Player loop (see [[entities/unity-ecosystem]]). ## Key Parameters - **`Awake`** — called once per object at scene load; all `Awake`s finish before any `Start`. - **`OnEnable`** — fires before `sceneLoaded` and before `Start`. - **`Start`** — called once before the first `Update`/`FixedUpdate` on that object. - **`Update`** — per-frame logic, before rendering and animation calculation. - **`FixedUpdate`** — per-physics-step logic. - **`LateUpdate`** — runs after all `Update`/`FixedUpdate` calls and animation calculation. - **`PlayerLoop` API** — retrieves/customizes the full engine update sequence. ## When To Use Put movement/input/gameplay logic that should run once per rendered frame in `Update`. Put anything interacting with `Rigidbody`/physics in `FixedUpdate`. Put camera-follow logic or code that must override animation results in `LateUpdate`, after targets have already moved and animations have already been evaluated. Use `Awake` for a component's own internal setup that doesn't depend on other objects, and `Start` for setup that may depend on another object's `Awake` having already run. Use `[InitializeOnLoad]`/`[RuntimeInitializeOnLoadMethodAttribute]` for code that must run at Editor launch or app startup without being wired to any particular GameObject. ## Risks & Pitfalls - Putting physics code in `Update` instead of `FixedUpdate` — introduces frame-rate-dependent inconsistency in physics behavior. - Relying on `Start`/`Awake` order **between different GameObjects** — only the Awake-before-Start guarantee across all objects is documented; you cannot rely on the order in which the same event function fires across different GameObjects, or between different instances of the same MonoBehaviour, unless explicitly configured via [[concepts/scripting-model|script execution order settings]]. - Adding an empty `OnGUI()` "just in case" — this silently adds per-frame IMGUI processing overhead even when unused. - Expecting `OnPreCull`/`OnPreRender`/`OnPostRender`/`OnRenderImage` to fire on arbitrary scripts — they only fire on scripts on the same GameObject as an enabled Camera; use the `Camera.onPreCull`-style delegates for other objects. - Assuming coroutine resumption and async/Task resumption interleave in a guaranteed order — the Manual explicitly states this is not guaranteed. - Forgetting that `Update`'s relative order between a parent and its own child GameObject is also not guaranteed. ## Related Concepts - [[concepts/scripting-model]] — MonoBehaviour fundamentals these callbacks build on - [[concepts/coroutines]] — coroutine resumption timing relative to the event lifecycle - [[concepts/physics]] — FixedUpdate and collision/trigger event functions - [[concepts/rendering-pipelines]] — how render-order callbacks differ under URP/HDRP vs. Built-in - [[entities/unity-ecosystem]] — ECS system group scheduling within the Player loop ## Sources - raw/web_community-unity-manual-event-functions.md - raw/web_community-unity-manual-event-function-execution-order.md --- title: "GameObjects, Components, and Prefabs" type: concept tags: [gameobjects, editor, foundational, beginner] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-introduction-to-gameobjects.md", "raw/web_community-unity-manual-use-components.md", "raw/web_community-unity-manual-prefabs.md", "raw/web_community-unity-manual-transforms.md"] confidence: high unity_version: "6.0" --- ## Definition The **GameObject** is the fundamental object in Unity scenes — everything in a game (characters, lights, cameras, props, scenery) is a GameObject. A GameObject accomplishes nothing on its own; it is a container for **Components**, which implement functionality. Every GameObject always carries a **Transform** component (position, rotation, scale, and parenting). A **Prefab** is a reusable asset template that stores a GameObject complete with its components, property values, and child GameObjects, from which you can stamp out instances in a scene. ## How It Works A GameObject gains behavior purely through the components attached to it: a Light object is a GameObject with a Light component; a solid cube is a GameObject with a Mesh Filter and Mesh Renderer component (to draw its surface) plus a Box Collider component (to represent its solid volume for physics). Unity ships many built-in component types, and custom components can be authored by writing scripts that derive from `MonoBehaviour` (see [[concepts/scripting-model]]). A GameObject can carry any number and combination of components, and some components are designed to work together — for example, a `Rigidbody` works in combination with a `Collider`. Components are added via the Editor's **Component menu** (e.g., `Component > Physics > Rigidbody`) or via the **Add Component** button in the Inspector, which opens the **Component browser** (searchable/browsable by category). A component must belong to the same project as the GameObject; the Editor cannot attach components from other projects, unattached scripts, or packages not yet added to the project. Component values are edited in the **Inspector** window, either as direct value properties (text, toggles, dropdowns) or as reference properties (dragged from the Project view or set via the object picker). Right-clicking a component (or using the kebab `⋮` menu) exposes context commands: **Reset**, **Remove Component** (blocked with a warning if another component depends on it, e.g. a Hinge Joint depends on a Rigidbody), **Move Up**/**Move Down**, **Copy Component**, **Paste Component As New**, and **Paste Component Values**. In Play Mode, component property edits made in the Inspector are temporary and revert when Play Mode ends, which is useful for rapid experimentation (e.g. tuning a `Jump Height` value live). The **Transform** component determines a GameObject's Position, Rotation, and Scale, measured relative to its parent (or in world space if it has no parent). It cannot be removed, and a GameObject cannot exist without one. Transforms can be edited via the Scene view's Move/Rotate/Scale gizmo tools, directly in the Inspector, or from C# scripts using the `Transform` class. Dragging one GameObject onto another in the Hierarchy window creates a **parent-child relationship**; a child GameObject moves, rotates, and scales along with its parent, and children can themselves have children, forming a **Transform hierarchy** whose topmost object (with no parent) is the **root** GameObject. Child Transform values shown in the Inspector are **local coordinates** (relative to the parent); the Transform scripting API exposes separate local and global (world) Position/Rotation/Scale, with conversions between them. Non-uniform scaling (different x/y/z scale values) is supported but behaves differently from uniform scaling — some components with circular/spherical elements (Sphere Collider, Capsule Collider, Light, Audio Source) don't fully support it, and a non-uniformly scaled, rotated parent can visually "shear" its children. **Prefabs** let you save a configured GameObject — with all its components, property values, and child GameObjects — as a reusable asset in the Project window. The prefab asset acts as a template; dragging it into a scene creates a **prefab instance** that stays linked to the asset. Related workflows include creating prefabs, editing them in prefab editing mode, nesting prefab instances inside other prefabs, creating prefab **variants** (predefined variations of a base prefab), overriding instance data on a per-instance basis, reverting an instance back to a plain GameObject (unpacking), and instantiating prefabs at runtime from C# code via the `PrefabUtility` API. ## Key Parameters - **GameObject** — the base container object; always has exactly one Transform and one parent. - **Component** — Transform, Mesh Filter, Mesh Renderer, Collider (Box/Sphere/Capsule), Rigidbody, Light, Audio Source, script components, etc. - **Transform properties** — Position, Rotation, Scale, and the "Enable Constrained Proportions" toggle (locks axes together when scaling). - **Prefab asset vs. prefab instance** — the template asset versus a placed, linked copy in a scene. - **Prefab Variant** — a prefab that inherits from and overrides a base prefab. ## When To Use Use components to compose behavior instead of writing monolithic classes — e.g., combine Rigidbody + Collider for physics-driven objects, or Mesh Filter + Mesh Renderer for visible geometry. Use the Transform hierarchy (parenting) to group related objects that should move together (a car body with wheel children, a character with an equipped-weapon child). Use prefabs any time a configured GameObject needs to be reused — enemies, pickups, bullets, UI widgets — so that a single edit to the prefab asset can propagate to every instance, and use prefab variants when you need several closely related versions (e.g., different enemy types sharing a base rig). ## Risks & Pitfalls - Trying to remove a Transform — not possible; every GameObject requires one. - Removing a component that another depends on (e.g., removing a Rigidbody while a Hinge Joint references it) — Unity warns but this breaks dependent functionality. - Adjusting Scale on the Transform instead of at the mesh/import level — instantiating GameObjects with adjusted Transform Scale can decrease performance; prefer setting scale via modeling application or Import Settings' Mesh Scale Factor. - Setting any Scale axis to 0 on a Transform — causes undefined math results (e.g., NaN), producing rendering artifacts. - Non-uniform scaling combined with rotation on parent objects, which can visually skew/shear children and break colliders that don't match the rendered mesh. - Forgetting that child Transform values shown in the Inspector are local (relative to parent), not global/world — scripts needing world position must use the appropriate Transform API. - Editing a prefab asset without realizing per-instance overrides exist, or being surprised when instance-level overrides don't get replaced by an asset-level edit. ## Related Concepts - [[concepts/overview]] — how GameObjects fit into scenes generally - [[concepts/scripting-model]] — writing custom components via MonoBehaviour - [[concepts/physics]] — Rigidbody and Collider components in depth - [[concepts/editor-and-projects]] — the Project/Inspector windows used to manage components ## Sources - raw/web_community-unity-manual-introduction-to-gameobjects.md - raw/web_community-unity-manual-use-components.md - raw/web_community-unity-manual-prefabs.md - raw/web_community-unity-manual-transforms.md --- title: "Input System (package)" type: concept tags: [input, packages, foundational, intermediate] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-input-system-concepts.md", "raw/web_community-input-system-quickstart.md", "raw/web_community-input-system-actions.md", "raw/web_community-unity-manual-input-system.md"] confidence: high unity_version: "6.0" --- ## Definition The **Input System** (package identifier `com.unity.inputsystem`, current released version 1.19.0 for Unity Editor 6000.0) is Unity's package offering "a more extensible and customizable alternative to Unity's classic input system in `UnityEngine.Input`," per the Manual's package listing. Rather than polling hardware directly, it is built around **Actions** — named, abstract representations of "things a user might want to do in your game or app" (its own example verbs: "Run", "Jump", "Crouch", "Use", "Start", "Quit") — which are decoupled from whatever physical device or control performs them. This action-based model is what the package's `input`, `events`, `keyboard`, `mouse`, `gamepad`, `touch`, `vr`, `xr` keywords point at: one API surface spanning keyboard, mouse, gamepad, touch, and VR/XR, in place of the legacy, always-available `UnityEngine.Input` class (the "Input Manager"). ## How It Works The Input System's basic concepts, as laid out by the Manual's Concepts page, form a pipeline from physical hardware to game logic: - **User** — the person providing input by holding or touching a device. - **Input Device** ("device") — a physical piece of hardware (keyboard, gamepad, mouse, touchscreen) that sends input into Unity. - **Control** — the separate individual parts of a device that each send a value, e.g. a gamepad's buttons, sticks, and triggers, or a mouse's X/Y sensors, buttons, and scroll wheels. - **Action** — a high-level, conceptual name for something the user can do ("Jump", "Select"), independent of which device or control triggers it. - **Binding** — the connection defined between an Action and specific device Controls. A single action, such as "Move", can have bindings to the arrow keys, the WASD keys, a gamepad's left stick, and a VR controller's primary 2D axis simultaneously — "multiple bindings like this means your game can accept cross-platform input." - **Action Map** — a named collection of Actions grouped by the situation in which they make sense together (e.g. one map for controlling a player, another for UI), so that a whole set of actions can be enabled or disabled as a group. - **Action Asset** — an asset type that stores a saved configuration of Action Maps, Actions, and Bindings. One Action Asset per project can be designated the **project-wide actions**, referenced in code via `InputSystem.actions`. - **Your Action Code** — the script logic that runs off configured actions, either by reading an action's current value/state directly (**polling**) or by attaching a **callback** method to be notified when the action is performed. Because gameplay code reads and reacts to Actions ("did Jump fire?") instead of specific device buttons, remapping controls or adding support for a new device type doesn't require touching gameplay scripts — only the bindings need to change. Actions also make it straightforward to build runtime control-rebinding for players. Two notes from the Actions manual page: Actions are a runtime-only feature (they can't be used in Editor window code), and if multiple actions are performed in the same frame, the order the Input System reports them in is undefined — code should not assume a particular firing order. At the API level (per the Actions manual page): `InputActionMap` is the API equivalent of an Action Map, `InputAction` is a named action that returns the current value of its bound controls or triggers callbacks, and `InputBinding` is the relationship between an action and the device controls it reads from. Each `InputAction` has a name (unique within its Action Map) and a stable unique ID that survives renames; the same is true for each `InputActionMap`'s name and ID. **Enabling actions.** Actions have an enabled state. Actions in an Action Asset assigned as project-wide are enabled by default and ready to use; actions defined elsewhere (a non-project-wide asset, or created in your own code) start disabled and must be enabled — individually (`lookAction.Enable()`) or as a whole Action Map (`gameplayActions.Enable()`) — before they respond to input. Enabling an action makes the Input System resolve its bindings (unless already resolved). While enabled, an action monitors its bound controls and reacts to state or Interaction changes during the Input System's update logic, which runs once per frame, once per fixed update, or manually, depending on the selected update mode. Certain configuration, such as an action's bindings, cannot be changed while the action is enabled; call `Disable()` to stop an action or Action Map from responding. **Ways to create Actions.** The primary, recommended workflow is the **Input Actions editor** in Project Settings, which lets you configure Action Maps, Actions, and Bindings in one place across the whole project. Because the underlying API is open, three alternative ways to create actions exist for less common scenarios: 1. **Declaring `InputAction`/`InputActionMap` fields directly in a `MonoBehaviour`** (e.g. `public InputAction move;`) — the Inspector then shows an interface similar to the Actions editor for setting up bindings, but the configuration is serialized with the Scene/Prefab data rather than a dedicated asset, and — unlike project-wide actions — must be enabled/disabled manually. 2. **Loading Actions from JSON**, either as a set of Action Maps (`InputActionMap.FromJson(json)`) or a full `InputActionAsset` (`InputActionAsset.FromJson(json)`); this works at runtime in the Player. 3. **Creating Actions entirely in code**, e.g. `new InputAction("look", binding: "/leftStick")`, adding further bindings with `.AddBinding(...)`, and composite bindings with `.AddCompositeBinding("Dpad").With("Up", "/w")...`; also works at runtime, and actions created this way during Play mode do not persist in the Action Asset after exiting Play mode. **The quickstart (polling) workflow.** Installing the package and, on first use, creating and assigning a default project-wide Action Asset (via Edit > Project Settings > Input System Package > Input Actions) gives a ready-to-use default configuration: two Action Maps, "Player" and "UI". "Player" defines game-related actions such as Move, Look, Jump, and Attack; "UI" defines interface actions such as Navigate, Submit, and Cancel. Each default action already has bindings across device types — for example "Move" is bound to WASD, the arrow keys, a gamepad stick, and a VR controller's primary 2D axis, while "Jump" is bound to the space key, a gamepad's south button, and an XR controller's secondary button. Because these defaults are pre-wired, scripting against them requires no configuration: ```csharp using UnityEngine; using UnityEngine.InputSystem; public class Example : MonoBehaviour { InputAction moveAction; InputAction jumpAction; private void Start() { moveAction = InputSystem.actions.FindAction("Move"); jumpAction = InputSystem.actions.FindAction("Jump"); } void Update() { Vector2 moveValue = moveAction.ReadValue(); if (jumpAction.IsPressed()) { // your jump code here } } } ``` Different action value types expose different read methods — `.ReadValue()` for a 2D axis like "Move", `.IsPressed()` for a button-like state such as "Jump". If two Action Maps each define an action of the same name, `FindAction` must be qualified as `"Player/Move"`. The quickstart guide notes the Input System supports "multiple workflows which you might prefer that offer different benefits," of which this polling-based use of the default project-wide actions is the one suited to most common scenarios; the sources mirrored so far describe this workflow and the underlying Actions/Action Maps/Bindings/Action Asset model in depth, but do not themselves walk through the alternative Actions-asset-driven callback workflow or a `PlayerInput` component-based workflow in comparable detail — see Risks & Pitfalls. ## Key Parameters - **`com.unity.inputsystem`** — the package identifier used in the Package Manager / `manifest.json`; version 1.19.0 is released for Unity Editor 6000.0. - **Action** — named, device-independent representation of something the user can do; has a name (unique per Action Map) and a stable ID. API type: `InputAction`. - **Action Map** — named group of related Actions that can be enabled/disabled together; has a name (unique among maps) and a stable ID. API type: `InputActionMap`. - **Binding** — the connection between an Action and one or more device Controls; a single action can have several bindings across device types. API type: `InputBinding`. - **Action Asset** — saved configuration of Action Maps/Actions/Bindings; one per project can be marked project-wide and reached via `InputSystem.actions`. - **Default Action Maps** — "Player" (Move, Look, Jump, Attack) and "UI" (Navigate, Submit, Cancel), included out of the box when a default project-wide Action Asset is created. - **`InputSystem.actions.FindAction("Name")`** — looks up an action by name (or `"Map/Name"` when the name is ambiguous across maps). - **`.ReadValue()` / `.IsPressed()`** — polling accessors whose shape depends on the action's value type (e.g. `Vector2` for a 2D move axis vs. a button-pressed boolean). - **`Enable()` / `Disable()`** — toggle whether an Action or Action Map responds to input; project-wide actions are enabled by default, actions from elsewhere start disabled. ## When To Use Use the Input System package for any new project, or when a project needs multiple input device types (gamepad, touch, VR/XR) handled through one API, runtime control rebinding, or a clean separation between "what the player intends" (the Action) and "which physical control did it" (the Binding). For the fastest path, create the default project-wide Action Asset and poll its pre-configured "Move"/"Jump"-style actions from `Update`, as shown in the quickstart. For custom or more numerous actions, author them in the Input Actions editor (recommended for anything project-wide) or, for actions scoped to a single component/prefab, declare `InputAction`/`InputActionMap` fields directly in a `MonoBehaviour`. Loading actions from JSON or building them entirely in code are available for scenarios needing runtime-generated or externally-defined input configurations. It remains Unity's forward-looking alternative to the legacy `UnityEngine.Input` Input Manager. ## Risks & Pitfalls - It is a separate package rather than an always-on built-in system, so it must be installed via the Package Manager, and in many project configurations an "Active Input Handling" mode (legacy Input Manager, the new Input System, or both) must be set explicitly — mixing assumptions about which is active is a common source of "input doesn't work" bugs when following mismatched tutorials. - Code written against the legacy `UnityEngine.Input` API (e.g. `Input.GetKeyDown`) is not automatically compatible with the Input System's action-based API — migrating requires rewriting input-handling code, not just swapping a package. - Actions are runtime-only: they cannot be used in Editor window code. - If multiple actions fire in the same frame, the order the Input System reports them in is undefined; do not write logic that depends on a particular firing order. - Actions embedded as `MonoBehaviour` fields (rather than in a project-wide Action Asset) must be enabled and disabled manually, and their bindings are serialized with the Scene/Prefab rather than a shared asset — convenient for bundling behavior with a prefab, but harder to audit as one complete control scheme once bindings are spread across multiple prefabs/scenes. - An action's configuration (e.g. its bindings) cannot be changed while the action is enabled; it must be disabled first. - **Depth beyond this overview** — the `PlayerInput` component, named **control schemes** for per-device/per-platform binding sets, the started/performed/canceled action-callback phases, composite bindings, and the Devices/Controls/Interactions model are all covered source-grounded in the XL (Pro) tier: see the XL reference pages `input-system-actions-and-assets`, `input-system-playerinput`, and `input-system-devices-and-controls`. This standard-tier page is the conceptual entry point; the XL pages carry the per-item detail. ## Related Concepts - [[concepts/scripting-model]] - [[concepts/event-lifecycle]] - [[concepts/gameobjects-components-prefabs]] ## Sources - raw/web_community-input-system-concepts.md - raw/web_community-input-system-quickstart.md - raw/web_community-input-system-actions.md - raw/web_community-unity-manual-input-system.md --- title: "Unity 6 Overview" type: concept tags: [editor, scripting, gameobjects, foundational, beginner] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-introduction-to-scenes.md", "raw/web_community-readme-md.md"] confidence: high unity_version: "6.0" --- ## Definition Unity 6 (internally versioned 6000.0) is a cross-platform game engine and development environment consisting of the Unity Editor (the authoring application) and the Unity Engine (the runtime that executes built applications). A Unity project is organized as a collection of **Scenes**, and within each scene, content is built from **GameObjects** that are given behavior and appearance through **Components**, some of which are written in C# via **scripting**. This page gives the high-level mental model; the other pages in this KB go deeper on each layer. ## How It Works A Unity project is a folder on disk containing an `Assets` folder (scripts, models, textures, scenes, and other assets), a `Packages` folder/manifest (dependencies managed by the Unity Package Manager), and project settings. When you open a project, the Editor loads one or more **scenes** — assets that "contain all or part of a game or application." A simple game might live in a single scene; a more complex game typically uses one scene per level, each with its own environments, characters, obstacles, decorations, and UI. When you create a new project, Unity opens a default sample scene containing just a Camera and a Light, which is the minimal viable scene. Inside a scene, everything you place is a **GameObject** — the fundamental container object in Unity (see [[concepts/gameobjects-components-prefabs]]). A GameObject on its own does nothing; it gains functionality by having **Components** attached to it (a Light component makes it a light, a Mesh Renderer and Collider make it a solid object, and so on). Every GameObject always carries a Transform component that positions it in the scene and optionally parents it to other GameObjects, forming a hierarchy. Scripting is where custom logic enters this model. You write C# scripts, most commonly as classes that derive from `MonoBehaviour`, and attach them to GameObjects as components. This lets you read input, run game rules, and connect UI, physics, animation, and rendering systems together over time. See [[concepts/scripting-model]] and [[concepts/event-lifecycle]] for the details of how and when this code runs. Beyond the built-in engine, Unity's functionality is extensible through **packages** managed by the Unity Package Manager (UPM) — self-contained units of Editor or Runtime tools, libraries, and asset collections that can be added to or removed from a project (see [[concepts/packages]]). Systems like the Input System, UI Toolkit, and the render pipelines (URP/HDRP) are themselves distributed as packages layered on top of the engine core. ## Key Parameters - **Scene** — the unit of content; a project can contain any number of scenes, and multiple scenes can be open for editing simultaneously (multi-scene editing). - **GameObject** — the fundamental object type placed in a scene; has no behavior by itself. - **Component** — a functional part attached to a GameObject (Transform, Mesh Renderer, Collider, Rigidbody, script components, etc.). - **Project structure** — `Assets/` (your content), `Packages/` (dependencies via UPM), Editor-managed settings. - **Package Manager (UPM)** — the mechanism for adding/removing engine and third-party functionality beyond the core install. ## When To Use This mental model — scenes containing GameObjects composed of components, driven by scripts, extended by packages — applies to essentially every Unity 6 project, from a simple prototype to a large production game. Understanding it first is a prerequisite for everything else in this KB: before touching physics, UI, or rendering, you need to know that those systems all plug into the same GameObject/component/scene structure. ## Risks & Pitfalls - Treating "the Editor" and "the game" as the same thing: code and behavior that run in Play Mode in the Editor are the same engine systems that run in a build, but Editor-only tooling (custom windows, `[InitializeOnLoad]`, etc.) does not ship with the game. - Cramming an entire game into one scene instead of splitting by level/section, which hurts iteration time and team collaboration as a project grows. - Assuming ecosystem/community resources (asset store plugins, third-party frameworks) are officially supported or maintained — the wider Unity ecosystem includes many community and paid assets of varying quality and upkeep, distinct from Unity's own Manual-documented systems. - Confusing the Unity Manual (conceptual/how-to documentation, the scope of this KB) with the Scripting API reference (per-class technical reference) — they serve different purposes. ## Related Concepts - [[concepts/editor-and-projects]] — scenes and project workflow in detail - [[concepts/gameobjects-components-prefabs]] — the composition model - [[concepts/scripting-model]] — where and how custom code fits in - [[concepts/packages]] — extending Unity via UPM - [[entities/unity-ecosystem]] — the broader tools/asset ecosystem around core Unity ## Sources - raw/web_community-unity-manual-introduction-to-scenes.md - raw/web_community-readme-md.md (ecosystem context; an archived community-maintained list of third-party Unity assets/tools/tutorials, not official Unity documentation — used only for framing the wider ecosystem, not for core facts about Unity itself) --- title: "Packages and the Unity Package Manager (UPM)" type: concept tags: [packages, editor, foundational, beginner] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-packages-and-package-management.md", "raw/web_community-unity-manual-install-a-upm-package-from-a-registry.md"] confidence: high unity_version: "6.0" --- ## Definition A **package** is a container of features and assets that fits a project's needs — this includes core Unity features bundled with the Editor install as well as optional features you add as needed. The **Unity Package Manager (UPM)** is the system and set of interfaces for finding, installing, updating, and removing packages in a project. ## How It Works Unity's Package Manager provides several interfaces for getting and managing packages: the **Package Manager window** (a GUI for browsing and managing packages), the **scripting API** (managing packages from C# scripts), and direct editing of the **project manifest file** (a JSON file listing package dependencies). Related concepts covered by the Manual include package **dependencies** (how UPM resolves version conflicts between packages), **package inspection** (getting details about an installed package), **feature sets** (curated collections of related packages bundled to accomplish a specific goal, such as building environments or optimizing for a platform), **Git dependencies** (fetching a package directly from a Git repository via a Git URL rather than a registry version — with no guarantee of quality, stability, or Semantic Versioning compliance), **Package Manager caches** (local storage of downloaded packages, with customizable locations), **scoped registries** (using or hosting a custom package registry server beyond Unity's own), and creating **custom packages** (with your own **package manifest**, which records the package's name, version, description, and dependencies). To **install a UPM package from a registry**: open the Package Manager window and select **Unity Registry** from the navigation panel for Unity's own packages, or **My Registries** to install from a scoped registry you've configured for the project (this option only appears once a scoped registry has been defined). Select the desired package from the list to see its details in the details panel. Note that experimental packages only appear in the list if already installed, and pre-release packages only appear once the **Show Pre-release Package Versions** project setting is enabled — otherwise an undiscoverable package won't show up even though it exists. If multiple versions are available, optionally select which version to install. Click **Install**; once the progress bar completes, the package is ready to use. Multiple packages can be installed in one action using the Package Manager's multi-select feature. When you install a package, UPM evaluates other installed packages and their dependencies to detect version conflicts, and automatically resolves them by installing a version that satisfies all constraints where possible. ## Key Parameters - **Package Manager window** — primary GUI (`Unity Registry` vs. `My Registries` navigation). - **Project manifest** — the JSON file (per-project) listing package dependencies; editable directly as an alternative to the GUI. - **Package manifest** (`package.json`) — per-package metadata: name, version, description, dependencies. - **Feature set** — a bundle of related packages installed together for a specific purpose. - **Scoped registry** — a non-Unity, project-configured package registry. - **Git dependency** — a package referenced by Git URL instead of a registry + version. - **Show Pre-release Package Versions** — project setting required to surface pre-release packages in the Package Manager list. ## When To Use Reach for the Package Manager window for everyday, GUI-driven package installs and version selection. Use the scripting API when package installation needs to be automated (e.g., a custom project setup/bootstrap tool). Edit the project manifest directly when you need fine-grained or scripted control over exact dependency versions, or need to add a Git or scoped-registry dependency that isn't conveniently reachable through the GUI. Use feature sets when adopting a whole toolset for a task (e.g., a platform's build tooling) rather than hunting down each package individually. Use scoped registries when your organization hosts private/internal packages alongside Unity's own registry. ## Risks & Pitfalls - Expecting an experimental or pre-release package to show up in the normal package list — experimental packages are hidden unless already installed, and pre-release packages require enabling **Show Pre-release Package Versions** first. - Treating Git dependencies as equivalent in reliability to registry packages — there is no guarantee of package quality, stability, validity, or that the version in `package.json` actually follows Semantic Versioning. - Version conflicts between packages with overlapping dependencies — UPM attempts automatic resolution, but the resolved version may not be the one you explicitly selected; check the Package Manager's dependency/conflict information rather than assuming your requested version is what's actually installed. - Editing the project manifest by hand without understanding UPM's dependency resolution rules, which can produce conflicts that the GUI would have surfaced or resolved automatically. - Forgetting that packages sourced from the Asset Store are handled differently from native UPM registry packages, even though both can appear inside the Package Manager window. ## Related Concepts - [[concepts/overview]] — packages as the mechanism for extending core Unity - [[concepts/input-system]] — a major package-delivered system - [[concepts/ui-toolkit]] — another package-delivered system - [[concepts/rendering-pipelines]] — URP/HDRP are delivered and configured as packages - [[entities/unity-ecosystem]] — the wider package/asset ecosystem around Unity ## Sources - raw/web_community-unity-manual-packages-and-package-management.md - raw/web_community-unity-manual-install-a-upm-package-from-a-registry.md --- title: "Performance and Best Practices" type: concept tags: [performance, scripting, editor, intermediate] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-best-practice-guides.md", "raw/web_community-unity-manual-building-plug-ins-for-desktop-platforms.md"] unity_version: "6.0" confidence: medium --- ## Definition Unity provides curated **best practice guides** — production-tested guidance from Unity experts — spanning art and design, DevOps, graphics and rendering, performance optimization, and scripting. These are e-books and long-form guides rather than API reference; they represent accumulated production wisdom about how to build Unity projects well and how to keep them running fast. Separately, projects that need functionality outside Unity's managed C# layer can extend the engine with **native plug-ins** (desktop platform note below), which carry their own performance and integration considerations. ## How It Works Unity organizes its best-practice guidance into five topic areas (per the Manual's "Best practice guides" index): - **Art and design** — e.g., VR/XR project setup, the definitive animation guide, 2D art/animation/lighting workflows, game design prototyping, UI Toolkit for advanced developers, level design. - **DevOps** — project organization and version control practices, comparisons of VCS options, Unity DevOps tooling (Asset Manager, Build Automation). - **Graphics & rendering** — URP shader/VFX authoring, in-depth URP setup guidance, HDRP lighting/environments, advanced visual effects with VFX Graph. See also [[concepts/rendering-pipelines]]. - **Performance optimization** — mobile/XR/Web optimization tips, console/PC optimization tips, an "ultimate guide to profiling Unity games" (profiling, memory management, power consumption), a general "game dev field guide" covering Editor navigation, profiling tools, physics, and Input Systems, and a productivity-tips guide covering Editor navigation, 2D workflows, debugging/profiling, URP, HDRP, and UI Toolkit. - **Scripting** — C# style guides, multiplayer networking fundamentals (including Netcode for GameObjects), DOTS (Data-Oriented Technology Stack) concepts for advanced developers, ScriptableObject-based modular architecture patterns (see [[concepts/scriptableobjects]]), and SOLID/design-pattern guidance for maintainable game code. **Native plug-ins for desktop** are one specific, well-documented area of Unity extensibility relevant to performance-sensitive or platform-integration work: - Desktop plug-ins are native-code libraries (C, C++, Objective-C) for macOS, Windows, and Linux. - **macOS**: deployed as bundles, or (under IL2CPP) as loose C++ files invoked via `[DllImport("__Internal")]`. Functions must be declared with C linkage (`extern "C"`) to avoid name-mangling issues. - **Windows**: `.dll` files with exported functions, or loose C++ files under IL2CPP; C++ functions need C linkage. - **Linux**: `.so` files; C++ functions need C linkage; if the library depends on another native plug-in, you must set the correct `rpath` (e.g., linker flag `-Wl,-rpath=$ORIGIN`) or `LD_LIBRARY_PATH` so the loader can find dependencies. - Plug-ins are managed inside Unity via the **Plugin Inspector** (select the plug-in file in the Project window); for Standalone platforms you choose the compatible CPU architecture there. - Invoke a plug-in from C# with `[DllImport("PluginName")]`, omitting any library prefix or file extension from the name. - **Native plug-ins cannot be unloaded** once loaded into an Editor session — changing a loaded plug-in requires restarting the Editor. The Editor loads a plug-in when a plug-in function is first invoked from an Editor script, when Play mode starts with "Load on startup" enabled, or when loaded manually via script. ## Key Parameters - Which best-practice topic area is relevant to the task at hand (art, DevOps, graphics, performance, or scripting) — the guides are organized this way and an agent should route questions accordingly. - For native plug-ins: target platform (macOS/Windows/Linux), scripting backend (Mono vs. IL2CPP — IL2CPP unlocks loose C++ file plug-ins on macOS/Windows), and correct C linkage/rpath configuration. ## When To Use - Point to the relevant best-practice guide by topic area when a question is about production-scale project organization, profiling methodology, or cross-cutting architecture patterns rather than a single API call. - Reach for native plug-ins only when functionality genuinely isn't available in managed C#/Unity APIs — e.g., OS-level calls, or wrapping an existing native (C/C++) library. This is a heavier-weight integration path with real platform-specific pitfalls. - Use the performance-optimization guides as a starting point before diving into Unity's Profiler tooling for a specific frame-time or memory problem. ## Risks & Pitfalls - Native plug-ins loaded into the Editor **cannot be unloaded or hot-swapped** — a changed plug-in requires an Editor restart, which surprises developers expecting the usual "just recompile" C# workflow. - Incorrect `rpath`/`LD_LIBRARY_PATH` configuration on Linux causes missing-library errors that can be confusing to diagnose since Linux does not automatically search the current directory for dependencies. - Forgetting C linkage (`extern "C"`) on C++/Objective-C plug-in functions causes name-mangling issues that break `[DllImport]` lookups. - Treating "best practice guides" as authoritative API documentation — they are production guidance/e-books, useful for architecture and workflow decisions, but not a substitute for the Scripting API reference (out of scope for this KB) when exact method signatures are needed. - General performance pitfall: profile before optimizing — the guides repeatedly emphasize using Unity's Profiler rather than guessing at bottlenecks. ## Related Concepts - [[concepts/rendering-pipelines]] — graphics/rendering performance is pipeline-specific. - [[concepts/scriptableobjects]] — referenced by the scripting best-practice guide for modular architecture. - [[concepts/physics]] — physics performance tips are called out specifically in the best-practice index. - [[syntheses/common-gotchas]] — concrete beginner/intermediate mistakes that undercut performance and stability. ## Sources - raw/web_community-unity-manual-best-practice-guides.md - raw/web_community-unity-manual-building-plug-ins-for-desktop-platforms.md --- title: "Physics System" type: concept tags: [physics, foundational, intermediate] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-physics.md", "raw/web_community-unity-manual-introduction-to-collider-types.md", "raw/web_community-unity-manual-rigidbody-physics.md", "raw/web_community-unity-manual-rigidbody-component-reference.md"] confidence: high unity_version: "6.0" --- ## Definition Unity's physics system simulates how objects accelerate and respond to collisions, gravity, and other forces, so you don't have to hand-code that behavior. Unity ships multiple physics engine implementations depending on your project type: **Built-in 3D physics** (an Nvidia PhysX integration) and **Built-in 2D physics** (a Box2D integration) for object-oriented projects, plus the **Unity Physics** package (and optionally **Havok Physics for Unity**) for projects built on Unity's Data-Oriented Technology Stack (DOTS). This page covers the built-in, object-oriented (Rigidbody/Collider) system used with [[concepts/gameobjects-components-prefabs]]. ## How It Works Physics-driven motion centers on two component types working together: **Rigidbody** — the `Rigidbody` component (backed by the `Rigidbody` class) is what makes a GameObject's movement and position governed by simulated physics forces and torque, rather than by hand-editing `Transform` properties directly. With `Use Gravity` enabled (the default), the physics system applies a gravitational force along the simulated gravity direction. `Mass` (default 1) does not affect how fast an object falls under gravity, but does affect how much force is needed to move it; `Linear Damping` and `Angular Damping` simulate drag/air resistance/friction on linear and rotational velocity respectively. `Is Kinematic` (disabled by default) switches the Rigidbody between physics-driven and kinematic (Transform-driven) movement — when enabled, the physics system cannot move or rotate the GameObject; you (or an animation) must do so via its Transform. **Colliders** — an invisible shape used to handle physical collisions; it doesn't need to match the object's visual mesh exactly. Collider **type** is determined by the configuration of the collider and any attached physics body (Rigidbody or ArticulationBody): - **Static colliders** — a collider with no Rigidbody/ArticulationBody. They don't respond to physics forces and don't move in reaction to collisions; use them for permanent scene geometry like floors and walls. Moving a static collider via its Transform at runtime is discouraged — the physics system doesn't recalculate or wake sleeping bodies in response, producing unintended side effects. - **Physics body colliders** — a collider that shares a GameObject with a Rigidbody or ArticulationBody, and so participates in physics calculations. These are **dynamic** by default. - **Dynamic colliders** — a physics body collider whose Rigidbody has `Is Kinematic` disabled. They respond to simulated forces, collide with other objects (including static colliders), and can be pushed or moved by other colliders. - **Kinematic colliders** — a physics body collider whose Rigidbody has `Is Kinematic` enabled (an ArticulationBody cannot be kinematic). Like static colliders they don't respond to physics forces, but unlike static colliders the physics system can still include them in calculations: they can wake sleeping colliders on contact, act as trigger colliders, and apply friction. `Rigidbody.isKinematic` can be toggled at runtime — a common pattern for ragdoll effects, where limbs are kinematic (animation-driven) by default and switched to dynamic on a heavy collision. **Collision vs. trigger**: a **collision** occurs when the physics engine detects that the colliders of two GameObjects make contact or overlap and at least one has a Rigidbody in motion — this produces physical collision response (objects bounce off / push each other). A collider marked as a **trigger** instead generates trigger events (used for detecting overlap, e.g. pickups or zone detection) without physical collision response; kinematic colliders in particular can act as trigger colliders and receive trigger events. **Collision Detection** mode on the Rigidbody (`Discrete` by default, or `Continuous`, `Continuous Dynamic`, `Continuous Speculative`) controls how carefully the physics system checks for collisions each step — `Discrete` is cheapest but can let fast-moving objects tunnel through thin colliders; the continuous modes trade CPU cost for accuracy against fast-moving collisions. Physics simulation runs on a fixed timestep separate from the regular per-frame update, which is why physics-affecting code belongs in `FixedUpdate` rather than `Update` — see [[concepts/event-lifecycle]] for how `FixedUpdate` is scheduled relative to the Player loop. ## Key Parameters - **`Mass`**, **`Linear Damping`**, **`Angular Damping`** — how the Rigidbody responds to forces and decays velocity. - **`Use Gravity`**, **`Is Kinematic`** — whether gravity applies, and whether the body is physics-driven or Transform/animation-driven. - **`Interpolate`** (`None` / `Interpolate` / `Extrapolate`) — smooths visual jitter between physics updates; `Interpolate` looks back at the previous two physics updates (more accurate, one-update lag), `Extrapolate` predicts forward (can overshoot). - **`Collision Detection`** (`Discrete` / `Continuous` / `Continuous Dynamic` / `Continuous Speculative`) — collision-detection accuracy vs. cost trade-off. - **`Freeze Position`/`Freeze Rotation`** constraints — restrict movement/rotation on selected axes. - **`Layer Override Priority`, `Include Layers`, `Exclude Layers`** — per-Rigidbody overrides of project-wide layer-based collision settings. ## When To Use Use the built-in 3D/2D physics system (Rigidbody + Colliders) for any object-oriented Unity project that needs realistic movement, gravity, or collision response — characters, projectiles, ragdolls, vehicles, environmental interactions. Reach for DOTS physics packages (Unity Physics / Havok Physics) instead only if the project is built on Unity's Data-Oriented Technology Stack. ## Risks & Pitfalls - **Doing physics work in `Update` instead of `FixedUpdate`** — moving a Rigidbody or applying forces outside the fixed physics step produces frame-rate-dependent, jittery, or inconsistent motion; physics state changes belong in `FixedUpdate`. - **Moving a Static collider via Transform at runtime** — the physics system won't recalculate or wake dependent bodies, so objects resting on it (e.g., a car with Wheel Colliders that has gone to sleep) won't react as expected. - **Confusing kinematic with static** — both ignore incoming forces, but only kinematic colliders can wake other sleeping bodies, act as triggers, or apply friction; a kinematic Rigidbody is still expected to move via script/animation, not via forces. - **Using `Discrete` collision detection on fast-moving objects** — thin colliders can be tunnelled through; switch to a `Continuous` mode for fast movers instead. - Setting `Angular Damping` to a very high value does not stop rotation entirely — damping only decays velocity over time, it isn't a hard freeze (use rotation constraints for that). ## Related Concepts - [[concepts/gameobjects-components-prefabs]] - [[concepts/event-lifecycle]] - [[concepts/scripting-model]] - [[concepts/performance-best-practices]] ## Sources - raw/web_community-unity-manual-physics.md - raw/web_community-unity-manual-introduction-to-collider-types.md - raw/web_community-unity-manual-rigidbody-physics.md - raw/web_community-unity-manual-rigidbody-component-reference.md --- title: "Rendering Pipelines" type: concept tags: [rendering, editor, foundational] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-render-pipelines.md", "raw/web_community-unity-manual-introduction-to-render-pipelines.md", "raw/web_community-unity-manual-camera-inspector-window-reference-for-the-built.md", "raw/web_community-unity-manual-lighting.md"] unity_version: "6.0" confidence: high --- ## Definition A **render pipeline** is the series of operations Unity performs to take the contents of a [[concepts/scriptableobjects|scene]] (GameObjects, lights, materials) and turn them into pixels on a screen. Unity 6 ships three pre-built render pipelines — the **Built-In Render Pipeline**, the **Universal Render Pipeline (URP)**, and the **High Definition Render Pipeline (HDRP)** — and also lets advanced developers write a fully custom pipeline using the **Scriptable Render Pipeline (SRP)** API. Choosing a render pipeline is one of the first and most consequential decisions in a new Unity project, because pipelines are not easily swapped mid-project and each has different capabilities, performance characteristics, and target platforms. ## How It Works Every render pipeline, regardless of which one you use, repeats the same three broad stages once per frame: 1. **Culling** — decide which objects in the scene actually need to be drawn. This includes *frustum culling* (removing objects outside the camera's view) and *occlusion culling* (removing objects hidden behind other objects). 2. **Rendering** — draw the surviving objects with correct lighting into pixel buffers. 3. **Post-processing** — apply full-screen filters and effects (color grading, bloom, depth of field, etc.) to the pixel buffers to produce the final output frame. Unity's three built-in options differ in how much of this pipeline you can customize: - **Built-In Render Pipeline** — Unity's original, general-purpose pipeline. It has limited options for customization from C# (deep customization requires purchasing access to Unity's engine source in C++). It's still usable in Unity 6 but is not the pipeline for new advanced-graphics projects. - **Universal Render Pipeline (URP)** — an SRP-based pipeline built for scalability across a wide range of platforms (mobile through high-end desktop/console). It exposes culling, rendering, and post-processing to direct C# customization. - **High Definition Render Pipeline (HDRP)** — an SRP-based pipeline aimed at cutting-edge, high-fidelity graphics on high-end platforms (PC, consoles). Also fully customizable via C#. - **Custom SRP** — experienced graphics programmers can write their own pipeline from scratch on top of the Scriptable Render Pipeline API for bespoke rendering needs. See [[syntheses/render-pipeline-picker]] for a full side-by-side comparison and decision guidance. ### Cameras A **Camera** component defines a viewpoint into the scene and is the thing a render pipeline actually renders from; a scene can contain multiple cameras. In the Built-In Render Pipeline, the Camera Inspector exposes the properties that control what and how a camera renders, including: - **Clear Flags / Background** — what happens to unwritten pixels (e.g., solid color vs. skybox). - **Culling Mask** — which object layers this camera renders. - **Projection** — Perspective (with Field of View) vs. Orthographic (uniform, no perspective; note deferred rendering isn't supported in Orthographic mode — forward rendering is always used). - **Physical Camera** properties — Focal Length, Sensor Size, Lens Shift — for simulating real-world camera/lens attributes. - **Clipping Planes** (Near/Far), **Viewport Rect**, and **Depth** (draw order among multiple cameras). - **Rendering Path** — Vertex Lit, Forward, or "Use Player Settings" (Built-In Render Pipeline specific; URP/HDRP configure rendering paths differently). - **Target Texture** — render to a Render Texture instead of the screen. - **Occlusion Culling**, **Allow HDR**, **Allow MSAA**, **Allow Dynamic Resolution**, **Target Display**. ### Lighting Lighting is configured largely independently of, but interacts closely with, the chosen render pipeline — the lighting workflow differs between the Built-In Render Pipeline and URP, and HDRP has its own lighting model. Core lighting concepts an agent should know: - **Light sources** — Light components, ambient light, emissive materials, light cookies. - **Direct vs. indirect lighting** — whether Unity calculates global illumination (GI) in real time or bakes it into the build ahead of time. - **Shadows** — techniques for casting shadows from a GameObject onto itself or nearby GameObjects. - **Reflections** — Reflection Probes capture a spherical view of surroundings, stored as a Cubemap, for use on reflective materials. - **Optimizing lighting** reduces draw calls and per-vertex/per-pixel lighting work — see [[concepts/performance-best-practices]]. ## Key Parameters - Which render pipeline is active (Built-In, URP, HDRP, custom) — set at project creation or via project graphics settings, and not trivially changed later. - Rendering path (forward vs. deferred) and its interaction with camera Projection mode. - Real-time vs. baked lighting/GI choice. - Camera culling mask, clipping planes, and HDR/MSAA/dynamic-resolution toggles, which all trade visual fidelity for performance. ## When To Use - Use this concept whenever deciding how a project should render graphics, whenever debugging "why doesn't my shader/light/post-effect work" (the answer is often pipeline-specific), or whenever comparing platform targets (mobile vs. high-end PC/console). - Consult [[syntheses/render-pipeline-picker]] directly for a recommendation given a specific project's platform and fidelity requirements. ## Risks & Pitfalls - **Pipeline lock-in**: shaders, post-processing assets, and some lighting features are pipeline-specific. A shader written for the Built-In Render Pipeline generally won't work unmodified in URP or HDRP, and migrating pipelines mid-project is a significant undertaking. - **Orthographic + deferred**: deferred rendering is not supported in Orthographic camera mode; Unity silently falls back to forward rendering. - **Custom render pipelines** are for experienced graphics developers only — writing one from the SRP API is a substantial undertaking, not a casual choice. - **Execution-order surprises**: rendering-related MonoBehaviour callbacks like `OnPreCull`, `OnPreRender`, `OnPostRender`, and `OnRenderImage` apply to the Built-In Render Pipeline only, and only fire on scripts attached to the same GameObject as an enabled Camera — see [[concepts/event-lifecycle]]. ## Related Concepts - [[syntheses/render-pipeline-picker]] — decision guide comparing Built-In vs URP vs HDRP. - [[concepts/performance-best-practices]] — profiling and optimizing rendering/lighting cost. - [[concepts/event-lifecycle]] — where render-related callbacks fit in the frame execution order. - [[concepts/gameobjects-components-prefabs]] — the Camera and Light components live on GameObjects. ## Sources - raw/web_community-unity-manual-render-pipelines.md - raw/web_community-unity-manual-introduction-to-render-pipelines.md - raw/web_community-unity-manual-camera-inspector-window-reference-for-the-built.md - raw/web_community-unity-manual-lighting.md --- title: "ScriptableObject" type: concept tags: [scripting, gameobjects, foundational, intermediate] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-scriptableobject.md"] confidence: high unity_version: "6.0" --- ## Definition `ScriptableObject` is a serializable Unity type derived from `UnityEngine.Object`, used to define custom data containers that live as assets in a project rather than as components attached to a GameObject. Like `MonoBehaviour`, you don't instantiate `ScriptableObject` directly — you write your own custom C# class that derives from it, then create instances of that class, typically through the Assets menu in the Unity Editor. Every instance of such a derived class is commonly called "a ScriptableObject." This makes ScriptableObject one of the two fundamental Unity types alongside [[concepts/scripting-model]] within the broader [[concepts/scripting-model]]. ## How It Works Unlike MonoBehaviours, ScriptableObjects are not attached to [[concepts/gameobjects-components-prefabs]] as components — they exist independently in the project as assets. Because they inherit from `UnityEngine.Object`, you can drag or pick ScriptableObject instances directly into fields in the Inspector, the same way you would reference any other asset. To create a ScriptableObject script, use the predefined template: **Assets > Create > Scripting > ScriptableObject Script** from the main menu, or the equivalent option in the Project window's context/create menu. This produces a custom base class inheriting from `UnityEngine.ScriptableObject`. Adding the `CreateAssetMenu` attribute to that class lets you then create instances of it as project assets via the Assets menu: ```csharp [CreateAssetMenu(fileName = "Data", menuName = "ScriptableObjects/SpawnManagerScriptableObject", order = 1)] public class SpawnManagerScriptableObject : ScriptableObject { public string prefabName; public int numberOfPrefabsToCreate; public Vector3[] spawnPoints; } ``` After creating an instance via **Assets > Create > ScriptableObjects > SpawnManagerScriptableObject**, a MonoBehaviour script can hold a public field of that type, populate it via the Inspector, and read its values at runtime (for example, to drive prefab spawn positions from data authored at design time). Saving behavior differs by context: in the Unity Editor, you can save data to ScriptableObjects in both Edit mode and Play mode, and changes made through Editor authoring tools or the Inspector are automatically written to disk and persist between Editor sessions. However, changes made to a ScriptableObject via script in Edit mode are **not** automatically saved — you must call `EditorUtility.SetDirty` on the object so Unity's serialization system recognizes it as changed, otherwise the change exists only in memory and reverts when the Editor restarts. In a standalone Player at runtime, you can only **read** saved data from ScriptableObject assets — there is no facility to persist new changes back to disk in a build. ## Key Parameters - **`CreateAssetMenu`** — the attribute (`fileName`, `menuName`, `order`) that exposes a ScriptableObject-derived class as a creatable asset type in the Assets menu. - **`EditorUtility.SetDirty`** — required after modifying a ScriptableObject via script in Edit mode, to force serialization of the change to disk. - **Script/class name match** — as with any Unity script, the file name must match the class name. ## When To Use The main value of a ScriptableObject is as a data store, though it can also define behavior. Primary use cases per the Manual: - **Shared runtime data** referenced by multiple objects/prefabs — for example, instead of every prefab instance carrying its own copy of unchanging config data in a MonoBehaviour (duplicated per instance), store it once in a ScriptableObject and have all instances reference it, reducing memory usage to a single copy. - **Saving/storing data during an Editor session** — this is why many Unity authoring tools, such as `EditorTool` and `EditorWindow`, are themselves built on `ScriptableObject`. - **Saving data as a project asset** to be consumed at runtime (game settings, spawn tables, tuning values, etc.). ## Risks & Pitfalls - **Editor-vs-build persistence mismatch**: values edited on a ScriptableObject asset in the Editor persist to disk, but at runtime in a built Player you can only read that data — script changes made in a build do not write back to the asset. Relying on runtime mutation of a ScriptableObject asset to persist across sessions in a shipped build will silently fail to save. - **Forgetting `EditorUtility.SetDirty`** after modifying a ScriptableObject via an Editor script — without it, the change appears to work in the current Editor session but reverts on reopening the Editor. - Because a ScriptableObject asset is a single shared instance, mutating its fields at runtime affects every object referencing it — appropriate for shared config, but a bug if you actually wanted per-instance data (in which case a plain data class or MonoBehaviour field may be more appropriate). ## Related Concepts - [[concepts/scripting-model]] - [[concepts/gameobjects-components-prefabs]] - [[concepts/coroutines]] - [[concepts/editor-and-projects]] ## Sources - raw/web_community-unity-manual-scriptableobject.md --- title: "The Unity Scripting Model" type: concept tags: [scripting, gameobjects, foundational, beginner] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-programming-in-unity.md", "raw/web_community-unity-manual-creating-scripts.md", "raw/web_community-unity-manual-monobehaviour.md", "raw/web_community-unity-manual-naming-scripts.md", "raw/web_community-unity-manual-fundamental-unity-types.md"] confidence: high unity_version: "6.0" --- ## Definition Programming in Unity means authoring project functionality in C# code rather than solely through the Editor UI, giving finer control by interacting directly with the public Unity APIs. Scripts are usually C# classes created inside Unity that either derive from `MonoBehaviour` (to become a custom Component attached to GameObjects), derive from `ScriptableObject` (to store data independent of GameObjects), or are plain, non-Unity classes. ## How It Works Unlike most assets, scripts are typically created directly within Unity: from the main menu via `Assets > Create > Scripting`, or from the Create (`+`) menu in the Project window toolbar via `Scripting`, selecting the type of script to create. This creates the file in the currently selected Project panel folder and opens the new file name for editing. A newly created `MonoBehaviour` script has boilerplate resembling: ``` using UnityEngine; using System.Collections; public class NewMonoBehaviourScript : MonoBehaviour { // Start is called once before the first execution of Update after the MonoBehaviour is created void Start() { } // Update is called once per frame void Update() { } } ``` The class derives from the built-in `MonoBehaviour` class, which is the framework that lets a script attach to a GameObject in the Editor as a Component and provides hooks into engine events (see [[concepts/event-lifecycle]]). A class is a blueprint: each time a script component is attached to a GameObject, Unity creates a new instance of that blueprint. The class name is taken from the file name at creation time, and it is best practice to keep the class name and file name in sync. A script only defines the blueprint — none of its code runs until an instance is attached to a GameObject, either by dragging the script asset onto a GameObject in the Hierarchy/Inspector, or via the Scripts submenu of the Component menu. Notably, `MonoBehaviour` objects are **not** initialized via a C# constructor — object construction is handled by the Unity Editor, not at the start of gameplay. Defining a constructor on a `MonoBehaviour` interferes with normal Unity operation and can cause major problems. Instead, `Start()` is the conventional place for one-time initialization, and `Update()` is the place for per-frame logic (movement, input handling, triggering actions). `Debug.Log(...)` is the basic mechanism for printing messages to the Console window (`Window > General > Console`) — e.g., calling `Debug.Log("Hello world!")` inside `Start()` confirms a script is running. `MonoBehaviour` also provides the API for starting, stopping, and managing **coroutines** (see [[concepts/coroutines]]), and access to a large set of **event functions** (see [[concepts/event-lifecycle]]). **Naming** matters beyond style. The file name given at script creation becomes the class name inside it, and it's good practice to keep them matching. For scripts derived from `MonoBehaviour` or `ScriptableObject`, Unity can still resolve the class even when the file name and class name diverge, but with limits: if multiple classes are defined in one file, Unity picks the one matching the file name; if the C# `partial` keyword splits one `MonoBehaviour`-derived class across multiple files, only the file matching the partial class's name can be used as a Component; and whenever a class name can't be unambiguously matched to a file, Unity shows a warning. To avoid class name collisions across a growing project (e.g., two developers each naming a class `Controller`), organize classes under C# **namespaces**, e.g. `namespace Enemy { public class Controller1 : MonoBehaviour { ... } }`, referenced fully as `Enemy.Controller1`, or shortened via `using Enemy;`. However, Unity enforces a specific limitation: **a file containing a MonoBehaviour or ScriptableObject definition cannot use multiple namespaces within that same file** — doing so produces the console warning "Class MyClass can not exist in multiple namespaces in the same file..." and Unity will not recognize the class as usable on GameObjects. This limitation was introduced in Unity 2020.1 to improve import/compilation speed. Underpinning all of this are Unity's **fundamental built-in classes**, which custom types inherit from to integrate with Editor and Engine functionality: `UnityEngine.Object` is the base class for all objects the Editor can reference from Inspector fields; `MonoBehaviour` (inherit to make a script a Component controlling GameObject behavior and respond to events); `ScriptableObject` (inherit to store data independent of GameObjects — see [[concepts/scriptableobjects]]); and Unity-specific C# **attributes**, which mark special behavior for code (e.g. `[InitializeOnLoad]`, `[RuntimeInitializeOnLoadMethod]`, discussed further in [[concepts/event-lifecycle]]). Beyond these class-level building blocks, day-to-day scripting also leans on core value types like `Vector3`, `Quaternion`, `Transform`, and `Time` for positions, rotations, hierarchy access, and frame/delta timing respectively. ## Key Parameters - **`MonoBehaviour`** — base class for GameObject-attached script components; provides event functions and coroutine support. - **`ScriptableObject`** — base class for data containers independent of any GameObject. - **`UnityEngine.Object`** — root base class for anything Inspector-referenceable. - Script creation paths: `Assets > Create > Scripting`, or the Project window `+` menu's `Scripting` submenu. - File-name/class-name matching, and the namespace-per-file limitation for MonoBehaviour/ScriptableObject files. ## When To Use Use `MonoBehaviour` scripts whenever behavior needs to live on a GameObject and react to engine events (movement, input, collisions, per-frame logic). Use `ScriptableObject` when you need shared or configuration data that shouldn't be duplicated per-instance or tied to a scene. Use plain C# classes for logic that has no need to plug into the Editor/Engine lifecycle at all. Adopt namespaces as soon as a project has more than a couple of contributors or a growing script count, to preempt class-name collisions — but keep MonoBehaviour/ScriptableObject definitions one-namespace-per-file. ## Risks & Pitfalls - Defining a constructor on a `MonoBehaviour` — breaks Unity's object lifecycle; use `Awake()`/`Start()` instead (see [[concepts/event-lifecycle]]). - Letting file name and class name drift apart, which can produce ambiguous-class warnings, especially combined with `partial` classes. - Mixing multiple namespaces inside a single file that also defines a MonoBehaviour or ScriptableObject — Unity will refuse to recognize the class as a usable Component. - Assuming a script does something just because it exists in the project — none of its code runs until an instance is attached to a GameObject. - Two teams/contributors independently naming classes identically (e.g., `Controller`) without namespacing, causing compiler ambiguity as the project scales. ## Related Concepts - [[concepts/gameobjects-components-prefabs]] — what scripts attach to - [[concepts/event-lifecycle]] — the event functions MonoBehaviour exposes and their order - [[concepts/coroutines]] — coroutine support provided by MonoBehaviour - [[concepts/scriptableobjects]] — the other fundamental base type for data - [[concepts/packages]] — how additional scripting APIs (Input System, UI Toolkit, etc.) arrive as packages ## Sources - raw/web_community-unity-manual-programming-in-unity.md - raw/web_community-unity-manual-creating-scripts.md - raw/web_community-unity-manual-monobehaviour.md - raw/web_community-unity-manual-naming-scripts.md - raw/web_community-unity-manual-fundamental-unity-types.md --- title: "UI Toolkit and Unity UI (uGUI)" type: concept tags: [ui, editor, foundational] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-ui-toolkit.md", "raw/web_community-unity-manual-unity-ui.md"] unity_version: "6.0" confidence: high --- ## Definition Unity ships two distinct systems for building user interfaces. **UI Toolkit** (formerly "UIElements") is the modern, web-inspired UI system: it structures UI with **UXML** (markup) and styles it with **USS** (a CSS-like stylesheet language), and it's built on a rendering system that sits directly on top of Unity's graphics device layer. **Unity UI** (package name `com.unity.ugui`, commonly called "uGUI") is the older, established, GameObject-based UI system: every UI element is a GameObject with Components, arranged and positioned in the Game View like any other object in a scene. You **cannot** use Unity UI to author or edit interfaces directly in the Unity Editor's UI-authoring tools the way you can with UI Toolkit's UI Builder — uGUI is authored by placing and configuring GameObjects in-scene. ## How It Works **UI Toolkit** workflow: - Structure UI in **UXML** or directly in C#. - Style UI with **USS** stylesheets. - Author visually with the **UI Builder**, a dedicated visual tool for creating and editing UXML/USS assets. - Handle interaction through an event system: elements receive input, touch, and pointer events, drag-and-drop, and other event types via a dispatcher/handler/synthesizer pipeline. - **Data binding** links element properties directly to backing data/control values. - UI Toolkit supports both **Editor UI** (custom inspectors, EditorWindows) and **runtime UI** (in-game UI), and includes text support, testing/debugging tools, and migration guides for moving from uGUI or IMGUI. **Unity UI (uGUI)** workflow: - Build interfaces as GameObjects (Canvas, Panels, Buttons, Text, Images, etc.) with Components, positioned and arranged in the Game View using the standard Scene/Inspector workflow familiar from any other GameObject. - Because it's GameObject-based, it composes naturally with the rest of the scene graph, prefabs, and existing MonoBehaviour scripting patterns — see [[concepts/gameobjects-components-prefabs]]. - Unity UI is a **core package** — its version is fixed to match the Editor version, so it doesn't need independent version management the way optional packages do (see [[concepts/packages]]). ## Key Parameters - **Authoring format**: UXML/USS (UI Toolkit) vs. GameObjects/Components/Canvas (uGUI). - **Editor-time authoring**: UI Toolkit has a dedicated visual editor (UI Builder) and can build Editor-only tooling (custom inspectors, EditorWindows); uGUI cannot be used to build Editor UI. - **Event handling model**: UI Toolkit uses its own dispatcher-based event system; uGUI uses the standard Unity Event System / EventSystem GameObject and MonoBehaviour callbacks. - **Rendering**: UI Toolkit's runtime UI uses UI Renderer, built directly on Unity's graphics device layer. ## When To Use - **UI Toolkit** is Unity's forward-looking system: prefer it for new projects, for Editor tooling (custom windows/inspectors — it's the only option of the two for this), for UI that needs to scale across many screen sizes/resolutions with CSS-like styling, and for teams that want a data-binding-driven, web-like authoring workflow. - **Unity UI (uGUI)** remains the established, widely-documented system with the largest base of existing tutorials, asset-store content, and production track record. Prefer it when working in an existing uGUI-based project, when relying on third-party assets/plugins built for uGUI (see [[entities/unity-ecosystem]]), or when a team's existing GameObject-based workflow and muscle memory outweigh the benefits of switching. - Consult Unity's official "Comparison of UI systems in Unity" resource (linked from the UI Toolkit manual page) before starting a new project's UI architecture. ## Risks & Pitfalls - Treating the two systems as freely interchangeable: they have different authoring formats, event models, and (partially) different terminology; mixing them in the same project is possible but adds complexity. - Assuming Unity UI can be used to build Editor windows/inspectors — it cannot; that's UI Toolkit's job. - Migrating an existing uGUI project to UI Toolkit (or vice versa) is a nontrivial migration, not a drop-in swap — Unity provides dedicated migration guides because of this. - IMGUI (the legacy IMGUI UI system, `OnGUI`) is a separate, older system still referenced in Unity's event-function docs; it is not recommended for new UI work and adds per-frame overhead even when its callback body is empty. Don't confuse it with either UI Toolkit or uGUI. ## Related Concepts - [[concepts/gameobjects-components-prefabs]] — uGUI elements are ordinary GameObjects/Components. - [[concepts/packages]] — Unity UI is a core package; UI Toolkit ships as part of the Editor. - [[entities/unity-ecosystem]] — third-party UI assets (e.g., NGUI, TextMesh Pro) built around these systems. - [[concepts/event-lifecycle]] — how UI/input events relate to the MonoBehaviour event-function sequence. ## Sources - raw/web_community-unity-manual-ui-toolkit.md - raw/web_community-unity-manual-unity-ui.md --- title: "Unity Ecosystem Catalog" type: entity tags: [packages, scripting, ui, animation, foundational] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-readme-md.md"] unity_version: "6.0" confidence: low --- ## Overview This page is a **catalog** of third-party tools, frameworks, libraries, and learning resources for Unity, drawn from the community-maintained "awesome-unity" list. It exists so an agent can quickly answer "is there a tool for X?" without re-deriving the ecosystem from scratch. The source list is a community-curated collection (originally hosted at github.com/RyanNielson/awesome-unity) and has since been **archived by its maintainer** — treat every specific entry as a historically-documented option, not a live recommendation. Many linked entries reference older Unity versions and Asset Store URLs; before adopting any tool, verify it against the current Unity 6 Asset Store / Package Manager / GitHub status, as maintenance state may have changed since the list was last updated. This catalog is **low** confidence by design — it's an unverified index, not confirmed current guidance. ## Characteristics Catalog, grouped by category as in the source list: **2D** - 2D Rope System (Paid) — scripts for 2D ropes in-editor or at runtime. - Ferr2D Terrain Tool (Paid) — handcrafted 2D landscapes/levels. - Pixel Camera 2D — pixel-perfect camera with scaling for 2D games. - Spine (Paid) — skeletal animation editor with a Unity runtime library. - Tiled2Unity — converts Tiled map editor files into Unity prefabs, with PolygonCollider2D support for complex collision. - Unity Anima2D — skeletal animation editor (per-object and skinned mesh); superseded by Unity's own 2D Animation package. - UnityTiled — importer for Tiled maps. **AI** - A* Pathfinding Project — optimized pathfinding algorithms, large feature set. - Apex Path (Paid) — dynamic pathfinding with local avoidance steering and dynamic obstacles. - Crystal AI — utility-based AI framework for C#/Unity. **Augmented & Virtual Reality** - ARToolKit — AR SDK (libraries, utilities, examples). - Google VR SDK — Daydream/Cardboard app support for Android/iOS. - SteamVR Unity Toolkit / Virtual Reality Toolkit (VRTK) — VR controller interaction abstractions, locomotion, visual effects. - Vuforia — AR SDK with image/object recognition and terrain tracking. **Camera** - UFPS (Paid) — camera, controllers, and effects for FPS games. **Character Controllers** - CharacterController2D — 2D controller mirroring Unity's built-in CharacterController API shape. **Frameworks** - Fungus — library for illustrated Interactive Fiction games. - StrangeIoC — lightweight Inversion-of-Control framework for C#/Unity. - uFrame (Paid) — game architecture framework for maintainable, consistent codebases. **Input** - InControl — cross-platform input manager. - InputBinder — bind inputs to methods via code or Inspector. - TouchKit / TouchScript — gesture and touch-input recognition. (See also Unity's own [[concepts/input-system|Input System]] for the current first-party option.) **Modeling** - SabreCSG — CSG-based level-design tools for building complex levels in-editor. **Monetization** - Unity Monetization (Unity Ads) — video ad network with regular/opt-in ad integration. **Networking** - Nakama — open-source distributed server for social/realtime games. - Photon Bolt (Paid) / Photon Unity Networking — networked-game middleware; PUN free for up to 20 concurrent users. **Scripting** - Easy Save 2 (Paid) — cross-platform save/load data utility. - UniStorm (Paid) — dynamic day/night weather system with storms and cloud shadows. **Services** - Unity Analytics — dashboard for player/session/retention/revenue metrics. **Tweening** - DOTween — numeric/Vector/string tweening; successor to HOTween. - GoKit — lightweight tween library. - iTween — simple animation/tweening system. - LeanTween — free, lightweight tweening library, tweens arbitrary values via `.value()`. **UI** - NGUI (Paid) — UI system and event-notification framework (predates uGUI's dominance; compare [[concepts/ui-toolkit]]). - TextMesh Pro — distance-field text rendering for crisp text at any scale; now integrated into Unity itself as a core package. **Utilities** - Consolation — in-game debug console surfacing `Debug.Log` output. - GitHub for Unity — GitHub workflow integration, Git LFS and file-locking support. - Grouping Tool — group scene objects easily. - Scene View Bookmarks — bookmark/recall Scene View camera positions. - SnazzyGrid (Paid) — snapping/grid tools for scene object placement. - UniMerge (Paid) — scene/prefab merge tool with VCS integration. (Relevant to prefab-merge conflicts — see [[syntheses/common-gotchas]].) - UniRx — Reactive Extensions (Rx) reimplementation for Unity/C#. - UnityToolbag — miscellaneous open-source scripts/helpers. **Video** - Vimeo Unity SDK — stream Vimeo videos into Unity, or record/publish to Vimeo. **Visual Scripting** - Playmaker (Paid) — finite-state-machine-based visual scripting for prototypes, AI behaviors, animation graphs, interactive objects. **Example Projects** - Nodulus — a complete puzzle game, playable online, as a reference project. **Learning Resources** - Tips & tricks: Editor Tips (gif-based editor efficiency tips), Unity Labs' Super Science (open-source gems for education), Unity Tips (official short tutorial videos). - Tutorials: 2D splatter effects via stencil buffer, "A Gentle Introduction to Shaders in Unity3D", Amit's Game Programming Information, Catlike Coding (C# scripting tutorials), sprite-gap-fixing tutorial, Game Programming Patterns, "Modern GUI Development in Unity 4.6" (historical uGUI intro), official video tutorials, Ray Wenderlich's Unity tutorials, Unity/HoloLens development tutorials, Unity's official VR documentation. ## How to Use - Treat this page as a **lookup index**: search it by category (2D, AI, Networking, Tweening, UI, etc.) before assuming "there's no tool for that" in the Unity ecosystem. - Always cross-check an entry's current maintenance status and Unity-6 compatibility before recommending it for a new project — the source list is archived and several entries (e.g., Unity Anima2D, NGUI) reference functionality Unity has since absorbed into first-party systems (2D Animation package, uGUI/UI Toolkit). - For first-party equivalents to catalog entries, prefer linking to this KB's own concept pages: [[concepts/input-system]] over third-party input assets, [[concepts/ui-toolkit]]/uGUI over NGUI, [[concepts/animation]] over legacy tweening/animation assets where Mecanim already covers the need. ## Related Entities - No other entity pages exist yet in this KB; this is currently the sole `wiki/entities/` page. Link future entity pages here as they are added (e.g., specific packages profiled individually). ## Related Concepts - [[concepts/packages]] — how first-party and some third-party packages are installed/managed via UPM, as an alternative to Asset Store assets listed here. - [[concepts/input-system]] — first-party alternative to the catalog's Input-category assets. - [[concepts/ui-toolkit]] — first-party alternative/successor to catalog UI assets like NGUI. - [[concepts/animation]] — first-party Mecanim system, relevant when comparing to catalog tweening/animation tools. - [[syntheses/common-gotchas]] — prefab-merge tooling (UniMerge) relates to the prefab-override gotcha. ## Sources - raw/web_community-readme-md.md --- title: "Activity Log" type: log --- # Activity Log ## 2026-07-17 — XL (Pro) tier built: 14 per-item reference pages **Triggered by:** user request to curate an XL tier for Unity after the base shipped. **Gathered (additive):** 40 deep-reference sources into raw/ (xl-* prefix): 13 Unity 6 ScriptReference class pages, 9 Input System 1.14 manual pages, 9 physics component pages, 6 animation pages, 3 HDRP pages. URP deep pages are JS-rendered (extracted empty) — deferred. **Built `wiki-xl/` (14 reference pages, type: reference / edition: xl, each links up to its standard parent):** 5 Scripting API (scripting-api-monobehaviour, -transform-gameobject, -math-types, -physics-and-camera, -time-and-objects), 3 Input System (input-system-actions-and-assets, -playerinput, -devices-and-controls — these close the gaps the base input-system page flagged), 2 physics (physics-colliders-reference, physics-joints-and-collision), 3 animation (animation-animator, -state-machines, -clips), 1 rendering (hdrp-reference). Added wiki-xl/index.md. **Base tier touched:** wiki/concepts/input-system.md gap note now points to the XL pages instead of flagging the topics as unsourced; wiki/index.md gained an "XL Edition (Pro)" section. **Honesty notes:** ScriptReference index pages carry member names + one-line descriptions, not per-overload signatures (sub-pages unmirrored) — XL API pages are complete member catalogs. Several Manual landing pages (state machines, blend trees, CharacterController scripting, CCD tuning) are topic indexes; deep property tables live on unfetched sub-pages, flagged inline. URP deep-reference pending a JS-capable fetch. **Gaps for a future XL pass:** URP deep reference; per-overload C# signatures for the Scripting API classes; the sub-page property tables noted above. --- ## 2026-07-17 — Initial build (medium rung, core-dev scope) **Triggered by:** user request for a Unity wiki, scoped to "core Unity for developers." **Gathered:** 31 sources. Unity has no llms.txt and no official docs repo; docs_crawl only followed one hop, so sources are a curated web_urls list of Unity 6 Manual core-dev pages (docs.unity3d.com/6000.0) verified to resolve, plus 3 Input System package-manual pages (Concepts/Quickstart/Actions) fetched to ground the input page, plus the archived awesome-unity community list. Script Reference (the separate per-class API site) intentionally excluded. **Built (17 pages):** 14 concepts (overview, editor-and-projects, gameobjects-components-prefabs, scripting-model, event-lifecycle, coroutines, scriptableobjects, physics, input-system, ui-toolkit, rendering-pipelines, animation, packages, performance-best-practices), 1 entity (unity-ecosystem — catalog from the archived awesome-unity list, confidence low by design/framed as historical), 2 syntheses (render-pipeline-picker Built-in/URP/HDRP, common-gotchas casebook). **Honesty notes (proof discipline):** input-system was first drafted from general knowledge (its only source was a package stub) — re-grounded against 3 real manual pages; the re-ground refused to state PlayerInput/control-schemes/callback-phases since those don't appear in the mirrored sources, and flagged them as coverage gaps rather than fabricating. performance-best-practices rests on best-practice-guides only (the UnderstandingPerformance page didn't gather). unity-ecosystem's source list is archived/unmaintained — page treats entries as historical, not live recommendations. **Gaps for a future pass:** mirror Input System PlayerInput + control-scheme pages; add the UnderstandingPerformance deep-dive; 2D/sprites, netcode, animation state-machine depth are out of the core-dev scope. --- Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion --- title: "Common Unity Gotchas: A Casebook" type: synthesis tags: [scripting, physics, gameobjects, performance, beginner, intermediate] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-event-functions.md", "raw/web_community-unity-manual-event-function-execution-order.md", "raw/web_community-unity-manual-scriptableobject.md", "raw/web_community-unity-manual-prefabs.md", "raw/web_community-unity-manual-rigidbody-component-reference.md", "raw/web_community-unity-manual-rigidbody-physics.md", "raw/web_community-unity-manual-physics.md"] unity_version: "6.0" confidence: high --- ## Comparison This synthesis is organized as a casebook rather than a table: each entry names a mistake, explains the underlying mechanism, and cites the source it's drawn from. | Gotcha | Underlying mechanism | Source | |---|---|---| | Physics code placed in `Update` instead of `FixedUpdate` | Physics updates on a separate, fixed time step from frame rendering | event-functions.md | | Relying on execution order between different GameObjects' same event function | Unity does not guarantee this order except where explicitly documented/settable | event-function-execution-order.md | | ScriptableObject edits made via script in Edit mode silently not persisting | Unity only auto-saves ScriptableObject edits made through Inspector/authoring tools, not through arbitrary script mutation | scriptableobject.md | | Prefab instance overrides silently lost or misunderstood | Prefab instances store per-instance overrides layered on top of the source asset | prefabs.md | | Rigidbody movement fighting Transform-based movement | Is Kinematic toggles whether physics or Transform edits control the GameObject | rigidbody-component-reference.md | | Jittery Rigidbody motion | Physics updates and frame renders don't share a time step; no interpolation set | rigidbody-component-reference.md | | Fast-moving Rigidbody tunneling through walls | Default Discrete collision detection isn't built for high-speed collisions | rigidbody-component-reference.md | | Wrong physics engine assumed for project type | Object-oriented (PhysX/Box2D) vs. DOTS (Unity Physics/Havok Physics) projects need different physics packages | physics.md | ## Analysis **1. Physics logic in `Update` instead of `FixedUpdate`.** The frame-rendering loop (`Update`) and the physics simulation loop (`FixedUpdate`) run on different, independently-ticking schedules — Unity's docs state plainly that "since the physics updates and frame updates don't occur with the same frequency, you can get more accurate results from physics code if you place it in the `FixedUpdate` function rather than `Update`." Applying forces, setting velocity, or moving a Rigidbody inside `Update` produces frame-rate-dependent, inconsistent physics behavior. The fix is mechanical: any code that reads or writes Rigidbody state belongs in `FixedUpdate`, not `Update` or `LateUpdate`. **2. Assuming execution order across GameObjects (or even within a script instance).** Unity's own execution-order documentation is explicit about its **Limitations**: "In general, you can't rely on the order in which the same event function is invoked for different GameObjects, except when the order is explicitly documented or settable," and "You can't specify the order in which an event function is called for different instances of the same MonoBehaviour script." A script that assumes its `Awake`/`Start`/`Update` runs before or after a sibling or parent/child object's equivalent callback is relying on undefined behavior. Where cross-object ordering genuinely matters, use `Awake` for self-contained initialization (all `Awake` calls finish before any `Start` call, so `Start` can safely reference state set up in another object's `Awake`) or explicit **Script execution order** settings — see [[concepts/event-lifecycle]]. **3. ScriptableObject edits made via script not persisting.** In the Editor, changes made through the Inspector or Unity's own authoring tools to a ScriptableObject asset are automatically written to disk. But "Unity doesn't automatically save changes to a ScriptableObject made via script in Edit mode" — an Editor script or tool that mutates a ScriptableObject's fields directly must call `EditorUtility.SetDirty()` on it, or the change appears to work in the current session but silently reverts the next time the Editor is closed and reopened. This is a frequent source of "my custom editor tool's changes keep disappearing" bug reports. See [[concepts/scriptableobjects]]. **4. Prefab instance overrides misunderstood.** Prefabs store a template asset plus, per placed instance, a layer of instance-specific overrides (components, data, child GameObjects). Developers who don't understand this layering can be surprised when: editing the source prefab asset doesn't propagate to an instance because the instance has an override on that property; or "reverting" an instance removes changes they intended to keep. Unity's prefab documentation explicitly separates "Overriding prefab instance data" from "Revert a prefab instance to a GameObject" as distinct operations — know which one you're invoking. See [[concepts/gameobjects-components-prefabs]]. **5. Rigidbody vs. Transform movement conflict.** A Rigidbody's `Is Kinematic` flag determines who's allowed to move the GameObject: when enabled, "the physics system cannot apply forces to move or rotate the GameObject, instead, Unity can only move and rotate it via its Transform." Mixing paradigms — e.g., leaving Is Kinematic off while also directly setting `transform.position` on a dynamic Rigidbody — fights the physics engine and produces unpredictable collision behavior. **6. Jittery Rigidbody motion.** Because physics poses are computed on the fixed-update schedule while rendering happens on the frame schedule, a Rigidbody's visual motion can appear jittery. Unity's `Interpolate` property (None / Interpolate / Extrapolate) exists specifically to smooth this mismatch — Interpolate uses the previous two physics poses (more accurate, one-step lag); Extrapolate predicts ahead (can look smoother but is less accurate, best for constant-velocity cases). Leaving this at the default (**None**) is fine until jitter is visibly a problem, at which point picking the wrong one of Interpolate/Extrapolate for the use case is itself a common secondary mistake. **7. Fast objects tunneling through geometry.** The default **Collision Detection** setting on a Rigidbody is **Discrete**, which is inexpensive but not designed for fast-moving objects — they can pass straight through thin colliders between physics steps ("tunnelling"). Continuous / Continuous Dynamic / Continuous Speculative trade CPU cost for tunnelling resistance; picking Discrete for a bullet, projectile, or otherwise fast-moving object is a classic gotcha. **8. Wrong physics engine/package for the project's architecture.** Unity offers built-in 3D (PhysX) and 2D (Box2D) physics for object-oriented projects, but a **separate set of DOTS-specific packages** (Unity Physics, optionally extended by Havok Physics) for projects built on the Data-Oriented Technology Stack. Assuming the object-oriented Rigidbody/Collider APIs apply unchanged inside a DOTS/ECS project (or vice versa) is a category error the physics manual calls out directly by presenting them as separate installation paths. ## Recommendations - Put all Rigidbody-affecting code in `FixedUpdate`; reserve `Update` for input/logic and `LateUpdate` for camera-follow/animation-override work (per [[concepts/event-lifecycle]]). - Never assume cross-GameObject or cross-instance execution order; use `Awake` for self-init and Script Execution Order settings when explicit ordering is required. - Any Editor-time script that mutates a ScriptableObject must call `EditorUtility.SetDirty()` (and `AssetDatabase.SaveAssets()` if immediate persistence is needed) or changes will silently revert. - Before editing a prefab instance, know whether the change should apply to the shared asset (edit the prefab) or just this placement (instance override) — and know which button ("Revert" vs. manually clearing an override) does which. - Set `Is Kinematic` deliberately: on for Transform-driven movement, off for physics-driven movement — don't drive both simultaneously. - Only reach for Interpolate/Extrapolate once jitter is actually observed, and match the choice to whether the object's velocity is variable (Interpolate) or roughly constant (Extrapolate). - Set Collision Detection to a Continuous mode for any fast-moving Rigidbody that must not tunnel through static geometry. - Confirm object-oriented vs. DOTS project architecture before choosing a physics package. ## Pages Compared - [[concepts/event-lifecycle]] - [[concepts/scriptableobjects]] - [[concepts/gameobjects-components-prefabs]] - [[concepts/physics]] - [[concepts/performance-best-practices]] --- title: "Render Pipeline Picker: Built-In vs URP vs HDRP" type: synthesis tags: [rendering, foundational] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/web_community-unity-manual-render-pipelines.md", "raw/web_community-unity-manual-introduction-to-render-pipelines.md", "raw/web_community-unity-manual-camera-inspector-window-reference-for-the-built.md", "raw/web_community-unity-manual-lighting.md"] unity_version: "6.0" confidence: high --- ## Comparison | Dimension | Built-In Render Pipeline | Universal Render Pipeline (URP) | High Definition Render Pipeline (HDRP) | |---|---|---|---| | Type | Original, general-purpose pipeline | Scriptable Render Pipeline (SRP) | Scriptable Render Pipeline (SRP) | | Customization from C# | Limited; deep customization requires purchasing Unity engine C++ source access | Full — culling/rendering/post-processing exposed to C# | Full — culling/rendering/post-processing exposed to C# | | Target platforms | Broad/legacy, general purpose | Wide range, scalable — mobile through high-end desktop/console | High-end platforms only (PC, consoles) | | Visual fidelity ceiling | Moderate | Scalable (moderate to good, tuned for reach) | Highest — cutting-edge, high-fidelity graphics | | Orthographic + deferred | Deferred not supported in Orthographic camera mode (forward always used) | Pipeline-specific rendering path config | Pipeline-specific rendering path config | | Current status in Unity 6 | Supported, but not the default recommendation for new advanced-graphics projects | Actively developed default recommendation for most projects | Actively developed, recommended only for high-end targets | | Lighting workflow | Own lighting workflow ("Lighting in the Built-In Render Pipeline") | Own lighting workflow ("Lighting in URP") | Own advanced lighting/environment system | | Shader/asset portability | Not directly portable to URP/HDRP | Not directly portable to Built-In/HDRP | Not directly portable to Built-In/URP | | Custom SRP option | N/A (not SRP-based) | Can be extended/forked as a custom SRP | Can be extended/forked as a custom SRP | ## Analysis All three pipelines implement the same conceptual pipeline — culling → rendering → post-processing (see [[concepts/rendering-pipelines]]) — but differ in how much of that pipeline is exposed and tuned for which hardware tier: - The **Built-In Render Pipeline** trades customizability for simplicity and broad applicability; it's the path of least resistance for a straightforward or legacy project but the most limited when advanced graphics control from script is needed. - **URP** is deliberately the "scalability" choice: it's built as an SRP specifically so that the *same* pipeline architecture can run acceptably from mobile to high-end desktop, at the cost of not reaching HDRP's fidelity ceiling. - **HDRP** commits fully to high-end visual fidelity and sacrifices reach — it is explicitly scoped to high-end platforms only, not mobile or low-spec targets. - Because shaders and pipeline-specific assets don't transfer cleanly between the three, the choice of pipeline is effectively a **project-founding decision**: it should be made deliberately at project start rather than revisited casually mid-project. - Camera behavior (e.g., Orthographic mode forcing forward rendering) and lighting configuration are pipeline-aware — workflows for lighting and camera setup differ across all three, so a lighting or camera tutorial written for one pipeline may not directly apply to another. ## Recommendations - **Pick the Built-In Render Pipeline if**: maintaining or extending an existing legacy project already built on it, or the project genuinely doesn't need SRP-level rendering customization and simplicity/familiarity is valued over long-term pipeline investment. Not recommended as a fresh default for new Unity 6 projects with any graphics ambition. - **Pick URP if**: the project needs to run across a wide range of hardware (mobile, cross-platform, indie/mid-scale titles), the team wants direct C# control over rendering without committing to high-end-only hardware, or there's no strong reason to need HDRP's fidelity ceiling. This is Unity's default recommendation for most new projects. - **Pick HDRP if**: the project targets high-end PC/console exclusively and needs cutting-edge visual fidelity (advanced lighting, environment effects, and post-processing) and the team accepts the narrower platform reach. - **Write a custom SRP only if**: the team includes experienced graphics engineers with bespoke rendering requirements that neither URP nor HDRP can satisfy — this is a significant, ongoing engineering investment, not a shortcut. - Whichever pipeline is chosen, treat it as fixed for the life of the project unless a deliberate, budgeted migration is planned — see [[concepts/rendering-pipelines]] risks & pitfalls. ## Pages Compared - [[concepts/rendering-pipelines]] - [[concepts/performance-best-practices]]