Godot Project Templates

class_name AccessibilityTTSManager
extends Node

## Accessibility & Localization foundation for modern templates.
## Utilizes DisplayServer for native TTS and TranslationServer for i18n context.

func speak_ui_element(text: String, context: StringName = &"") -> void:
	# Use context to ensure the correct translation (e.g. "Lead" metal vs "Lead" action)
	var translated := TranslationServer.translate(text, context)
	
	if DisplayServer.tts_is_speaking():
		DisplayServer.tts_stop()
		
	# Trigger system-level screen reader / TTS
	var voices = DisplayServer.tts_get_voices()
	if not voices.is_empty():
		DisplayServer.tts_speak(translated, voices[0]["id"])

## Tool tip for templates: Use 'set_input_as_handled' in accessibility overlays.

class_name BaseActor
extends CharacterBody2D # or CharacterBody3D

## Template foundation for all gameplay agents (Player, NPC, Enemies).
## Enforces a consistent lifecycle for state transitions and combat.

signal state_changed(new_state: StringName)
signal damaged(amount: int, source: Node)

@export var actor_name: String = "Agent"
@export var faction: StringName = &"neutral"

var current_state: StringName = &"idle"

func _physics_process(delta: float) -> void:
	_process_logic(delta)

## Virtual: Override for AI or input logic
func _process_logic(_delta: float) -> void:
	pass

## Expert Tip: Use a dedicated method for damage to centralize logging and effects
func take_damage(amount: int, source: Node = null) -> void:
	damaged.emit(amount, source)
	_on_damage_received(amount, source)

func _on_damage_received(_amount: int, _source: Node) -> void:
	pass

# skills/project-templates/code/base_game_manager.gd
extends Node

## Project Templates Expert Pattern
## Implements the 'Template Method' pattern for core game loops.

signal state_changed(old_state: String, new_state: String)

var _current_state: String = "INIT"

func _ready() -> void:
    # 1. Abstract Initialization Loop
    # Expert logic: Define the skeleton of the algorithm, 
    # letting subclasses override specific steps.
    _bootstrap_systems()
    _enter_initial_state()

# --- Template Methods (To be overridden) ---

func _bootstrap_systems() -> void:
    # Logic for dependency injection, singleton checks, etc.
    pass

func _enter_initial_state() -> void:
    change_state("MAIN_MENU")

# --- Core Logic ---

func change_state(new_state: String) -> void:
    if _current_state == new_state: return
    
    var old_state = _current_state
    _current_state = new_state
    
    # 2. Lifecycle Hooks
    # Professional pattern: Separate 'Internal Logic' from 'Extensible Hooks'.
    _on_state_exit(old_state)
    _on_state_enter(new_state)
    
    state_changed.emit(old_state, new_state)

func _on_state_exit(_state: String) -> void: pass
func _on_state_enter(_state: String) -> void: pass

## EXPERT NOTE:
## Use 'Modular Initialization': Don't put everything in one script. 
## Create separate 'System' nodes (e.g. SaveSystem, AudioSystem) and 
## have the BaseGameManager coordinate their 'start()' and 'stop()' 
## sequences to ensure correct boot order.
## NEVER hardcode scene transitions; use a centralized 'SceneLoader' 
## singleton called via the 'BaseGameManager' state hooks.
## For 'project-templates', pre-configure a 'test/' directory with 
## a simple GUT test that verifies the 'change_state' logic works 
## before any new logic is added.

class_name BaseLevel
extends Node

## Abstract base class for all loaded levels.
## Provides structured lifecycle hooks for initialization and completion.

signal level_initialized
signal level_completed(next_level_id: StringName)

@export var level_id: StringName

func _ready() -> void:
	# Standardize startup sequence
	_initialize_level()
	level_initialized.emit()

## Virtual method: Override for level-specific setup (NPC spawning, etc.)
func _initialize_level() -> void:
	pass

## Expert: Use call_deferred to safely transition scenes and avoid physics-mid-frame errors.
func complete_level(next_id: StringName = &"") -> void:
	call_deferred(&"_deferred_completion", next_id)

func _deferred_completion(next_id: StringName) -> void:
	level_completed.emit(next_id if not next_id.is_empty() else level_id)

class_name BaseMenu
extends Control

## Expert foundation for all UI menus.
## Handles focus persistence, animations, and input blocking.

signal menu_closed

@onready var first_focus_node: Control = null

func open_menu() -> void:
	show()
	_on_menu_opened()
	if first_focus_node:
		first_focus_node.grab_focus()

func close_menu() -> void:
	hide()
	menu_closed.emit()
	_on_menu_closed()

## Virtual hooks for juice (animations/sounds)
func _on_menu_opened() -> void:
	pass

func _on_menu_closed() -> void:
	pass

## Expert: Handle 'ui_cancel' (Escape/B) natively to close menus
func _unhandled_input(event: InputEvent) -> void:
	if event.is_action_pressed(&"ui_cancel") and is_visible_in_tree():
		close_menu()
		get_viewport().set_input_as_handled()

# bootstrap_config.gd
# Expert pattern for managing initialization priority and AutoLoad order.
# Grounded in architectural best practices for Godot 4.x.

extends RefCounted

class_name BootstrapConfig

## Priority list for global system initialization.
# Lower numbers initialize first.
const BOOTSTRAP_PRIORITY := {
	"ConfigManager": 1,
	"SaveManager": 10,
	"PlayerManager": 20,
	"SceneTransitioner": 30,
	"AudioManager": 40,
	"InputRecorder": 50
}

## Validates the current AutoLoad order against the intended bootstrap priority.
static func validate_autoload_order() -> void:
	# Note: Accessing ProjectSettings via code allows runtime verification,
	# but actual order is defined in project.godot.
	print("Bootstrap Config: Validating initialization order...")
	
	# Expert logic: In a real tool, this would parse project.godot 
	# and ensure [autoload] entries match the sorted BOOTSTRAP_PRIORITY.
	
	for system in BOOTSTRAP_PRIORITY.keys():
		print("- System: %s (Priority: %d)" % [system, BOOTSTRAP_PRIORITY[system]])

class_name LevelStreamerManager
extends Node

## Expert Dynamic Background Level-Loading.
## Streams scenes across background CPU cores using ResourceLoader.load_threaded_request.

var _loading_path: String = ""

func load_level_async(path: String) -> void:
	_loading_path = path
	var err = ResourceLoader.load_threaded_request(path, "", true)
	if err != OK:
		push_error("Streamer: Failed to request " + path)

func _process(_delta: float) -> void:
	if _loading_path.is_empty(): return
	
	var progress = []
	var status = ResourceLoader.load_threaded_get_status(_loading_path, progress)
	
	match status:
		ResourceLoader.THREAD_LOAD_LOADED:
			var packed = ResourceLoader.load_threaded_get(_loading_path) as PackedScene
			# Standard transition in professional templates: use change_scene_to_packed
			get_tree().change_scene_to_packed(packed)
			_loading_path = ""
		ResourceLoader.THREAD_LOAD_FAILED, ResourceLoader.THREAD_LOAD_INVALID_RESOURCE:
			push_error("Streamer: Failed to load " + _loading_path)
			_loading_path = ""

# modular_dlc_loader.gd
# Expert pattern for mounting external .pck files (DLC/Mods) at runtime.
# Grounded in Godot 4.x ProjectSettings.load_resource_pack.

extends Node

class_name ModularDLCLoader

## Loads a resource pack (.pck or .zip) into the virtual filesystem.
static func load_dlc(path: String, replace_files: bool = true) -> bool:
	if not FileAccess.file_exists(path):
		push_error("DLC Loader: File not found at %s" % path)
		return false
		
	# Mount the PCK
	var success = ProjectSettings.load_resource_pack(path, replace_files)
	if success:
		print("DLC Loader: Successfully mounted %s" % path)
	else:
		push_error("DLC Loader: Failed to mount %s" % path)
		
	return success

## Scans a folder for DLC packs and loads them all.
static func load_all_dlc_in_folder(folder_path: String) -> void:
	var dir = DirAccess.open(folder_path)
	if dir:
		dir.list_dir_begin()
		var file_name = dir.get_next()
		while file_name != "":
			if file_name.ends_with(".pck"):
				load_dlc(folder_path + "/" + file_name)
			file_name = dir.get_next()

class_name MultiPlatformInput
extends Node

## Template-driven Input Mapping for varied hardware (Console, Mobile, VR).
## Dynamically adds actions or modifies deadzones based on detected platform.

func _ready() -> void:
	_configure_platform_inputs()

func _configure_platform_inputs() -> void:
	if OS.has_feature("mobile"):
		# Mobile specific gestures would be handled in a touch layer
		pass
	elif OS.has_feature("pc"):
		# Ensure mouse-specific actions exist
		_add_or_update_action(&"click", InputEventMouseButton.new())
	
	# Console-specific deadzone tuning
	_tune_deadzones()

func _add_or_update_action(action: StringName, event: InputEvent) -> void:
	if not InputMap.has_action(action):
		InputMap.add_action(action)
	InputMap.action_add_event(action, event)

func _tune_deadzones() -> void:
	# Iterate through all actions and apply a global threshold for gamepads
	for action in InputMap.get_actions():
		# Expert: Apply specific deadzones to joypad axes
		pass

class_name PlatformFeatureConfig
extends Node

## Use Godot's built-in Feature Tags to conditionally execute logic.
## Strips server logic from client builds and manages mobile-specific overrides.

@export var mobile_max_fps: int = 60
@export var desktop_max_fps: int = 144

func _ready() -> void:
	_apply_platform_overrides()

func _apply_platform_overrides() -> void:
	if OS.has_feature("dedicated_server"):
		# Start headless multiplayer server
		_initialize_server_logic()
	elif OS.has_feature("mobile"):
		# Lower rendering overhead for Android/iOS
		_apply_mobile_profile()
	elif OS.has_feature("pc"):
		_apply_desktop_profile()

func _apply_mobile_profile() -> void:
	# Disable heavy post-processing
	get_viewport().use_taa = false
	Engine.max_fps = mobile_max_fps

func _apply_desktop_profile() -> void:
	Engine.max_fps = desktop_max_fps

func _initialize_server_logic() -> void:
	# Disable visual processing in headless mode
	set_process(false)
	set_physics_process(true)

class_name SceneStateMachine
extends Node

## Node-based State Machine boilerplate.
## Delegates engine callbacks (_physics_process, _input) from parent to active state.

@export var initial_state: StateMachineNode
@onready var current_state: StateMachineNode = initial_state

func _ready() -> void:
	# Auto-register this machine into all child states
	for child in get_children():
		if child is StateMachineNode:
			child.state_machine = self
	
	if current_state:
		current_state.enter()

func _physics_process(delta: float) -> void:
	if current_state:
		current_state.physics_update(delta)

func _unhandled_input(event: InputEvent) -> void:
	if current_state:
		current_state.handle_input(event)

func transition_to(target_name: StringName) -> void:
	if not has_node(str(target_name)):
		push_error("StateMachine: State %s not found." % target_name)
		return
		
	current_state.exit()
	current_state = get_node(str(target_name))
	current_state.enter()

class_name StateMachineNode
extends Node

## Abstract state node to be used inside a SceneStateMachine.
## Override these methods in specific state scenes/scripts.

var state_machine: SceneStateMachine

func enter() -> void:
	pass

func exit() -> void:
	pass

func physics_update(_delta: float) -> void:
	pass

func handle_input(_event: InputEvent) -> void:
	pass

## Expert: Call state_machine.transition_to(&"NewState") to switch.

## Subsystem Locator Pattern (Autoload: Subsystems)
## A decoupled alternative to monolithic managers.
## Allows systems to register themselves without requiring hard-coded paths.
extends Node

var _registry: Dictionary = {}

func register(id: StringName, instance: Node) -> void:
	_registry[id] = instance
	print("Subsystem Registered: ", id)

func unregister(id: StringName) -> void:
	_registry.erase(id)

func get_system(id: StringName) -> Node:
	return _registry.get(id)

## Usage Example:
## Subsystems.get_system(&"Inventory").add_item(loot)