API stability

Hammerite is versioned as one (HammeriteVersion.string(), and every addon's plugin.cfg), following semantic versioning over the classes listed here: their public properties, methods, signals and constants, the autoloads (Hammerite, HammeriteEditor, HammeriteAudio, HammeriteNavigation), and the shader contracts a game's own shaders are written against. What changes is in CHANGELOG.md, and what each of them does is in the API reference.

  • A patch release (2.0.x) fixes things and changes none of it.
  • A minor release adds to it.
  • Only a major release removes or changes any of it.

Hammerite 2.0 is native: its classes are one GDExtension library rather than scripts, and the API broke where a native class cannot say what a script could. Migrating to 2.0 has every change from 1.x. What 2.0 supports is this page's list, and it is held to for every 2.x release.

The virtuals are supported with their classes. A script extending a supported class overrides its virtuals - the entity interface's _set_editor_active, _apply_entity_property and the rest, a tool's _tool_input and _get_tool_name, a property control's _get_value - and those are part of it, as the class reference lists them under each class, the required ones included. Any other member whose name starts with _ is not: the library binds some privates under their old names because the suites reach them, and they are experimental.

Everything else is experimental: every other class, and any member of a supported class tagged experimental on its own - much of HammeriteMapEditor is what its own menus and tools call, and is marked so. It is tagged in its class reference, so Godot's built-in help and the API reference show the warning, and it may change in any release. In 2.0 that is most of what is underneath the list: the compiler and its fragments, the BVH and the grids, the lightmapper's passes, patches and packer, the entity sets and their entities (the logic entities, movers, triggers, spot and movable lights, particles, scenes as props), the audio graph and its builder, the navigation cache and floor edges, the editor's own tools, views, browsers and dialogs, the migration's class and its dialog, and the classes that describe the library itself. If you need something that is only experimental, say so - that is how things get onto this list.

The Dark mission importer is not part of any release after 2.0.0. Its classes - the importer, the Dark database and primals it reads with, and their objects and patrols - read a DromEd mission to benchmark Hammerite against it, and are built only into the dev package a checkout of the source builds (BUILDING.md), never into runtime or full. They are development only, not part of the supported API, and may change or go in any release.

What would break 2.x, and so waits for 3.0:

  • removing or renaming a supported class, or any public property, method, signal, constant, enum or enum value of one, or a virtual it lists;
  • changing what one takes or answers: an argument added without a default, a type narrowed, a virtual made required, an autoload member typed differently;
  • renaming anything in a shader contract;
  • a map or other data file saved by 2.x that a later 2.x does not open, or a resource it saved as a .tres or .res that a later 2.x does not load;
  • removing the migration from 1.x: tools/migrate_to_2.sh, File → Migrate 1.x Resources… in the map editor and Project → Tools → Migrate Hammerite 1.x Resources... in the Godot editor, and what each migrates. 2.0 reads no 1.x resource without it, so it ships with every 2.x release. Those three are the promise, not the class they call or its dialog, which are experimental like the rest of the migration's code.

Adding a class, a member or an argument with a default is not breaking, nor is anything experimental changing, nor a fix that makes a class do what its reference says it does.

A .hmap saved by any earlier Hammerite opens in a later one, 1.x's included; see "Compatibility" in the core README. A .tres, .res or scene 1.x saved has to be migrated before 2.0 loads it (Migrating a project).

Supported classes

Core: the map

HammeriteMap, HammeriteBrush, HammeriteFace, HammeriteEntity, HammeriteBrushEntity, HammeriteLayer, HammeriteCell, HammeritePortal, HammeriteBoundaryWall, HammeritePrefab, HammeritePrefabSet, HammeritePrefabInstance, HammeriteSkybox, and what the map hands back: HammeriteMapBakeWarning, HammeriteMapGraphWarning, HammeriteMapLightingSnapshot, HammeriteMapBVHHitResult, HammeriteFaceUvAnchor, and what a prefab builds: HammeritePrefabPlacement

Core: in the scene

HammeriteMap3D, HammeriteWorldrepCompile, HammeriteCompileProgress

Core: entities

HammeritePointEntityNode3D, HammeritePointEntityAnimatableBody3D, HammeritePointEntityRigidBody3D, HammeriteBrushEntityNode3D, HammeriteBrushEntityStaticBody3D, HammeriteBrushEntityArea3D, HammeriteEntityNodes, HammeritePointLight3D, HammeriteDynamicLight3D, HammeriteDynamicPointLight3D, HammeriteDirectionalLight3D, HammeriteDynamicDirectionalLight3D, HammeriteGenericBrushEntity, HammeritePropModel, HammeriteDecal3D, HammeriteGizmoBuffer, HammeriteEditorHandle

Core: lighting

HammeriteLightmapper, HammeriteBakeSettings, HammeriteLightmapBakeReport, HammeriteLightmapBakeReportPassSnapshot, HammeriteBakedLight, HammeriteLightProbeSet, HammeriteLightCurve, HammeriteEyeAdaptation3D, HammeriteBakeOccluders, HammeriteBakeOccluder, HammeriteBrushEntityLighting, HammeriteShaderGlobals

Core: files, names and extension

HammeriteDataFile, HammeriteDataFileReadReport, HammeriteUnknownData, HammeriteReferences, HammeriteReferenceChange, HammeriteTextureLibrary, HammeriteModelLibrary, HammeriteAssetLibrary, HammeriteBrushPropertySchema, HammeriteBrushPropertyDef, HammeriteBrushPropertyRegistry, HammeriteBrushFill, HammeriteBrushFillRegistry, HammeriteSkyPropertySchema, HammeriteSkyPropertyRegistry, HammeriteEntityTypeRegistry, HammeriteUtils, HammeriteVersion

Editor

HammeriteMapEditor, HammeriteMapEditorSettings, HammeriteEditorColors, HammeriteEditorTheme, HammeriteEditorCommand, HammeriteEditorCommands, HammeriteEditorTool, HammeriteEditorToolSimpleToolPopup, HammeritePropertyControl, HammeriteEditorWorkspaces, HammeriteManual, HammeriteManualSearchHit, HammeriteManualPageHeading, HammeriteManualSection, HammeriteManualPage, HammeriteNotableSizes

Audio

HammeriteAudioRuntime, HammeriteAudioManager, HammeriteAudioHearing, HammeriteAudioMixSettings, HammeriteAudioSoundSpec, HammeriteAudioBakeReport, HammeriteAudioEmitter3D, HammeriteAudioReceiver3D, HammeriteAudioSoundTypes, HammeriteAudioSoundType, HammeriteAudioSoundEvent, HammeriteAudioPreset, HammeriteAudioMaterials, HammeriteAudioMaterial, HammeriteAudioBrushProperties, HammeriteAudioPortalProperties, HammeriteAudioEditorExtension

Navigation

HammeriteNavigationRuntime, HammeriteNavigationAgentProfile, HammeriteNavigationAgentProfiles, HammeriteNavigationBrushProperties, HammeriteNavigationEditorExtension, HammeriteNavigationLinkEntity3D, HammeriteNavigationBakeReport, HammeriteNavigationSurface, HammeriteNavigationLinkData, HammeriteNavigationBuilder, HammeriteNavigationLinkBuilder, HammeriteNavigationMeshWriter

Shader contracts

A game draws its own water and its own sky with shaders of its own, and those are written against names in Hammerite's shaders rather than against a class. These are covered by the same promise.

Water - a shader_type spatial shader that includes res://addons/hammerite-core/resources/materials/hammerite_water.gdshaderinc, defines void water_surface(inout HammeriteWater w), and then includes hammerite_water_main.gdshaderinc (see "Water's look" in the core README).

  • struct HammeriteWater. What the surface is handed: time, uv, uv2, screen_uv, depth, position, normal, view_dir, ndotv, from_above, inv_view, inv_projection, vertex, and the brush's clarity, tint and disturbance. What it gives back: colour, alpha, carried.
  • The helpers: water_travelled, water_below, water_lit, water_lit_from_below, water_slope, water_height, water_view_position, water_transmittance, water_fresnel.

Anything else those files declare - their uniforms, and what they include in turn - is not part of it.

Walls - a shader_type spatial shader that includes res://addons/hammerite-core/resources/materials/hammerite_surface.gdshaderinc, defines void brush_surface(inout HammeriteSurface s), and then includes hammerite_surface_main.gdshaderinc, handed over as HammeriteBrush.get_surface_material() (see "Walls' look" in the core README).

  • struct HammeriteSurface. What the surface is handed: time, uv, uv2, position, face_normal, view_dir, u_axis, v_axis, has_uv_axes. What it gives back: albedo, normal, glow.
  • The helper surface_normal_from_map.

Sky - a shader_type sky material handed to HammeriteSkybox.set_dome_material(). A uniform it declares under one of these names is set from the skybox: horizon_color, zenith_color, body_direction, body_color, body_energy, body_is_moon, light_energy. And one named after each property declared on the sky (HammeriteSkyPropertyRegistry), with / as _: clouds/cover is clouds_cover.

Shader globals - the names HammeriteShaderGlobals declares.

Hammerite 2.0 · built from 6d57ab2d, 2026-10-17