HammeriteMap3D

Core: in the scene. Inherits Node3D

3D representation of a HammeriteMap.

Listens to changes in the map and keeps the representation up to date.

Properties

Methods

Signals

entity_instance_created

signal entity_instance_created(entity: HammeriteEntity, instance: Node)

Emitted when an entity instance is created.

entity_instance_removed

signal entity_instance_removed(entity: HammeriteEntity, instance: Node)

Emitted when an entity instance is about to be removed.

map_assigned

signal map_assigned(map: HammeriteMap)

Emitted when a map has been assigned but BEFORE its contents are built. For the systems a map's own contents depend on: anything that a map's entities will reach for during construction has to be standing before construction starts.

map_changed

signal map_changed(map: HammeriteMap)

Emitted after map is set to a new value (including null). Lets extensions (e.g. hammerite-audio) react to map changes without depending on HammeriteMapEditor.

runtime_data_changed

signal runtime_data_changed(key: StringName, value)

Emitted by set_runtime_data().

simulation_reset

signal simulation_reset()

Emitted after every entity has been told to reset_simulation(). For what a game keeps outside its entities - what has happened, what the player is carrying - which no entity can put back, but a playtest changed all the same.

Property descriptions

detail_tint_visible

var detail_tint_visible: bool

Whether detail-tier brushwork is tinted while the editor is up.

editor_active

var editor_active: bool

Whether the editor is on screen, and so whether entity instances should draw what they draw for the author: a light's billboard, a marker for something with no mesh of its own. Off by default, because a game that ships without hammerite-editor should never show them. Turning it off also rebuilds the rooms' collider if an edit left it stale.

editor_camera

var editor_camera: Camera3D

The camera the rooms are culled for while editor_active - the editor's own, which is not the viewport's. None, and the editor shows every room.

map

var map: HammeriteMap

The map this node shows. Assigning one frees everything built for the previous map, stops following its edits, and builds the new one at once, whether or not this node is in a tree yet; map_assigned fires before the build and map_changed after it. Assigning the map already shown does nothing; assigning null always lets go of whatever was built and the frame systems (set_frame_system()).

wireframes_visible

var wireframes_visible: bool

Whether the air brushes' wireframes are drawn while the editor is up: an author's affordance rather than part of the world, and the host's to switch.

Method descriptions

build_world_now()

func build_world_now() -> void

Build now what is waiting to be built of the compiled world - its rooms' meshes, and their collider while nobody is authoring - rather than on the next frame, as an edit leaves it so a run of edits builds it once. For a host putting a map up behind a loading screen: the next frame is the one the player sees, and a large level's rooms held it for three seconds. Nothing when nothing is waiting.

Experimental: A seam for loading screens; not yet part of the supported API.

can_simulate()

func can_simulate(entity: HammeriteEntity) -> bool

Whether entity has a running instance that says it can be simulated at all. A light can; a marker with nothing to do cannot, and neither can an entity the map has not built yet.

far_plane()

static func far_plane() -> float

The far plane to pair with near_plane(), in Hammerite units; where FAR_PLANE went.

get_brush_instance()

func get_brush_instance(brush: HammeriteBrush) -> Node3D

The node drawing brush on its own - for a detail brush - or null for a structural or air brush, which the compiled rooms draw, and for a brush owned by an entity.

get_entity_instance()

func get_entity_instance(entity: HammeriteEntity) -> Node

The node built for entity, or null when there is none: not built yet, in a variant that is not active, a classname no class answers to, or an instance that freed itself - a crate that broke.

get_fill_instance()

func get_fill_instance(brush: HammeriteBrush) -> Node

The game's node over brush's fill, or null when it has no fill or nothing registered a class for it.

get_fill_instances()

func get_fill_instances() -> Node[]

Every node a fill has put over a brush, for whoever has to ask all of them something - the editor asking what to draw, and what an author may take hold of.

get_runtime_data()

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

What was kept under key with set_runtime_data() or set_frame_system(), or default for nothing there.

get_sky_renderer()

func get_sky_renderer() -> HammeriteSkyRenderer

The sky this map is under (HammeriteSkyRenderer), or null. Anything that wants to follow the weather - a directional light following the sun, an editor showing a preview - asks here.

has_simulated()

func has_simulated(entity: HammeriteEntity) -> bool

Whether entity has run since the last reset. True while it is paused, unlike is_simulating(); false once it has been reset.

is_authoring()

func is_authoring() -> bool

Whether the world is held still for an author: the editor is active and nothing in it has been started. False in a game with no editor, whose world runs from the moment its map is built.

is_light_seen()

func is_light_seen(light: HammeriteEntity) -> bool

Whether the camera can see into any room light's baked light falls in - not only the one it stands in: a lamp lights the wall across a doorway from it. As conservative as is_room_seen_at(), and true wherever that is, as with the camera in no room. True as well for a light no bake holds, which has nothing to say either way.

For a light deciding whether its flicker is worth telling anyone this frame.

is_room_seen_at()

func is_room_seen_at(point: Vector3) -> bool

Whether the camera can see into the room point is in, through the doorways from the room it stands in - as the rooms were last culled for drawing, and as conservative: true for a room it cannot rule out. True as well where nothing is being ruled out - with the camera in no room - and for a point in no room.

For a game deciding what is worth doing every frame: somebody in a room that is not drawn is not seen.

is_simulating()

func is_simulating(entity: HammeriteEntity) -> bool

Whether entity has been told to start and not yet told to stop.

near_plane()

static func near_plane() -> float

What a camera looking at a Hammerite map should see, in Hammerite units (see the Units table in the README): a unit is about an inch, and rooms are hundreds of units across. Godot's own defaults are metres - 0.05 to 4000 - so a map measured in inches is cut off at a hundred yards and spends most of its depth precision on the first inch. A game sets these on its own camera; HammeriteEditorCamera3D sets them on the editor's. Where NEAR_PLANE went.

reset_simulation()

func reset_simulation(entities: HammeriteEntity[] = []) -> void

Put entities back as the map built them, including those that say they cannot simulate, and emit simulation_reset. An empty entities means every entity in the map.

rooms_of_box()

func rooms_of_box(box: AABB) -> Dictionary[Vector2i, bool]

The rooms box reaches into, by HammeriteCell.key(): those its middle, its corners and places along its longest side are in.

set_frame_system()

func set_frame_system(key: StringName, system: Object) -> void

Keep system under key (get_runtime_data()) as a system that runs with this map: its update(delta) is called every frame, and when the map is cleared its cleanup() is called and it is removed. Either method may be left out. How an addon gets the frame without core knowing it exists.

set_runtime_data()

func set_runtime_data(key: StringName, value) -> void

Keep value with this view under key, and emit runtime_data_changed.

set_skybox()

func set_skybox(skybox: HammeriteSkybox) -> void

Put a sky over this map, or take it away. Both the renderer and the worldrep are told: whether a face wears the sky material is decided as it is meshed. For a change to the sky's own parameters, set them on the skybox itself: the sky that is up follows. Sets the sky of the variant whose sky is in effect (HammeriteMap.get_sky_owner()).

start_simulation()

func start_simulation(entities: HammeriteEntity[] = []) -> void

Start or continue simulating entities. Affects only a subset if an array of entities is passed as an argument.

stop_simulation()

func stop_simulation(entities: HammeriteEntity[] = []) -> void

Pause entities that can simulate, leaving them as they are. An empty entities means every entity in the map.

trigger_named()

func trigger_named(entity_name: String, impulse = null) -> int

Trigger every entity named entity_name that can be triggered, handing each impulse; how many were. A name is not an id: several entities may share one, and they are triggered together.