> 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/code/getting-started/setup/adding-initializing-gum/unity.md). # Unity {% hint style="warning" %} The Unity package is experimental. It supports Windows x64 and macOS (Intel and Apple silicon). Linux, Android, iOS, and WebGL are not supported yet. {% endhint %} Gum for Unity draws Gum UI (layout, Forms controls, and `.gumj` projects) with SkiaSharp. It needs two Unity packages: Gum, and SkiaGameRendering, which supplies SkiaSharp. ## Quick Start 1. Install the two packages (see **Install the Packages** below). Gum requires Unity 6 or newer. 2. In **Edit > Project Settings > Player**, set **Active Input Handling** to **Input System Package (New)** or **Both**. 3. In your scene, create an empty GameObject (**GameObject > Create Empty**) and name it `Gum`. 4. Select the `Gum` GameObject. In the Inspector, click **Add Component** and add `GumRenderer`, then add `GumInput`. 5. With the `Gum` GameObject still selected, click **Add Component > New script**, name it `GumExample`, and replace its contents with: ```csharp using Gum.Forms.Controls; using UnityEngine; public class GumExample : MonoBehaviour { void Start() { var button = new Button(); button.Text = "Click me"; button.AddToRoot(); } } ``` 6. Press **Play**. A button labeled "Click me" appears in the Game view. `GumRenderer` sets up Gum in `Awake`, so your own code can create UI from `Start` or later. ## Install the Packages 1. Open **Window > Package Manager**. 2. Click the **+** button, then **Install package from git URL**. 3. Paste this URL and click **Install**: ``` https://github.com/vchelaru/SkiaGameRendering.git#upm ``` 4. Repeat with this URL: ``` https://github.com/vchelaru/Gum.git#upm ``` You can also add both lines to `Packages/manifest.json` instead: ```json "com.vchelaru.skiagamerendering": "https://github.com/vchelaru/SkiaGameRendering.git#upm", "com.vchelaru.gum": "https://github.com/vchelaru/Gum.git#upm" ``` The `#upm` at the end of each URL tells Unity to use the ready-to-install copy of the package that Gum publishes with each release. It always points at the newest one. Unity does not update on its own, so to upgrade, reinstall the package or use the update button in Package Manager. To stay on a specific Gum version, end the Gum URL with `#upm/v` instead, for example `#upm/v2026.10.2-preview.2.2`. Each version is listed under [Gum's tags on GitHub](https://github.com/vchelaru/Gum/tags) as `upm/v`. ## What the Components Do * `GumRenderer` sets up Gum and draws the UI over the screen. * `GumInput` passes Unity's mouse, touch, keyboard, and gamepad input to Gum each frame. It belongs on the same GameObject as `GumRenderer`. Mouse and touch work right away. To move between Forms controls with the keyboard or a gamepad, call `GumService.Default.UseKeyboardDefaults()` or `GumService.Default.UseGamepadDefaults()` in your script. ## Using the Code Samples in These Docs Most code samples on other pages are written for a `Game` class. In Unity, adapt them like this: * Code under a `// Initialize` comment goes in your script's `Start` method. * Code under a `// Update` comment goes in your script's `Update` method. Skip any `GumUI.Update` call, since `GumRenderer` already updates Gum. * Skip any `GumUI.Draw` call, since `GumRenderer` already draws Gum. * `GumUI` in the samples is `GumService.Default`. Samples that use MonoGame types such as `GameTime`, `GraphicsDevice`, or `Microsoft.Xna.Framework.Color` do not apply to Unity. ## Loading a Gum Project 1. Copy your Gum project folder into `Assets/StreamingAssets`. 2. Set `GumRenderer.ProjectFile` to the `.gumj` path inside that folder, for example `GumProject/GumProject.gumj`. If you add the components from code, add them to an inactive GameObject, set `ProjectFile`, then activate the GameObject. ## Rendering Gum draws on the GPU through SkiaGameRendering on every graphics API it supports, including Direct3D 11 and Metal. On any other API, Gum draws on the CPU and uploads a texture each frame, and the console logs a warning explaining why. `GumRenderer.Texture` holds the result either way. Turn off `GumRenderer.DrawToScreen` to display the texture yourself. ## IL2CPP If you build with IL2CPP, add an `Assets/link.xml` file to your project that keeps `netstandard`: ```xml ``` The `Samples/UnityGum` project in the Gum repository has one. --- # 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/code/getting-started/setup/adding-initializing-gum/unity.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.