Troubleshooting

Troubleshooting

Start with Tools > Starhelm > Dashboard. It lists what the open scene is missing — executor, actors, world query, movement, dialogue, gizmos, actions — and fixes each with one button. Most "nothing happens" reports are a missing row there.

My AI does nothing

Open the Why not? tab first. It answers exactly this question: pick the actor, and every action it knows is listed worst-first with the gate that stops it - work refused, a schedule that has it resting, no valid target, a condition that fails, a cost it cannot pay, a target someone else already claimed. Nothing is executed to find out, so it is safe outside Play mode. The list below is what to check if you would rather reason it through by hand.

1. Is there an executor? Without one, no queue is ever ticked. The Dashboard adds it.
2. Was the scene saved? A scene built but never written to disk comes back empty the next time Unity opens, taking every Starhelm object with it. The scene builder saves for you; if you wired things by hand, save before closing.
3. Is the actor on duty? An actor with a Template Worker refuses work outside its schedule hours. Its inspector shows off duty while playing.
4. Does it refuse that work? Work priorities with weight 0 mean "never do this". Check the Template Brain.
5. Open the Debugger (Tools > Starhelm > Debugger) in Play mode. It shows, per actor, the action running and the reason behind every state it went through.

An action starts and immediately blocks

The Debugger prints the reason. The usual ones:

• "Target already reserved" — another actor claimed it. Expected in a colony; if it never resolves, check that actions release reservations by completing or being cancelled.
• "Too far" — a distance condition without an approach. Tick Approach on the action and give the scene a movement adapter, and the actor will walk into range first.
• "Cannot pay…" — the actor lacks the resource or stat. Costs are atomic: nothing is spent unless everything can be.
• "No valid target" — the target descriptor found nothing. Check its tag filter and radius.

Dialogue stays silent

See the When nothing plays section of Dialogue. In short: tick Log Dialogue, and check the Dialogue row in the Dashboard.

Nothing walks anywhere

Actions only travel when Approach is enabled and the scene has an IMovementAdapter. The Dashboard's Movement row adds one. Without an adapter the approach is skipped silently, which is intentional — a game that positions its own actors should not be forced into ours.

CS0234: 'Debug' does not exist in the namespace 'Starhelm'

Starhelm 0.8.0 renamed the Starhelm.Debug assembly and namespace to Starhelm.Diagnostics, because Starhelm.Debug shadowed UnityEngine.Debug inside every Starhelm file and broke a plain Debug.Log. Change your using Starhelm.Debug; to using Starhelm.Diagnostics;. Types such as ActionDebugOverlay and ActionGizmos kept their names and their script GUIDs, so scenes and prefabs that already reference them are unaffected, and an asmdef referencing the assembly by GUID needs no change.

Compile errors after an update

• Delete Library/ScriptAssemblies or restart Unity: assembly renames need a full recompile.
• If Starhelm is installed as a package, Unity caches the resolved commit. Bump the version in the git URL (#v0.11.0) or remove the entry from Packages/packages-lock.json to force a re-fetch.

Assets lost their data after I renamed something

Polymorphic modules are stored with [SerializeReference], which records the type name and namespace. Renaming or moving a shipped type orphans that data unless it carries [MovedFrom]. This is why Starhelm freezes the identity of every module type it ships — do the same for your own once your project depends on them.

Performance questions

Steady-state execution allocates nothing: instances and contexts are pooled, tags are normalised once, and traces build no strings unless ActionTracing.Enabled is true (off in release builds). There are no coroutines anywhere — everything is tick-driven, which also makes it pausable and deterministic. If you need to profile, the executor exposes per-actor counters through executor.Stats.

Still stuck

Open an issue or use the contact form. A copy of the Debugger timeline for the misbehaving actor, plus the console output with Log Dialogue on, is usually enough to pin it down.