HammeriteMapEditor

Editor. Inherits PanelContainer

The in-game level editor: a Control that edits a HammeriteMap through the game's own HammeriteMap3D, and the object games and addons extend it through.

Get one from HammeriteEditor.integrate(), which puts it in the tree, then set map_3d before map and show or hide it with activate() and deactivate(). The host owns the key that toggles it, and should ask prompt_unsaved_changes() before quitting. The seams a game or addon extends it through: entity types (register_point_entity_type(), extend_point_entity_type() and their brush counterparts), property controls (register_property_editor(), register_property_choices(), register_brush_property_editor(), register_brush_property_choices()), register_runtime_panel(), register_cell_overlay(), add_toolbar_button(), add_right_panel(), register_manual_section(), register_manual_pages(), and commands for menu items and keys. They may be called before the editor is in the tree. How they are named, and undone. register_* stores a definition, named by an id or a pair the caller chose, and unregister_* takes it away by the same; add_* puts a node in the editor, and remove_* takes that node back - so keep what an add_* returns, or the control it was handed. Every seam has its inverse, so an addon can undo all of what it did. Most of its other methods are what the editor's own menu commands and tools call - selection verbs, start_*_tool, toggles - and log their outcome to the editor's message log rather than returning it. Those are marked experimental: free to change, and not for a host to call.

Properties

Methods

Signals

active_status_changed

signal active_status_changed(active: bool)

Emitted when editor activates or deactivates

grid_changed

signal grid_changed(grid: HammeriteGrid)

Emitted when the grid has changed.

active_tool_changed

signal active_tool_changed(tool: HammeriteEditorTool)

Emitted when the active tool has changed.

active_texture_changed

signal active_texture_changed(texture: Texture2D)

Emitted when the active texture has changed.

active_decal_changed

signal active_decal_changed(texture: Texture2D)

Emitted when the decal the decal tool will place changes, so the tool's panel can show it.

selection_changed

signal selection_changed()

Emitted when selection has changed.

map_changed

signal map_changed(map: HammeriteMap)

Emitted when the map has changed.

map_saved

signal map_saved(map: HammeriteMap)

After map has been written to disk, with its worldrep caches: for an addon that keeps a cache of its own beside the map, as hammerite-nav does.

tool_metadata_changed

signal tool_metadata_changed(object_id: StringName, key: StringName, value)

Emitted when tool metadata has changed.

tool_metadata_cleared

signal tool_metadata_cleared()

Emitted when tool metadata has been cleared.

volume_mode_changed

signal volume_mode_changed(mode: int)

Emitted when the global volume authoring mode has changed.

gizmos_presented

signal gizmos_presented()

Emitted once a frame, when presented_gizmos holds what that frame drew.

runtime_state_changed

signal runtime_state_changed()

Emitted when the editor has done something to running entities - an action, or starting, pausing or resetting them - so what shows their runtime state can read it again.

cell_overlay_changed

signal cell_overlay_changed(overlay_id: StringName)

Emitted when the cell overlay changes, so the viewports redraw.

Enumerations

enum VisualizationMode

enum VolumeMode

enum DockOrder

Constants

ANY_TYPE

const ANY_TYPE = &"*"

For register_property_editor(): a control for a property every entity type carries.

PANEL_WIDTH_MIN

const PANEL_WIDTH_MIN = 120.0

Narrowest a side panel may be dragged. Not zero: a panel dragged shut is one an author has to know to drag back out of the edge of the window, and the layer tree and the property rows stop being readable long before that.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

BROWSER_SHARE

const BROWSER_SHARE = 0.66

How much of the editor a browser covers when it opens. Most of it, because picking a texture is looking at a wall of them - and not all of it, because a picker that fills the screen reads as a mode rather than as a choice.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

ENTITY_SEARCH_SHARE

const ENTITY_SEARCH_SHARE = Vector2(0.3, 0.4)

How much of the editor the entity search popup covers, as a fraction of the editor's width and height.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

WIRED

const WIRED = &"hammerite_menu_wired"

Marks a popup this class has already connected to. See fill_menu().

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

LAUNCHER_RECENT

const LAUNCHER_RECENT = 20

How many commands the launcher remembers having run.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

LAUNCHER_SHARE

const LAUNCHER_SHARE = Vector2(0.4, 0.45)

How much of the editor the command launcher covers, as a fraction of the editor's width and height.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

AUTOSAVE_SECONDS

const AUTOSAVE_SECONDS = 300.0

How often a map with unsaved changes is written to its autosave.

Property descriptions

map

var map: HammeriteMap = null

The map being edited. Assigning one swaps it in at once, with no question about unsaved changes (ask prompt_unsaved_changes() first): it is given to map_3d, or to the 3D map assigned later, the active layer goes back to 0, the map counts as saved, and map_changed is emitted. To open a file use open_map_at().

map_3d

var map_3d: HammeriteMap3D = null

The game's HammeriteMap3D the editor shows and simulates. Setting it parents the editor's 3D overlays under it, gives it map when there is one, and hooks its editor state to active_status_changed. See set_map_3d().

camera

var camera: HammeriteEditorCamera = null

The focused view's camera, as a HammeriteEditorCamera facade built fresh on every read. Same as get_camera().

default_texture

var default_texture: Texture2D = null

The texture that is active when the editor starts, read once in _ready. Null starts with none.

settings

var settings: HammeriteMapEditorSettings = <unknown>

The project's editor settings. The editor keeps a copy of what it is given and changes only that as the author toggles options, so the project's resource is only ever read; what the person chose is remembered in workspace. Change a palette or an option through this after assigning it.

workspace

var workspace: HammeriteEditorWorkspace = <unknown>

How this person has arranged the editor, as against how the game has dressed it. Read from user:// before anything is built, so the panels come up the width they were left - see HammeriteEditorWorkspace for why it is a second file rather than more fields on settings.

core

var core: HammeriteMapEditorCore = <unknown>

Core editing logic (pure logic, no UI dependencies)

manual

var manual: HammeriteManual = <unknown>

The manual's sections and pages. Addons and games add theirs with register_manual_section() and register_manual_pages().

manual_browser

var manual_browser: HammeriteManualBrowser = null

Built the first time the manual is opened.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

entity_search

var entity_search: HammeriteEntitySearchPopup = null

The entity search popup, built the first time open_entity_search() is called; null before that.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

command_launcher

var command_launcher: HammeriteCommandLauncher = null

Built the first time it is opened.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

active_layer_id

var active_layer_id: int

Active layer ID - new objects will be created in this layer

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

prefab_sets

var prefab_sets: Dictionary[String, HammeritePrefabSet]

Loaded prefab sets mapped by their file path.

viewport

var viewport: Viewport = null

The focused view's SubViewport - the maximised one while a view is maximised. Null while no view has focus.

quad_viewport

var quad_viewport: HammeriteQuadViewportContainer = null

The container of the four views (perspective, top, front, side). Built in _init.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

gizmos

var gizmos: HammeriteGizmoBuffer = <unknown>

What tools, the selection and the editor's own nodes want drawn over the level this frame. Written from anywhere during the frame, shown once everything has had its turn, then emptied.

presented_gizmos

var presented_gizmos: HammeriteGizmoBuffer = <unknown>

The last frame of gizmos, as the views draw it.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

canvas

var canvas: HammeriteEditorCanvas = null

The layer the editor is drawn on, and the authority on how big it is drawn. Null when something built the editor itself rather than through HammeriteEditor.integrate() - the tests do, and nothing here may assume it is there. Setting it is what wires the scale in both directions, because there is more than one way for the scale to change and only one of them came through ui_scale: the View menu's bigger and smaller call HammeriteEditorCanvas.step() straight on the canvas. Listening to the canvas catches every route rather than the one that happens to go through this class - which is why the remembered scale was written by the property and never by the menu, and so never came back.

ui_scale

var ui_scale: float = 1.0

What the editor is drawn at, in physical pixels per UI unit. See HammeriteEditorCanvas.

grid

var grid: HammeriteGrid

HammeriteGrid (delegated to core)

active_tool

var active_tool: HammeriteEditorTool

Active tool (delegated to core)

active_tool_popup

var active_tool_popup: Control = null

The panel the active tool shows in the Tool Options box, or null. Freed when the tool is left; see set_active_tool_popup().

active_texture

var active_texture: Texture2D

Active texture (delegated to core)

texture_browser

var texture_browser: HammeriteTextureBrowser = null

The texture browser window, built in _ready and opened with open_texture_browser().

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

decal_browser

var decal_browser: HammeriteTextureBrowser = null

The same browser pointed at the decal library - see HammeriteTextureBrowser.library.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

active_decal

var active_decal: Texture2D = null

What the decal tool will place, chosen from decal_browser.

terrain_cell_size

var terrain_cell_size: float = 32.0

How wide a cell of terrain is made, in world units, when a brush is converted to one.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

entity_browser

var entity_browser: HammeriteEntityBrowser = null

What the entity tool offers, in the left panel. Long-lived rather than made per tool session: the pictures in it cost a frame each to draw and nothing about a type changes while the editor runs.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

prop_browser

var prop_browser: HammeritePropBrowser = null

The model browser the prop tool shows in the left panel.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

prefab_browser

var prefab_browser: HammeritePrefabBrowser = null

The prefab browser the prefab tool shows in the left panel. Refilled by load_prefab_set() and create_prefab_set().

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

selection

var selection: HammeriteObjectSelection

Selection (delegated to core)

assign_selected_texture

var assign_selected_texture: bool = true

Whether a texture chosen in texture_browser also becomes active_texture. Set on every open_texture_browser(); see set_active_texture().

show_grid

var show_grid: bool = true

Whether the grid on the walls is asked for. Assigning it applies it and remembers it in workspace, as toggle_grid() does.

show_wireframes

var show_wireframes: bool = true

Whether the compiled graph's outlines are wanted - see toggle_wireframes(). Assigning it applies it and remembers it in workspace, so it survives closing the editor.

show_detail_tint

var show_detail_tint: bool = true

Whether detail-tier brushwork wears its tint - see toggle_detail_tint(). Assigning it applies it and remembers it in workspace.

vis_mode

var vis_mode: int = 0

What the 3D views shade with while the editor is active. Assigning it is the same as set_vis_mode().

volume_mode

var volume_mode: int = 1

Global brush authoring tier (see VolumeMode). New brushes are stamped with this at commit time. Defaults to AIR: the world starts as rock, so the first thing drawn is a room.

top_working_plane_offset

var top_working_plane_offset: float = 0.0

Height (world Y) of the working plane the top view draws and projects onto, in world units. The views read it each time; see get_working_plane().

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

front_working_plane_offset

var front_working_plane_offset: float = 0.0

Depth (world Z) of the front view's working plane, in world units.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

left_working_plane_offset

var left_working_plane_offset: float = 0.0

Position along world X of the side view's working plane, in world units.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

undo_redo

var undo_redo: UndoRedo

UndoRedo (delegated to core)

picks_faces

var picks_faces: bool = false

Clicks and box selections pick faces rather than brushes and entities.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

dock

var dock: HammeriteDock = null

The side columns and the panels in them, which an author can move between the two and fold.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

commands

var commands: HammeriteEditorCommands = null

Every command the editor has, what it is bound to, and where it appears. Addons add to it with HammeriteEditorCommands.register(); the menubar reads it; _input() dispatches through it. It is the only place a binding is written down.

Method descriptions

suggest_ui_scale()

func suggest_ui_scale(scale: float) -> void

What the HOST thinks the editor should be drawn at - its own UI-scale setting, usually. A suggestion rather than an assignment, and the difference is the whole point: the host reads its settings file on the first frame and tells the editor a frame after that, which lands AFTER the remembered scale has been restored and puts the project's answer back over the person's. Told this way, the host's answer is the starting point on a machine where nobody has chosen, and is quietly ignored on one where somebody has. A host reacting to its setting actually CHANGING should assign ui_scale instead. That is somebody moving a slider now, and it should win.

dress_window()

func dress_window(window: Window) -> void

Hand a popup the editor's scale. A Window is not on the editor's layer, so without this it comes up at whatever the host project scales its own UI by - which is the thing the layer exists to stop.

windows_to_dress()

func windows_to_dress() -> Window[]

The popups the editor built for itself, for the layer to scale. Asked for rather than found in the tree: a browser is built before the editor is in a tree at all, and is only parented while it is up - which is exactly when it is too late to decide how big it should be.

step_ui_scale()

func step_ui_scale(up: bool) -> void

One step bigger or smaller, for the two commands in the View menu.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

to_embedder()

func to_embedder(point: Vector2) -> Vector2

Where a point in the editor's own coordinates is, in the coordinates a popup Window is placed in. The editor's coordinates are physical pixels (HammeriteEditorCanvas); a popup is not on that layer, so it is placed either in the embedding viewport's units or - when subwindows are real windows - on the screen. Both are this, and neither is the editor's own.

embedder_size()

func embedder_size(units: Vector2) -> Vector2

The same conversion for a size rather than a point.

set_volume_mode()

func set_volume_mode(mode: int) -> void

Set the global brush authoring tier. HammeriteBrush tools stamp this onto what they draw.

cycle_volume_mode()

func cycle_volume_mode() -> void

Cycle SOLID -> AIR -> DETAIL -> SOLID. Convenient to bind to a key or toolbar button.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

stamp_new_brush()

func stamp_new_brush(brush: HammeriteBrush) -> void

Make brush what a new brush is made as: the current volume_mode and the active layer. Called by every tool that draws one. Detail is an additive solid occupant, so it maps to SOLID + is_detail.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

apply_volume_mode_to_selection()

func apply_volume_mode_to_selection() -> void

Apply the current volume_mode to the selected brushes, with undo - the "change an existing brush's tier" counterpart to stamping new brushes. Setting volume_type / is_detail emits tier_changed, which recompiles the worldrep and re-routes each brush's 3D representation.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

apply_fill_to_selection()

func apply_fill_to_selection(fill_id: StringName) -> void

Fill the selected air brushes with fill_id (empty for nothing), with undo. Air only: a fill says what is IN a room, so a solid in the selection is skipped rather than silently given a fill nothing would ever read.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

bring_selection_to_front()

func bring_selection_to_front() -> void

Put the selected brushwork last in the CSG program, so it wins wherever it overlaps. The program runs in order and a solid after an air brush fills it, so "in front" is "later" - which is what puts a pillar back that the room drawn after it swallowed. Until now the only way was to duplicate the pillar, because a new brush goes to the end.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

send_selection_to_back()

func send_selection_to_back() -> void

And first, so everything drawn since wins over it: a room carved after this rock still carves it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

apply_csg_place_to_selection()

func apply_csg_place_to_selection(field: StringName, value: int) -> void

Write one of the two CSG-place numbers onto every selected brush, from the inspector.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

apply_interior_exterior_to_selection()

func apply_interior_exterior_to_selection(mode: int) -> void

Say whether the selected rooms count as outdoors for the light bake, or leave it derived. Air only, for the reason a fill is: it is an answer about a room, and the rock around one is not lit by daylight whatever anybody says about it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

top_rows()

func top_rows() -> Control[]

The menubar's row and the toolbar, top first: what HammeriteEditorWorkspaces stands its logo beside.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

set_logo_inset()

func set_logo_inset(width: float, rows: int) -> void

Leave width free at the left of the first rows of top_rows(), where the logo is drawn over them, and none at the left of the rest.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

open_context_menu()

func open_context_menu(at: Vector2 = Vector2(inf, inf)) -> void

Open the right-click menu for whatever is selected now, at the cursor or at at. at is in the editor's own coordinates; a popup is a Window and is placed in neither those nor the viewport's, which is what to_embedder() is for. Does nothing when nothing applies. See HammeriteContextMenu.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

fill_viewport_menu()

func fill_viewport_menu(popup: PopupMenu) -> void

The dropdown in the corner of the perspective view, filled from the table like everything else, so the keystroke, the tick and the label are one definition rather than three. Public because the viewport builds the button and this class owns the commands.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

fill_menu()

func fill_menu(menu_name: StringName, popup: PopupMenu) -> void

Put the commands of menu_name into popup, and wire it to run and refresh them.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

measure()

func measure(position: Vector3, text: String) -> void

Show text at position for this frame. Tools call it from process, so it lasts exactly as long as the drag does.

measure_box()

func measure_box(box: AABB) -> void

Show the size of box along every axis it has one, in world units, on the three edges that meet at its near-bottom corner. What a brush tool is drawing is a box, and its size is the question the author is answering while they drag it.

measurement_text()

static func measurement_text(units: float, axis: int = -1) -> String

How a measurement reads: whole units, since the grid is whole units and so is everything an author types, and the name of that size along axis when the game has one for it - "108 (door frame height)" up a wall, and only there. What is worth naming is a fact about a game, so the names come from HammeriteNotableSizes, which Hammerite leaves empty. axis is a Vector3.Axis, or -1 for a measurement along none of them - see measurement_axis().

measurement_axis()

static func measurement_axis(direction: Vector3) -> int

The Vector3.Axis a measurement along direction is a size on, or -1 when it runs along none of them - a face pulled out of a sloped roof is not measuring a height or a width.

has_picked_face_uv()

func has_picked_face_uv() -> bool

Whether anything is held to paint with. What the select tool asks before reading a click as a paint rather than as a selection.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

pick_face_uv()

func pick_face_uv() -> void

Take the UVs off the selected face, to be painted onto others. One face, because "make these look like that one" has one THAT in it - several selected faces that disagree have no answer to pick up, and the first of them in an arbitrary order is not it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

drop_picked_face_uv()

func drop_picked_face_uv() -> void

Forget what was picked up, so a click is a click again.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

paint_face_uv()

func paint_face_uv(faces: HammeriteFace[]) -> void

Paint what was picked up onto faces, carrying the texture when the setting says to.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

paint_face_uv_on_selection()

func paint_face_uv_on_selection() -> void

Paint what was picked up onto every selected face.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

present_gizmos()

func present_gizmos() -> void

Show this frame's gizmos in every view and start the next frame empty.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

selection_labels()

static func selection_labels(map: HammeriteMap, chosen: HammeriteObjectSelection, sets: Dictionary[String, HammeritePrefabSet]) -> Array

What to call each selected prefab instance and brush entity, and where: [[top of its box, text], ...] (#67). A point entity names itself (HammeriteEntity2D); a box of brushes has nothing to say what it is, and selecting one - a click on any of its brushes - looked just like selecting that brush. An instance is called by its prefab and id, "window_breakable (211)"; a brush entity by its type and its name if it has one, "door (main_gate)". One inside a selected instance is the instance's.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

narrow_or_exit()

func narrow_or_exit() -> void

Cmd+N: further in if there is something to narrow to, out if there is not, and in from nothing.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

pop_narrow_or_narrow()

func pop_narrow_or_narrow() -> void

Cmd+Shift+N. Enters from nothing, same as Cmd+N did, rather than doing nothing at all.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_move_tool()

func start_move_tool() -> void

G: what "move the thing I picked" means depends on what was picked.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

begin_volume_tier_choice()

func begin_volume_tier_choice() -> void

Tab going down: a tap cycles the volume type, a hold opens the wheel at the cursor (#53). Which one it was is only known when it comes up again (_finish_volume_choice()). Takes the event so the focus does not jump off the viewport onto the toolbar.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

press_face_mode_key()

func press_face_mode_key() -> void

The face mode key going down turns face mode over at once, so a hold picks faces from the first click. A tap leaves it that way; a hold, or a click during the press, turns it back on release (_tick_face_mode_key()).

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

set_uv_lock()

func set_uv_lock(locked: bool) -> void

The toolbar button and the Edit menu's tick are two views of one setting; whichever is used, the other has to follow.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

toggle_grid()

func toggle_grid() -> void

Show or hide the grid drawn on the walls (the hammerite_show_grid shader global, only while the editor is active), and remember the choice in workspace.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

is_grid_3d_requested()

func is_grid_3d_requested() -> bool

Whether the grid plane in the perspective view is asked for. What the author asked for, not whether it is on screen: it is hidden while the editor is inactive.

toggle_grid_3d()

func toggle_grid_3d() -> void

Show or hide the grid plane in the perspective view, and remember the choice in workspace.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

are_wireframes_requested()

func are_wireframes_requested() -> bool

Whether the compiled graph's outlines are wanted: cell walls, the hatched discarded faces and portal apertures (HammeriteSubtractiveOverlay3D). What the author asked for, not whether they are on screen - the editor being away takes them off screen without changing the answer.

are_detail_tints_requested()

func are_detail_tints_requested() -> bool

Whether detail brushwork wears its tint - what the author asked for, as with are_wireframes_requested(). Detail brushwork is dressing rather than structure, and the tint says which is which while you are building. It is in the way while you are looking at what you built.

toggle_detail_tint()

func toggle_detail_tint() -> void

Show or hide the tint on detail brushwork, and remember the choice in workspace.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

toggle_wireframes()

func toggle_wireframes() -> void

Show or hide the compiled graph's outlines (see are_wireframes_requested()), and remember the choice in workspace. They describe how the world was carved, which is what you want while carving it and clutter while looking at the room you carved.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

is_typing()

static func is_typing(viewport: Viewport) -> bool

Whether a key pressed in viewport is somebody typing: a text field or a spin box has the focus. Anything with a single-key shortcut asks this first, or the letter never reaches the field.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

uv_pinned_faces()

func uv_pinned_faces() -> Array

The faces that have been pinned about UV lock, as [locked, unlocked] (#72), while the face tool is running - and nothing at any other time, since this is an answer to a question only that tool asks. Only faces that carry the property themselves. Every other face follows the editor's own setting, which is in the Edit menu with a tick beside it; drawing all of them would be drawing the setting on every wall in the map. What is worth seeing is where somebody has departed from it - and because the property bag is sparse, that set is small by construction.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

invalidate_uv_pins()

func invalidate_uv_pins() -> void

Work the pinned faces out again on the next frame that asks. Cheap to call; the walk is over every face in the map, so it is not something to do per frame.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

toggle_wysiwyg_previews()

func toggle_wysiwyg_previews() -> void

Toggle WYSIWYG tool previews (see HammeriteMapEditorSettings.wysiwyg_previews). With them on, the brush a tool is drawing takes part in the compiled world, so a carve actually carves; with them off it is a wireframe and the world only changes on commit.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

remember_toggle()

func remember_toggle(toggle: StringName, on: bool) -> void

Record that the author turned toggle, one of HammeriteMapEditorSettings's options, to on, so the next session starts that way.

toggle_warning_markers()

func toggle_warning_markers() -> void

Show or hide the 2D viewports' warning markers. They sit on top of the geometry, so there has to be a way to get them out of the way while working on something dense. Editor-only regardless: nothing draws these during gameplay.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

toggle_fade_off_cut()

func toggle_fade_off_cut() -> void

Turn HammeriteMapEditorSettings.fade_off_cut over - whether a 2D view draws faintly what its cut does not pass through - remember it in workspace, and redraw the 2D views.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

get_active_selection()

func get_active_selection() -> HammeriteObjectSelection

Get the active selection (delegated to core)

merge_selected_brushes()

func merge_selected_brushes(remove_source_brushes: bool = true) -> void

Merges selected brushes into one.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

register_point_entity_type()

func register_point_entity_type(typename: StringName, props: Dictionary) -> void

Declare the point entity type typename. props are the defaults a new entity of it gets, laid over HammeriteMap.BASE_ENTITY_PROPS: classname names the node class HammeriteMap3D builds for it, _aabb sizes its editor box, and _editor_* keys (_editor_icon, _editor_tint, _editor_rotation_axes) are display-only and never stored on entities. Replaces any registration of that name, so re-registering one of core's types drops every property it is not given here; to refine an existing type, use extend_point_entity_type().

unregister_entity_type()

func unregister_entity_type(typename: StringName) -> void

Take away the entity type typename, point or brush. Entities of it in a map keep their type, and are built again if it is registered again.

register_brush_entity_type()

func register_brush_entity_type(typename: StringName, props: Dictionary) -> void

As register_point_entity_type(), for a type made of brushwork. Replaces any registration of that name; see extend_brush_entity_type().

extend_point_entity_type()

func extend_point_entity_type(typename: StringName, props: Dictionary, base: StringName = &"") -> void

Register typename as the registered type base (by default typename itself) with props laid over its properties - the way to add a field to one of core's types without losing the ones it already has, or to derive a new type from one. Amending a type that is not registered yet registers nothing and pushes an error, so call it after the type's owner has registered it. Deriving a new type from a missing base pushes an error and registers props alone.

extend_brush_entity_type()

func extend_brush_entity_type(typename: StringName, props: Dictionary, base: StringName = &"") -> void

As extend_point_entity_type(), for a brush entity type.

register_property_editor()

func register_property_editor(entity_type: StringName, prop_name: StringName, factory: Callable) -> void

Give the property prop_name of the entity type entity_type an inspector control of the game's own. factory is called as factory(value, map: HammeriteMap, entity: HammeriteEntity) each time the row is built, and returns a HammeritePropertyControl. entity_type may be ANY_TYPE for a property every entity carries; a registration naming the type outright wins over it. Registering the same pair again replaces the factory; unregister_property_editor() takes it away.

unregister_property_editor()

func unregister_property_editor(entity_type: StringName, prop_name: StringName) -> void

Take away the control register_property_editor() or register_property_choices() gave prop_name on entity_type, leaving the built-in one.

register_runtime_panel()

func register_runtime_panel(key: StringName, factory: Callable) -> void

Give a running thing an inspector panel of the game's own - what an NPC is doing and why, say. key is an entity type or a class name (a script's class_name or an engine class); factory is called as factory(instance: Node) -> Control, and may return null for nothing to show. The panel is built when the selection settles on one running thing and freed when it moves on. See get_runtime_panel() for which registration wins.

unregister_runtime_panel()

func unregister_runtime_panel(key: StringName) -> void

Take away the panel register_runtime_panel() registered for key.

get_runtime_panel()

func get_runtime_panel(instance: Object, entity: HammeriteEntity = null) -> Callable

The register_runtime_panel() factory for instance, whose authored entity is entity when it has one: the entity's type first, then the classes instance is, nearest first. An empty Callable when none is registered.

register_property_choices()

func register_property_choices(entity_type: StringName, prop_name: StringName, provider: Callable) -> void

Give one string property a drop-down of legal values: register_property_editor() with a ready-made control. provider is called as provider(map: HammeriteMap, entity: HammeriteEntity) -> PackedStringArray each time the row is built, so it may answer from a directory or from the map. Replaces any control registered for the same pair.

register_brush_property_editor()

func register_brush_property_editor(key: StringName, factory: Callable) -> void

Give a brush property declared with HammeriteBrushPropertySchema an inspector control of the game's own. key is the property's namespaced key (audio/ambient); factory is called as factory(value, map: HammeriteMap) and returns a HammeritePropertyControl. Unlike register_property_editor() there is no entity argument: the control serves the whole multi-brush selection.

register_brush_property_choices()

func register_brush_property_choices(key: StringName, provider: Callable) -> void

Give a string brush property a drop-down of legal values. provider is called as provider(map: HammeriteMap) -> PackedStringArray each time the row is built. Replaces any control registered for key.

unregister_brush_property_editor()

func unregister_brush_property_editor(key: StringName) -> void

Take away the control register_brush_property_editor() or register_brush_property_choices() gave key.

get_brush_property_editor()

func get_brush_property_editor(key: StringName) -> Callable

The factory register_brush_property_editor() registered for key, or an empty Callable.

get_property_editor()

func get_property_editor(entity_type: StringName, prop_name: StringName) -> Callable

The factory registered for prop_name on entity_type - the type's own registration first, then one for ANY_TYPE - or an empty Callable.

get_point_entity_types()

func get_point_entity_types() -> Dictionary[StringName, Dictionary]

Every registered point entity type, as typename -> its default properties. A copy, all the way down: change a type through register_point_entity_type() or extend_point_entity_type().

get_brush_entity_types()

func get_brush_entity_types() -> Dictionary[StringName, Dictionary]

Every registered brush entity type, as typename -> its default properties; a copy, as get_point_entity_types() is.

get_all_entity_types()

func get_all_entity_types() -> Dictionary[StringName, Dictionary]

Every registered type, point and brush, merged into a new dictionary. Its values are still the registry's own dictionaries.

is_brush_entity_type()

func is_brush_entity_type(typename: StringName) -> bool

Whether typename is a registered brush entity type.

is_point_entity_type()

func is_point_entity_type(typename: StringName) -> bool

Whether typename is a registered point entity type.

rotation_axes_of()

func rotation_axes_of(typename: StringName) -> String

Which axes an entity of typename may be turned about: some of "xyz", from its registration's _editor_rotation_axes, or empty for a type that may not be turned.

get_entity_type_display_property()

func get_entity_type_display_property(typename: StringName, key: StringName, default = null) -> Variant

A display-only property (_editor_icon, _editor_tint, _editor_rotation_axes...) of the registered type typename. These live on the type registration and are never copied onto entities, so read them through here by HammeriteEntity.type. default when the type or the key is not registered.

gen_entity()

func gen_entity(typename: StringName) -> HammeriteEntity

A new entity of typename with its registered defaults (display-only _editor_* keys left out), a fresh id from map and the active layer. Not added to the map: pass it to HammeriteMap.add_entity(). An unregistered type pushes a warning and gets only HammeriteMap.BASE_ENTITY_PROPS.

create_brush_entity()

func create_brush_entity() -> HammeriteBrushEntity

A new, empty brush entity of HammeriteMap.default_brush_entity_type, with its map set but not added to it. Asserts that the default type is a brush entity type.

bridge_faces()

func bridge_faces() -> void

Make a new brush that is the convex hull of the selected faces, textured with active_texture and on the active layer, with undo. Logs nothing when the faces make no hull.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

flood_fill_face_selection()

func flood_fill_face_selection(max_angle_deg: float = 30.0) -> void

Flood fill face selection starting from the currently selected face. Selects all connected faces within an angular threshold (default 30 degrees).

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

grow_face_selection()

func grow_face_selection() -> void

Grow the face selection to every face touching one already selected.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

select_face_loop()

func select_face_loop() -> void

Select the face loops running through the selected faces.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

pick_object()

func pick_object() -> HammeritePickResult

Pick an object from the map.

pick_face_candidates()

func pick_face_candidates(back_faces: bool = false, narrow_state: HammeriteNarrowState = null) -> HammeritePickResult[]

Everything under the cursor, chosen the way pick_object() chooses - for callers that want the whole list rather than the first of it. The choice is the point. Face mode in a 2D view picks the face whose EDGE the cursor is near, because a wall is seen edge-on from above and there is nothing else to aim at; the view ray would answer with the floor. Selection used to ask the camera directly and get exactly that: the wall lit up under the cursor and the floor was what got selected.

set_vis_mode()

func set_vis_mode(mode: int) -> void

Shade the 3D views with mode and remember it in workspace. Writes the hammerite_vis_* global shader parameters, which the game's materials read too - so it applies only while the editor is active, and Lit is restored when it deactivates. See shown_vis_mode().

shown_vis_mode()

func shown_vis_mode() -> int

What the shaders are drawing with: vis_mode while the editor is up, Lit while it is not. The globals are the game's as much as the editor's views, so a closed editor must not leave the game in whatever the author was looking at.

is_simulation_active()

func is_simulation_active() -> bool

Check if simulation is currently active.

start_simulation()

func start_simulation() -> void

The toolbar's Play: run the selected entities, or every entity in the map when none are selected (see HammeriteMap3D.start_simulation()), and tint the editor's frame to say so. Emits runtime_state_changed. Does nothing while there is no map_3d. For the selection alone without touching the transport state, see simulate_selection().

pause_simulation()

func pause_simulation() -> void

The toolbar's Pause: stop every running entity where it stands. start_simulation() resumes it. Emits runtime_state_changed.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

stop_simulation()

func stop_simulation() -> void

The toolbar's Stop: stop every running entity and reset it to the way the map built it. Emits runtime_state_changed.

run_action_on_selection()

func run_action_on_selection(action_id: StringName) -> void

Ask every selected entity that offers action_id to do it. Not undoable, and deliberately so: an action acts on the running instance, not on anything the map stores, so there is nothing to put back. Resetting the simulation is what undoes it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

selection_offers_action()

func selection_offers_action(action_id: StringName) -> bool

Whether anything selected offers action_id, for greying the command that runs it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

actions_offered_by_selection()

func actions_offered_by_selection() -> Dictionary[StringName, String]

The actions every selected entity offers, as id -> label. An intersection rather than a union: a button that acted on some of the selection and not the rest would be lying about what it does.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

simulate_selection()

func simulate_selection() -> void

Run whichever selected entities can be simulated, leaving the rest of the map alone. The toolbar's transport runs the whole map; this is the same three verbs aimed at a selection, so a door can be opened and shut without the lamps guttering and the water sloshing beside it.

pause_selection_simulation()

func pause_selection_simulation() -> void

Stop the selected entities where they stand. simulate_selection() picks them up again.

reset_selection_simulation()

func reset_selection_simulation() -> void

Stop the selected entities and put them back the way the map built them.

selection_can_simulate()

func selection_can_simulate() -> bool

Whether anything selected could be simulated at all.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

selection_is_simulating()

func selection_is_simulating() -> bool

Whether anything selected is running right now.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

selection_has_simulated()

func selection_has_simulated() -> bool

Whether anything selected has run since it was last reset - so whether there is anything to put back, and whether starting it again is a resume rather than a start.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

is_active()

func is_active() -> bool

Whether the editor is up: between activate() and deactivate().

activate()

func activate() -> void

Bring the editor up over the game: stop the map's simulation, show and unpause the editor, make the mouse visible, and apply its visualization mode and authoring overlays. Emits active_status_changed.

deactivate()

func deactivate() -> void

Put the editor away and hand the world back to the game: leave narrowing, start every entity's simulation, hide and pause the editor, put the shaders back to Lit and hide the authoring overlays. The mouse mode is left to the host. Emits active_status_changed.

get_camera()

func get_camera() -> HammeriteEditorCamera

A HammeriteEditorCamera facade over the focused view's camera - picking and plane projection for whichever view the author is in. The same object until the focus moves to another view.

is_camera_dragging()

func is_camera_dragging() -> bool

Whether the focused view's camera is being driven by the mouse right now: mouse look in the 3D view, a pan or zoom in a 2D one. Narrower than is_camera_navigating(), which also covers keyboard flight and every view.

is_camera_navigating()

func is_camera_navigating() -> bool

Whether the camera has the keyboard - it is being flown, or driven in a 2D view. The editor's single-key shortcuts and the active tool's keys both stand aside while it does, or W flies the camera and toggles WYSIWYG previews in the same press. Mouse input is not affected: a right click that turns out not to be a camera drag still has to reach the tool underneath.

get_working_plane()

func get_working_plane() -> Plane

Get the working plane from the active viewport

offset_working_plane()

func offset_working_plane(amount: float) -> void

Offset the working plane along the orthogonal axis

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

pick_working_plane_from_face()

func pick_working_plane_from_face() -> bool

Pick the working plane from a brush face under the mouse cursor

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

is_perspective_viewport_focused()

func is_perspective_viewport_focused() -> bool

Whether the 3D view is the one with focus.

is_viewport_focused()

func is_viewport_focused() -> bool

Whether any of the four views has focus. Tools and picking only act while one does.

should_process_active_tool()

func should_process_active_tool() -> bool

Returns a boolean stating whether to process the active tool.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

on_grid_changed()

func on_grid_changed(grid: HammeriteGrid) -> void

Connected to the grid's Resource.changed: emits grid_changed. Not meant to be called. A tool reads HammeriteEditorTool.grid live, so it needs no telling.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

calculate_selection_aabb()

func calculate_selection_aabb() -> AABB

Calculate the AABB of the current selection (both brushes and entities).

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

focus_to_selection()

func focus_to_selection() -> void

Focus all cameras to the current selection. Calculates the AABB of selected brushes and entities, then animates all viewport cameras to fit that AABB in view.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

open_entity_search()

func open_entity_search() -> void

Opens the field that finds an entity by its type, its name or a property.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

open_command_launcher()

func open_command_launcher() -> void

Opens the field that runs a command by typing its name.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

launcher_entries()

func launcher_entries() -> HammeriteCommandMatcher.Entry[]

What the launcher offers now: every command but those a tool asks for itself while it runs, and the actions the selection offers that no command covers, as the right-click menu has them.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

remember_launched()

func remember_launched(entry: HammeriteCommandMatcher.Entry) -> void

Put entry at the head of the launcher's recently run list, kept in workspace and capped at LAUNCHER_RECENT.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

go_to_entity()

func go_to_entity(entity: HammeriteEntity) -> void

Selects entity alone and moves every view onto it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

clear_selection()

func clear_selection() -> void

Clear selection (delegated to core)

select_brush()

func select_brush(brush: HammeriteBrush, toggle: bool, select_individual: bool) -> void

Select brush - or, unless select_individual, the whole prefab instance or group it belongs to. toggle adds it to the selection, or takes it out when it is already in; false replaces the selection.

flip_selection()

func flip_selection(axis: int) -> void

Flip the selection through its own middle, along one world axis. Undo is the same flip.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

snap_selection_to_grid()

func snap_selection_to_grid() -> void

Puts every selected brush and entity on the grid, each on its own.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

delete_selection()

func delete_selection() -> void

Deletes the currently selected objects

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

duplicate_selection()

func duplicate_selection() -> void

Copy the selection in place as one undo step and start the move tool on the copy.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

copy_selection()

func copy_selection() -> void

Put the selection on the system clipboard as map data text (see HammeriteDataFile.to_text()), so it pastes into another map or another editor.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

cut_selection()

func cut_selection() -> void

copy_selection(), then delete the selection: one undo step.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

paste()

func paste() -> void

Where they were copied from - into another map, the same place in it.

paste_at_cursor()

func paste_at_cursor() -> void

With the bottom of what was copied on the working plane under the cursor, moved by whole grid steps so brushwork that was on the grid stays on it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

group_selection()

func group_selection() -> int

Put every selected brush and entity in one new group, with undo. Clicking any of them then selects the group; see select_brush().

narrow_to_objects()

func narrow_to_objects(brush_ids: int[], entity_ids: int[] = [], clear_selection: bool = true) -> void

Narrow the view to the brushes and entities with these ids: push a level onto the narrowing stack that shows only them. clear_selection empties the selection made outside narrowing; with no ids at all it pushes a warning and does nothing.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

narrow_to_brushes()

func narrow_to_brushes(brush_ids: int[], clear_selection: bool = true) -> void

Enter narrowing mode with specific brush IDs (for backwards compatibility).

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

narrow_to_selection()

func narrow_to_selection() -> void

Enter narrowing mode with the current selection. Hides all brushes and entities except those selected.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

narrow_to_prefab_instance()

func narrow_to_prefab_instance(instance_id: int, clear_selection: bool = true) -> void

Enter narrowing mode with a specific prefab instance. Narrows to all brushes and entities that belong to the given instance_id. Enables prefab editing mode where changes are tracked and synced.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

narrow_further()

func narrow_further() -> void

Narrow further based on current narrow-level selection.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

pop_narrow()

func pop_narrow() -> void

Pop one level from the narrow stack.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

exit_narrow()

func exit_narrow() -> void

Exit narrowing mode completely.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

is_narrowing()

func is_narrowing() -> bool

Check if currently in narrowing mode (delegated to core)

get_current_narrow_state()

func get_current_narrow_state() -> HammeriteNarrowState

Get the current narrow state (delegated to core)

ungroup_selection()

func ungroup_selection() -> void

Take every selected brush and entity out of its group, with undo.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

get_all_gizmo_instances()

func get_all_gizmo_instances() -> HammeriteMap2DGizmos[]

The gizmo layers of the three 2D views that exist, top, front and side.

redraw_gizmos()

func redraw_gizmos() -> void

Ask the 2D views' gizmo layers to redraw, after something they draw changed outside an edit.

set_tool_metadata()

func set_tool_metadata(object_id: StringName, key: StringName, value) -> void

Set tool-specific metadata for an object (delegated to core)

get_tool_metadata()

func get_tool_metadata(object_id: StringName, key: StringName, default = null) -> Variant

Get tool-specific metadata for an object (delegated to core)

clear_tool_metadata()

func clear_tool_metadata() -> void

Clear all tool metadata (delegated to core)

clear_tool_metadata_for_object()

func clear_tool_metadata_for_object(object_id: StringName) -> void

Clear tool metadata for a specific object (delegated to core)

reset_selection_transforms()

func reset_selection_transforms() -> void

Move each selected brush's node back to the brush's centroid, undoing a node transform left over from dragging. Brushes only; entities are not reset.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

create_brush_entity_from_selection()

func create_brush_entity_from_selection() -> void

Creates a new brush entity from the selected brushes.

apply_texture()

func apply_texture(texture: Texture2D) -> void

Applies the given texture to the current selection.

register_cell_overlay()

func register_cell_overlay(id: StringName, label: String, colour_for: Callable) -> void

Register a way of colouring air cells in the 2D viewports. colour_for is called per cell as func(cell: HammeriteCell, map: HammeriteMap) -> Color and returns the fill to draw it with; a fully transparent colour means "nothing to say about this one", and the plain room fill is used instead. This is the seam that lets an addon put what it knows onto the floorplan without the editor knowing what the addon is. The editor's own interior/exterior overlay is registered through it like anyone else's, so the path an addon takes is the path that is exercised.

unregister_cell_overlay()

func unregister_cell_overlay(id: StringName) -> void

Remove a registered overlay, falling back to the plain fill if it was the active one.

get_cell_overlays()

func get_cell_overlays() -> StringName[]

The id of every registered overlay, in the order the picker lists them.

get_cell_overlay_label()

func get_cell_overlay_label(id: StringName) -> String

What the picker calls overlay id, or empty for one nothing registered.

get_active_cell_overlay()

func get_active_cell_overlay() -> StringName

The id of the overlay the 2D views colour cells with, or empty for the plain room fill.

set_active_cell_overlay()

func set_active_cell_overlay(id: StringName) -> void

Colour the 2D views' cells with the overlay registered as id (register_cell_overlay()), or with the plain fill for an empty one. Emits cell_overlay_changed when it changes, and moves the toolbar's picker to it. An unregistered id draws the plain fill.

get_cell_overlay_color()

func get_cell_overlay_color(cell: HammeriteCell) -> Color

The colour to fill cell with, or a transparent colour to use the plain room fill.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

add_toolbar_button()

func add_toolbar_button(icon: Texture2D, tooltip: String, on_pressed: Callable) -> Button

Add an addon's button to the toolbar, between the built-in tools and the simulation controls. Returns the Button so the caller can keep it for remove_toolbar_button() and reflect its tool's state. It joins the tool button group, so activating any other tool releases it - an addon tool is a tool like the rest, and the toolbar should say which one is live.

remove_toolbar_button()

func remove_toolbar_button(button: Button) -> void

Remove a button previously added with add_toolbar_button(), and free it.

add_right_panel()

func add_right_panel(panel: Control) -> void

Add an addon tool's panel to the Tool Options box, which stands in the right-hand column until the author moves it. The panel is NOT taken ownership of: remove_right_panel() only detaches it, so a tool that rebuilds its UI across activations can keep and re-add the same control, and one that is done with it frees it itself.

remove_right_panel()

func remove_right_panel(panel: Control) -> void

Detach a panel previously added with add_right_panel(). Does not free it.

register_manual_section()

func register_manual_section(id: StringName, title: String, directory: String, order: int = -1) -> void

Adds a section to the manual: the pages in directory, listed as title. order places it among the others (core 10, editor 20, audio 30, navigation 40); a negative one puts it last.

unregister_manual_section()

func unregister_manual_section(id: StringName) -> void

Remove the manual section registered as id with register_manual_section().

register_manual_pages()

func register_manual_pages(id: StringName, directory: String) -> void

Adds the pages in directory to the manual's section id, beside the section's own.

unregister_manual_pages()

func unregister_manual_pages(id: StringName, directory: String) -> void

Undo register_manual_pages(): stop listing the pages in directory under section id.

open_manual()

func open_manual(location: String = "") -> void

Opens the manual at location (<section>/<page>.md, optionally #anchor); with none, at the active tool's page, or where it was left.

manual_page_for()

func manual_page_for(tool: HammeriteEditorTool) -> String

The page tool documents, when the manual has it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

cleanup_last_tool()

func cleanup_last_tool() -> void

Go back to the select tool: clear the toolbar's highlight and make a new HammeriteSelectTool active through set_active_tool(), which lets go of the tool it replaces. What a tool's HammeriteEditorTool.exit_requested is answered with.

remove_active_tool_popup()

func remove_active_tool_popup() -> void

Removes the active tool popup from the viewport container. A tool's panel is made for that tool and goes with it. Taken out of the tree and kept, it was never freed, and every tool picked left one behind for the rest of the session.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

keep_alive()

func keep_alive(t: HammeriteEditorTool) -> void

Hold a reference to t after it stops being the active tool, while it still has work in flight across frames (a bake between two of its frames). Autosave waits while any tool is held. Release it with let_go().

let_go()

func let_go(t: HammeriteEditorTool) -> void

Release a tool held by keep_alive().

set_active_tool()

func set_active_tool(t: HammeriteEditorTool) -> void

Make t the active tool. The tool it replaces is left: its HammeriteEditorTool.exit_requested is disconnected, HammeriteEditorTool.exit() and then HammeriteEditorTool.release() are called, and the panel it added is freed. A panel t added as it was made stays, as active_tool_popup. Emits active_tool_changed once, for t.

set_active_tool_popup()

func set_active_tool_popup(popup: Control) -> void

Show popup in the Tool Options box as active_tool_popup. It is freed when the tool is left. Tools call this through HammeriteEditorTool.add_popup().

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_select_tool()

func start_select_tool() -> void

Initializes the select tool. Selection is built into HammeriteMapEditor, so this acts like the default state.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_transform_tool()

func start_transform_tool(mode: int) -> void

Start the transform gizmo on the selection, in mode. Refused, with a warning, for scaling a selection that holds a prefab instance.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_face_move_tool()

func start_face_move_tool() -> void

Initializes the face moving tool.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_extrude_tool()

func start_extrude_tool() -> void

Initializes the face extrusion tool.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_cube_brush_tool()

func start_cube_brush_tool() -> void

Initializes the cube brush tool.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_cylinder_brush_tool()

func start_cylinder_brush_tool() -> void

Initializes the cylinder brush tool.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_stair_brush_tool()

func start_stair_brush_tool() -> void

Start the stair brush tool.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_arch_brush_tool()

func start_arch_brush_tool() -> void

Initializes the arch brush tool.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_polygon_brush_tool()

func start_polygon_brush_tool() -> void

Start the polygon brush tool: draw an outline, then extrude it.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_clip_tool()

func start_clip_tool() -> void

Start the clip tool, which cuts the selected brushes by a plane.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_face_tool()

func start_face_tool() -> void

Start the face edit tool, with its UV panel in the Tool Options box.

start_vertex_tool()

func start_vertex_tool() -> void

Start the vertex tool on the selected brushes.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_entity_tool()

func start_entity_tool() -> void

Start the entity tool, which places entities chosen from the entity browser.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_prop_tool()

func start_prop_tool() -> void

Start the prop tool, which places models chosen from prop_browser.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_decal_tool()

func start_decal_tool() -> void

Start the decal tool, which places active_decal flush to a surface.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_terrain_tool()

func start_terrain_tool() -> void

Start the terrain sculpting tool.

convert_selection_to_terrain()

func convert_selection_to_terrain() -> void

Turn the selected brushes into terrain, terrain_cell_size to a cell.

selection_can_be_terrain()

func selection_can_be_terrain() -> bool

Enabled whenever brushwork is selected, rather than only when some of it would convert. A greyed-out menu item says nothing about WHY, and the why is the whole of this: an author who has selected a room's air brush and means to make ground of it has a wrong idea about terrain, and wants telling. convert_selection_to_terrain() does the telling.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_prefab_tool()

func start_prefab_tool() -> void

Start the prefab tool, which places prefabs chosen from prefab_browser.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_lightmap_tool()

func start_lightmap_tool() -> void

Start the lightmap tool, which bakes the map's lighting.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

start_sky_tool()

func start_sky_tool() -> void

Start the sky tool, which edits the map's skybox.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

open_texture_browser()

func open_texture_browser(assign_selected: bool = true) -> void

Open the texture browser window. If assign_selected is false, does not assign the active texture when selecting a texture from the browser. This is useful when we want to pick a texture from some other tool, e.g. the face edit tool.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

browser_rect()

func browser_rect(placed: Rect2) -> Rect2

Where a browser opens: where it was left, or centred over the editor.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

embedder_rect()

func embedder_rect() -> Rect2

The editor's own area, in the embedder's pixels: what its windows are kept inside.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

open_decal_browser()

func open_decal_browser() -> void

Choose a decal. Kept apart from the active TEXTURE: a decal and a wall texture are picked from different places for different purposes, and one browser overwriting the other's choice would be a surprise every time.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

close_decal_browser()

func close_decal_browser() -> void

Take the decal browser window down, if it is up.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

set_active_decal()

func set_active_decal(texture: Texture2D) -> void

Make texture what the decal tool places, and emit active_decal_changed.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

close_texture_browser()

func close_texture_browser() -> void

Take the texture browser window down, if it is up.

focus_entity_properties()

func focus_entity_properties() -> void

Put the keyboard in the inspector's first field for the selected entity.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

set_active_texture()

func set_active_texture(texture: Texture2D) -> void

Make texture the active_texture, what new brushwork is drawn with. Changes nothing that exists: apply_texture() puts a texture on the selection. active_texture_changed is emitted only when it does change.

apply_colors()

func apply_colors() -> void

Make a change to HammeriteMapEditorSettings.colors show everywhere: what draws a colour every frame shows it already, and the flat views' brushes and the faces' tints, which take theirs when they are built, take it again here.

create_transform_gizmo_3d()

func create_transform_gizmo_3d(helper: HammeriteTransformHelper, mode: int) -> HammeriteTransformGizmo3D

A 3D transform gizmo driving helper in mode, added to the focused view's viewport. The caller owns it and frees it.

Experimental: The editor's own plumbing, between its scripts; not for a game or an addon.

set_map_3d()

func set_map_3d(map: HammeriteMap3D) -> void

Setter of map_3d. Parents the face highlight and the carved-world overlays under map (once - they stay with the first map given), gives it map when one was assigned first, connects its editor state to active_status_changed, and gives it the perspective camera.

is_grid_shown()

func is_grid_shown() -> bool

Whether the grid should be on the walls right now: asked for AND the editor up to ask it. Worth a method because the shader global itself cannot be read back - RenderingServer.global_shader_parameter_get() answers null for these - so this is the only place the answer exists.

prompt_load_map()

func prompt_load_map() -> void

File > Open: ask about unsaved changes, then show a file dialog and open what is chosen with open_map_at().

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

open_map_at()

func open_map_at(path: String) -> bool

Open the map at path: a .hmap from anywhere, or a Godot resource from this project. A coroutine - it may ask whether to take an autosave, and the map is compiled before it is shown - so await it: true once the map is the editor's, false when it could not be read or the opening was cancelled.

has_unsaved_changes()

func has_unsaved_changes() -> bool

Whether the map has changes that are not in its file.

mark_unsaved()

func mark_unsaved() -> void

Count the map as changed, for an edit made without going through undo_redo.

prompt_unsaved_changes()

func prompt_unsaved_changes() -> bool

Before the map goes, ask whether to save its unsaved changes, drop them, or stay. True when it is fine to go on; nothing is asked when there is nothing to lose. The editor asks this before opening another map; a host quitting the game with the editor up should ask it too:

if await map_editor.prompt_unsaved_changes():
get_tree().quit()

new_map()

func new_map() -> void

Start an empty map, once any unsaved changes to this one have been seen to.

autosave_path_for()

static func autosave_path_for(path: String) -> String

Where the autosave of the map saved at path goes: beside it, or under user:// for a map not saved yet or one where the game cannot write - res:// in an exported game.

autosave()

func autosave() -> int

Write the map to its autosave now, on a worker like a save. Its own file, and whether it counts as saved, are left alone.

save_map()

func save_map() -> bool

File > Save: to the map's own file, asking for one if it has none yet. A coroutine: true once it is saved.

save_map_to()

func save_map_to(path: String) -> bool

Write the map to path and everything saved with it. The file is replaced only once the new one is complete, and the one it replaces is kept as <path>.bak. On a worker: the editor goes on drawing, with the status bar saying how far the save has got, but nothing can be edited until it is done - see is_saving().

is_saving()

func is_saving() -> bool

A save is writing the map on a worker. Nothing may edit the map until it is done: the editor shields itself, and code of a game's own that changes the map from outside should wait for this.

prompt_save_map_as()

func prompt_save_map_as() -> void

File > Save As: ask for a path and save there with save_map_to().

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

load_prefab_set()

func load_prefab_set(path: String) -> HammeritePrefabSet

Load a prefab set from disk (delegated to core with UI updates)

save_prefab_set()

func save_prefab_set(path: String) -> int

Save a prefab set to disk.

create_prefab_set()

func create_prefab_set(path: String, set_name: String) -> HammeritePrefabSet

Start an empty prefab set to be saved at path, and offer it in the prefab browser.

save_all_modified_prefab_sets()

func save_all_modified_prefab_sets() -> int

Returns how many could not be saved; each says why in the log.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

open_prefab_browser()

func open_prefab_browser() -> void

Open the prefab browser (for backwards compatibility, now just activates prefab tool).

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

close_prefab_browser()

func close_prefab_browser() -> void

Hide prefab_browser.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

create_prefab_from_selection()

func create_prefab_from_selection() -> void

Create a prefab from the current selection.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

instantiate_prefab()

func instantiate_prefab(prefab: HammeritePrefab, at_cursor: bool = true) -> void

Instantiate a prefab in the map.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

break_prefab_instance()

func break_prefab_instance() -> void

Break a prefab instance into regular brushes/entities. Clears both instance_id and prefab_id, making the brushes/entities fully independent.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

duplicate_instance()

func duplicate_instance() -> void

Duplicate a prefab instance. Creates a new instance with a new instance_id, copying all brushes and entities. The new instance inherits the transform of the original.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

reset_instance_transform()

func reset_instance_transform() -> void

Reset a prefab instance rotation (and scale when implemented). This removes rotation and scale from the instance, keeping the current position. The geometry is transformed to remove rotation while maintaining the instance's location.

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

log_message()

func log_message(message: String, type: int = 0) -> void

Add message to the editor's message log, whose latest line shows in the status bar. Translate it before passing it in; the log does not.

log_info()

func log_info(message: String) -> void

log_message() as information.

log_warning()

func log_warning(message: String) -> void

log_message() as a warning.

log_error()

func log_error(message: String) -> void

log_message() as an error. Does not @GlobalScope.push_error().

log_success()

func log_success(message: String) -> void

log_message() as a success.

clear_log()

func clear_log() -> void

Clear all log entries

undo_action()

func undo_action() -> void

Undo the last action

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

redo_action()

func redo_action() -> void

Redo the last undone action

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

move_selection_to_active_layer()

func move_selection_to_active_layer() -> void

Move selected objects to the active layer

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).

is_editing_prefab_instance()

func is_editing_prefab_instance() -> bool

Check if currently editing a prefab instance (delegated to core)

Experimental: The editor's own: what its menus, keys, tools and views call. Not part of the supported API (docs/api-stability.md).