HammeriteNavigation

Autoloads. Inherits Node

Hammerite Navigation runtime facade (autoload: HammeriteNavigation).

Builds a map's navigation when the map arrives, and gives gameplay code the two things it needs afterwards: which navigation layer an agent belongs on, and how to open or close a named link. Hooks HammeriteMap3D directly, with no dependency on hammerite-editor, so navigation works in builds that ship without the editor at all. Set the profiles before any map is assigned - the compile prepares navigation for whatever table is set then, and a table that arrives later bakes it all again - and integrate once per map:

HammeriteNavigation.profiles = load("res://resources/nav_agent_profiles.tres")
HammeriteNavigation.integrate(map_3d)
map_3d.map = map

The state itself lives in HammeriteNavigationRuntime, which this delegates to - an autoload cannot be mentioned by anything that has to compile without a scene tree.

Properties

Methods

Signals

navigation_built

signal navigation_built(map_3d: HammeriteMap3D, report: HammeriteNavigationBakeReport)

Emitted after a map's navigation has been built, with what the bake did and did not manage. Connect it to put the warnings wherever this game puts warnings.

Property descriptions

profiles

var profiles: HammeriteNavigationAgentProfiles

The game's agent profiles. Hammerite has no bestiary - what a guard is, is the game's to say - so the table is authored as a resource and assigned here. Without one, everything is baked for a single stand-in agent. Assigning one warns of anything HammeriteNavigationAgentProfiles.validate() finds in it, and a table that describes other agents than the last rebuilds every map already integrated, at the end of the frame - navigation built for the old table would route agents by it.

Method descriptions

integrate()

func integrate(map_3d: HammeriteMap3D) -> void

Build navigation for map_3d now, and again whenever its map changes.

rebuild()

func rebuild(map_3d: HammeriteMap3D) -> HammeriteNavigationBakeReport

Re-derive map_3d's navigation from its map as it stands now. Reads the compiled world rather than recompiling anything, so it costs a fraction of what putting the map together did: about 205 ms on a 256-room level, against four and a half seconds of compile (tests/benchmark_nav.gd). Call it after changing something navigation should notice at runtime, such as a door that has become a wall.

save_cache()

func save_cache(map_3d: HammeriteMap3D) -> int

Save map_3d's navigation beside its map, so the next load takes it rather than building it. HammeriteNavigationEditorExtension does this whenever the editor saves a map; a project that saves maps some other way calls it after saving. ERR_INVALID_DATA when the navigation was built before the map's last edits, ERR_UNCONFIGURED for a map with nowhere to keep one.

set_link_enabled()

func set_link_enabled(link_name: String, enabled: bool) -> int

Switch every link named link_name on or off; returns how many links carry the name. Remembered through a rebuild, a variant switch or a new map, until it is switched back.

layer_bit()

func layer_bit(profile_name: StringName) -> int

The navigation-layer bit for agents of profile_name, to put on their NavigationAgent3D.navigation_layers. Zero - which matches nothing - when the game has no such profile, so an agent asking for one that was never authored stays put rather than walking everywhere.

get_profile()

func get_profile(profile_name: StringName) -> HammeriteNavigationAgentProfile

The profile named profile_name, for gameplay code that wants the measurements themselves - how high this kind of agent climbs, how far it will drop.