> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/gum-tool/gum-elements/general-properties/variable-references.md). # Variable References ## Introduction `Variable References` allows any variable on an instance or component to reference other variables. These other variables can be on the same instance or component, a different instance, or even variables from a different component.

Component setting its Height relative to its Width

One common use of `Variable References` is to create a centralized style component which can be referenced throughout a Gum project. Variables which are assigned through `Variable References` cannot be directly set on the instance - the value obtained through the reference overwrites any custom value. For example, the reference `Height = Width` results in Height being read-only and depending on Width. Note that this is using a shorthand variable assignment which is discussed in later sections.

Height is assigned to Width, so it is read only

{% hint style="info" %} Variable references can also be re-evaluated at runtime to support theming and dynamic styling. For details, see [Runtime Variable References](/gum/code/styling/runtime-variable-references.md). {% endhint %} {% hint style="info" %} Variable references mimic the C# syntax, but provide only a subset of C# functionality. Future versions of Gum may expand supported syntax. If your project requires additional functionality, please post an issue on GitHub, or make a request in the Discord server. {% endhint %} ## Variable Reference Syntax `Variable References` can contain multiple lines. Each line is a separate variable reference. Each variable reference uses the following syntax: ```csharp {Variable} = {Components or Screens}/{ComponentOrScreenName}.{Instance}.{Variable} ``` For example, to assign a Component's X value to a different component's X value, the following syntax could be used: ```csharp X = Components/OtherComponent.X ``` ### Variable Assignment Reference X references the X value in OtherComponent. Note that X could be the X value on any component or any instance inside of a component: ``` X = Components/OtherComponent.X ``` Spaces are optional around the equals sign, but spaces are not allowed in variable names. The following lines are okay: ```csharp Y=Components/OtherComponent.Y Width = Components/OtherComponent.Width ``` However, the following is not allowed: ```csharp // Spaces are not allowed, so Gum would comment this reference: X Units = Components/OtherComponent.X Units ``` {% hint style="info" %} Previous versions of Gum included spaces in some variable names. The public release of Gum in February 2025 has removed all spaces to simplify the syntax. For more information, see the [Removal of Variable Spaces](/gum/gum-tool/upgrading/breaking-changes/removal-of-variable-spaces.md) page. {% endhint %} Lines can be commented out to disable the reference. If Gum encounters a scripting error, it will automatically comment out lines as well so that you can make corrections: ```csharp // This is considered a comment so it will not run // Neither will this: // X = Components/OtherComponent.Y ``` An Instance can reference its own Component's X value by using the qualified name: ```csharp X = Components/ComponentContainingThisInstance.X ``` An instance or component can reference the variable of another instance in the same component by using the name of the instance. The name of the containing component or screen is not required if the instances are both in the same component or screen: ```csharp Width = OtherInstanceInSameComponent.Width ``` Components and instances can reference variables that are contained within instances of other components. In this case the name of the referenced instance is appended to the qualified name of the Screen or Component: ```csharp Red = Components/StyleComponent.PrimaryColorRectangle.Red ``` Elements and Screens inside subfolders can be referenced. The subfolder path is included with forward slashes: ```csharp XUnits = Components/ComponentFolder/ComponentInFolder.XUnits ``` The *right side* can be a variable in a Screen, although this isn't too common in practice: ```csharp Green = Screens/MainMenuGum.ColoredRectangleInstance.Green ``` Similarly, variables on Standards can also be referenced. This is also quite rare, since this modifying the Standard element also has side effects on every other instance that is of the same type: ```csharp YUnits = Standards/Text.YUnits ``` Although it's common for variables to reference the same variable on a different object (such as X being set to another object's X value), this is not a requirement. For example, the following lines are valid: ```csharp Y = OtherInstance.X Width = Components/OtherComponent.Height ``` Instances can reference their own variables, but these must be qualified. For example, ColoredRectangleInstance can assign its Width to equal its own Height. The [`@` prefix](#referencing-the-owning-instance-with) is a shorter way to write the same thing: ```csharp Width = ColoredRectangleInstance.Height // is equivalent to: Width = @Height ``` {% hint style="warning" %} A name with no qualification always means the **containing component or screen**, including on an instance. `X = Height` on an instance reads `Height` from the containing component, not from the instance. Gum does not change what you type. To reference the instance's own `Height`, qualify it (`X = ColoredRectangleInstance.Height`) or use `@Height`. {% endhint %} Variables can be assigned to constant values, essentially locking the value: ```csharp X = 100 Text = "Hello" Visible = true ``` Math operations can be used in variable assignments. This includes add, subtract, multiply, divide, modulo (`%`, the remainder after dividing), and parenthesis to control order of operations: ```csharp Y = (TitleText.Y + 2) * 7 - 4 ``` Modulo is useful for repeating patterns. For example, a ternary can pick a color for every fourth item (see [Conditional (Ternary) Expressions](#conditional-ternary-expressions)): ```csharp Red = @Index % 4 == 0 ? 255 : 100 ``` Math operations can reference both constant values (1, 2, 3) or other variables: ```csharp Width = (OtherInstance.Height * 3) + 10 ``` ## Conditional and Logical Expressions Variable references support conditional (ternary) expressions, comparison operators, and logical operators. These can be combined to drive variable values from boolean conditions or to switch between values based on other variables. ### Conditional (Ternary) Expressions A conditional expression uses the C# `cond ? a : b` syntax. If `cond` evaluates to `true`, the result is `a`; otherwise the result is `b`. The condition can be a boolean variable or a comparison: ```csharp Width = TitleText.Visible ? 200 : 100 X = Background.Width > 500 ? Background.X : 0 ``` Just like simple variable references, the right side can be fully qualified to point at another element: ```csharp Width = Components/AppState.IsExpanded ? 400 : 200 ``` Ternary expressions can be nested. Use parenthesis to make the order of evaluation clear: ```csharp Width = Container.Width > 500 ? 300 : (Container.Width > 250 ? 200 : 100) ``` ### Comparison Operators The operators `==`, `!=`, `<`, `>`, `<=`, and `>=` can be used to compare values. The result is a `bool`, so comparisons are most often used as the condition of a ternary or as the right side of a `bool` assignment: ```csharp Visible = Background.Width > 100 Width = ScoreText.Y >= TitleText.Y ? 300 : 100 ``` ### Logical Operators The logical operators `&&` (and) and `||` (or) combine two `bool` values into a single `bool`. Both operands must be `bool`: ```csharp Visible = ToggleButton.Visible && ContentArea.Visible Visible = ErrorIcon.Visible || WarningIcon.Visible ``` ### Boolean Negation The `!` operator inverts a `bool` value: ```csharp Visible = !LoadingSpinner.Visible ``` ### Math Functions Variable references can call a fixed set of functions. These are Gum's own functions, not C# methods: write `Max(Width, 50)`, not `Math.Max(Width, 50)`. ```csharp Width = Max(Container.Width / 2, 100) Width = Clamp(Container.Width, 100, 400) X = 100 * Cos(Angle) Y = 100 * Sin(Angle) ``` The supported functions are: | Function | Result | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `Sin(angle)`, `Cos(angle)`, `Tan(angle)` | Trigonometric functions. The angle is in degrees, the same unit as `Rotation`. | | `Sqrt(x)` | Square root. | | `Abs(x)` | Absolute value. | | `Floor(x)`, `Ceiling(x)`, `Round(x)` | Rounds down, up, or to the nearest whole number. `Round` rounds halves to the nearest even number, so `Round(2.5)` is `2`. | | `Min(a, b)`, `Max(a, b)` | The smaller or larger of two values. | | `Clamp(value, min, max)` | Limits `value` to the range from `min` to `max`. | Function names are case sensitive. A reference that calls an unknown function, passes the wrong number of values, or produces no number (such as `Sqrt` of a negative value) is commented out and the tool explains why. Because angles are in degrees, a variable that animates from `0` to `360` drives a full circle through `Sin` and `Cos`. ### Category-State Assignment Variable references can drive a component's categorical state by assigning to `State`. The right side must resolve to a `string` matching one of the state names defined in that category. This is useful for switching visual states from another instance's variable. For example, on a button-derived component with a `ButtonCategory` containing `Enabled` and `Disabled` states: ```csharp ButtonCategoryState = Background.Visible ? "Enabled" : "Disabled" ``` If the right side is a literal string, Gum validates it against the category's state names and comments out the line if there is no match. ### Behavior-Driven References Standard Forms behaviors (Button, TextBox, Slider, and so on) can use a category-state assignment to drive a visual state from a **Behavior Property** — a property in the Variables tab's **Behavior** category that also flows through to the runtime Forms control. See [Behavior Properties](/gum/gum-tool/gum-elements/behaviors.md#behavior-properties) for what these are. For example, a TextBox-derived component previews its multi-line layout at design time using a reference like: ```csharp LineModeCategoryState = TextWrapping == "Wrap" ? "Multi" : (AcceptsReturn ? "Multi" : "Single") ``` This works the same as any other category-state assignment — the driven state is read-only, and changing `TextWrapping` or `AcceptsReturn` in the Behavior category updates the preview immediately. The only difference is where the right-hand variable comes from: a Behavior Property instead of an ordinary instance variable. These references ship pre-authored on the standard Forms behaviors, so you typically won't write one yourself unless you're customizing a Forms component's default visual or authoring a custom behavior. ### Enum Assignment Variables whose type is an enumeration — such as `ChildrenLayout`, or unit and alignment types like `XUnits` and `WidthUnits` — can be assigned using the enum value's name as a string. Gum converts the name to the matching enum value: ```csharp ChildrenLayout = "LeftToRightStack" ``` Because the right side is a string, an enum can also be selected with a ternary or driven from another variable. For example, a container can switch its layout direction based on a `bool`: ```csharp ChildrenLayout = IsHorizontal ? "LeftToRightStack" : "TopToBottomStack" ``` The name must match one of the enum's values; if it does not, the assignment is not applied. An enum variable can also be assigned from another variable of the same enum type, or from the enum's underlying integer value: ```csharp ChildrenLayout = OtherContainer.ChildrenLayout ``` {% hint style="warning" %} Gum treats the prefixes `Components/`, `Screens/`, and `Standards/` as special prefixes and does not consider this to be a division operator. Therefore, you should not name variables Components, Screens, or Standards as these are reserved words. Other variable references can freely use the forward slash character to create division. For example, the following two lines of code show the difference between a simple variable reference assignment and a division operation: ```csharp // This is a direct assignment setting X to // the X value on Components/OtherComponent: X = Components/OtherComponent.X // This is a division operation setting X to // the result of dividing the CustomVariable by OtherComponent.X X = CustomVariable/OtherComponent.X ``` {% endhint %} Numeric variable types can be mixed. For example, Red is typically an `int` value (whole number), while X is a `float` (supports decimals). Gum automatically casts the variable appropriately: ```csharp X = ColoredRectangleInstance.Red Green = ColoredRectangleInstance.Y ``` Gum automatically casts any value to a `string` (text). For example, a Text's Text variable could be assigned to its own Y value: ```csharp Text=TextInstance.Y ``` Strings can be *concatenated* (combined) using the + operator: ```csharp Text="My Position is " + TextInstance.X + ", " + TextInstance.Y ``` Gum cannot convert unrelated types, including different Units. For example, the following would be commented out by Gum: ```csharp //WidthUnits = TextInstance.HeightUnits ``` ### Referencing Custom Variables Variable references can include custom variables, both on the left and right side. Custom variables can be combined with variable references to create flexible layouts. For more information on using custom variables, see the [Add Variables page](/gum/gum-tool/variables/add-variable.md). ### Unqualified and Shorthand Assignments As mentioned above, fully qualified assignments are allowed in any context. For example, a component can reference its own qualified variables: ```csharp X = Components/SameComponent.Y ``` Components do not need to qualify their own variables. They can reference them without any qualification. Therefore, the following variable reference is equivalent to the fully-qualified reference above: ```csharp X = Y ``` Similarly, the following two variable references are equivalent assuming ContainedInstance is part of the component with the reference: ```csharp Y = Components/SameComponent.InstanceInComponent.Y // is equivalent to: Y = InstanceInComponent.Y ``` Instances must qualify their own variables, or use `@`. See [the warning above](#unqualified-instance-warning) for what an unqualified name means instead: ```csharp X = SameInstance.Y // or: X = @Y ``` An instance row can read a variable of its containing component without any qualification, such as a custom variable: ```csharp X = Sin(WaveValue) ``` The left side of an assignment can be omitted if referencing the same variable on another instance or component. For example, by typing `OtherInstance.YUnits` , Gum automatically expands the reference to `YUnits = OtherInstance.YUnits` .

OtherInstance.YUnits is automatically prefixed with the text YUnits=

Note that this only works when assigning one variable directly to another variable. Complex assignments will not be prefixed. ### Referencing the Owning Instance with @ A name qualified with an instance name, such as `Item1.Index`, keeps pointing at `Item1` after the instance is copied and pasted. The `@` prefix instead means "the instance that owns this row", so the same text works on every copy: ```csharp Width = @Index * 10 ``` If this row is on `Item1`, `@Index` reads `Item1.Index`. After pasting `Item1` as `Item2`, the row is unchanged and `@Index` reads `Item2.Index`. `@` works on any variable, and can be followed by a nested instance when the owner is a component instance: ```csharp Text = @Child.Text ``` On a component or screen row, `@` refers to the element itself, so `Width = @Height` is the same as `Width = Height`. {% hint style="info" %} Available in November 2026, or now if building Gum from source. {% endhint %} ### Position Among Siblings with Index `Index` is the position of an instance among the instances that share its parent, counting from zero. The first instance is `0`, the next is `1`, and so on. Combined with `@`, a single row gives every copy of an instance a value based on where it sits: ```csharp X = @Index * 20 ``` Instances placed directly in a component or screen are siblings of each other. Instances whose `Parent` variable names the same container are siblings of each other, separately from instances in other containers. Another instance's position can be read by qualifying it, such as `Item2.Index`. `Index` is read-only, so it can only appear on the right side of a row. It updates when instances are added, deleted, or reordered. A bare `Index` on an instance row means the containing component or screen, which has no siblings, so use `@Index` or a qualified name such as `Item2.Index`. {% hint style="info" %} If a component defines its own custom variable named `Index`, that variable is used instead of the position. {% endhint %} {% hint style="info" %} Available in November 2026, or now if building Gum from source. {% endhint %} ### Computed Size and Position with Absolute Values Some values only exist after Gum lays out an element, such as the width of a `Text` that sizes itself to its content. Variable references can read these final values in pixels through the `Absolute` variables: * `AbsoluteX`, `AbsoluteY` * `AbsoluteLeft`, `AbsoluteTop`, `AbsoluteRight`, `AbsoluteBottom` * `AbsoluteWidth`, `AbsoluteHeight` For example, a background can be 20 pixels wider than a label no matter how long the label's text is: ```csharp Width = TitleText.AbsoluteWidth + 20 ``` Absolute variables follow the same rules as other variables on the right side. A name qualified with an instance reads that instance, `@AbsoluteWidth` reads the instance which owns the row, and an unqualified name on an instance row reads the containing component or screen: ```csharp Height = Background.AbsoluteHeight / 2 Width = Max(@AbsoluteHeight, 100) ``` Absolute variables are read-only, so they can appear only on the right side. They also read only instances inside the same component or screen as the row. A fully qualified path such as `Components/Other.Instance.AbsoluteWidth` is not supported. {% hint style="info" %} At runtime, Absolute variables in a reference require the `Gum.Expressions` package. See [Runtime Variable References](/gum/code/styling/runtime-variable-references.md#expression-support-optional). {% endhint %} ### Current Language The reserved name `global::Localization.CurrentLanguage` is the index of the language the project is currently using, which is useful for adjusting a layout to text that is longer in some languages. Index `0` is the string ID, `1` is the first language, `2` is the second, and so on, matching the `CurrentLanguage` property used in code (see [Localization](/gum/code/localization.md)). ```csharp Width = global::Localization.CurrentLanguage == 2 ? 220 : 160 ``` The `global::` prefix is required, and the name is case sensitive. Because the value is a number, it is most often compared in a ternary expression as shown above. Changing the **Language** in the project properties updates the preview in the tool. See [Localization](/gum/gum-tool/localization.md) for adding a localization file and selecting a language. {% hint style="info" %} At runtime, a reference which reads the current language needs `Gum.Expressions`. It updates when the language changes. See [Runtime Variable References](/gum/code/styling/runtime-variable-references.md). {% endhint %} ### Color Expansion Assigning color values is a common part of styling, so to help with this situation, Gum also expands the "Color" variable into all three components when the Variable References text box loses focus. For example, the following text can be used to assign all three values at once: ```csharp Components/Styles.PrimaryColor.Color ``` When the Variable References box loses focus, this is expanded to the following assignments: ```csharp Red = Components/Styles.PrimaryColor.Red Green = Components/Styles.PrimaryColor.Green Blue = Components/Styles.PrimaryColor.Blue ```

Assigning Color expands the variables automatically

## Missing Reference Target (GUM0009) A variable reference can read from something the project does not have: an element that was deleted, renamed outside of Gum, or never imported, or an instance or variable that element does not have. For example, `Color = Components/Styles.Primary.FillColor` in a project with no `Styles` component. Such a reference never resolves, so the variable keeps its default value. Gum reports a **GUM0009** warning in the [Errors tab](/gum/gum-tool/editor-tab.md) for each of these lines, naming the element, the state, the line, and what it reads that is missing. `gumcli check` reports the same warning. To resolve it, add or import the missing element, or change the reference to point at one the project has. Renaming an element in Gum updates the references to it, so this usually happens after editing files outside of Gum or importing only part of another project. ## Variable References in the Property Grid As shown above, Variable References can be used to assign one variable to another. If a variable is referenced, then the variable cannot be manually assigned. The Variable Reference takes priority. For example, if an object references the Red, Green, and Blue variables, then those values cannot be manually set on the object. The values appear disabled and text indicates why they are read-only.

Left-side variables become read-only

### Set by The text under a read-only variable starts with **Set by** and shows the right side of the reference. For example, `X = Leader.X` displays `Set by Leader.X` under `X`. When the right side is a plain variable such as `Leader.X` or `Components/Styles.PrimaryColor.Red`, the text is a link. Clicking it selects the instance or component which provides the value, so you can follow a chain of references without searching the Project tab. An expression, an `@` reference, or a `global::Localization.CurrentLanguage` lookup shows the same **Set by** text, but it is not a link because it has no single source to select. An **Unlink** button (the delete icon) appears next to the text when the selected state's own Variable References list assigns the variable. Clicking it comments out that line with `//`. The variable keeps its current value and becomes editable again. **Unlink** supports undo, which restores the line and makes the variable read-only again. {% hint style="warning" %} Add a screenshot of the Variables tab showing the **Set by** link and the **Unlink** button under a read-only variable. {% endhint %} {% hint style="info" %} Available in November 2026, or now if building Gum from source. {% endhint %} ## Obtaining a Qualified Variable Name Typing a variable name can be tedious, especially when referencing a variable in a different Screen or Component. Qualified variable names can be obtained by right-clicking on the variable name in Gum and selecting the **Copy Qualified Variable Name** option. This can then be pasted in the Variable References box of any other object.

Right-click to obtain the qualified name of a variable

## Example - Creating Color Styles The following example creates a Styles component which contains a color value which is referenced by objects in a MainMenu Screen. Any component can serve as a centralized location for styling, but we use the name **Styles** by convention. The Styles component can contain as many objects as are needed to style your project. Additional objects can be added to help indicate how things are used visually. For example, we include a Text object to indicate the red color is the **Primary Color**.
The color value can be referenced by any other object including objects in different screens or components. To add a variable reference: 1. Select the object which should have a variable reference 2. Click inside the **Variable References** text box 3. Type the variable reference. The format of the variable reference is\ \ `{VariableName} = {Components or Screens}/{ComponentOrScreenName}.{InstanceName}.{InstanceVariable}`\ \ For example, to reference the Red variable in the Styles component, the syntax is\ \ `Red = Components/Styles.PrimaryColor.Red`\\ Since color values have three components (Red, Green, and Blue), then all three components must be referenced. In this example, the background can reference the three colors with the following assignment text: ``` Red = Components/Styles.PrimaryColor.Red Green = Components/Styles.PrimaryColor.Green Blue = Components/Styles.PrimaryColor.Blue ```

Background instance referencing the Styles.PrimaryColor color values

The types of the objects that contain the **Variable References** or which are being referenced do not matter. For example, a Text object could have its color values depend on the color values defined by a ColoredRectangle in the Styles component.

TextInstance also referencing the PrimaryColor color values

Once Variable References are set, the referenced instances (instances in Styles) can be changed and the changes will immediately propagate throughout the entire project.

Changing the source color values updates all objects referencing the Style.PrimaryColor values

## Example - Building a Ruler This example builds a ruler out of notches. Every notch has the same three variable references, so each one finds its height, label, and width from its own position. Adding more notches takes only copy and paste. 1. Create a component named **Ruler** and set its **Children Layout** to `Left to Right Stack`. 2. Add a Text instance to Ruler named `Notch0`. 3. Select `Notch0` and type the following into the **Variable References** box: ```csharp Height = @Index % 4 > 0 ? 15 : 30 Text = @Index * 5 Width = @Height / 3 ``` 4. Copy and paste `Notch0` as many times as you need. Each copy keeps the same three lines, and `@` makes each line read the copy's own values. The rows work as follows: * `Height` is `30` when `@Index % 4` is `0`, which happens at positions 0, 4, 8, and so on. Every other notch is `15`. The `%` operator gives the remainder after dividing, so `@Index % 4` counts `0, 1, 2, 3` and then starts over. The comparison `> 0` is true for all but every fourth notch. * `Text` shows the position times 5, so the notches read `0, 5, 10, 15, ...`. Gum converts the number to text automatically. * `Width` is a third of the notch's own height. `@Height` reads the result of the `Height` row, and Gum evaluates the rows in dependency order, so the order they are typed in does not matter. Moving a notch to a new position, or deleting one, changes the `Index` of the notches after it. Their heights, labels, and widths update to match. ## Example: Semantic Color Categories on Standard Elements The example above references a Styles component from one object at a time. You can go further and build a reusable, semantic color palette (for example: **White**, **Gray**, **Black**, **Primary**, **Success**, **Warning**, **Danger**) that any instance in your project can select by name, without hardcoding a color anywhere outside of the Styles component. This combines two features already covered elsewhere: 1. **A category per Standard Element** - Select the `NineSlice`, `Sprite`, or `Text` Standard Element and add a category (for example `ColorCategory`) with one state per palette name. See [Categories](/gum/gum-tool/gum-elements/states/categories.md) for how to create categories and states. 2. **A Variable Reference per state** - Select each state in the category and use the Color Expansion shorthand to point it at the matching instance in your Styles component: ``` Components/Styles.PrimaryColor.Color ``` Repeat this for every state in the category (`White`, `Gray`, `Primary`, `Success`, and so on), pointing each one at its matching Styles instance. Because the reference lives on the Standard Element itself, every instance of that Standard Element across your entire project shares the same palette. {% hint style="warning" %} Add a screenshot showing the `ColorCategory` states on the `NineSlice` Standard Element, each with a Color Expansion reference into the Styles component. {% endhint %} Repeat the category on each Standard Element that needs coloring (`NineSlice`, `Sprite`, `Text`). Once this is set up, any instance anywhere in the project can select a palette color with a single [category-state assignment](#category-state-assignment) instead of a color reference: ``` ColorCategoryState = "Primary" ``` {% hint style="info" %} This pattern is also what makes the palette recolorable from game code at runtime - for example, letting a game read player-customizable colors from settings and apply them on startup. See [Runtime Variable References](/gum/code/styling/runtime-variable-references.md). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.flatredball.com/gum/gum-tool/gum-elements/general-properties/variable-references.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.