Support
Troubleshooting
How to isolate problems, validate, and report useful details.
v0.9.4Godot 4.7 stable4.6.3 supportedSupport
This page summarizes the current v0.9.4 workflow and keeps Early Access boundaries clear.
Troubleshooting
| Problem | First fix |
|---|---|
| Plugin does not appear | Check folder nesting. The correct path is addons/dreamcatcher/plugin.cfg. Restart Godot after fixing. |
| Panels are missing | Restart Godot, reset editor layout if needed, and check whether plugin enabled cleanly. Check Module Manager and no-autoload mode. |
| A custom node is missing | The module that owns it may be disabled. Open Module Manager and verify module state. |
| Generated asset does not appear | Refresh filesystem, check res://dream/generated/_registry/, and run generated asset validation. |
| Regenerate button is disabled | Direct regeneration is mainly supported for stored map/dungeon/overworld presets in v0.9.4. |
| Assign says metadata-only | This is expected for some v0.9.4 assignments. It means traceable assignment metadata was saved but full runtime binding may need later/manual setup. |
| Quick Play does not run | Validate the current scene, check for missing main scene/current scene, and review Godot output errors. |
| Visual Logic does not trigger | Check trigger area/collision layers, assigned sequence, condition values, and whether the actor can interact with the object. |
| NPC dialogue does not show | Check dialogue resource reference, speaker/portrait references, interaction trigger, and UI/dialogue system availability. |
| Chest gives infinite rewards | Add an opened variable/switch and check it before giving the reward. |
| Map event does not work | Validate destination references, trigger shape, collision layers, target scene/spawn ID, and event page conditions. |
| Imported tilesheet looks wrong | Check tile size, layout profile, spacing/margins, and asset license/ownership. |
| Audio/VFX does not play | Check file path, assignment target, audio bus, metadata-only status, and whether runtime binding is supported for that case. |
| Export Preflight fails | Install Godot export templates, check missing scenes/resources, and review platform-specific SDK/account requirements. |
| Project feels slow | Run Content Validator, use Asset Cleaner, inspect Performance Panel, and reduce heavy generated content until the prototype is stable. |
If nothing happens: debugging Dreamcatcher logic
Debugging is checking the chain from player action to feedback. Do not randomly change many things. Follow the chain.
Player action→Trigger emitted?→Object receives?→Graph assigned?→Conditions pass?→Action runs?→Feedback visible?→State saved?
| Symptom | Most likely missing link | First checks |
|---|---|---|
| NPC does nothing | Trigger or graph assignment | InteractionArea, event trigger, DreamBehavior graph, signal name |
| Dialogue opens but quest does not start | Choice consequence link | Choice ID, graph call, quest ID, switch/variable name |
| Door never opens | State condition | Door graph, unlock switch, quest completion, condition branch |
| Attack animation plays but no damage | Hitbox/hurtbox/damage graph | AttackArea, Hurtbox, collision layers, damage formula |
| Enemy does not chase | Detection/navigation/AI state | DetectionArea, AI graph, navigation, collision blockers |
| HUD does not update | State binding or signal | HUD instance, data source, update graph, signal connection |
| Validator complains about missing resource | Broken reference | File path, ID spelling, renamed/deleted asset, registry entry |
Presentation-specific debugging
Use this when the core logic works but the game does not feel or respond correctly.
Sound does not play
- Can the sound preview in Sound Studio?
- Is the project path still valid?
- Is the Visual Logic action after the real event?
- Is volume/mute set correctly?
- Does a temporary input trigger play it?
Music stacks or never stops
- Check map BGM versus battle BGM ownership.
- Confirm combat start/end triggers both exist.
- Do not start the same loop repeatedly on every frame.
- Restore map music after battle/cutscene ends.
Animation does not switch
- Check animation names exactly.
- Confirm the state actually changes.
- Test one animation with a temporary trigger.
- Check whether attack/hurt locks need to end.
VFX appears in the wrong place
- Check local versus global coordinates.
- Spawn on the target object first.
- Check if the effect is parented to UI, map, or actor.
- Test with a visible placeholder effect.
Cutscene never returns control
- Confirm an end beat exists.
- Check the return-control action.
- Check dialogue/camera wait completion.
- Add a debug fallback key only while testing.
UI feedback does not update
- Confirm the HUD scene is loaded.
- Check label/bar node path.
- Confirm the state/event actually changes.
- Test one UI update with a temporary input graph.
