Getting started

From an empty project to a room you can carve, light and walk around in. The finished result is examples/minimal: open it in Godot from inside this repository (its addons/ are links to the addons beside it) and press F5.

Install the addons first: Installing Hammerite.

1. Textures

Hammerite looks textures up by name. Put some in a folder - res://textures/stone_wall.png is the texture stone_wall - and tell the library where they are before any map is built:

HammeriteTextureLibrary.search_paths = ["res://textures"]

A face whose texture cannot be found draws the fallback checkerboard, so a missing texture is seen rather than silently wrong.

2. A map in the scene

A map is data (HammeriteMap); HammeriteMap3D is the node that builds it into the world.

var map: HammeriteMap = HammeriteDataFile.read("res://maps/start.hmap") as HammeriteMap

var map_3d := HammeriteMap3D.new()
add_child(map_3d)
map_3d.map = map

The world starts running as soon as it is built: anything in it that moves, flickers or plays does so without being told to. With the editor up over it, it is held still for the author. Entities are placed in the map's space, so map_3d can stand anywhere in your scene.

A game's own entity types are registered before the map is built; see Custom entities.

.hmap is Hammerite's own format: data only, safe to load from anywhere, and the one the editor saves a player's or a mod's map in. A map can also be a Godot .tres or .res inside the project. HammeriteDataFile.last_error says why a read returned null.

3. The editor

The editor runs inside the game, over the level the game has loaded, so what you see while editing is the game itself. The game decides when it opens:

map_editor = HammeriteEditor.integrate(self)   # a node already in the tree
map_editor.map_3d = map_3d                     # before the map
map_editor.map = map
map_editor.deactivate()                        # start in the game

func _unhandled_input(event: InputEvent) -> void:
    if event is InputEventKey and event.pressed and event.keycode == KEY_F10:
        if map_editor.is_active():
            map_editor.deactivate()
        else:
            map_editor.activate()

Quitting is the game's too. Ask the editor first, so unsaved work is offered a save:

func _ready() -> void:
    get_tree().auto_accept_quit = false

func _notification(what: int) -> void:
    if what == NOTIFICATION_WM_CLOSE_REQUEST and await map_editor.prompt_unsaved_changes():
        get_tree().quit()

4. Carve, light, save

Run the game and press F10. The editor's own manual is under Help > Manual (Shift F1), and its first page walks through a first room: press B, draw a box (new brushes are Air until you change the tier on the toolbar), Enter to keep it. The world is solid rock until you carve it; the manual's The carved world explains why that matters.

Light with a light_point entity and the lightmap tool (Cmd L, Bake), then File > Save Map (Cmd S). The bake is saved with the map; the game shows it without baking again.

5. Your own things

• Entities of your own - doors, pickups, spawn points: Custom entities.
• What each addon offers and how to extend the editor: the READMEs of core, editor, audio and nav.
• How big a level can get: Performance and limits.