Troubleshooting
Installing
"Shader compilation failed" / "Global uniform 'hammerite_…' does not exist".
Once, on the very first import of a project, this is expected: Godot imports before any plugin can
declare the shader globals. If it goes on, the core plugin is not enabled - enable Hammerite Core
in Project Settings > Plugins - or the globals were removed; disabling and enabling the plugin
declares them again. The Hammerite autoload lists any that are missing when the game starts.
Errors about files under res://addons/hammerite-core/… not found. The addon folders must keep
their names and sit directly under res://addons/. See Installing.
"invalid UID … using text path instead". Harmless, and gone after the project's next import. It
means an addon's .import file was not copied with its asset; copy the addon folders whole.
Maps
A map will not open. The editor's message log (hover the status bar's last section) says why;
from code, HammeriteDataFile.last_error. The usual reasons:
- written by a newer Hammerite - the file's format is newer than this copy of the addons.
- it points at a script / a file outside the game - a map cannot name code, by design.
- the file is damaged - the save was cut short or the file was edited. The editor keeps the
previous save beside the map as
level.hmap.bak, and unsaved work aslevel.autosave.hmap.
A map opens with warnings in the log. Something in it is not what this game has now: a property a class no longer has (left out), a class this game does not have (kept, and saved back unchanged - typically an addon that has since been disabled), or a texture or model the game no longer provides. The Problems panel lists the last kind.
Faces show a magenta checkerboard. Their texture was not found. Set
HammeriteTextureLibrary.search_paths before the map is built, and check the texture's file name
matches the name the face holds.
An entity is missing in the game. The output has could not find script for classname …: no
class has the class_name its classname property names. Check the spelling and that the script
declares class_name.
A room is black, or light leaks between rooms. Bake again after carving; a bake describes the world as it was when baked. The Problems panel lists what the last bake could not do.
The editor
Shortcuts do nothing. A tool other than Select takes the plain keys while it is running: press
Esc first. Keys are also ignored while a text field has focus. On Windows and Linux, Cmd in the
manual is Ctrl, and a Ctrl combination is Alt.
Clicking selects brushes, not faces. Faces are picked in face mode: tap Q or press Faces on
the toolbar, or hold Q while clicking.
The UI is too small or too large. View > Bigger UI / Smaller UI (Cmd = / Cmd -). It is
remembered per machine.
The in-game manual is empty in an exported game. The editor plugin packs the addons' manual
pages into an export. Pages of your own kept elsewhere must be listed in
hammerite/manual/export_directories in the project settings.
Baking
Baking fails or crashes on start. Baking needs the Forward+ or Mobile renderer, and a GPU with
compute shaders. It does not run under the Compatibility renderer, on the web or with --headless:
the lightmap tool says so in its panel, and a script's bake() answers ERR_UNAVAILABLE. HammeriteLightmapper.can_bake() asks beforehand.
Baking is slow or runs out of memory. See Performance and limits: coarser lightmap scale on large dim surfaces is the main lever.