HammeriteWorldrepCompile

Core: in the scene. Inherits RefCounted

A just-loaded map's worldrep, compiled on a worker thread so that whoever loaded it can go on drawing, say how far the compile has got, and let it be cancelled (#109). A large level takes minutes to carve the first time, and done where a view first asks for it, it held the main thread for all of them.

Only for a map nothing else holds yet. The compile writes the map's derived state as it goes, so a view reading the same map meanwhile would read it half-built, on another thread. Hand the map to its views once is_done(), after finish():

var job := HammeriteWorldrepCompile.create(map)
job.start()
# each frame: show job.progress.describe(); job.cancel() if asked
if job.is_done() and job.finish():
map_3d.map = map

Properties

Methods

Property descriptions

map

var map: HammeriteMap

The map being compiled, as given to create(). Read-only: the worker holds it.

progress

var progress: HammeriteCompileProgress

How far the compile has got; safe to read from the main thread while it runs. Also set as HammeriteMap.compile_progress until finish(). Read-only, as map is.

Method descriptions

add_stage()

static func add_stage(stage_names: PackedStringArray, run: Callable) -> void

Hook run into every compile from now on, called as run(map, progress) on the worker once the worldrep is compiled. It reports under stage_names, which are how far through the whole compile a bar is measured; it should stop early once HammeriteCompileProgress.report() answers false, and whatever it derived goes in HammeriteMap.derived. Replaces a stage already added with the same first name.

cancel()

func cancel() -> void

Stop at the next item. finish() then answers false.

clear_stages()

static func clear_stages() -> void

Drop every hooked stage - see the Hammerite autoload's _exit_tree for why this must happen.

create()

static func create(target: HammeriteMap) -> HammeriteWorldrepCompile

A compile of target, not started; where new(map) went.

finish()

func finish() -> bool

Wait for the worker, and whether the compile ran to the end. A cancelled one leaves the worldrep invalid rather than partial, so the map is still usable - its next query compiles it again.

is_done()

func is_done() -> bool

Whether the worker has finished, cancelled or not. False until start(), so a loading screen polling it before the compile begins waits rather than moving on.

load_models()

func load_models(budget_msec: int) -> bool

Load the models the map's props wear, on this thread, until budget_msec has gone: what a host waiting for the compile can do with the thread it waits on, between the frames it draws. True once every one is loaded, so the props built afterwards find them waiting rather than loading them one by one as each is built - a second of a Thief mission's load. Here rather than on a worker of their own: the compile keeps every core busy, and loading models beside it stretched it by more than it saved. The thread waiting on it is the one it leaves idle.

remove_stage()

static func remove_stage(first_stage_name: String) -> void

Unhook the stage add_stage() registered under first_stage_name. Compiles already started keep it.

start()

func start() -> void

Begin compiling. What must happen on the calling thread happens here, before the worker starts.

stop_all()

static func stop_all() -> void

Stop every compile under way and wait for its worker. For a game closing while one runs - during a loading screen, say: the worker goes on calling the stages hooked into it, which are other addons' nodes, and the tree frees those as it goes. On Linux that was a segmentation fault on the way out.