HammeritePointEntityNode3D

Core: entities. Inherits Node3D

Base for the node of an entity that stands at one point: a light, a marker, a pickup.

HammeriteMap3D builds one for every entity whose classname names a class extending this: it creates the node, calls set_map_3d() if it has one, then set_entity(), then set_editor_active(), and starts it if the world is running. Only set_editor_active() and apply_entity_property() must be written; every other hook does nothing until overridden. Authored values arrive at apply_entity_property(), the simulation hooks run it, the inspector reads the runtime properties, and scripting calls trigger(). docs/guides/writing-an-entity.md builds one. An entity is placed in the map's space: set Node3D.position, not Node3D.global_position, and it goes wherever the HammeriteMap3D goes. HammeritePointEntityAnimatableBody3D and HammeritePointEntityRigidBody3D are the same interface on physics bodies.

Properties

Methods

Signals

rebuild_requested

signal rebuild_requested()

Emitted when the entity's classname changes. HammeriteMap3D answers by freeing this node and building one of the new class.

Property descriptions

entity

var entity: HammeriteEntity = null

The authored entity this node stands for. Null until set_entity().

Method descriptions

get_entity()

func get_entity() -> HammeriteEntity

Getter of entity.

set_entity()

func set_entity(new_entity: HammeriteEntity) -> void

Bind this node to new_entity: follow its property, visibility and drag-preview signals, and apply every property through update_properties(). HammeriteMap3D calls it once; an override must call super(), and a second call connects the signals again.

update_properties()

func update_properties() -> void

Apply every property the entity's type declares, as the entity holds it or as the type defaults it: a map saved before a property existed has no key for it, and its entities read the type's default. set_entity() calls it. Override it, calling super(), for what wants every property applied first - gathering the probes that light the node once it knows where it stands.

request_rebuild()

func request_rebuild() -> void

Emit rebuild_requested, so HammeriteMap3D frees this node and builds it again from the entity.

turn_to()

func turn_to(facing: Basis) -> void

Turn to facing, keeping whatever size the node has given itself. In the map's space, as its origin is: an entity under a HammeriteMap3D that is moved or turned goes with it. Override where the turn belongs to something other than this node - a character it puts in the world, say, which moves itself and must not be carried round by its parent.

set_editor_active()

abstract func set_editor_active(active: bool) -> void

Show or hide what this entity draws only for an author - a light's icon, a marker for something with no mesh. active follows HammeriteMap3D.editor_active: it is told as the node is built and on every change, and says nothing about whether the world is running.

draw_editor_gizmos()

func draw_editor_gizmos(_gizmos: HammeriteGizmoBuffer) -> void

Draw what the author should see of this entity - its bounds, where it points, how far it reaches - into gizmos. The editor calls it every frame it is up and the entity is visible; the default draws nothing.

draws_editor_gizmos_only_when_picked()

func draws_editor_gizmos_only_when_picked() -> bool

Whether draw_editor_gizmos() draws nothing unless the entity is selected or hovered, so the editor need not ask it on the frames it is neither - a level's props and lamps are thousands.

get_editor_handles()

func get_editor_handles() -> HammeriteEditorHandle[]

The points of this entity an author may take hold of in the viewport, or nothing where it offers none. Drawn and picked by the editor while the entity is selected; see HammeriteEditorHandle.

move_editor_handle()

func move_editor_handle(_handle_id: StringName, _to: Vector3) -> void

One of get_editor_handles() has been dragged to to, snapped to the grid. Read the position as whatever the value it stands for actually is.

get_aabb()

func get_aabb() -> AABB

The entity's box in map space, for picking and selection: the _aabb its type registered, sized and placed where it stands (HammeriteEntity.get_aabb()). Override when the node knows its real extent, as a model does.

can_simulate()

func can_simulate() -> bool

Whether the editor offers to run this entity, and whether HammeriteMap3D.start_simulation() starts it. The default does nothing when run, so offers nothing.

start_simulation()

func start_simulation() -> void

Start or resume whatever this entity does over time, if can_simulate() says it does anything. Called through HammeriteMap3D.start_simulation(): once the map is built unless the editor is up over it, as the node is built into a world already running, and when the editor hands the view back.

stop_simulation()

func stop_simulation() -> void

Pause, keeping the state reached, so a later start_simulation() resumes. The editor stops the world when it opens.

reset_simulation()

func reset_simulation() -> void

Put the running thing back the way the map built it.

get_runtime_properties()

func get_runtime_properties() -> Dictionary[StringName, Variant]

What the inspector shows of the RUNNING thing, beside its authored properties - which are entity's, read with HammeriteEntity.get_property().

get_runtime_property()

func get_runtime_property(key: StringName, default_value = null) -> Variant

One of get_runtime_properties(), or default_value where there is none of that name. Not HammeriteEntity.get_property(), which reads an authored value.

set_runtime_property()

func set_runtime_property(_key: StringName, _value) -> void

Set a runtime property, changing the running node to match. The editor's inspector sets only those get_runtime_properties() lists, and undoes one by setting the old value back. Not saved with the map; reset_simulation() puts it back.

reset_runtime_properties()

func reset_runtime_properties() -> void

Put every runtime property back to what it was when the map was built.

can_trigger()

func can_trigger() -> bool

Whether something - the editor's Trigger, a HammeriteTrigger, the game - may trigger() it.

trigger()

func trigger(_impulse = null) -> void

Do whatever this entity does when triggered. impulse is whatever the one triggering it handed over - null from the editor's Trigger, a HammeriteTrigger's target_impulse - and what it means is the entity's to say: a light might read a bool as on or off and toggle on null, a lift a floor number.

get_actions()

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

The actions this entity offers in the editor's runtime panel, as id -> label. An action is a thing done TO a running entity, not a value set on it: it belongs beside the runtime properties because that is what it acts on, and it is not undoable because there is nothing authored to put back. Every entity that says it can be triggered gets Trigger for nothing. Override to add more, and call super() unless you mean to drop it.

run_action()

func run_action(action_id: StringName) -> void

Do one of get_actions(). Override alongside it.

apply_entity_property()

abstract func apply_entity_property(prop_name: StringName, value) -> void

Apply one property to the node: each as the entity is built - the entity's value, or its type's default where the entity has none - and each time the author changes one. prop_name is never classname. origin is in the map's space, so set Node3D.position from it. Where the type turns or sizes, rotation or scale has already been applied.

set_light_modulation()

func set_light_modulation(modulation: float) -> void

For a light: scale what the bake recorded of it - every face and prop it lit - by modulation, through its HammeriteBakedLight (or its light group's). Does nothing for an entity the bake has no light for, which is every one that is not a light, and before a bake.