Example Mods.md

Example Mods

These examples are small patterns you can copy into your own mod and adjust.

Example 1: Autoload Logger

Layout:

LoggerMod/
  mod.txt
  scripts/logger_mod/main.gd

mod.txt:

[mod]
id="logger_mod"
name="Logger Mod"
version="1.0.0"
author="You"
priority=0

[autoload]
LoggerMod="res://scripts/logger_mod/main.gd"

scripts/logger_mod/main.gd:

extends Node

func _ready() -> void:
	print("[LoggerMod] loaded")

Example 2: Hook a Vanilla Method

mod.txt:

[mod]
id="ready_hook_example"
name="Ready Hook Example"
version="1.0.0"
author="You"
priority=0

[autoload]
ReadyHookExample="res://scripts/ready_hook_example/main.gd"

[hooks]
res://scripts/menu.gd="_ready"

main.gd:

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:
	var id = modlib.hook("menu-_ready-post", Callable(self, "_after_menu_ready"))
	if id == -1:
		push_warning("Failed to register hook")

func _after_menu_ready() -> void:
	print("[ReadyHookExample] menu ready finished")

Example 3: Optional Compatibility With Another Mod

extends Node

func _ready() -> void:
	var modlib = Engine.get_meta("OrcmodLib")
	if modlib.has_mod("extra_maps", "1.1.0"):
		print("Extra Maps compatibility enabled")
	else:
		print("Extra Maps not loaded or too old")

Example 4: Replace Hook

mod.txt:

[mod]
id="replace_hook_example"
name="Replace Hook Example"
version="1.0.0"
author="You"
priority=0

[autoload]
ReplaceHookExample="res://scripts/replace_hook_example/main.gd"

[hooks]
res://scripts/player.gd="_process"

main.gd:

extends Node

func _ready() -> void:
	var modlib = Engine.get_meta("OrcmodLib")
	modlib.frameworks_ready.connect(func():
		modlib.hook("player-_process", Callable(self, "_replace_player_process"))
	)

func _replace_player_process(delta: float) -> void:
	var modlib = Engine.get_meta("OrcmodLib")
	modlib.skip_super()
	# Custom process behavior here.

Use replace hooks carefully. They can break other mods that expect vanilla behavior.

Example 5: Generic Registry Sharing

Mod A:

extends Node

func _ready() -> void:
	var modlib = Engine.get_meta("OrcmodLib")
	modlib.register(modlib.Registry.RESOURCES, "mod_a.api", {
		"version": "1.0.0",
		"feature_enabled": true,
	})

Mod B:

extends Node

func _ready() -> void:
	var modlib = Engine.get_meta("OrcmodLib")
	var api = modlib.get_entry(modlib.Registry.RESOURCES, "mod_a.api")
	if api is Dictionary and api.get("feature_enabled", false):
		print("Mod A integration active")

Example 6: Declared Script Override

mod.txt:

[mod]
id="player_override_example"
name="Player Override Example"
version="1.0.0"
author="You"
priority=50

[script_overrides]
res://scripts/player.gd="res://scripts/player_override_example/player.gd"

Use this only when a hook cannot express the change.