Runtime API.md

Runtime API

OrcKit exposes its runtime API through Godot engine metadata:

Engine.get_meta("OrcmodLib")

The API key is OrcmodLib.

Safe Access Pattern

func get_modlib():
	if not Engine.has_meta("OrcmodLib"):
		return null
	return Engine.get_meta("OrcmodLib")

Use it from your autoload:

extends Node

func _ready() -> void:
	var modlib = get_modlib()
	if modlib == null:
		push_warning("OrcKit API is not available")
		return

	print("OrcKit ", modlib.version())

func get_modlib():
	if not Engine.has_meta("OrcmodLib"):
		return null
	return Engine.get_meta("OrcmodLib")

Waiting for Framework Readiness

Hook registration should wait for frameworks_ready.

extends Node

func _ready() -> void:
	var modlib = Engine.get_meta("OrcmodLib")
	if modlib._is_ready:
		_install(modlib)
	else:
		modlib.frameworks_ready.connect(func(): _install(modlib))

func _install(modlib) -> void:
	print("ready to register hooks")

Version Helpers

modlib.version()       # "1.0.0"
modlib.major_version() # 1
modlib.minor_version() # 0
modlib.patch_version() # 0

Use these when your mod needs a minimum OrcKit feature level.

if modlib.major_version() < 1:
	push_error("This mod requires OrcKit 1.x")

Mod Presence Helpers

modlib.has_mod("other_mod")
modlib.has_mod("other_mod", "1.2.0")
modlib.mod_info("other_mod")
modlib.loaded_mods()

has_mod(id, min_version := "")

Returns true if a loaded mod with that id exists. If min_version is provided, the loaded version must be greater than or equal to the requested version.

if modlib.has_mod("extra_maps", "1.1.0"):
	print("Extra Maps compatibility enabled")

mod_info(id)

Returns a dictionary for a loaded mod:

mod_id
mod_name
version
file_name
priority

Example:

var info = modlib.mod_info("extra_maps")
if not info.is_empty():
	print(info["mod_name"], " v", info["version"])

loaded_mods()

Returns all loaded mod ids:

for id in modlib.loaded_mods():
	print("Loaded mod: ", id)

Hook API

var hook_id = modlib.hook("player-_ready-pre", Callable(self, "_before_ready"), 100)
modlib.unhook(hook_id)
modlib.has_hooks("player-_ready-pre")

Helpers:

modlib.add_hook("res://scripts/player.gd", "_ready", Callable(self, "_before_ready"), true)
modlib.hook_many({
	"player-_ready-pre": Callable(self, "_before_ready"),
	"player-_ready-post": Callable(self, "_after_ready"),
}, 100)

See Hooks for full behavior.

Replace Hook Helpers

modlib.has_replace("player-_ready")
modlib.get_replace_owner("player-_ready")
modlib.skip_super()

skip_super() is used inside a replace hook to stop the vanilla method from running.

Registry API

modlib.register(modlib.Registry.RESOURCES, "my_resource", resource)
modlib.get_entry(modlib.Registry.RESOURCES, "my_resource")

See Registry Facade.

Debug Helpers

modlib.seq()

seq() returns a dispatch sequence counter used internally by hook dispatch. It is mostly useful for debugging hook order.

API Stability Notes

Use public-looking helpers such as version(), has_mod(), hook(), add_hook(), and registry methods. Avoid depending on underscored fields except for _is_ready when waiting for readiness, because underscored fields are internal loader state.