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.

"Can't open GDExtension dynamic library" / "Hammerite's native library is not loaded". The library is in hammerite-core/bin/, and core does not load without it - the parse errors that follow, about HammeriteGeometry and the rest, are what is left without it. Copy the folder whole, bin/ included. A checkout of the Hammerite repository has no library until it builds one: tools/build_native.sh. A platform with no library in bin/ - Web among them - is not supported.

"addons/hammerite-editor/ is installed, but Hammerite's native library is the runtime package" / "… which is built with addons/…, but it is not installed". The folders and the library came from different packages: a runtime library with the editor's folder beside it, or a full one with a folder missing. A package is installed whole - replace all of the folders with one package's. See Installing. In a checkout, tools/build_native.sh runtime installs the runtime library under the full package's folders; tools/build_native.sh puts full back.

"Hammerite's native library, the full package, was built from other sources". Only in a checkout: the sources have changed since the library was built. Run tools/build_native.sh there.

"Failed loading resource: res://addons/hammerite-core/scripts/resources/map.gd", or another script under res://addons/hammerite-*/scripts/, followed by a map, a bake or a scene of your own failing to load. The file was saved by Hammerite 1.x, which named its classes by those scripts, and 2.0 has none of them. Migrate the project: tools/migrate_to_2.sh, or Project → Tools → Migrate Hammerite 1.x Resources... in the Godot editor. See Migrating to 2.0.

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.get_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 as level.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.get_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.