> For the complete documentation index, see [llms.txt](https://niam.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://niam.gitbook.io/documentation/game-creator-2/inline-variables/introduction.md). # Introduction This page introduces the motivation behind the package, explains what problems it solves, and provides a high-level conceptual map of its features. Inline Variables let you create **temporary variables directly inside an Instruction List**. They are designed for values that only matter while a sequence of instructions is running: a filtered list of enemies, a loop counter, a temporary damage value, or any other piece of state that you need briefly but don't want to store permanently. Think of them as **scratch variables for your instruction flow**: ``` Create temporary value ↓ Use it in several instructions ↓ Instruction List finishes ↓ Variable is automatically discarded ``` You don't need to create a variable component, create a Global Variable asset, or remember to clean up the value afterward. ## Why Inline Variables? GC2's regular variable system is designed for data that has a meaningful lifetime beyond a single instruction sequence. * **Local Variables** belong to a GameObject and can be shared by instruction flows that access that object. * **Global Variables** belong to the project and are available across scenes and instruction flows. That's exactly what you want for persistent or reusable state. But not every value deserves that lifetime. Consider an instruction flow that finds all enemies within range, processes each one, and calculates some temporary result: ``` Find enemies in range ↓ Store the result ↓ For Each enemy ↓ Calculate temporary value ↓ Use the value ``` None of these intermediate values necessarily need to exist after the flow finishes. Without Inline Variables, you would typically have to use a Local or Global Variable as temporary "scratch space". This introduces unnecessary state and can make instruction flows harder to maintain. It can also become problematic when the same instruction flow runs multiple times at once: two executions may end up reading and writing the same temporary variable. **Inline Variables solve this by making the lifetime of the variable match the lifetime of the instruction flow that uses it.** ## The Solution An Inline Variable is declared directly in an `InstructionList` and is available to the instructions that execute within its scope. When the execution finishes, the inline variable is automatically discarded. For example: ``` Instruction List │ ├─ Declare Inline Variable: Damage │ ├─ Calculate Damage │ ├─ Apply Damage │ └─ End ↓ Damage is discarded ``` This means you can create state exactly where you need it without adding permanent state to your scene or project. ### Execution Isolation Inline Variables are also isolated between executions. Each execution has its own variable context, identified through GC2's `Args` execution context. If the same Instruction List runs simultaneously for multiple objects, each execution gets its own inline variables. For example: ``` Enemy A → Instruction List → Damage = 20 Enemy B → Instruction List → Damage = 50 ``` The two executions do not overwrite each other's `Damage` value. This makes Inline Variables particularly useful for **temporary state in reusable and concurrently executed instruction flows**. ## Types of Inline Variables Inline Variables currently come in two main forms. ### Inline Name Variable An Inline Name Variable stores a value under a name. For example: ``` Damage = 25 ``` The variable can then be read or modified by subsequent instructions in the same scope. Use an Inline Name Variable when you need a **single temporary value**.\ Use an Inline Name Variables (plural) when you need declare **multiple temporary value** at once. Typical examples include: * A temporary number * A calculated position * A selected GameObject * A boolean condition * A temporary string * An intermediate result from another instruction ### Inline List Variable An Inline List Variable stores an ordered collection of values. For example: ``` Targets = [Enemy A, Enemy B, Enemy C] ``` Use an Inline List Variable when you need to temporarily collect, filter, or process multiple values. Typical examples include: * Enemies found by a physics query * Characters within a radius * Child transforms * Results collected during an instruction flow * Values that need to be processed with `For Each` ## Scope and Lifetime Inline Variables have two related concepts of lifetime: **Execution lifetime** determines how long the variable exists at all. An inline variable belongs to the execution of its `InstructionList`. When that execution finishes, the variable is cleaned up automatically. **Scope lifetime** determines which instructions can see the variable. Control-flow instructions can create nested scopes. A nested scope can access variables from its parent scope, while variables declared inside the nested scope disappear when that scope ends. For example: ``` Outer Scope │ ├─ Damage = 10 │ ├─ If Condition │ │ │ ├─ Bonus = 5 │ │ │ └─ Use Damage + Bonus │ └─ Use Damage ``` Here, `Damage` is visible inside the nested `If` scope, while `Bonus` only exists inside that nested scope. ### Variable Shadowing Nested scopes can declare a variable with the same name as one in an outer scope. When this happens, the innermost declaration takes precedence. ``` Outer Scope │ ├─ Value = 10 │ └─ Nested Scope │ ├─ Value = 20 │ └─ Use Value → 20 ``` The outer `Value` still exists, but references inside the nested scope resolve to the inner `Value`. ## Choosing the Right Variable Type A useful rule is: > **Give a variable the smallest lifetime and scope that makes sense for its job.** | Requirement | Local Variable | Global Variable | Inline Variable | | ---------------------------------------- | ------------------------- | ------------------------- | --------------- | | Temporary execution state | — | — | ✅ | | Automatically cleaned up | — | — | ✅ | | Declared directly in an Instruction List | — | — | ✅ | | Shared through a GameObject | ✅ | — | — | | Shared project-wide | — | ✅ | — | | Intended to survive an instruction run | ✅ | ✅ | — | | Isolated between concurrent executions | Depends on how it is used | Depends on how it is used | ✅ | ### Use Inline Variables when... The value is an **intermediate result** or **temporary state** that only exists to support one instruction flow. Examples: * A temporary calculation * A list of objects being processed * A loop-related value * A value passed between several instructions * Scratch state needed during a reusable instruction sequence ### Use Local Variables when... The value belongs to a **GameObject** and should remain available beyond the current instruction execution. Examples: * A character's persistent state * A component-specific setting * Data that multiple instruction flows on the same object need to access ### Use Global Variables when... The value represents **project-wide state** or needs to remain available across scenes or independent instruction flows. Examples: * Game settings * Persistent progression * Global counters * Shared project state ## A Simple Mental Model If you're unsure which type to use, ask: **"How long should this value exist?"** ``` Only while this instruction flow runs? ↓ Inline Variable For the lifetime of this GameObject? ↓ Local Variable Across the whole project? ↓ Global Variable ``` This keeps temporary state close to the instructions that use it while reserving Local and Global Variables for data that genuinely needs a broader lifetime. ## How Inline Variables Work Internally, Inline Variables are managed by an `InlineVariablesManager`. The manager maintains a stack of variable scopes for each GC2 `Args` execution context. When a new scope begins, a scope is pushed onto the stack. When that scope ends, it is popped automatically. Variable lookup starts with the innermost scope and continues outward. This provides: * **Automatic cleanup** * **Nested scopes** * **Variable shadowing** * **Execution isolation** * **No manual teardown** You normally don't need to interact with the manager directly. It exists to provide the runtime behavior that makes Inline Variables feel like ordinary variables while keeping their lifetime tied to InstructionList execution. Once you understand the basic rule— > **Inline Variables are temporary state belonging to an InstructionList execution.** —the rest of the system follows naturally.