364 lines
12 KiB
GDScript
364 lines
12 KiB
GDScript
## AvatarSystem - Global avatar orchestrator (autoload singleton).
|
|
##
|
|
## Owns the AvatarCatalog, AvatarLoader, and the current player's AvatarLoadout.
|
|
## Provides a single entry point for the rest of the game to:
|
|
## - Load the asset catalog.
|
|
## - Load a player's avatar from a loadout.
|
|
## - Equip / unequip items and persist the resulting loadout.
|
|
##
|
|
## Registered as an autoload singleton named "AvatarSystem" in project.godot.
|
|
|
|
extends Node
|
|
|
|
# Sibling avatar scripts are referenced via preload rather than by their global
|
|
# class_name so this autoload parses correctly from a bare clone -- a headless
|
|
# `godot <scene>` run does not rebuild the global class registry (only an editor
|
|
# scan / `--import` does), and this script is parsed at startup before any such
|
|
# scan could have happened. See docs/architecture/avatar.md.
|
|
const AvatarCatalog := preload("res://scripts/avatar/avatar_catalog.gd")
|
|
const AvatarLoader := preload("res://scripts/avatar/avatar_loader.gd")
|
|
const AvatarLoadout := preload("res://scripts/avatar/avatar_loadout.gd")
|
|
const AvatarSlotRegistry := preload("res://scripts/avatar/avatar_slot_registry.gd")
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Signals
|
|
# ---------------------------------------------------------------------------
|
|
|
|
## Emitted when the catalog has finished loading.
|
|
signal catalog_loaded
|
|
|
|
## Emitted when the catalog fails to load.
|
|
signal catalog_load_failed(error_message: String)
|
|
|
|
## Emitted when the avatar has been fully assembled and is ready to render.
|
|
signal avatar_ready(avatar_node: Node3D)
|
|
|
|
## Emitted when the loadout changes (after equip/unequip).
|
|
signal loadout_changed(loadout: AvatarLoadout)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# State
|
|
# ---------------------------------------------------------------------------
|
|
|
|
## The asset catalog (id -> metadata + path).
|
|
var catalog: AvatarCatalog = null
|
|
|
|
## The loader used to import GLB assets and assemble the avatar.
|
|
var loader: AvatarLoader = null
|
|
|
|
## The current player's loadout.
|
|
var current_loadout: AvatarLoadout = null
|
|
|
|
## The assembled avatar node (null until avatar_ready).
|
|
var avatar_node: Node3D = null
|
|
|
|
## Whether the catalog has been loaded.
|
|
var is_catalog_loaded: bool = false
|
|
|
|
## Whether an avatar is currently assembled.
|
|
var is_avatar_ready: bool = false
|
|
|
|
## Default catalog path.
|
|
const DEFAULT_CATALOG_PATH := "res://assets/avatars/catalog.json"
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Lifecycle
|
|
# ---------------------------------------------------------------------------
|
|
|
|
func _ready() -> void:
|
|
catalog = AvatarCatalog.new()
|
|
loader = AvatarLoader.new()
|
|
loader.init_loader(catalog)
|
|
add_child(loader)
|
|
|
|
|
|
## Load the asset catalog. Call this once at startup (or on demand).
|
|
func load_catalog(path: String = DEFAULT_CATALOG_PATH) -> Error:
|
|
var err := catalog.load_catalog(path)
|
|
if err == OK:
|
|
is_catalog_loaded = true
|
|
catalog_loaded.emit()
|
|
else:
|
|
catalog_load_failed.emit("Failed to load catalog: %s" % err)
|
|
return err
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Avatar assembly
|
|
# ---------------------------------------------------------------------------
|
|
|
|
## Load and assemble an avatar from a loadout.
|
|
## Returns the assembled avatar Node3D on success, or null on failure.
|
|
func load_avatar(loadout: AvatarLoadout) -> Node3D:
|
|
if not is_catalog_loaded:
|
|
push_error("AvatarSystem: catalog not loaded; call load_catalog() first")
|
|
return null
|
|
|
|
if loadout == null:
|
|
push_error("AvatarSystem: loadout is null")
|
|
return null
|
|
|
|
# Validate the loadout against the catalog.
|
|
var validation := catalog.validate_loadout(loadout)
|
|
if not validation.valid:
|
|
push_error("AvatarSystem: invalid loadout: %s" % str(validation.errors))
|
|
return null
|
|
|
|
current_loadout = loadout
|
|
|
|
# Reset any previous avatar.
|
|
loader.reset()
|
|
|
|
# Load the base body.
|
|
var base_body_id := loadout.base_body
|
|
var base_node := loader.load_base_body(base_body_id)
|
|
if base_node == null:
|
|
push_error("AvatarSystem: failed to load base body '%s'" % base_body_id)
|
|
return null
|
|
|
|
# Load each equipped attachment.
|
|
for slot_id in AvatarSlotRegistry.SLOT_IDS:
|
|
var slot_value = loadout.slots.get(slot_id)
|
|
|
|
if slot_id == "accessory":
|
|
# Accessory is an array of asset ids.
|
|
if slot_value is Array:
|
|
for asset_id in slot_value:
|
|
if asset_id is String and not (asset_id as String).is_empty():
|
|
loader.load_attachment(slot_id, asset_id)
|
|
else:
|
|
# Exclusive slot: single asset id or null.
|
|
if slot_value is String and not (slot_value as String).is_empty():
|
|
loader.load_attachment(slot_id, slot_value)
|
|
|
|
# Hide base meshes for equipped body-part slots.
|
|
for slot_id in AvatarSlotRegistry.BODY_PART_SLOTS:
|
|
var slot_value = loadout.slots.get(slot_id)
|
|
if slot_value is String and not (slot_value as String).is_empty():
|
|
loader.set_base_mesh_visible(slot_id, false)
|
|
|
|
avatar_node = loader.avatar_node
|
|
is_avatar_ready = avatar_node != null
|
|
if is_avatar_ready:
|
|
avatar_ready.emit(avatar_node)
|
|
|
|
return avatar_node
|
|
|
|
|
|
## Equip an item into a slot and rebuild the avatar.
|
|
## Returns true on success.
|
|
func equip(slot_id: String, asset_id: String) -> bool:
|
|
if current_loadout == null:
|
|
push_error("AvatarSystem: no loadout loaded")
|
|
return false
|
|
|
|
if not AvatarSlotRegistry.has_slot(slot_id):
|
|
push_error("AvatarSystem: unknown slot '%s'" % slot_id)
|
|
return false
|
|
|
|
if not catalog.has_asset(asset_id):
|
|
push_error("AvatarSystem: unknown asset '%s'" % asset_id)
|
|
return false
|
|
|
|
var asset := catalog.resolve(asset_id)
|
|
if asset.get("slot") != slot_id:
|
|
push_error("AvatarSystem: asset '%s' is for slot '%s', not '%s'" % [
|
|
asset_id, asset.get("slot"), slot_id])
|
|
return false
|
|
|
|
if slot_id == "accessory":
|
|
if not current_loadout.add_accessory(asset_id):
|
|
push_error("AvatarSystem: could not add accessory '%s'" % asset_id)
|
|
return false
|
|
else:
|
|
current_loadout.set_equipment(slot_id, asset_id)
|
|
|
|
loadout_changed.emit(current_loadout)
|
|
return true
|
|
|
|
|
|
## Unequip an item from a slot and rebuild the avatar.
|
|
## Returns true on success.
|
|
func unequip(slot_id: String, asset_id: String = "") -> bool:
|
|
if current_loadout == null:
|
|
push_error("AvatarSystem: no loadout loaded")
|
|
return false
|
|
|
|
if not AvatarSlotRegistry.has_slot(slot_id):
|
|
push_error("AvatarSystem: unknown slot '%s'" % slot_id)
|
|
return false
|
|
|
|
if slot_id == "accessory":
|
|
if asset_id.is_empty():
|
|
push_error("AvatarSystem: accessory unequip requires an asset id")
|
|
return false
|
|
if not current_loadout.remove_accessory(asset_id):
|
|
push_error("AvatarSystem: accessory '%s' not equipped" % asset_id)
|
|
return false
|
|
else:
|
|
current_loadout.set_equipment(slot_id, "")
|
|
|
|
loadout_changed.emit(current_loadout)
|
|
return true
|
|
|
|
|
|
## Serialize the current loadout to JSON.
|
|
func save_loadout() -> String:
|
|
if current_loadout == null:
|
|
return ""
|
|
return current_loadout.to_json()
|
|
|
|
|
|
## Load a loadout from a JSON string.
|
|
func load_loadout_from_json(json_string: String) -> AvatarLoadout:
|
|
var loadout := AvatarLoadout.from_json(json_string)
|
|
if not loadout.validate():
|
|
push_error("AvatarSystem: invalid loadout JSON: %s" % str(loadout.validation_errors))
|
|
return null
|
|
return loadout
|
|
|
|
|
|
## Get the list of available assets for a given slot.
|
|
func get_assets_for_slot(slot_id: String) -> Array[String]:
|
|
return catalog.get_assets_by_slot(slot_id)
|
|
|
|
|
|
## Get the display name for an asset id.
|
|
func get_asset_display_name(asset_id: String) -> String:
|
|
var asset := catalog.resolve(asset_id)
|
|
return asset.get("display_name", asset_id)
|
|
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Local-player convenience API
|
|
#
|
|
# The rest of the game (the main menu, the in-world player) only needs three
|
|
# things: load the catalog once, hand us the player's loadout (as the dict the
|
|
# backend returns), and ask for an assembled avatar node to drop into a scene.
|
|
# ---------------------------------------------------------------------------
|
|
|
|
## True once a loadout has been handed to us (from the backend or a default).
|
|
func has_loadout() -> bool:
|
|
return current_loadout != null
|
|
|
|
|
|
## Ensure the catalog is loaded (idempotent). Safe to await repeatedly.
|
|
func ensure_catalog() -> bool:
|
|
if is_catalog_loaded:
|
|
return true
|
|
var ok := load_catalog() == OK
|
|
if ok and current_loadout == null:
|
|
_try_load_cached_loadout()
|
|
return ok
|
|
|
|
|
|
func _try_load_cached_loadout() -> void:
|
|
if FileAccess.file_exists("user://loadout.json"):
|
|
var f := FileAccess.open("user://loadout.json", FileAccess.READ)
|
|
if f != null:
|
|
var txt := f.get_as_text()
|
|
f.close()
|
|
var dict: Variant = JSON.parse_string(txt)
|
|
if dict is Dictionary:
|
|
set_loadout_from_dict(dict as Dictionary)
|
|
|
|
|
|
## Return the current loadout as a dictionary. If none is set, returns a default
|
|
## loadout using the first available base body, or {} if catalog is empty.
|
|
func get_current_loadout_dict() -> Dictionary:
|
|
if current_loadout != null:
|
|
return current_loadout.to_dict()
|
|
ensure_catalog()
|
|
if current_loadout != null:
|
|
return current_loadout.to_dict()
|
|
var bases := get_assets_for_slot("base_body")
|
|
if not bases.is_empty():
|
|
return {"base_body": bases[0], "slots": {}}
|
|
return {}
|
|
|
|
|
|
## Set the current player's loadout from the dict shape the backend's
|
|
## GET /api/avatar/loadout returns (i.e. AvatarLoadout.to_json() parsed).
|
|
## Returns true if it validated and was stored.
|
|
func set_loadout_from_dict(loadout_dict: Dictionary) -> bool:
|
|
var lo := AvatarLoadout.from_dict(loadout_dict)
|
|
if not lo.validate():
|
|
push_warning("AvatarSystem: rejecting invalid loadout dict: %s"
|
|
% str(lo.validation_errors))
|
|
return false
|
|
current_loadout = lo
|
|
loadout_changed.emit(current_loadout)
|
|
return true
|
|
|
|
|
|
## Assemble a fresh avatar Node3D from the current loadout, ready to parent
|
|
## into a scene (e.g. onto the in-world player). Returns null if there's no
|
|
## loadout or the catalog isn't loaded or assembly failed.
|
|
func build_current_avatar() -> Node3D:
|
|
# Self-sufficient: load the catalog if needed, and fall back to a bare
|
|
# default loadout when login didn't prime one -- the player should always
|
|
# get *an* avatar, never a placeholder capsule, as long as the assets exist.
|
|
if not ensure_catalog():
|
|
push_warning("AvatarSystem: catalog unavailable; cannot build avatar")
|
|
return null
|
|
if current_loadout == null:
|
|
var bases := get_assets_for_slot("base_body")
|
|
if bases.is_empty():
|
|
return null
|
|
set_loadout_from_dict({"base_body": bases[0], "slots": {}})
|
|
return assemble_avatar(current_loadout)
|
|
|
|
|
|
## Assemble a standalone avatar node from [param loadout] using a throwaway
|
|
## loader -- unlike load_avatar(), this touches no shared state, so it's safe
|
|
## to call many times (local player + one per remote peer). Returns null only
|
|
## if the assets are genuinely missing. Accepts either AvatarLoadout or Dictionary.
|
|
func assemble_avatar(loadout) -> Node3D:
|
|
if loadout == null:
|
|
return null
|
|
if not ensure_catalog():
|
|
return null
|
|
|
|
var lo: AvatarLoadout = null
|
|
if loadout is AvatarLoadout:
|
|
lo = loadout
|
|
elif loadout is Dictionary:
|
|
lo = AvatarLoadout.from_dict(loadout as Dictionary)
|
|
else:
|
|
return null
|
|
|
|
var validation := catalog.validate_loadout(lo)
|
|
if not validation.valid:
|
|
push_warning("AvatarSystem: invalid loadout, skipping: %s" % str(validation.errors))
|
|
return null
|
|
|
|
var l = AvatarLoader.new()
|
|
l.init_loader(catalog)
|
|
var base := l.load_base_body(lo.base_body)
|
|
if base == null:
|
|
l.free()
|
|
return null
|
|
|
|
for slot_id in AvatarSlotRegistry.SLOT_IDS:
|
|
var v = lo.slots.get(slot_id)
|
|
if slot_id == "accessory":
|
|
if v is Array:
|
|
for aid in v:
|
|
if aid is String and not (aid as String).is_empty():
|
|
l.load_attachment(slot_id, aid)
|
|
elif v is String and not (v as String).is_empty():
|
|
l.load_attachment(slot_id, v)
|
|
|
|
for slot_id in AvatarSlotRegistry.BODY_PART_SLOTS:
|
|
var v = lo.slots.get(slot_id)
|
|
if v is String and not (v as String).is_empty():
|
|
l.set_base_mesh_visible(slot_id, false)
|
|
|
|
l.apply_skin_tone(lo.skin_tone)
|
|
|
|
l.free()
|
|
return base
|