Getting Started
Troubleshooting & Safe Setup
Fix common setup issues and gather useful support details.
v0.9.4Godot 4.7 stable4.6.3 supportedCurrent
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. |
Godot setup verification checklist
Use this checklist after installing or updating Dreamcatcher to confirm that the editor surfaces, starter workflows, generated assets, validation tools, and export preparation helpers behave as expected.
| Area | Expected result |
|---|---|
| Enable plugin in clean project | Plugin loads without critical errors. |
| Restart Godot | Dreamcatcher surfaces return. |
| Disable/re-enable plugin | Docks/toolbars clean up and do not duplicate. |
| No-autoload mode | Autoload warning in this guide matches actual behavior. |
| Scene Composer | Creates/saves a usable scene. |
| Quick Play | Runs the chosen test scene. |
| Generated Asset Browser | Shows record, metadata, preview/report where supported. |
| Dungeon/map/overworld regeneration | Works from stored preset where supported. |
| Assign/apply | UI wording and actual behavior match metadata/supported-field boundaries. |
| Content Validator | Warnings/errors make sense and can be rerun. |
| Asset Cleaner | Review-before-delete behavior matches docs. |
| Export Preflight | Shows real Godot template/platform warnings. |
Common validation messages and fixes
| Validator message | Meaning | Fix |
|---|---|---|
| Item has no icon | UI may show an empty slot. | Assign a generated or imported icon. |
| Quest missing reward | Quest can finish without a clear result. | Add item, currency, flag, or state reward. |
| Map event missing target | Door/transfer may fail. | Assign destination scene/spawn. |
| Asset path inside plugin folder | User content may be unsafe during plugin update. | Move to res://dream/generated/ or a project folder. |
| Export template missing | Godot cannot build the target. | Install official Godot export templates. |
