extends Node ## Local card-definition cache. ## ## Syncs all published card definitions from the server using the ## content.sync message (cursor-based, incremental). Definitions are text ## only (stats, CDN URLs for art/models) — no binary assets are stored here. ## ## Also caches tile model bindings fetched via content.tile_models. ## ## Storage layout: ## user://content/defs.json — { "version": int, "defs": { id: dto } } ## user://content/tile_models.json — { "Forest_Square": "https://...", ... } ## ## Usage: ## ContentCache.start_sync() ## ContentCache.get_definition("some-guid") → Dictionary or {} ## ContentCache.get_tile_model_url("Forest", "Square") → String or "" ## ContentCache.sync_complete.connect(...) const CACHE_DIR := "user://content" const CACHE_PATH := "user://content/defs.json" const TILE_MODELS_PATH := "user://content/tile_models.json" const TILE_BOTTOMS_PATH := "user://content/tile_bottoms.json" const PAGE_SIZE := 200 const REFRESH_INTERVAL_SECS := 300.0 # re-sync every 5 minutes during live play signal sync_progress(fetched_total: int) ## Running count of total definitions in memory. signal sync_complete(total: int) ## Emitted once sync finishes. signal sync_failed(error: String) ## Emitted if sync cannot complete. signal tile_models_ready ## Emitted when tile model bindings are loaded. var _defs: Dictionary = {} ## definitionId (String) → definition Dictionary var _sync_version: int = 0 ## Stored DefinitionVersion cursor. var _is_syncing: bool = false ## "Affinity_Shape" (e.g. "Forest_Square") → CDN model URL string var _tile_models: Dictionary = {} ## Array of CDN URL strings for tile bottom (stalagmite) models. var _tile_bottom_urls: Array = [] # ── Lifecycle ───────────────────────────────────────────────────────────────── func _ready() -> void: _load_from_disk() _load_tile_models_from_disk() _load_tile_bottoms_from_disk() # ── Public API ──────────────────────────────────────────────────────────────── ## Return the cached definition dictionary, or {} if not found. func get_definition(id: String) -> Dictionary: return _defs.get(id, {}) ## True if the definition is cached. func has_definition(id: String) -> bool: return _defs.has(id) ## Returns all cached definition IDs. func get_all_definition_ids() -> Array: return _defs.keys() ## The current sync-version cursor (0 = never synced). func get_sync_version() -> int: return _sync_version ## Total number of definitions currently in memory. func definition_count() -> int: return _defs.size() ## True while a sync is in progress. func is_syncing() -> bool: return _is_syncing ## Start (or resume) the incremental sync. ## Emits sync_progress during, sync_complete or sync_failed when done. ## Also triggers a fresh fetch of tile model bindings and bottom models. func start_sync() -> void: if _is_syncing: return _is_syncing = true _fetch_page(_sync_version) fetch_tile_models() fetch_tile_bottoms() ## Return the GLB animation track name for a card action. ## ## Looks for an animationBinding with the given action_name (case-insensitive). ## If found and the binding has a non-empty animationTrackName, returns that. ## Otherwise returns the action_name itself so the caller can do its own ## case-insensitive fuzzy match against the AnimationPlayer's track list. ## ## card_def_id: card definition GUID string ## action_name: e.g. "attack", "idle", "death", "move" func get_anim_track(card_def_id: String, action_name: String) -> String: var def := get_definition(card_def_id) var action_lower := action_name.to_lower() for binding: Dictionary in def.get("animationBindings", []): if str(binding.get("actionName", "")).to_lower() == action_lower: var track := str(binding.get("animationTrackName", "")) return track if not track.is_empty() else action_name return action_name ## Return the CDN URL for a tile's 3D model, or "" if not assigned. ## affinity: e.g. "Forest" shape: "Square" or "Hex" func get_tile_model_url(affinity: String, shape: String) -> String: return _tile_models.get(affinity + "_" + shape, "") ## Returns a random active tile bottom (stalagmite) CDN URL, or "" if none configured. func get_random_tile_bottom_url() -> String: if _tile_bottom_urls.is_empty(): return "" return _tile_bottom_urls[randi() % _tile_bottom_urls.size()] as String ## Fetch tile bottom model URLs from the server and update the local cache. func fetch_tile_bottoms() -> void: Network.request( "content.tile_bottoms", {}, func(_type: String, p: Variant): _on_tile_bottoms(p), func(code: String, msg: String): push_warning("ContentCache: tile_bottoms fetch failed — %s %s" % [code, msg]) ) ## Fetch tile model bindings from the server and update the local cache. ## Emits tile_models_ready when done (even on error, using cached data). func fetch_tile_models() -> void: Network.request( "content.tile_models", {}, func(_type: String, p: Variant): _on_tile_models(p), func(code: String, msg: String): push_warning("ContentCache: tile_models fetch failed — %s %s" % [code, msg]) tile_models_ready.emit() ) # ── Sync loop ───────────────────────────────────────────────────────────────── func _fetch_page(since_version: int) -> void: Network.request( "content.sync", { "sinceVersion": since_version, "pageSize": PAGE_SIZE }, func(_type: String, p: Variant): _on_page(p), func(code: String, msg: String): _on_error(code, msg) ) func _on_page(payload: Variant) -> void: var p := payload as Dictionary var cards : Array = p.get("cards", []) var next_ver : int = p.get("currentVersion", _sync_version) var has_more : bool = p.get("hasMore", false) for card in cards: var id: String = str(card.get("id", "")) if not id.is_empty(): _defs[id] = card _sync_version = next_ver sync_progress.emit(_defs.size()) if has_more: _fetch_page(next_ver) else: _is_syncing = false _save_to_disk() sync_complete.emit(_defs.size()) # Schedule next background refresh so live content patches are picked up # without restarting the client. get_tree().create_timer(REFRESH_INTERVAL_SECS).timeout.connect( func() -> void: start_sync(), CONNECT_ONE_SHOT) func _on_error(code: String, msg: String) -> void: _is_syncing = false var detail := msg if not msg.is_empty() else code push_warning("ContentCache: sync failed — %s" % detail) sync_failed.emit(detail) func _on_tile_models(payload: Variant) -> void: var p := payload as Dictionary var bindings : Array = p.get("bindings", []) _tile_models.clear() for item in bindings: var d := item as Dictionary if d == null: continue var key := str(d.get("affinity", "")) + "_" + str(d.get("shape", "")) var url := str(d.get("modelPublicUrl", "")) if not key.is_empty() and not url.is_empty(): _tile_models[key] = url _save_tile_models_to_disk() tile_models_ready.emit() func _on_tile_bottoms(payload: Variant) -> void: var p := payload as Dictionary var urls : Array = p.get("urls", []) _tile_bottom_urls.clear() for u in urls: if typeof(u) == TYPE_STRING and not (u as String).is_empty(): _tile_bottom_urls.append(u as String) _save_tile_bottoms_to_disk() # ── Persistence ─────────────────────────────────────────────────────────────── func _load_from_disk() -> void: if not FileAccess.file_exists(CACHE_PATH): return var file := FileAccess.open(CACHE_PATH, FileAccess.READ) if not file: push_warning("ContentCache: could not open cache file") return var text := file.get_as_text() file.close() var parsed: Variant = JSON.parse_string(text) if typeof(parsed) != TYPE_DICTIONARY: push_warning("ContentCache: cache file is malformed — starting fresh") return var root := parsed as Dictionary _sync_version = int(root.get("version", 0)) var defs: Variant = root.get("defs", {}) if typeof(defs) == TYPE_DICTIONARY: _defs = defs as Dictionary func _save_to_disk() -> void: DirAccess.make_dir_recursive_absolute(CACHE_DIR) var file := FileAccess.open(CACHE_PATH, FileAccess.WRITE) if not file: push_warning("ContentCache: could not write cache file") return file.store_string(JSON.stringify({ "version": _sync_version, "defs": _defs })) file.close() func _load_tile_models_from_disk() -> void: if not FileAccess.file_exists(TILE_MODELS_PATH): return var file := FileAccess.open(TILE_MODELS_PATH, FileAccess.READ) if not file: return var parsed: Variant = JSON.parse_string(file.get_as_text()) file.close() if typeof(parsed) == TYPE_DICTIONARY: _tile_models = parsed as Dictionary func _save_tile_models_to_disk() -> void: DirAccess.make_dir_recursive_absolute(CACHE_DIR) var file := FileAccess.open(TILE_MODELS_PATH, FileAccess.WRITE) if not file: return file.store_string(JSON.stringify(_tile_models)) file.close() func _load_tile_bottoms_from_disk() -> void: if not FileAccess.file_exists(TILE_BOTTOMS_PATH): return var file := FileAccess.open(TILE_BOTTOMS_PATH, FileAccess.READ) if not file: return var parsed: Variant = JSON.parse_string(file.get_as_text()) file.close() if typeof(parsed) == TYPE_ARRAY: _tile_bottom_urls = parsed as Array func _save_tile_bottoms_to_disk() -> void: DirAccess.make_dir_recursive_absolute(CACHE_DIR) var file := FileAccess.open(TILE_BOTTOMS_PATH, FileAccess.WRITE) if not file: return file.store_string(JSON.stringify(_tile_bottom_urls)) file.close()