> For the complete documentation index, see [llms.txt](https://morningheartgames.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit-ecs/start/documentation.md). # ECS Runtime Guide Gameplay Ability Toolkit ECS is an add-on for Gameplay Ability Toolkit. It runs the toolkit's abilities, effects, attributes and tags on Unity's Entities package (ECS). You author the same assets as for the GameObject runtime: attribute sets, effects, abilities and tags. The add-on bakes them into data that Burst-compiled systems process, so one scene can hold hundreds of thousands of actors, each with its own attributes, cooldowns, buffs and debuffs. With Netcode for Entities installed, it adds server-authoritative replication and client prediction. This page lists what you need, helps you pick a runtime, gets you running in a few minutes, and maps the rest of the manual. ## Requirements | What | Version | Notes | | ------------------------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Unity | 6000.6 or newer | On older editors the add-on stays off. The toolkit itself still works there. | | Gameplay Ability Toolkit | 1.2.0 or newer | Sold separately. Import it before the add-on. Without it, the add-on stays switched off and says so when the editor starts. | | UniTask | 2.5.11 or newer | Required by the toolkit, and installed from its Dashboard. See the toolkit's [Getting Started](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/start/01-getting-started). | | Entities (`com.unity.entities`) | 6.6.0 or newer | Open **Tools > Gameplay Ability Toolkit > Dashboard > Dependencies** and click **Package Manager** in the **Entities** row. | | Netcode for Entities (`com.unity.netcode`) | 6.6.0 or newer, optional | Same page, **Netcode for Entities** row. It cannot be installed in the same project as Netcode for GameObjects. | Burst, Collections and Mathematics come with Entities. You do not set any scripting define by hand: the add-on sets `GAS_ECS_CORE_READY` once it finds a supported toolkit, and each ECS assembly switches on when its package is present. The runtime works with any render pipeline. The ECS Swarm demo needs the Universal Render Pipeline and a GPU with compute shader support, and has been tested on Windows. ## Which runtime to use The add-on does not change the GameObject runtime, the `AbilitySystemComponent` described in the [toolkit's manual](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit). Each actor runs on one runtime or the other, never both. Both runtimes read the same assets, so you can author once and choose per actor type. | Your game | Use | | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A handful to a few hundred actors, each a GameObject with animation, physics and scene references | The GameObject runtime. Ability tasks, targeting, cue notifies, the toolkit's input binding and its runtime UI components work only there, because they need scene objects. | | Hundreds to hundreds of thousands of actors: swarms, crowds, bullet-hell enemies, RTS units, simulations | The ECS runtime. | | A game already built on Entities | The ECS runtime. | | Server-authoritative multiplayer on Entities, with client prediction | The ECS runtime with Netcode for Entities. | The ECS runtime follows the GameObject runtime's rules. Where the two differ on purpose, [Differences from the GameObject runtime](/docs/gameplay-ability-toolkit-ecs/reference/differences-from-core.md) lists it. ## How many actors The ECS Swarm demo lets you choose 2,000, 10,000, 50,000, 100,000, 200,000 or 1,000,000 enemies. Each one is a real entity with its own gameplay state. At 1,000,000 the camera rises to show the whole crowd from above, and the crowd renderer uses its normal distance LOD. Close-up play and a full-population overview are different rendering workloads. [Performance](/docs/gameplay-ability-toolkit-ecs/reference/performance.md#controlled-rendered-combat-results) gives the measured frame rates for each population, with the hardware and test conditions. They are results for that workload, not a frame-rate promise for every game. ## Start here 1. **Install Entities.** Open **Tools > Gameplay Ability Toolkit > Dashboard** and go to the **ECS Start** page. In its first step, **Install Entities**, click **Package Manager**. Install **Entities** from the Unity Registry and wait for Unity to recompile. 2. **Run the starter scene.** On the same page, click **Make It** on the **Starter scene** tile, wait for Unity to compile, and press Play. The hero takes a wound every second and heals itself when its health runs low; the Console reports each heal. [Getting started](/docs/gameplay-ability-toolkit-ecs/start/getting-started.md) builds the same scene by hand and explains every part. 3. **Play the demo.** Click **Open** on the **ECS Swarm demo** tile and press Play. Move with WASD, aim with the mouse, click to strike, and press 1-8 for the skills. The buttons under **ENEMIES** on the HUD change the population. See [ECS Swarm demo](/docs/gameplay-ability-toolkit-ecs/start/swarm-demo.md). 4. **Look at the demo's authoring.** Stop Play mode. In the Hierarchy, tick the checkbox of `Swarm Entities (SubScene)` to open it for editing. The runtime authoring is two kinds of object: the `GAS Catalog`, and the actors (`Player` and the inactive `Enemy Template`). 5. **Build your own.** Under **Or build it yourself**, the ECS Start page checks each part as you add it: a SubScene, a catalog, an actor, an ability, then Play. To make an ability that hits other actors, use **Tools > Gameplay Ability Toolkit > ECS > New Ability** ([Abilities that reach other actors](/docs/gameplay-ability-toolkit-ecs/build-with-it/delivery.md)). ## Editor tools | Tool | Where | Use it to | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | ECS Start | **Tools > Gameplay Ability Toolkit > Dashboard > ECS Start** | Install Entities, make the starter scene, open the demo, and set up a scene step by step. | | ECS Runtime | **Dashboard > ECS Runtime** | See the actors and queues in Play mode, the catalog's bake report, and a check of the installed networking packages. | | ECS Networking | **Dashboard > ECS Networking**, when Netcode for Entities is installed | Check ghost setup, prediction status and the predicted-input path. | | New Ability | **Tools > Gameplay Ability Toolkit > ECS > New Ability...**, or **Assets > Create > Gameplay Ability Toolkit > ECS > Ability (Step by Step)...** | Make an ability step by step: its kind (self, area, arc, nearest or projectile), cost and cooldown, what it hits, when, and who uses it. | | Actor Debugger | **Tools > Gameplay Ability Toolkit > ECS > Actor Debugger** | See one actor's attributes, tags, abilities, effects, waits and montage by name. | | Remove the ECS Add-on | **Tools > Gameplay Ability Toolkit > ECS > Remove the ECS Add-on...** | List what depends on the add-on, then remove it. See [Troubleshooting](/docs/gameplay-ability-toolkit-ecs/reference/troubleshooting.md). | ## The manual | Page | Read it to | | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | [Getting started](/docs/gameplay-ability-toolkit-ecs/start/getting-started.md) | Install Entities and build an entity that heals itself, step by step. | | [ECS Swarm demo](/docs/gameplay-ability-toolkit-ecs/start/swarm-demo.md) | Play the demo, and see how each of its parts uses the runtime. | | [How it works](/docs/gameplay-ability-toolkit-ecs/build-with-it/concepts.md) | Understand the catalog, actors, requests, results and the frame order. | | [Authoring](/docs/gameplay-ability-toolkit-ecs/build-with-it/authoring.md) | Learn what bakes, what the catalog refuses, and how waits and montages replace ability tasks. | | [Abilities that reach other actors](/docs/gameplay-ability-toolkit-ecs/build-with-it/delivery.md) | Make abilities that hit other actors (areas, arcs, nearest targets, projectiles) without code. | | [Writing gameplay code](/docs/gameplay-ability-toolkit-ecs/build-with-it/gameplay-code.md) | Request activations and effects, read attributes and tags, and react to results. | | [Cues and presentation](/docs/gameplay-ability-toolkit-ecs/build-with-it/presentation.md) | Turn cue events into visuals and sound, pose characters from montages, and show runtime state in UI. | | [Netcode for Entities](/docs/gameplay-ability-toolkit-ecs/build-with-it/netcode-for-entities.md) | Replicate abilities and predict them on clients. | | [Performance](/docs/gameplay-ability-toolkit-ecs/reference/performance.md) | See the measured numbers, and the habits that keep a game fast. | | [Differences from the GameObject runtime](/docs/gameplay-ability-toolkit-ecs/reference/differences-from-core.md) | Know what is not available on entities, and what behaves differently. | | [Troubleshooting](/docs/gameplay-ability-toolkit-ecs/reference/troubleshooting.md) | Find out why nothing happened. | | [API reference](/docs/gameplay-ability-toolkit-ecs/reference/api-reference.md) | Look up the public types. | | [Minimal ECS example](/docs/gameplay-ability-toolkit-ecs/reference/minimal-example.md) | Read a short code-first tour, including a catalog built in code. |