Godot Autoload Architecture

class_name AutoLoadBootstrapper
extends Node

## Expert AutoLoad Bootstrapper (Godot 4.6).
## Orchestrates two-phase initialization across all Singletons.
## PLACE THIS LAST IN THE PROJECT SETTINGS AUTOLOAD LIST.

func _ready() -> void:
	var root := get_tree().root
	var services: Array[Node] = []
	
	# 1. Discovery
	for child in root.get_children():
		if child.has_method("init_service") and child != self:
			services.append(child)
	
	# 2. Phase 1: Dependency Resolution
	for s in services:
		s.call("init_service")
	
	# 3. Phase 2: Execution Start
	for s in services:
		if s.has_method("start_service"):
			s.call("start_service")
	
	print("[BOOTSTRAP]: All global services synchronized and started.")

## [SKILL NOTICE]: This pattern resolves circular dependencies where 
## AutoLoad A needs AutoLoad B's 'ready' state to initialize.

# autoload_init_order_diag.gd
# Checking Autoload initialization sequence
extends Node

# EXPERT NOTE: Autoloads initialize in the order they appear in 
# Project Settings -> AutoLoad. Use this for dependency debugging.

func _ready():
	print("[AutoLoad Diagnostic] Initialized: ", name)
	
	# Check for dependencies. If 'GlobalConfig' must be first:
	if not get_tree().root.has_node("GlobalConfig"):
		push_error("CRITICAL: GlobalConfig Autoload missing or loaded after %s!" % name)

# skills/autoload-architecture/scripts/autoload_initializer.gd
extends Node

## AutoLoad Initializer Expert Pattern
## Manages explicit initialization order and dependency injection for AutoLoads.

class_name AutoLoadInitializer

var _initialized: Dictionary = {}
var _init_order: Array[StringName] = []

func register_autoload(autoload_name: StringName, init_callback: Callable) -> void:
	_init_order.append(autoload_name)
	_initialized[autoload_name] = {
		"callback": init_callback,
		"complete": false
	}

func initialize_all() -> void:
	print("=== Initializing AutoLoads ===")
	
	for autoload_name in _init_order:
		var data: Dictionary = _initialized[autoload_name]
		if data["complete"]:
			continue
			
		print("Initializing: %s" % autoload_name)
		data["callback"].call()
		data["complete"] = true

func is_initialized(autoload_name: StringName) -> bool:
	return _initialized.get(autoload_name, {}).get("complete", false)

func wait_for_autoload(autoload_name: StringName) -> void:
	while not is_initialized(autoload_name):
		await get_tree().process_frame

## EXPERT USAGE:
## In each AutoLoad's _ready():
##   AutoLoadInitializer.register_autoload(&"GameManager", initialize)
##
## func initialize() -> void:
##   # Heavy initialization here
##   pass
##
## Then in main scene:
##   AutoLoadInitializer.initialize_all()

# autoload_reference_checker.gd
# Validating singleton availability before access
extends Node

# EXPERT NOTE: Using 'get_node("/root/Name")' is safer than using the 
# global name if you code for packages/plugins that might lack the Autoload.

static func get_events(tree: SceneTree) -> Node:
	var path = "/root/GlobalEvents"
	if tree.root.has_node(path):
		return tree.root.get_node(path)
	push_warning("GlobalEvents Autoload not found!")
	return null

# cross_autoload_comms.gd
# Rules for Autoload-to-Autoload communication
extends Node

# EXPERT NOTE: Avoid circular dependencies between Autoloads.
# If A needs B and B needs A, your project will likely hang on boot.

func _ready():
	# Use 'await' if checking for a sibling Autoload's node tree
	if not get_tree().root.has_node("SaveManager"):
		await get_tree().process_frame # Give other singletons time to init
		
	_initialize_hooks()

func _initialize_hooks():
	# Connecting to another Singleton safely
	if get_tree().root.has_node("SaveManager"):
		var sm = get_node("/root/SaveManager")
		sm.save_requested.connect(_on_save)

func _on_save():
	pass

# debug_console_autoload.gd
# Universal debug overlay accessible from any scene
extends CanvasLayer

# EXPERT NOTE: UI Autoloads should use CanvasLayer to ensure they 
# always draw on top of game scenes.

@onready var label = $Label

func _ready():
	process_mode = PROCESS_MODE_ALWAYS # Console works even when paused

func log_message(msg: String):
	label.text += "\n" + msg
	print("[Debug] ", msg)

# global_event_bus.gd
# Centralized signal routing to decouple systems
extends Node

# EXPERT NOTE: An Event Bus should ideally hold no state. 
# It only acts as a post office for signals.

signal level_started(id: int)
signal enemy_defeated(type: String, points: int)
signal game_paused(is_paused: bool)

func notify_enemy_killed(type: String, val: int):
	enemy_defeated.emit(type, val)

class_name GlobalGameState
extends Node

## Expert Global State Machine (Godot 4.6).
## Uses deferred transitions to prevent frame-locked race conditions.

signal state_changed(old_state: State, new_state: State)

enum State { MENU, LOADING, IN_GAME, PAUSED, GAME_OVER }

var current_state: State = State.MENU
var _is_transitioning: bool = false

func request_transition(new_state: State) -> void:
	if _is_transitioning or current_state == new_state:
		return
	
	_is_transitioning = true
	# Use call_deferred to ensure physics/logic have finished current frame
	call_deferred("_apply_transition", new_state)

func _apply_transition(new_state: State) -> void:
	var old := current_state
	current_state = new_state
	_is_transitioning = false
	state_changed.emit(old, current_state)

## [SKILL NOTICE]: NEVER change global state inside a physics callback 
## without deferring, or related systems may read stale/conflicting data.

# lazy_loaded_singleton.gd
# Creating "Autoloads" on demand to save memory
extends Node

# EXPERT NOTE: If a singleton is rarely used, don't put it in 
# Project Settings. Load it manually when needed.

static var _instance: Node = null

static func get_instance(tree: SceneTree) -> Node:
	if not is_instance_valid(_instance):
		_instance = load("res://systems/heavy_system.tscn").instantiate()
		tree.root.add_child(_instance)
	return _instance

# persistent_data_holder.gd
# Keeping data alive across scene changes
extends Node

# EXPERT NOTE: Values in Autoloads survive SceneTree.change_scene_to_file().
# Use for player inventory, settings, and quest progress.

var inventory: Array[String] = []
var settings: Dictionary = {"volume": 0.8, "fullscreen": false}

func add_item(item: String):
	inventory.append(item)
	print("Items persistent: ", inventory)

# safe_scene_switcher.gd
# Robust scene transitioning via Autoload
extends Node

# EXPERT NOTE: Managing scenes in an Autoload prevents data loss 
# during transition and ensures proper cleanup of the current scene.

var current_scene: Node = null

func _ready() -> void:
	# Autoloads are the first children. The active game scene is the last child.
	current_scene = get_tree().root.get_child(-1)

func goto_scene(path: String) -> void:
	# NEVER free the current scene while it's executing (e.g., inside a signal).
	# Use call_deferred to wait until the end of the frame.
	call_deferred("_deferred_goto_scene", path)

func _deferred_goto_scene(path: String) -> void:
	# Safety: Free current scene before loading new one
	if is_instance_valid(current_scene):
		current_scene.free()
		
	var next_scene_res = ResourceLoader.load(path) as PackedScene
	current_scene = next_scene_res.instantiate()
	
	get_tree().root.add_child(current_scene)
	# Set as current for get_tree().current_scene access
	get_tree().current_scene = current_scene

# service_locator.gd
# Expert Service Locator pattern using Godot 4.1+ static variables.
# Decouples system discovery from hardcoded Autoloads.

extends Node

class_name ServiceLocator

## Global registry of services, accessible via static methods.
static var _services: Dictionary = {}

## Registers a service provider (Node or RefCounted).
static func register_service(id: String, provider: Object) -> void:
	if _services.has(id):
		push_warning("Service Locator: Overwriting existing service '%s'." % id)
	_services[id] = provider
	print("Service Locator: Registered '%s' (%s)" % [id, provider.get_class()])

## Retrieves a registered service. Returns null if not found.
static func get_service(id: String) -> Object:
	if not _services.has(id):
		push_error("Service Locator: Service '%s' not found!" % id)
		return null
	return _services[id]

## Removes a service from the registry.
static func unregister_service(id: String) -> void:
	if _services.erase(id):
		print("Service Locator: Unregistered '%s'" % id)

## Clears all services (useful for unit test teardown).
static func clear_all() -> void:
	_services.clear()
	print("Service Locator: All services cleared.")

## Usage Expert Tip:
## Instead of using hardcoded Autoloads, have your managers register themselves:
## func _ready():
##     ServiceLocator.register_service("save_manager", self)

class_name ServiceRegistry
extends Node

## Expert Service Locator (Godot 4.6).
## Prevents Global Namespace Pollution by centralizing dependencies.

var _services: Dictionary = {}

func register(service_name: StringName, instance: Object) -> void:
	if _services.has(service_name):
		push_warning("[SERVICE]: %s already registered. Overwriting." % service_name)
	
	_services[service_name] = instance
	if instance is Node and not instance.is_inside_tree():
		add_child(instance)

func get_service(service_name: StringName) -> Object:
	return _services.get(service_name)

func unregister(service_name: StringName) -> void:
	var service = _services.get(service_name)
	if service:
		_services.erase(service_name)
		if service is Node and service.get_parent() == self:
			service.queue_free()

## [SKILL NOTICE]: Use StringName (&"Name") for keys to ensure O(1) 
## dictionary lookups at the engine-core level.

# singleton_dependency_diagram.gd
# Utility to visualize Singleton dependencies and generate a Mermaid diagram.
# Expert tool for managing initialization order.

extends RefCounted

class_name SingletonDependencyDiagram

## Generates a Mermaid 'graph TD' diagram of active Autoloads.
static func generate_mermaid_diagram() -> String:
	var diagram := "graph TD\n"
	
	# Get all children of root (this includes Autoloads)
	var root = Engine.get_main_loop().root
	var autoloads := []
	
	for child in root.get_children():
		# Filter for typical Autoload nodes (exclude the main scene)
		if child.name != "root" and child != Engine.get_main_loop().root.get_child(-1):
			autoloads.append(child)
	
	if autoloads.is_empty():
		return "No Autoloads detected."
		
	for node in autoloads:
		diagram += "  %s[%s]\n" % [node.name, node.name]
		
	# Expert logic: Analyze signals and cross-references (simplified example)
	# In a full implementation, you'd scan script properties for other Autoload names.
	diagram += "\n  %% Manual annotations or analysis result follows\n"
	
	return diagram

## Prints the Mermaid code to console for use in documentation.
static func print_diagram() -> void:
	print(generate_mermaid_diagram())

# singleton_health_check_test.gd
# Template for verifying global singleton state using expert unit testing patterns.
# Designed for compatibility with GUT (Godot Unit Test) or GdUnit4.

extends Node

## Health Check: Verify that core singletons are correctly initialized.
func test_singleton_initialization():
	# Verify ServiceLocator
	var root = Engine.get_main_loop().root
	assert_not_null(root.get_node_or_null("GameManager"), "GameManager must be registered as an Autoload.")
	
	# Verify default states
	# var gm = root.get_node("GameManager")
	# assert_eq(gm.score, 0, "GameManager score should start at 0.")
	
	print("Health Check: Singletons are stable.")

## Helper for GUT (if using)
func assert_not_null(obj, msg):
	if obj == null:
		push_error(msg)
	else:
		print("PASSED: ", msg)

# skills/autoload-architecture/code/stateless_bus.gd
extends Node

## Stateless Signal Bus Expert Pattern
## Optimized for decoupling and lazy-loading of systems.

# 1. Defined Semantic Signals
# Avoid 'generic' signals. Be specific about the domain.
signal player_health_changed(new_health: int, max_health: int)
signal level_completed(id: String, score: int)
signal system_booted(id: String)

func _ready() -> void:
    # 2. Boot-time Priorities
    # Autoloads initialize in order. Use signals to notify
    # other singletons that this generic hub is ready.
    system_booted.emit("StatelessBus")

func notify_health(h: int, m: int) -> void:
    player_health_changed.emit(h, m)

## EXPERT NOTE:
## NEVER store state (e.g. current_health) in the Signal Bus.
## The bus is a 'Post Office' - it delivers messages (Signals),
## it does not store packages (State). 

# static_state_manager.gd
# Using static variables for high-performance global state
extends RefCounted
class_name GlobalState

# EXPERT NOTE: static var is shared across all instances of the class. 
# It does NOT require an Autoload node in the SceneTree. 
# Access via: GlobalState.score += 10

static var score: int = 0
static var player_name: String = "Player1"
static var unlocked_levels: Array[int] = [1]

static func add_score(val: int) -> void:
	score += val

static func is_level_unlocked(lvl: int) -> bool:
	return unlocked_levels.has(lvl)

# thread_safe_global_access.gd
# Handling global data from background threads
extends Node

# EXPERT NOTE: Modifying Autoload nodes or SceneTree properties 
# from threads is UNSAFE. Use Mutex for data or call_deferred for nodes.

var _shared_data: Dictionary = {}
var _lock: Mutex = Mutex.new()

func update_data_safely(key: String, val: Variant):
	_lock.lock()
	_shared_data[key] = val
	_lock.unlock()

func get_data_safely(key: String) -> Variant:
	_lock.lock()
	var res = _shared_data.get(key)
	_lock.unlock()
	return res