Troubleshooting

Troubleshooting

Start with Tools > Starhelm > Hub. 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

1. Is there an executor? Without one, no queue is ever ticked. The Hub 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 Hub.

Nothing walks anywhere

Actions only travel when Approach is enabled and the scene has an IMovementAdapter. The Hub'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.

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.8.2) 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.