Callbacks

Sometimes, it's difficult to replace a Scene properly due to lingering references to the original PackedScene floating around in various AutoLoads or class scripts. If you simply want to add, remove, or tweak some small Node or value in a scene when it appears, it may be easier to use a callback and make your changes in a script when the Scene is added to the SceneTree.

callbacks.connect_class_ready

func connect_class_ready(script_path: String, callback_owner: Object, callback_function: String, callback_binds: Array = []) -> void

Runs a function when any Node instanced from a given script class enters the SceneTree for the first time. This is useful if multiple scenes contain instances of the same class and you want to change most or all of them.

Example:

func init_content():
	DLC.mods_by_id.cat_modutils.callbacks.connect_class_ready("res://nodes/warp_region/WarpTarget.gd", self, "_on_WarpTarget_ready")

func _on_WarpTarget_ready(scene: Node) -> void:
	print("There's a WarpTarget named " + scene.name + " here!")

callbacks.connect_scene_ready

func connect_scene_ready(scene: String, callback_owner: Object, callback_function: String, callback_binds: Array = []) -> void

Runs a function when any Node instanced from a given scene path enters the SceneTree for the first time. This is useful to change a specific PackedScene at a known resource path, even if another mod has taken over the path, and may alleviate chain-loading compatibility issues where loading a PackedScene to replace it will cause its dependent Resources to load before other mods have a chance to replace them as well. Note that connect_scene_ready may be used for any scene that gets instanced, such as individual NPCs, objects, or UI elements.

⚠️ Streaming level chunks like the Overworld require special handling, and won't be detected by this callback.

⚠️ The vanilla signal SceneManager.connect("scene_changed", ...) and the SceneManager.current_scene Node may be preferred when detecting the root scene is your goal.

Example:

func init_content():
	DLC.mods_by_id.cat_modutils.callbacks.connect_scene_ready("res://world/maps/interiors/GramophoneInterior.tscn", self, "_on_GramophoneCafe_ready")

func _on_GramophoneCafe_ready(scene: Node) -> void:
	print("Entered the Gramophone Café!")

callbacks.connect_chunk_setup

func connect_chunk_setup(scene: String, chunk_index: Vector2, callback_owner: Object, callback_function: String, callback_binds: Array = []) -> void

Runs a function when a specific streaming level chunk finishes setup. Scene should be the root scene that contains the chunk, such as "res://world/maps/Overworld.tscn", and chunk index should be the X and Y grid values of the chunk, such as Vector2(3, -1)

The referenced node will be a Chunk, not a DesignChunk, and may despawn and re-spawn its "detail" Nodes several times throughout its lifespan. This callback has not been fully tested yet, and requires intimate knowledge of the Chunk class, so best practices for using it are not currently known.