> 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/reference/troubleshooting.md). # Troubleshooting the ECS runtime Most problems with the ECS runtime look the same: nothing happens. This page lists each symptom with its usual cause and the fix. The sections follow the order you meet them: setup and baking, requests, name lookups, effects, waits, cues, slow frames, networking, errors, the demo and removal. Start with the first section, which shows what the runtime holds for an actor. You need an ECS scene that you can run, such as the one from [Getting started](/docs/gameplay-ability-toolkit-ecs/start/getting-started.md). ## See what the runtime holds | Where | Shows | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Gas Entity Authoring** Inspector, section **As an entity** | Whether the GameObject will be baked (it has to be in a SubScene), whether it has a catalog, which of its abilities the catalog knows, what each one does, and what the catalog build says about them. | | **Gas Catalog Authoring** Inspector, section **What it bakes** | How many attribute sets, effects and abilities the catalog lists and bakes, and everything the build refused. **Collect Now**, shown while **Auto Collect Definitions** is on, adds the project's definitions without waiting for the automatic pass. | | **Tools > Gameplay Ability Toolkit > ECS > Actor Debugger** | One actor's attributes, tags, abilities with their cooldowns, effects with their time left, waits and montage, by name. Read-only. It works in Play mode, or in Edit mode with a SubScene open. Leave **Follow selection** on to show the entity selected in the Entities Hierarchy, or pick a **World** and an **Actor**. | | **Window > Entities > Hierarchy** and the Entities Inspector | The same buffers as raw numbers. | | **Tools > Gameplay Ability Toolkit > Dashboard > ECS Runtime** | The catalog's bake report. In Play mode it also shows the runtime's counters and queue depths, once the world has a `GasSimulationStats` entity (see [Performance](/docs/gameplay-ability-toolkit-ecs/reference/performance.md#read-the-runtimes-counters)). | ## Setup and baking | Symptom | Cause | Fix | | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The ECS menus, components or Dashboard pages are missing | The ECS modules compile only on Unity 6000.6 or newer, with Gameplay Ability Toolkit 1.2.0 or newer and the Entities package in the project. | Without the toolkit, or with an older one, the add-on switches itself off and shows a dialog when the editor starts. Import or update the toolkit and the add-on switches back on. With the toolkit present, open **Tools > Gameplay Ability Toolkit > Dashboard > Dependencies**. Its **Entities** row says **Needs Unity 6.6** when the editor is too old. When the editor is new enough and Entities is missing, the row says **Not installed** and has a **Package Manager** button. After installing, wait for Unity to finish recompiling. | | The GameObject never becomes an entity, and the Inspector shows **SubScene: Not in one** | Only GameObjects inside a SubScene are baked. | Put the actors and the catalog inside a SubScene. | | The entity exists but nothing happens to it | An inactive GameObject bakes to a disabled entity, which the runtime ignores. | Activate the GameObject. (The ECS Swarm demo keeps its enemy template inactive on purpose.) | | The Inspector shows **Catalog: Missing**, and the Console shows an error that the actor has no catalog assigned | The **Catalog** field fills in by itself only when the scene holds exactly one catalog, and the automatic setup does not run in Play mode. An actor with no catalog bakes without attribute values or ability slots. | Add exactly one `GasCatalogAuthoring`, or assign the **Catalog** field by hand. **Tools > Gameplay Ability Toolkit > ECS > Re-run automatic setup** forces a pass. | | The Inspector shows **Other catalogs: N more in this scene** | A world holds exactly one catalog. | Keep one and remove the others. | | An actor's ability shows **Not in the catalog** | The catalog does not list it, so the actor is not granted it. | Add it to the catalog's **Abilities** list, or turn **Auto Collect Definitions** on. | | New assets are missing from the catalog | **Auto Collect Definitions** adds assets only outside Play mode, and it only adds: it never removes or reorders. | Click **Collect Now** on the catalog, or run **Re-run automatic setup**. With **Auto Collect Definitions** off, add the assets by hand. | | The Console shows `[GAS.Entities]` warnings, or the catalog's build report lists items | The catalog skipped or changed something it cannot represent exactly. | See [What the catalog reports](/docs/gameplay-ability-toolkit-ecs/build-with-it/authoring.md#what-the-catalog-reports) for each message and what to do. | | An actor prefab, such as a Netcode ghost, bakes with no catalog | Unity does not allow a prefab asset to refer to an object in a scene. | Put `GasCatalogAuthoring` on a prefab, use that prefab as the actor's catalog, and place an instance of it in the SubScene. See [Spawning actors at run time](/docs/gameplay-ability-toolkit-ecs/build-with-it/authoring.md#spawning-actors-at-run-time) and, for a ghost, [Set up a player actor](/docs/gameplay-ability-toolkit-ecs/build-with-it/netcode-for-entities.md#set-up-a-player-actor). | ## An activation request does nothing Work through these in order. 1. **Did the request go anywhere?** `GasEntityFactory.RequestActivation` returns `false` when the world has no activation queue. The runtime creates its queues on the first frame a catalog exists, so `false` means the world has no catalog yet: the SubScene is not loaded, or it has no `GasCatalogAuthoring`. 2. **What did the result say?** Read the `GasAbilityActivationEvent` for the request (see [Writing gameplay code](/docs/gameplay-ability-toolkit-ecs/build-with-it/gameplay-code.md#reacting-to-results)) and look up its `FailureReason`: | `FailureReason` | Look at | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `InvalidRequest` | The ability index: `FindAbilityIndex` returns -1 for a name the catalog does not have. The actor must also have been granted the ability. An ability that is still running cannot start again unless it is instanced per execution, and an ability that declares waits stays running until a wait or an end request ends it. On a Netcode client, the actor may not be simulated on this client. | | `AbilitySystemNotFound` | The target is `Entity.Null`, has been destroyed, or is not an actor. An actor has ability slots and attribute values, which baking `GasEntityAuthoring` gives it. | | `Cooldown` | `GasAbilitySlot.CooldownRemaining` on the actor. | | `Cost` | The cost effect, and the attribute it spends. | | `TagRequirements` | The ability's tag requirements against the owner's, the source's and the ability target's tags. Blocked tags include those that other running abilities block. | 3. **Is there no result at all?** Either the result was read before your system looked, or another system cleared it. Read results in `GasResultSystemGroup`, and let only one system clear them. A request made in `GasResultSystemGroup` is served on the next frame, so its result appears then. An ability started by a trigger writes no result when it is already running and cannot run twice. ## A name lookup returns -1 `FindAbilityIndex`, `FindEffectIndex`, `FindTagIndex` and `FindAttributeIndex` return -1 when the catalog has nothing under that name. | Cause | Fix | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | Abilities and effects are found by their **asset name**, not by the Title shown in the Inspector. | Pass the asset's file name without the extension. | | Tags are found by their full dotted name. | Use `State.Stunned`, not `Stunned`. | | Attributes are found by the attribute set asset's name and the attribute's name. | `FindAttributeIndex("HeroAttributes", "Health")`. | | With **Auto Collect Definitions** off, the catalog holds only what its lists name and what those assets reference. | Add the asset to the catalog's lists. | | Two assets have the same name: the lookup finds the first. The catalog reports this when it bakes. | Rename one. | | The name is longer than 61 bytes. The catalog truncates it and reports that. | Shorten the name. | ## Effects, cooldowns and time | Symptom | Cause | Fix | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Effects never expire, or cooldowns never end | The runtime reads time from its own clock, `GasTime`. In a scene it creates and advances the clock itself. In a world you build yourself (for a test or a tool) there is no clock until you make one, and time stays at zero. | Create it with `GasEntityFactory.CreateTime`. If you set `GasTime.Manual`, the runtime stops advancing the clock and you must advance it. | | An attribute still shows its old value right after you asked for an effect | You read it before the runtime served the request. | Requests made in `GasRequestSystemGroup` are served in the same frame. Read the attribute in `GasResultSystemGroup`, or on the next frame. | | An effect does not apply | A queued request gives no reason when it fails. | Apply the effect once with the `GasEffectUtility.TryApplyEffect` overload that has an `out GasEffectFailureReason`, and read the reason (next table). | | An effect applies, but one of its modifiers is missing | A modifier whose own source or target tags are not met is dropped while the rest of the effect applies. (A tag filter on an attribute-based magnitude that fails keeps the modifier with a magnitude of 0.) | Check the tags of the source and target when the application starts. See [Differences from the GameObject runtime](/docs/gameplay-ability-toolkit-ecs/reference/differences-from-core.md#behavior-that-differs). | | `GasEffectFailureReason` | Means | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `InvalidEffectIndex` | The effect index is outside the catalog, for example -1 from a lookup that found nothing. | | `TargetCannotReceiveEffects` | The target does not exist or is not an actor. | | `ApplicationRequirementsNotMet` | The target lacks one of the effect's required tags, or fails its required query. This is the usual answer. | | `TargetNotSimulated` | Netcode for Entities is not simulating the target on this client this tick. | | `InvalidEffectData` | The effect's baked data is unusable, such as a modifier range outside the table. Check the catalog's build report. | ## Waits and triggers | Symptom | Cause | Fix | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | A wait never completes | The catalog skipped the wait when it baked. A wait is skipped when it names no tag, attribute or effect, when the tag, attribute set or effect it names is not in the catalog, or when its window has no length (a `Delay` below 0, or an `InputHeld` or `InputDoubleTap` with a **Duration** of 0 or less). | Read the Console report when the SubScene bakes, and fix what it names. | | A `TagAdded` wait never fires | It fires on the moment the tag is added, so the tag has to be added after the ability starts. | Use `TagPresent` if the tag may already be there: it holds as soon as the tag is owned. | | An `InputHeld` or other input wait never fires | The input kinds read `GasInputState.Held`, which your input code has to write. | Write `GasInputState` from your input code. With Netcode for Entities, `GasAbilityInput` fills it. | | An ability with waits never ends, and the next activation fails with `InvalidRequest` | An ability that declares waits stays active until one of them ends it. | Give one wait the action `EndAbility`, or end the ability with `GasEntityFactory.RequestEnd`. | | An ability does not start from its trigger | The trigger's tag is not in the catalog, which the build reports. Or the tag was added and removed within one frame, which triggers nothing. Or the ability is already running and cannot run twice, so the request is passed over without a result. | Add the tag to the catalog, keep the tag for at least a frame, or end the running ability first. | | A triggered ability starts a frame late | Triggers run last in the update, so the ability they start is served on the next frame. | This is by design. See [How it works](/docs/gameplay-ability-toolkit-ecs/build-with-it/concepts.md#the-frame). | ## Cue events | Symptom | Cause | Fix | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Cue events pile up | Nobody clears them. The runtime appends cue events and never clears them. | Clear each buffer after your presenter reads it. The Dashboard's **ECS Runtime** page counts waiting cues and warns when more than 100 are waiting. | | Cues never arrive | The effect has no cue tags, or they are not the tags your presenter looks for. Or your presenter reads them before the runtime has run. | Check the effect's **Cues** tags. Read cues in `PresentationSystemGroup`. | | With Netcode for Entities, a cue arrives a tick late, or plays for an effect the server refused | A predicting client raises a cue only from a tick's first full prediction. | See [Cues and presentation](/docs/gameplay-ability-toolkit-ecs/build-with-it/presentation.md#with-netcode-for-entities). | ## Slow frames | Symptom | Cause | Fix | | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GasSimulationStats.ActorsConsidered` stays close to your actor count on a frame where nothing happened | A system of yours takes `GasAttributeValue`, `GasTagCount` or `GasAbilitySlot` read-write, which marks every chunk it touches as changed. Or a modifier in the catalog captures live from another actor. | See [Read the runtime's buffers read-only](/docs/gameplay-ability-toolkit-ecs/reference/performance.md#read-the-runtimes-buffers-read-only) and [Avoid live captures from another actor](/docs/gameplay-ability-toolkit-ecs/reference/performance.md#avoid-live-captures-from-another-actor). | | A large population is slow in general | Several causes are possible. | Work through [Habits that keep it fast](/docs/gameplay-ability-toolkit-ecs/reference/performance.md#habits-that-keep-it-fast). | ## Netcode for Entities | Symptom | Cause | Fix | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Console warning: "Ignoring invalid \[Unity.Entities.UpdateBeforeAttribute] attribute" (or `UpdateAfterAttribute`), naming `GasSimulationSystemGroup` | A system orders itself against `GasSimulationSystemGroup` from `SimulationSystemGroup`. That order stops being valid when Netcode moves the runtime into its prediction loop. | Put the system in `GasRequestSystemGroup` or `GasResultSystemGroup` with `[UpdateInGroup]`. Those groups move with the runtime. | | Abilities on the owner's client resolve one round trip late | The ghost is not predicted: its `SupportedGhostModes` is Interpolated only. | Add Predicted to `SupportedGhostModes`. **Tools > Gameplay Ability Toolkit > Dashboard > ECS Networking** lists this and the other ghost settings it finds wrong. | ## An error inside a system An exception thrown in a system's update appears in the Console as an error, and the part of that system's work after the exception does not happen that frame. When a result or an effect is missing, check the Console for an exception first. ## The ECS Swarm demo | Symptom | Cause | Fix | | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The Console says the catalog is missing some of the demo's assets | The SubScene's `GAS Catalog` lists were changed. | The lists must name `SwarmAttributes` and every `GA_Swarm*` and `GE_Swarm*` asset. | | Nothing is drawn, or the Console says the presenter has no crowd to draw with | The demo needs the Universal Render Pipeline and a graphics card and API with compute shaders. | Use a supported GPU. On the `Swarm Presenter`, check that **Crowd**, **Crowd Shader** and **Crowd Cull** are assigned. | | The hero or the damage numbers are missing, but the enemies are drawn | The `Swarm Presenter` draws the hero only when **Hero Asset** and **Hero Material** are both assigned, and the damage numbers only when **Numbers Material** is assigned. It reports nothing when they are empty. | Assign them on the `Swarm Presenter`. | | Nothing moves in a project with Netcode for Entities | The demo runs in the default world, which Netcode makes the server world. If your project's own bootstrap creates only a client world, the demo has no world to run in. | Let Netcode create its worlds automatically, which makes the server world the default world. See [Automatic world creation](/docs/gameplay-ability-toolkit-ecs/build-with-it/netcode-for-entities.md#automatic-world-creation). | ## Removing the add-on Use **Tools > Gameplay Ability Toolkit > ECS > Remove the ECS Add-on...** (also on **Dashboard > Dependencies**, row **Remove the ECS add-on**, button **Remove...**) rather than deleting the folder by hand. It first lists what depends on the add-on or on Entities. Click **Show** to find an entry in the Project window. | Marked | Means | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Will not compile | An assembly or a script that names the add-on or Entities and cannot switch off. Fix these first: gate the assembly on `GAS_ECS_CORE_READY` and `GAS_ENABLE_ENTITIES`, or move the script into such an assembly. | | Missing scripts | A scene or prefab with the add-on's components, a SubScene or a ghost. They show as Missing Script once the add-on is gone, and come back if you import it again. Nothing is deleted from them. | | Switches off | An assembly gated like the add-on's, such as the ones the New Ability window makes for hook scripts. It stops compiling with the add-on and starts again when it returns. | Then: 1. Under **1. Review Unity dependencies**, open Package Manager and remove the packages you no longer need. Keep Entities if your own code uses it. 2. Under **2. Delete the add-on**, click **Delete the Add-on** and confirm. This deletes the add-on's folder and also clears the `GAS_ECS_CORE_READY` define the add-on set. Left behind, that define would switch on code that is gated on it with nothing to compile against. ## Next steps * [How it works](/docs/gameplay-ability-toolkit-ecs/build-with-it/concepts.md): the frame order, and what the runtime checks for you. * [Writing gameplay code](/docs/gameplay-ability-toolkit-ecs/build-with-it/gameplay-code.md): requests, results and reading state. * [Performance](/docs/gameplay-ability-toolkit-ecs/reference/performance.md): measuring, and the habits that keep a game fast. * [Differences from the GameObject runtime](/docs/gameplay-ability-toolkit-ecs/reference/differences-from-core.md): behavior that is not a bug. * [API reference](/docs/gameplay-ability-toolkit-ecs/reference/api-reference.md): the public types.