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

runtime_data_changed

signal runtime_data_changed(key: StringName, value)

Emitted by set_runtime_data().

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.

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. Acoustics is the example: the entities built by _init_map include sounds, and a sound asks for its audio manager the moment it is created - so a manager set up on map_changed arrives too late, and the sound binds to the outgoing map's manager or to none at all. Anything that a map's entities will reach for during construction has to be standing before construction starts.

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.

Constants

NEAR_PLANE

const NEAR_PLANE = 1.0

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 long sightline loses its far end, which shows up first on water: a flat sheet meets the far plane along a straight line, where a wall just stops. A game sets these on its own camera; HammeriteEditorCamera3D sets them on the editor's.

FAR_PLANE

const FAR_PLANE = 65536.0

The far plane to pair with NEAR_PLANE, in Hammerite units.

Property descriptions

map

var map: HammeriteMap = null

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.

editor_active

var editor_active: bool = false

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. hammerite-editor keeps this in step with itself; nothing else has to touch it. Held here rather than subscribed to from here, so an entity created while it is already on can be told so as it is built instead of waiting for the next change and drawing nothing until then.

editor_camera

var editor_camera: Camera3D = null

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.

wireframes_visible

var wireframes_visible: bool = true

Whether the authoring overlays are drawn while the editor is up: the air brushes' wireframes, and the tint marking detail-tier brushwork. Both are an author's affordance rather than part of the world, and both are the host's to switch - see set_wireframes_visible() and set_detail_tint_visible().

detail_tint_visible

var detail_tint_visible: bool = true

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

Method descriptions

set_map()

func set_map(_map: HammeriteMap) -> void

Setter of map. Does nothing when _map is already the map, unless it is null: assigning null always lets go of whatever was built and the frame systems (set_frame_system()).

set_editor_active()

func set_editor_active(active: bool) -> void

Setter of editor_active: tells every entity instance and air-brush preview. Turning it off also rebuilds the rooms' collider if an edit left it stale.

set_wireframes_visible()

func set_wireframes_visible(visible_now: bool) -> void

Setter of wireframes_visible: shows or hides the air brushes' wireframes.

set_detail_tint_visible()

func set_detail_tint_visible(visible_now: bool) -> void

Setter of detail_tint_visible: shows or hides the tint that marks detail-tier brushwork.

set_runtime_data()

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

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

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.

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.

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.

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.

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.

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_simulating()

func is_simulating(entity: HammeriteEntity) -> bool

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

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.

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.

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_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.

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.

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 _cull_rooms() last worked it out 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_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.

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.

set_skybox()

func set_skybox(skybox: HammeriteSkybox) -> void

Put a sky over this map, or take it away. Both the renderer and the WORLDREP have to be told: whether a face wears the sky material is decided as it is meshed, so a map that had no sky is still wearing flat colour where its apertures are until its brushes are built again. For a change to the sky's own parameters - a different horizon colour, a moon instead of a sun - set them on the skybox itself: the sky that is up follows, and nothing needs remeshing for that. Sets the sky of the variant whose sky is in effect (HammeriteMap.get_sky_owner()): the one being looked at, if it has its own.

get_sky_renderer()

func get_sky_renderer() -> HammeriteSkyRenderer

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