HammeriteEntity

Core: the map. Inherits Resource

One placed thing in a HammeriteMap that is not world geometry: a light, a prop, a spawn point.

An entity is data - a registered type, a classname and a properties bag - and HammeriteMap3D builds a node for it by looking the classname up as a class_name. A point entity stands at origin; a HammeriteBrushEntity owns brushes instead. Make one and add it to a map in one call with HammeriteMap.create_entity(); make() makes one that is not in a map yet. selected, hovered, hidden and temporary_transform are the editor's state, never saved.

Properties

Methods

Signals

group_changed

signal group_changed()

Emitted when group_id has changed.

layer_changed

signal layer_changed()

Emitted when layer_id has changed.

delete_requested

signal delete_requested()

Emitted by request_delete(). The owning HammeriteMap listens and removes the entity.

property_changed

signal property_changed(prop_name: StringName, value)

Emitted by set_property() and clear_property(), and for each value that changes when properties is assigned whole. Not emitted by set_property_no_emit(), or by writing into the dictionary directly.

selection_changed

signal selection_changed(selected: bool)

Emitted when entity selection state has changed.

hidden_changed

signal hidden_changed(hidden: bool)

Emitted when hidden is set, with the new value: true when the entity has been hidden.

hover_changed

signal hover_changed(hovered: bool)

Emitted when entity hover state has changed.

temporary_transform_changed

signal temporary_transform_changed(transform: Transform3D)

Emitted when temporary transform has changed (used during transform tool operations).

Constants

EDITOR_ONLY_PREFIX

const EDITOR_ONLY_PREFIX = "_editor_"

A type's registration also carries what the editor draws it with - its icon, its tint - under this prefix. That belongs to the type, never to one entity of it: a copy on the entity is an editor asset baked into the map, and it goes stale the moment the type's picture changes.

KEY_BOX_BASIS

const KEY_BOX_BASIS = &"_aabb_basis"

Which way this entity's box is turned. Identity - no turn at all - for almost everything.

KEY_ROTATION

const KEY_ROTATION = &"rotation"

Which way the entity itself is turned (#77), as Euler angles in degrees - what Node3D.rotation_degrees holds, so a value typed into the property panel reads the way Godot's own does. Only on a type that declares it may be turned (_editor_rotation_axes in its registration); everything else has no such property and faces the way it was made.

KEY_SCALE

const KEY_SCALE = &"scale"

How far the entity itself is stretched along each of its own axes, before it is turned - what Node3D.scale holds. Only on a type that declares it may be sized, by carrying this in its registration; everything else has no such property and is the size it was made.

LEAST_SCALE

const LEAST_SCALE = 0.001

The least an entity may be sized to along an axis: nothing has no inverse, and a mesh of no depth has no inside to be lit from.

Property descriptions

type

var type: StringName = &""

The registered entity type this was made as (e.g. &"prop_model"), which names its editor registration and defaults. Distinct from the classname property, which names the node class built for it.

id

var id: int = 0

Unique within its map, from HammeriteMap.gen_entity_id(). 0 means unassigned, and HammeriteMap.add_entity() refuses it.

group_id

var group_id: int = 0

The editor group this entity is selected together with, or 0 for none. Emits group_changed.

prefab_id

var prefab_id: int = 0

The HammeritePrefab.prefab_id of the prefab this entity was placed from, or 0 if it is not part of a prefab instance.

instance_id

var instance_id: int = 0

The HammeritePrefabInstance.instance_id this entity belongs to, or 0 if none.

layer_id

var layer_id: int = 0

The HammeriteLayer this entity is on; it is present in the world only while that layer is (HammeriteMap.is_entity_present()). Emits layer_changed.

properties

var properties: Dictionary = {}

The entity's authored values, keyed by StringName. Keys starting with EDITOR_ONLY_PREFIX are dropped on assignment. Prefer set_property(), which emits property_changed.

map

var map: HammeriteMap

The map this entity belongs to. Held weakly, as a brush holds its map (see HammeriteBrush.map).

selected

var selected: bool = false

Editor selection state, not saved. Emits selection_changed.

hidden

var hidden: bool = false

Hidden by an editor tool, not saved. Emits hidden_changed.

hovered

var hovered: bool = false

Editor hover state, not saved. Emits hover_changed.

temporary_transform

var temporary_transform: Transform3D = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)

Temporary transform applied during transform tool operations. This allows preview without recalculating geometry. Not saved; identity when no tool is using it.

origin

var origin: Vector3

Where a point entity stands, in map space: the origin property. Setting it goes through set_property(), so it emits property_changed.

Method descriptions

set_group_id()

func set_group_id(id: int) -> void

Setter for group_id; emits group_changed when it changes.

set_layer_id()

func set_layer_id(id: int) -> void

Setter for layer_id; emits layer_changed when it changes.

make()

static func make(typename: StringName) -> HammeriteEntity

A new entity of typename: a HammeriteBrushEntity for a brush type, carrying every property the type declares at its default (HammeriteEntityTypeRegistry). It has no id and is in no map; HammeriteMap.create_entity() gives it both.

get_map()

func get_map() -> HammeriteMap

The map this entity was added to, or null before HammeriteMap.add_entity() or once the map is freed.

set_map()

func set_map(new_map: HammeriteMap) -> void

Set by HammeriteMap.add_entity(). Only records the back-reference; it does not add the entity to new_map.

set_selected()

func set_selected(is_selected: bool) -> void

Setter for selected; emits selection_changed.

set_hidden()

func set_hidden(is_hidden: bool) -> void

Setter for hidden; emits hidden_changed.

set_hovered()

func set_hovered(is_hovered: bool) -> void

Setter for hovered; emits hover_changed.

request_delete()

func request_delete() -> void

Ask the owning map to remove this entity, by emitting delete_requested. Does nothing before the entity is added to a map.

get_classname()

func get_classname() -> StringName

The classname property: the class_name of the node built for this entity, or empty if it has none.

get_origin()

func get_origin() -> Vector3

The origin property, or Vector3.ZERO when it has none (a brush entity).

set_origin()

func set_origin(origin: Vector3) -> void

Setter for origin; emits property_changed.

get_basis()

func get_basis() -> Basis

KEY_ROTATION as a basis: identity for an entity that is not turned, or cannot be.

is_turnable()

func is_turnable() -> bool

Whether this entity carries a turn of its own - whether its type lets it be turned at all.

get_scale()

func get_scale() -> Vector3

KEY_SCALE: one along each axis for an entity that is not sized, or cannot be. Never less than LEAST_SCALE, and never mirrored - a mesh turned inside out is lit from the wrong side.

is_scalable()

func is_scalable() -> bool

Whether this entity carries a size of its own - whether its type lets it be sized at all.

get_transform()

func get_transform() -> Transform3D

What a point of the entity's own goes through to stand in the world: sized along its own axes, then turned, then put where the entity is.

transform_by()

func transform_by(transform: Transform3D) -> void

Carry this entity through transform, as a prefab instance carries what it holds: its origin moved, and - where it can be turned - its turn turned with it. Only the turn of transform is taken; an entity is sized by its own KEY_SCALE, never by what it stands in.

rotation_of()

static func rotation_of(basis: Basis) -> Vector3

basis as what KEY_ROTATION stores: degrees, and near-whole numbers rounded to them, so a quarter turn made with the tool reads 90 rather than 89.99999.

may_turn_about()

static func may_turn_about(axes: String, axis: Vector3) -> bool

Whether axes - a type's _editor_rotation_axes, some of "xyz" - lets it turn about axis: a world axis the turn is about, or near enough to one.

get_aabb()

func get_aabb(center_on_origin: bool = true) -> AABB

The entity's axis-aligned box from its _aabb property, sized by get_scale(). Placed at origin when center_on_origin, otherwise relative to it. When it is turned (is_box_turned()) this is the box enclosing the turned one. Empty for a type with no _aabb, which includes brush entities.

is_box_turned()

func is_box_turned() -> bool

Whether this entity's box is turned, and so whether asking for the AABB loses something.

get_box()

func get_box() -> HammeriteEntityBox

The box it fills, turned if it is turned. What the editor draws and what a click is tested against.

Experimental: HammeriteEntityBox is not part of the supported API.

is_editor_only()

static func is_editor_only(prop_name) -> bool

Whether prop_name starts with EDITOR_ONLY_PREFIX and so belongs to the type's registration, not to a saved entity.

set_properties()

func set_properties(value: Dictionary) -> void

value without the keys that are is_editor_only(). Dropped on the way in, which is also the way a map is loaded: the property panel's type change once copied a type's whole registration, icon included, and a map saved then loses it the next time it is opened. Each value that differs from what was there before is announced (property_changed), and each one taken away is announced at the value it falls back to, so the entity's node follows a wholesale assignment - an undo, say - as it follows one property set.

get_property()

func get_property(prop_name: StringName, default = null) -> Variant

The value of prop_name: this entity's own, else its type's registered default, else default - as HammeriteBrush.get_property() and HammeriteSkybox.get_property() read theirs.

has_property()

func has_property(prop_name: StringName) -> bool

Whether this entity holds its own value of prop_name, rather than its type's default.

set_property()

func set_property(prop_name: StringName, value) -> void

Store value and emit property_changed, which the entity's node listens to. An editor-only key (is_editor_only()) belongs to the type and is refused.

clear_property()

func clear_property(prop_name: StringName) -> void

Forget this entity's own value of prop_name, so it reads its type's default again, and emit property_changed with that default.

set_property_no_emit()

func set_property_no_emit(prop_name: StringName, value) -> void

Store value without emitting property_changed, so the node does not hear of it. Refuses an editor-only key, as set_property() does.