diff --git a/Architecture-Client.md b/Architecture-Client.md index 8f794bb..f5d5e05 100644 --- a/Architecture-Client.md +++ b/Architecture-Client.md @@ -1,93 +1,26 @@ - # Tekton Armageddon - Client Architecture (Full Function Reference) [Back to Home](./Home) Complete per-function reference for the Godot 4.7 client codebase. Every script, signal, autoload dependency, and cross-file relationship documented. -[Back to top](#top) ## Table of Contents -[Back to top](#top) - -1. [Project Structure Overview](#1-project-structure-overview) -2. [Autoloads / Singletons Index](#2-autoloads--singletons-index) -3. [Service Layer](#3-service-layer) - - [3.1 NakamaManager](#31-nakamamanaager) - - [3.2 BackendService](#32-backendservice) - - [3.3 SteamworksManager](#33-steamworksmanager) -4. [Core Managers](#4-core-managers) - - [4.1 AuthManager](#41-authmanager) - - [4.2 LobbyManager](#42-lobbymanager) - - [4.3 GameStateManager](#43-gamestatemanager) - - [4.4 PlayerManager](#44-playermanager) - - [4.5 EventBus](#45-eventbus) - - [4.6 GameMode / ModeConfig](#46-gamemode--modeconfig) -5. [Player Subsystem Managers](#5-player-subsystem-managers) - - [5.1 PlayerMovementManager](#51-playermovementmanager) - - [5.2 PlayerInputManager](#52-playerinputmanager) - - [5.3 PlayerActionManager](#53-playeractionmanager) - - [5.4 PlayerboardManager](#54-playerboardmanager) - - [5.5 PowerupManager](#55-powerupmanager) -6. [Game Mode Managers](#6-game-mode-managers) - - [6.1 StopNGoManager](#61-stopngomanager) - - [6.2 GauntletManager](#62-gauntletmanager) - - [6.3 PortalModeManager](#63-portalmode_manager) - - [6.4 GoalManager](#64-goalmanager) - - [6.5 GoalsCycleManager](#65-goalscyclemanager) - - [6.6 PlayerRaceManager](#66-playerracemanager) - - [6.7 TurnManager](#67-turnmanager) -7. [Gameplay Managers](#7-gameplay-managers) - - [7.1 ObstacleManager](#71-obstaclemanager) - - [7.2 SpecialTilesManager](#72-specialtilesmanager) - - [7.3 StaticTektonManager](#73-statictektonmanager) -8. [UI / Presentation Managers](#8-ui--presentation-managers) - - [8.1 UIManager](#81-uimanager) - - [8.2 SfxManager](#82-sfxmanager) - - [8.3 MusicManager](#83-musicmanager) - - [8.4 NotificationManager](#84-notificationmanager) - - [8.5 ScreenShake](#85-screenshake) - - [8.6 CameraContextManager](#86-cameracontextmanager) - - [8.7 TouchControls](#87-touchcontrols) - - [8.8 TutorialManager / TutorialOverlay](#88-tutorialmanager--tutorialoverlay) -9. [Social / Economy Managers](#9-social--economy-managers) - - [9.1 UserProfileManager](#91-userprofilemanager) - - [9.2 GachaManager](#92-gachamanager) - - [9.3 SkinManager](#93-skinmanager) - - [9.4 ShopManager](#94-shopmanager) - - [9.5 JoinManager](#95-joinmanager) - - [9.6 FriendManager](#96-friendmanager) - - [9.7 MailManager](#97-mailmanager) - - [9.8 DailyRewardManager](#98-dailyrewardmanager) - - [9.9 AdminManager](#99-adminmanager) -10. [System Managers](#10-system-managers) - - [10.1 SettingsManager](#101-settingsmanager) - - [10.2 SessionManager](#102-sessionmanager) - - [10.3 GameUpdateManager](#103-gameupdatemanager) -11. [Core Scene Scripts](#11-core-scene-scripts) - - [11.1 main.gd (Main game scene controller)](#111-maingd-main-game-scene-controller) - - [11.2 player.gd](#112-playergd) - - [11.3 lobby.gd](#113-lobbygd) - - [11.4 animation.gd](#114-animationgd) -12. [UI Helper Classes (RefCounted)](#12-ui-helper-classes-refcounted) - - [12.1 LobbyMainMenu](#121-lobbymainmenu) - - [12.2 LobbyRoom](#122-lobbyroom) - - [12.3 LobbyRoomList](#123-lobbyroomlist) - - [12.4 LobbyChat](#124-lobbychat) -13. [Dependency Graph](#13-dependency-graph) - - [13.1 Manager Autoload Dependencies](#131-manager-autoload-dependencies) - - [13.2 Cross-Manager Signal Wiring](#132-cross-manager-signal-wiring) -14. [Scene Node Trees](#14-scene-node-trees) - - [14.1 main.tscn](#141-maintscn) - - [14.2 player.tscn](#142-playertscn) - - [14.3 lobby.tscn](#143-lobbytscn) - -[Back to top](#top) - - - -## Table of Contents +- [1. Project Structure Overview](#1-project-structure-overview) +- [2. Autoloads / Singletons Index](#2-autoloads-singletons-index) +- [3. Service Layer](#3-service-layer) +- [4. Core Managers](#4-core-managers) +- [5. Player Subsystem Managers](#5-player-subsystem-managers) +- [6. Game Mode Managers](#6-game-mode-managers) +- [7. Gameplay Managers](#7-gameplay-managers) +- [8. UI / Presentation Managers](#8-ui-presentation-managers) +- [9. Social / Economy Managers](#9-social-economy-managers) +- [10. System Managers](#10-system-managers) +- [11. Core Scene Scripts](#11-core-scene-scripts) +- [12. UI Helper Classes (RefCounted)](#12-ui-helper-classes-(refcounted)) +- [13. Dependency Graph](#13-dependency-graph) +- [14. Scene Node Trees](#14-scene-node-trees) [Back to top](#top) @@ -95,6 +28,7 @@ Complete per-function reference for the Godot 4.7 client codebase. Every script, [Back to top](#top) + ``` /home/dev/tekton/ project.godot -- Godot 4.7 project file @@ -180,13 +114,12 @@ Complete per-function reference for the Godot 4.7 client codebase. Every script, loading_screen.tscn -- Level loading screen ``` -[Back to top](#top) - ## 2. Autoloads / Singletons Index [Back to top](#top) + All managers are registered as autoloads in project.godot and accessible globally via `/root/`. The following are the configured autoloads: | Autoload Name | File | Purpose | @@ -235,16 +168,14 @@ All managers are registered as autoloads in project.godot and accessible globall | TouchControls | res://scripts/managers/touch_controls.gd | Mobile touch input overlay | | DailyRewardManager | res://scripts/managers/daily_reward_manager.gd | Daily reward claims | -[Back to top](#top) - ## 3. Service Layer [Back to top](#top) + ### 3.1 NakamaManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/nakama_manager.gd` (330 lines) **Extends:** Node @@ -292,11 +223,9 @@ Central Nakama SDK integration. Manages the Nakama client, session, socket, and **Dependencies:** Nakama GDExtension (NakamaClient, NakamaSocket, NakamaMultiplayerBridge). **Depended by:** AuthManager, BackendService, LobbyManager, LobbyRoom, LobbyChat, LobbyMainMenu, main.gd. -[Back to top](#top) ### 3.2 BackendService -[Back to top](#top) **File:** `/home/dev/tekton/scripts/services/backend_service.gd` (247 lines) **Extends:** Node @@ -361,11 +290,9 @@ Unified typed interface for all Nakama Lua RPCs. All platform authentication pat **Dependencies:** NakamaManager (autoload), SteamworksManager (child node). **Depended by:** AuthManager, LobbyManager, LobbyChat, lobby.gd (admin), FriendManager, MailManager, GachaManager, DailyRewardManager, AdminManager, SkinManager. -[Back to top](#top) ### 3.3 SteamworksManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/services/steamworks_manager.gd` (72 lines) **Extends:** Node @@ -395,16 +322,14 @@ NOT an autoload. Created as a child of BackendService. Provides Steam auth sessi **Dependencies:** GodotSteam GDExtension (ClassDB.class_exists("Steam")). **Depended by:** BackendService, AuthManager. -[Back to top](#top) - ## 4. Core Managers [Back to top](#top) + ### 4.1 AuthManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/auth_manager.gd` (515 lines) **Extends:** Node @@ -456,11 +381,9 @@ Centralized authentication handler. Supports Guest (device ID), Email/Password, **Dependencies:** NakamaManager, BackendService. **Depended by:** LobbyMainMenu, lobby.gd, UserProfileManager, login_screen.tscn. -[Back to top](#top) ### 4.2 LobbyManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/lobby_manager.gd` (1023 lines) **Extends:** Node @@ -566,11 +489,9 @@ Room/lobby lifecycle manager. Handles both Nakama (online) and LAN (direct ENet) **Dependencies:** NakamaManager, GameStateManager. **Depended by:** LobbyRoom, LobbyRoomList, LobbyMainMenu, main.gd, player.gd, lobby.gd, SceneManager (loading screen). -[Back to top](#top) ### 4.3 GameStateManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/game_state_manager.gd` (66 lines) **Extends:** Node @@ -604,11 +525,9 @@ Simple state machine and match configuration constants. **Dependencies:** None. **Depended by:** LobbyManager, main.gd, tutorial_manager.gd, many managers. -[Back to top](#top) ### 4.4 PlayerManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/player_manager.gd` (37 lines) **Extends:** Node @@ -630,11 +549,9 @@ Lightweight data container for player metadata. Stores display name and peer ID **Dependencies:** None. **Depended by:** UIManager, player.gd, various managers needing player identity. -[Back to top](#top) ### 4.5 EventBus -[Back to top](#top) **File:** `/home/dev/tekton/scripts/event_bus.gd` (73 lines) **Extends:** Node @@ -679,11 +596,9 @@ Centralized observer pattern for inter-manager communication. Replaces direct cr **Dependencies:** None. **Depended by:** UserProfileManager, GachaManager, ShopManager, many managers for loose coupling. -[Back to top](#top) ### 4.6 GameMode / ModeConfig -[Back to top](#top) **File:** `/home/dev/tekton/scripts/game_mode.gd` (41 lines) **Extends:** RefCounted @@ -723,16 +638,14 @@ Schema-driven validation for game mode settings. Consolidates duplicated/inconsi **Dependencies:** None (standalone utility classes). **Depended by:** LobbyManager, LobbyRoom, mode-specific managers. -[Back to top](#top) - ## 5. Player Subsystem Managers [Back to top](#top) + ### 5.1 PlayerMovementManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/player_movement_manager.gd` (33,053 chars) **Extends:** Node @@ -765,11 +678,9 @@ Handles player movement physics, grid-based pathfinding, movement range highligh **Dependencies:** player.gd (node refs), ObstacleManager, SpecialTilesManager, EnhancedGridMap. **Depended by:** player.gd, main.gd. -[Back to top](#top) ### 5.2 PlayerInputManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/player_input_manager.gd` (7,292 chars) **Extends:** Node @@ -798,11 +709,9 @@ Captures and buffers player input events. Supports keyboard, mouse, gamepad, and **Dependencies:** TouchControls (autoload). **Depended by:** player.gd, player_action_manager.gd. -[Back to top](#top) ### 5.3 PlayerActionManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/player_action_manager.gd` (8,828 chars) **Extends:** Node @@ -838,11 +747,9 @@ Action execution layer. Manages grab, put, arrange, tekton throw/knock actions. **Dependencies:** PlayerboardManager, PlayerInputManager, GoalsCycleManager. **Depended by:** player.gd, main.gd. -[Back to top](#top) ### 5.4 PlayerboardManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/playerboard_manager.gd` (22,790 chars) **Extends:** Node @@ -882,11 +789,9 @@ Manages each player's inventory board (2x5 or 3x5 grid of item slots). Handles s **Dependencies:** GoalsCycleManager, GoalManager, EnhancedGridMap (scene ref). **Depended by:** player.gd, PlayerActionManager. -[Back to top](#top) ### 5.5 PowerupManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/powerup_manager.gd` (9,417 chars) **Extends:** Node @@ -915,16 +820,14 @@ Powerup/boost system. Tracks boost charge level, special ability availability, a **Dependencies:** None. **Depended by:** player.gd (charged strike, knock), PlayerActionManager. -[Back to top](#top) - ## 6. Game Mode Managers [Back to top](#top) + ### 6.1 StopNGoManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/stop_n_go_manager.gd` (21,884 chars) **Extends:** Node @@ -957,11 +860,9 @@ State machine for the Stop n Go game mode. Alternates between GO (movement allow **Dependencies:** TurnManager, GoalManager, GoalsCycleManager, animation.gd (scene). **Depended by:** main.gd, player.gd. -[Back to top](#top) ### 6.2 GauntletManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/gauntlet_manager.gd` (5,467 chars) **Extends:** Node @@ -990,11 +891,9 @@ Manages the Candy Pump Survival / Gauntlet game mode. Handles round progression, **Dependencies:** TurnManager, EnhancedGridMap. **Depended by:** main.gd. -[Back to top](#top) ### 6.3 PortalModeManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/portal_mode_manager.gd` (20,072 chars) **Extends:** Node @@ -1024,11 +923,9 @@ Manages portal race mode (Tekton Doors variant). Tracks portal positions, door s **Dependencies:** SpecialTilesManager, EnhancedGridMap. **Depended by:** main.gd. -[Back to top](#top) ### 6.4 GoalManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/goal_manager.gd` (3,857 chars) **Extends:** Node @@ -1055,11 +952,9 @@ Goal definitions, validation rules, and completion detection. Checks if a player **Dependencies:** None. **Depended by:** GoalsCycleManager, PlayerboardManager, StopNGoManager. -[Back to top](#top) ### 6.5 GoalsCycleManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/goals_cycle_manager.gd` (20,175 chars) **Extends:** Node @@ -1090,11 +985,9 @@ Manages cycling goal rotation. Tracks per-player score, cycles active goals on t **Dependencies:** GoalManager, TurnManager, Timer (scene). **Depended by:** main.gd, PlayerActionManager, StopNGoManager. -[Back to top](#top) ### 6.6 PlayerRaceManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/player_race_manager.gd` (4,757 chars) **Extends:** Node @@ -1125,11 +1018,9 @@ Race-specific logic. Tracks player race position, finish locations, lap progress **Dependencies:** GoalsCycleManager. **Depended by:** player.gd, main.gd. -[Back to top](#top) ### 6.7 TurnManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/turn_manager.gd` (849 chars) **Extends:** Node @@ -1163,13 +1054,12 @@ Turn-based sequencing for game modes that use round-robin or ordered turns (e.g. **Dependencies:** None. **Depended by:** StopNGoManager, GauntletManager, GoalsCycleManager. -[Back to top](#top) - ## 7. Gameplay Managers [Back to top](#top) + ### 7.1 ObstacleManager [Back to top](#up) @@ -1200,11 +1090,9 @@ Obstacle placement and removal on the game grid. Handles wall tiles, blocking ti **Dependencies:** EnhancedGridMap (scene ref). **Depended by:** PlayerMovementManager, SpecialTilesManager. -[Back to top](#top) ### 7.2 SpecialTilesManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/special_tiles_manager.gd` (23,090 chars) **Extends:** Node @@ -1236,11 +1124,9 @@ Manages special floor tiles: ice (slippery), crack (breakable), portal tiles, te **Dependencies:** EnhancedGridMap, ObstacleManager, PortalModeManager. **Depended by:** PlayerMovementManager. -[Back to top](#top) ### 7.3 StaticTektonManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/static_tekton_manager.gd` (7,416 chars) **Extends:** Node @@ -1266,16 +1152,14 @@ Manages stationary Tekton turret behavior. Handles targeting, projectile spawnin **Dependencies:** EnhancedGridMap, ObstacleManager. **Depended by:** main.gd. -[Back to top](#top) - ## 8. UI / Presentation Managers [Back to top](#top) + ### 8.1 UIManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/ui_manager.gd` (21,645 chars) **Extends:** Node @@ -1308,11 +1192,9 @@ Manages the UI layer stack: show/hide panels, overlay management, HUD elements, **Dependencies:** None. **Depended by:** main.gd, lobby.gd. -[Back to top](#top) ### 8.2 SfxManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/sfx_manager.gd` (2,046 chars) **Extends:** Node @@ -1334,11 +1216,9 @@ Sound effect playback pool. Manages one-shot SFX with positional audio support. **Dependencies:** AudioStreamPlayer pool (scene). **Depended by:** player.gd, StopNGoManager, UIManager, many gameplay managers. -[Back to top](#top) ### 8.3 MusicManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/music_manager.gd` (4,082 chars) **Extends:** Node @@ -1362,11 +1242,9 @@ Background music controller. Handles crossfade between tracks, playlist sequenci **Dependencies:** AudioStreamPlayer (scene). **Depended by:** lobby.gd, main.gd. -[Back to top](#top) ### 8.4 NotificationManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/notification_manager.gd` (2,215 chars) **Extends:** Node @@ -1393,11 +1271,9 @@ On-screen message queue. Displays transient notification messages with type-base **Dependencies:** None. **Depended by:** player.gd, main.gd (unstuck feedback), StopNGoManager, many gameplay managers. -[Back to top](#top) ### 8.5 ScreenShake -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/screen_shake.gd` (1,839 chars) **Extends:** Node @@ -1417,11 +1293,9 @@ Camera screen shake effect manager. Applies noise-based displacement to Camera3D **Dependencies:** Camera3D (scene). **Depended by:** player.gd (heavy knock triggers shake), main.gd. -[Back to top](#top) ### 8.6 CameraContextManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/camera_context_manager.gd` (2,543 chars) **Extends:** Node @@ -1447,11 +1321,9 @@ Camera zoom level and context switching. Manages follow-camera behavior, zoom le **Dependencies:** Camera3D (scene). **Depended by:** main.gd. -[Back to top](#top) ### 8.7 TouchControls -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/touch_controls.gd` (23,640 chars) **Extends:** Node @@ -1477,11 +1349,9 @@ Mobile touch input overlay. Provides virtual joystick, action buttons, and gestu **Dependencies:** InputManager (scene). **Depended by:** PlayerInputManager. -[Back to top](#top) ### 8.8 TutorialManager / TutorialOverlay -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/tutorial_manager.gd` (22,243 chars) **Extends:** Node @@ -1532,16 +1402,14 @@ Tutorial UI overlay. Displays step instructions, highlights UI elements, and pro **Dependencies:** TutorialManager, UIManager. **Depended by:** TutorialManager. -[Back to top](#top) - ## 9. Social / Economy Managers [Back to top](#top) + ### 9.1 UserProfileManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/user_profile_manager.gd` (20,044 chars) **Extends:** Node @@ -1579,11 +1447,9 @@ User profile CRUD operations. Manages display name, avatar, bio, wallet balance, **Dependencies:** NakamaManager, EventBus, BackendService. **Depended by:** LobbyMainMenu, lobby.gd, ShopManager, GachaManager, SkinManager, many UI panels. -[Back to top](#top) ### 9.2 GachaManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/gacha_manager.gd` (5,117 chars) **Extends:** Node @@ -1608,11 +1474,9 @@ Gacha pull orchestration. Calls BackendService.perform_gacha_pull, processes res **Dependencies:** BackendService, UserProfileManager, EventBus. **Depended by:** gacha_panel.tscn (scene UI). -[Back to top](#top) ### 9.3 SkinManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/skin_manager.gd` (13,909 chars) **Extends:** Node @@ -1643,11 +1507,9 @@ Cosmetic skin system. Manages skin definitions, owned skins, equipped loadout, a **Dependencies:** UserProfileManager. **Depended by:** lobby.gd (3D preview), SkinShop UI. -[Back to top](#top) ### 9.4 ShopManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/shop_manager.gd` (484 chars) **Extends:** Node @@ -1664,11 +1526,9 @@ Thin data layer for shop catalog. Currently a stub; full shop logic lives in sce **Dependencies:** BackendService. **Depended by:** shop_panel.tscn (scene). -[Back to top](#top) ### 9.5 JoinManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/join_manager.gd` (484 chars) **Extends:** Node @@ -1685,11 +1545,9 @@ Thin manager for join code input and validation. Minimal stub. **Dependencies:** None. **Depended by:** lobby.gd (join code UI). -[Back to top](#top) ### 9.6 FriendManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/friend_manager.gd` (11,911 chars) **Extends:** Node @@ -1727,11 +1585,9 @@ Friends list management. Handles friend requests, accept/reject, friend list syn **Dependencies:** BackendService, NakamaManager. **Depended by:** LobbyRoom, LobbyChat, lobby.gd. -[Back to top](#top) ### 9.7 MailManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/mail_manager.gd` (5,271 chars) **Extends:** Node @@ -1759,11 +1615,9 @@ Mail/inbox CRUD operations. Calls BackendService RPCs for get, claim, delete mai **Dependencies:** BackendService. **Depended by:** lobby.gd, mailbox_panel.tscn (scene). -[Back to top](#top) ### 9.8 DailyRewardManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/daily_reward_manager.gd` (1,009 chars) **Extends:** Node @@ -1789,11 +1643,9 @@ Daily reward system. Handles claim state, reward config, and streak tracking. **Dependencies:** BackendService. **Depended by:** daily_reward_panel.tscn (scene). -[Back to top](#top) ### 9.9 AdminManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/admin_manager.gd` (2,538 chars) **Extends:** Node @@ -1815,16 +1667,14 @@ Admin panel state and permission checks. Determines if local player is admin or **Dependencies:** BackendService, NakamaManager. **Depended by:** admin_panel.tscn (scene), LobbyChat (/clear command). -[Back to top](#top) - ## 10. System Managers [Back to top](#top) + ### 10.1 SettingsManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/settings_manager.gd` (13,874 chars) **Extends:** Node @@ -1853,11 +1703,9 @@ User settings persistence. Reads/writes config to user://settings.cfg. Manages a **Dependencies:** ConfigFile. **Depended by:** Audio buses, video settings, gameplay UI, settings_menu.tscn. -[Back to top](#top) ### 10.2 SessionManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/session_manager.gd` (4,742 chars) **Extends:** Node @@ -1884,11 +1732,9 @@ Nakama session refresh lifecycle. Monitors session expiry and auto-refreshes bef **Dependencies:** NakamaManager. **Depended by:** AuthManager. -[Back to top](#top) ### 10.3 GameUpdateManager -[Back to top](#top) **File:** `/home/dev/tekton/scripts/managers/game_update_manager.gd` (14,405 chars) **Extends:** Node @@ -1919,16 +1765,14 @@ Hot-reload update system. Checks for patch.pck on the Gitea patches branch and d **Dependencies:** HTTPRequest (scene). **Depended by:** boot_screen.tscn, main.gd. -[Back to top](#top) - ## 11. Core Scene Scripts [Back to top](#top) + ### 11.1 main.gd (Main game scene controller) -[Back to top](#top) **File:** `/home/dev/tekton/scenes/main.gd` (2956 lines) **Extends:** Node @@ -2010,11 +1854,9 @@ The core game scene controller. Handles game initialization, player spawn, grid **Dependencies:** NakamaManager, LobbyManager, GameStateManager, PlayerMovementManager, PlayerActionManager, GoalsCycleManager, StopNGoManager, GauntletManager, PortalModeManager, PlayerRaceManager, PlayerboardManager, UIManager, SfxManager, MusicManager, NotificationManager, ScreenShake, CameraContextManager, TouchControls. **Depended by:** (this is the root game scene, depends on everything). -[Back to top](#top) ### 11.2 player.gd -[Back to top](#top) **File:** `/home/dev/tekton/scenes/player.gd` (2751 lines) **Extends:** CharacterBody3D (assumed from Node3D methods) @@ -2127,11 +1969,9 @@ The player character controller. Handles movement, action execution (grab/put/ar **Dependencies:** PlayerMovementManager, PlayerInputManager, PlayerActionManager, PlayerboardManager, PowerupManager, PlayerRaceManager, GoalsCycleManager, SfxManager, NotificationManager, EnhancedGridMap (scene node), LobbyManager. **Depended by:** main.gd (spawned per player). -[Back to top](#top) ### 11.3 lobby.gd -[Back to top](#top) **File:** `/home/dev/tekton/scenes/lobby.gd` (583 lines) **Extends:** Control @@ -2234,11 +2074,9 @@ The lobby/home screen controller. Manages main menu, room creation/joining, play **Dependencies:** AuthManager, NakamaManager, LobbyManager, UserProfileManager, SkinManager, MusicManager, FriendManager, MailManager, BackendService. **Depended by:** (root lobby scene; no dependents). -[Back to top](#top) ### 11.4 animation.gd -[Back to top](#top) **File:** `/home/dev/tekton/scenes/animation.gd` (41 lines) **Extends:** Control @@ -2263,18 +2101,16 @@ Stop n Go phase animation player. Controls ready-go countdown, stop phase overla **Dependencies:** AnimatedSprite2D, AnimationPlayer (scene nodes). **Depended by:** StopNGoManager, main.gd. -[Back to top](#top) - ## 12. UI Helper Classes (RefCounted) [Back to top](#top) + All UI helper classes are RefCounted objects instantiated by lobby.gd in _ready(). They do NOT extend Node -- they are lightweight event wiring and state management objects. ### 12.1 LobbyMainMenu -[Back to top](#top) ```gdscript class_name LobbyMainMenu extends RefCounted @@ -2310,11 +2146,9 @@ Event wiring for main menu buttons. Connects all lobby button signals to handler **Dependencies:** AuthManager, LobbyManager, UserProfileManager, NakamaManager, BackendService. **Depended by:** lobby.gd. -[Back to top](#top) ### 12.2 LobbyRoom -[Back to top](#top) ```gdscript class_name LobbyRoom extends RefCounted @@ -2361,11 +2195,9 @@ Room/lobby panel event wiring. Handles ready/start/leave buttons, player slot re **Dependencies:** LobbyManager, FriendManager, NakamaManager, NameGenerator, UserProfileManager. **Depended by:** lobby.gd. -[Back to top](#top) ### 12.3 LobbyRoomList -[Back to top](#top) ```gdscript class_name LobbyRoomList extends RefCounted @@ -2391,11 +2223,9 @@ Room list panel event wiring. Handles room list refresh, selection, join, and ba **Dependencies:** LobbyManager, AuthManager, UserProfileManager. **Depended by:** lobby.gd. -[Back to top](#top) ### 12.4 LobbyChat -[Back to top](#top) ```gdscript class_name LobbyChat extends RefCounted @@ -2433,16 +2263,14 @@ Global and direct message chat system. Handles Nakama socket channel chat, DM ta **Dependencies:** NakamaManager, BackendService, FriendManager, AdminManager, UserProfileManager. **Depended by:** lobby.gd. -[Back to top](#top) - ## 13. Dependency Graph [Back to top](#top) + ### 13.1 Manager Autoload Dependencies -[Back to top](#top) ASCII diagram showing which autoloads reference others: @@ -2573,11 +2401,9 @@ NakamaManager (no deps on other managers -- pure Nakama SDK) +-- JoinManager (no deps -- stub) ``` -[Back to top](#top) ### 13.2 Cross-Manager Signal Wiring -[Back to top](#top) Key signal connections between managers and scene scripts: @@ -2610,16 +2436,14 @@ UserProfileManager.profile_updated -> lobby.gd (_sync_room_profile_card) AuthManager.logged_out -> LobbyMainMenu.go_to_login ``` -[Back to top](#top) - ## 14. Scene Node Trees [Back to top](#top) + ### 14.1 main.tscn -[Back to top](#top) ``` Main (Node) -- attached: main.gd @@ -2649,11 +2473,9 @@ Main (Node) -- attached: main.gd +-- AnimationPlayer ``` -[Back to top](#top) ### 14.2 player.tscn -[Back to top](#top) ``` Player (CharacterBody3D) -- attached: player.gd @@ -2665,11 +2487,9 @@ Player (CharacterBody3D) -- attached: player.gd +-- (tektons picked up become children at runtime) ``` -[Back to top](#top) ### 14.3 lobby.tscn -[Back to top](#top) ``` Lobby (Control) -- attached: lobby.gd @@ -2708,4 +2528,3 @@ Lobby (Control) -- attached: lobby.gd +-- (dynamic instances: MailboxPanel, ShopPanel, GachaPanel, ProfilePanel, etc.) ``` -[Back to top](#top) diff --git a/Architecture-Server.md b/Architecture-Server.md index 32a6f21..5a9ee91 100644 --- a/Architecture-Server.md +++ b/Architecture-Server.md @@ -2,20 +2,33 @@ [Back to Home](./Home) - High-level architecture of the Nakama Lua backend. For detailed RPC reference (params, returns, errors), see [Nakama-Server-API](../Nakama-Server-API). -[Back to top](#top) - --- ## Table of Contents +- [System Overview](#system-overview) +- [Module Architecture](#module-architecture) +- [Authentication Flow](#authentication-flow) +- [Wallet & Economy Flow](#wallet-economy-flow) +- [Gacha Flow](#gacha-flow) +- [Mail/Inbox System](#mailinbox-system) +- [Client-Server Data Flow](#client-server-data-flow) +- [Admin Hierarchy](#admin-hierarchy) +- [Storage Collections](#storage-collections) +- [vs Nakama-Server-API](#vs-nakama-server-api) +- [Quick Reference: All 48 Registered RPCs](#quick-reference-all-48-registered-rpcs) +- [Deployment Topology](#deployment-topology) + [Back to top](#top) ## System Overview +[Back to top](#top) + + ```mermaid flowchart LR Client[Godot Client
player.tscn] -->|RPC calls| Nakama[Nakama Server
port 7350/7351] @@ -31,12 +44,14 @@ flowchart LR The Lua backend runs **inside** the Nakama process. Lua modules hook into Nakama's lifecycle (after-authentication, RPC dispatch, match signals). All game transactions (wallet, inventory, gacha, shop) are **server-authoritative** — the Godot client sends RPC requests and the Lua code validates and executes. -[Back to top](#top) --- ## Module Architecture +[Back to top](#top) + + ```mermaid flowchart TD main["main.lua
Entry point: loads all modules"] --> utils["utils.lua
Auth guards, channel resolver"] @@ -77,12 +92,14 @@ flowchart TD 8. `inbox.lua` — depends on utils 9. `gacha.lua` — no deps beyond utils -[Back to top](#top) --- ## Authentication Flow +[Back to top](#top) + + ```mermaid sequenceDiagram participant C as Godot Client @@ -113,12 +130,14 @@ sequenceDiagram 5. **Ban check:** If `metadata.banned == true`, raises error (player rejected). 6. Client receives session token and proceeds to lobby. -[Back to top](#top) --- ## Wallet & Economy Flow +[Back to top](#top) + + ```mermaid flowchart LR subgraph Client Side @@ -164,12 +183,14 @@ flowchart LR | Claim daily reward | `{star: +N}` or `{gold: +N}` | | Admin topup | `{gold: 999999}` | -[Back to top](#top) --- ## Gacha Flow +[Back to top](#top) + + ```mermaid flowchart TD A[Client: perform_gacha_pull] --> B{Check banner} @@ -205,12 +226,14 @@ flowchart TD **Pity:** Guaranteed Real Prize at 90 pulls. Pity counter resets on any Real Prize win. -[Back to top](#top) --- ## Mail/Inbox System +[Back to top](#top) + + ```mermaid flowchart TD Admin[Admin RPC] -->|admin_send_mail| Global[Global Mail
config/global_mail
system user] @@ -237,12 +260,14 @@ flowchart TD Grant --> UpdateState[Update state:
add mailId to claimed_ids] ``` -[Back to top](#top) --- ## Client-Server Data Flow +[Back to top](#top) + + ```mermaid sequenceDiagram participant C as Godot Client @@ -273,12 +298,14 @@ sequenceDiagram All transactions are **idempotent** via `idempotency_key` — if the same key is used twice, the server returns the previous result instead of re-executing. -[Back to top](#top) --- ## Admin Hierarchy +[Back to top](#top) + + | Role | Can | Guarded by | |---|---|---| | `player` (default) | Nothing special | — | @@ -295,12 +322,14 @@ utils.is_banned(metadata) -- returns boolean utils.resolve_channel_id(channelId) -- channel name → hashed ID ``` -[Back to top](#top) --- ## Storage Collections +[Back to top](#top) + + | Collection | Owner | Key | Public R | Public W | Purpose | |---|---|---|---|---|---| | `profiles` | User | `"profile"` | 1 | 0 | User metadata, role, ban status, loadout | @@ -319,12 +348,14 @@ utils.resolve_channel_id(channelId) -- channel name → hashed ID | `shop_config` | SYSTEM | `"featured_banners"` | 2 | 0 | Featured shop banners (max 3) | | `bans` | SYSTEM | User ID | 2 | 0 | Ban records (redundant with metadata) | -[Back to top](#top) --- ## vs Nakama-Server-API +[Back to top](#top) + + | Aspect | Architecture-Server (this page) | Nakama-Server-API | |---|---|---| | Audience | Architects, new devs | Implementers, AI agents | @@ -334,12 +365,14 @@ utils.resolve_channel_id(channelId) -- channel name → hashed ID | Storage | Conceptual collection overview | Exact schema per collection | | Best for | Understanding the system | Calling RPCs without reading code | -[Back to top](#top) --- ## Quick Reference: All 48 Registered RPCs +[Back to top](#top) + + | RPC Name | Module | Auth | Purpose | |---|---|---|---| | `update_display_name` | user | required | Change display name | @@ -368,12 +401,14 @@ utils.resolve_channel_id(channelId) -- channel name → hashed ID For full params/returns/errors on any RPC above, see [Nakama-Server-API](../Nakama-Server-API). -[Back to top](#top) --- ## Deployment Topology +[Back to top](#top) + + ```mermaid flowchart TD subgraph VPS [VPS 52.74.133.55] @@ -395,4 +430,3 @@ flowchart TD Client -->|Download patch| Gitea ``` -[Back to top](#top) diff --git a/Home.md b/Home.md index 7c21016..9591e56 100644 --- a/Home.md +++ b/Home.md @@ -1,6 +1,5 @@ # Tekton Dash Armageddon - - [Architecture - Client](./Architecture-Client) — Godot client code structure, managers, scenes, player controller - [Architecture - Server](./Architecture-Server) — Nakama Lua backend topology, auth flow, wallet economy, admin roles - [Nakama Server API](./Nakama-Server-API) — Full per-function RPC reference with params, returns, errors @@ -14,4 +13,6 @@ ## Table of Contents +_(no sections — this page is a link index)_ + [Back to top](#top) diff --git a/Nakama-Deployment.-.md b/Nakama-Deployment.-.md index 61eca05..c7cfada 100644 --- a/Nakama-Deployment.-.md +++ b/Nakama-Deployment.-.md @@ -7,10 +7,15 @@ After generating an updated `tekton_admin.js` locally (see [Skin Creation Workfl ## Table of Contents +- [Steps](#steps) + [Back to top](#top) ## Steps +[Back to top](#top) + + 1. **Copy the latest script** — open `server/nakama/tekton_admin.js` locally and copy its full contents. 2. **SSH into the VPS.** 3. **Create or edit the file on the remote server:** diff --git a/Nakama-Server-API.md b/Nakama-Server-API.md index 005ba6f..295e6a8 100644 --- a/Nakama-Server-API.md +++ b/Nakama-Server-API.md @@ -2,34 +2,29 @@ [Back to Home](./Home) - - > Auto-generated from source code. For AI agents -- call these RPCs without reading Lua. -## Table of Contents - -[Back to top](#top) - - -1. [Authentication & Core (core.lua)](#1-authentication--core-coreluau) -2. [Utilities (utils.lua)](#2-utilities-utilsluau) -3. [User Module (user.lua)](#3-user-module-userluau) -4. [Economy Module (economy.lua)](#4-economy-module-economyluau) -5. [Gacha Module (gacha.lua)](#5-gacha-module-gachaluau) -6. [Leaderboard Module (leaderboard.lua)](#6-leaderboard-module-leaderboardluau) -7. [Inbox/Mail Module (inbox.lua)](#7-inboxmail-module-inboxluau) -8. [Daily Rewards Module (daily_rewards.lua)](#8-daily-rewards-module-daily_rewardsluau) -9. [Admin Module (admin.lua)](#9-admin-module-adminluau) -10. [Storage Collections Reference](#10-storage-collections-reference) -11. [Leaderboard Config](#11-leaderboard-config) -12. [Error Strings Reference](#12-error-strings-reference) -13. [Permission Levels](#13-permission-levels) - --- ## Table of Contents +- [1. Authentication & Core (`core.lua`)](#1-authentication-core-(corelua)) +- [2. Utilities (`utils.lua`)](#2-utilities-(utilslua)) +- [3. User Module (`user.lua`)](#3-user-module-(userlua)) +- [4. Economy Module (`economy.lua`)](#4-economy-module-(economylua)) +- [5. Gacha Module (`gacha.lua`)](#5-gacha-module-(gachalua)) +- [6. Leaderboard Module (`leaderboard.lua`)](#6-leaderboard-module-(leaderboardlua)) +- [7. Inbox/Mail Module (`inbox.lua`)](#7-inboxmail-module-(inboxlua)) +- [8. Daily Rewards Module (`daily_rewards.lua`)](#8-daily-rewards-module-(dailyrewardslua)) +- [9. Admin Module (`admin.lua`)](#9-admin-module-(adminlua)) +- [10. Storage Collections Reference](#10-storage-collections-reference) +- [11. Leaderboard Config](#11-leaderboard-config) +- [12. Error Strings Reference](#12-error-strings-reference) +- [13. Permission Levels](#13-permission-levels) +- [RPC Summary Table](#rpc-summary-table) +- [Wallet Update Summary](#wallet-update-summary) + [Back to top](#top) ## 1. Authentication & Core (`core.lua`) @@ -39,8 +34,6 @@ ### After-Hook: `after_authenticate_steam` -[Back to top](#top) - | Field | Value | |---|---| @@ -54,8 +47,6 @@ ### Startup (not an RPC) -[Back to top](#top) - ``` nk.leaderboard_create("global_high_score", true, "desc", "best", nil, {}) @@ -74,8 +65,6 @@ Shared helpers used by other modules. ### Constants -[Back to top](#top) - | Constant | Value | Purpose | |---|---|---| @@ -87,8 +76,6 @@ Shared helpers used by other modules. ### `utils.is_admin(context)` -[Back to top](#top) - Checks if caller has admin/moderator/owner role. @@ -100,8 +87,6 @@ Checks if caller has admin/moderator/owner role. ### `utils.is_match_host(context, match_id)` -[Back to top](#top) - Checks if caller is the host of a match. @@ -115,22 +100,16 @@ Checks if caller is the host of a match. ### `utils.require_admin(context)` -[Back to top](#top) - Errors with `"Admin privileges required"` if caller is not admin/moderator/owner. ### `utils.require_admin_or_host(context, match_id)` -[Back to top](#top) - Errors with `"Admin or host privileges required"` if caller is neither admin nor match host. ### `utils.resolve_channel_id(channel_id)` -[Back to top](#top) - Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channel ID. @@ -150,8 +129,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### RPC: `get_user_profile` -[Back to top](#top) - | Field | Value | |---|---| @@ -185,8 +162,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### RPC: `update_user_profile` -[Back to top](#top) - | Field | Value | |---|---| @@ -213,8 +188,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### RPC: `search_users` -[Back to top](#top) - | Field | Value | |---|---| @@ -247,8 +220,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### RPC: `change_credentials` -[Back to top](#top) - | Field | Value | |---|---| @@ -280,8 +251,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### RPC: `send_lobby_invite` -[Back to top](#top) - | Field | Value | |---|---| @@ -310,8 +279,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### RPC: `send_friend_request` -[Back to top](#top) - | Field | Value | |---|---| @@ -340,8 +307,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### RPC: `admin_get_user_history` -[Back to top](#top) - | Field | Value | |---|---| @@ -369,8 +334,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### After-Hook: `after_authenticate` -[Back to top](#top) - | Field | Value | |---|---| @@ -388,8 +351,6 @@ Resolves a friendly room name (e.g. `"social_global"`) to a hashed Nakama channe ### Shop Catalog -[Back to top](#top) - Hardcoded items available for purchase: @@ -410,8 +371,6 @@ Hardcoded items available for purchase: ### RPC: `get_shop_catalog` -[Back to top](#top) - | Field | Value | |---|---| @@ -432,8 +391,6 @@ Hardcoded items available for purchase: ### RPC: `buy_currency` -[Back to top](#top) - | Field | Value | |---|---| @@ -487,8 +444,6 @@ Hardcoded items available for purchase: ### RPC: `purchase_item` -[Back to top](#top) - | Field | Value | |---|---| @@ -527,8 +482,6 @@ Hardcoded items available for purchase: ### RPC: `admin_set_featured_banners` -[Back to top](#top) - | Field | Value | |---|---| @@ -557,8 +510,6 @@ Hardcoded items available for purchase: ### RPC: `admin_get_featured_banners` -[Back to top](#top) - | Field | Value | |---|---| @@ -583,8 +534,6 @@ Hardcoded items available for purchase: ### Gacha Banners -[Back to top](#top) - | Banner ID | Name | Currency | Pull 1 Cost | Pull 10 Cost | Pity At | |---|---|---|---|---|---| @@ -593,8 +542,6 @@ Hardcoded items available for purchase: ### Drop Rates -[Back to top](#top) - | Rarity | Probability | Pool Items | |---|---|---| @@ -605,8 +552,6 @@ Hardcoded items available for purchase: ### Real Prize Catalog -[Back to top](#top) - | Item ID | Name | Category | |---|---|---| @@ -617,8 +562,6 @@ Hardcoded items available for purchase: ### Fragment Items -[Back to top](#top) - | ID | Name | Rarity | |---|---|---| @@ -628,8 +571,6 @@ Hardcoded items available for purchase: ### RPC: `perform_gacha_pull` -[Back to top](#top) - | Field | Value | |---|---| @@ -680,8 +621,6 @@ Hardcoded items available for purchase: ### Leaderboard Config -[Back to top](#top) - | Property | Value | |---|---| @@ -693,8 +632,6 @@ Hardcoded items available for purchase: ### RPC: `get_leaderboard_stats` -[Back to top](#top) - | Field | Value | |---|---| @@ -725,8 +662,6 @@ Hardcoded items available for purchase: ### RPC: `submit_score` -[Back to top](#top) - | Field | Value | |---|---| @@ -756,8 +691,6 @@ Hardcoded items available for purchase: ### RPC: `sync_leaderboard` -[Back to top](#top) - | Field | Value | |---|---| @@ -784,8 +717,6 @@ Hardcoded items available for purchase: ### RPC: `reset_stats` -[Back to top](#top) - | Field | Value | |---|---| @@ -805,8 +736,6 @@ Hardcoded items available for purchase: ### RPC: `admin_update_stats` -[Back to top](#top) - | Field | Value | |---|---| @@ -835,8 +764,6 @@ Hardcoded items available for purchase: ### RPC: `admin_delete_stats` -[Back to top](#top) - | Field | Value | |---|---| @@ -854,8 +781,6 @@ Hardcoded items available for purchase: ### RPC: `admin_sync_leaderboard` -[Back to top](#top) - | Field | Value | |---|---| @@ -874,8 +799,6 @@ Hardcoded items available for purchase: ### RPC: `admin_send_mail` -[Back to top](#top) - | Field | Value | |---|---| @@ -908,8 +831,6 @@ Hardcoded items available for purchase: ### RPC: `get_mail` -[Back to top](#top) - | Field | Value | |---|---| @@ -939,8 +860,6 @@ Hardcoded items available for purchase: ### RPC: `claim_mail_reward` -[Back to top](#top) - | Field | Value | |---|---| @@ -984,8 +903,6 @@ Array format: `[{type="star", amount=100}, {type="gold", amount=50}, {type="frag ### RPC: `delete_mail` -[Back to top](#top) - | Field | Value | |---|---| @@ -1001,8 +918,6 @@ Array format: `[{type="star", amount=100}, {type="gold", amount=50}, {type="frag ### RPC: `save_mail_state` -[Back to top](#top) - | Field | Value | |---|---| @@ -1018,8 +933,6 @@ Array format: `[{type="star", amount=100}, {type="gold", amount=50}, {type="frag ### RPC: `admin_list_mail` -[Back to top](#top) - | Field | Value | |---|---| @@ -1037,8 +950,6 @@ Array format: `[{type="star", amount=100}, {type="gold", amount=50}, {type="frag ### RPC: `admin_update_mail` -[Back to top](#top) - | Field | Value | |---|---| @@ -1061,8 +972,6 @@ Array format: `[{type="star", amount=100}, {type="gold", amount=50}, {type="frag ### RPC: `admin_delete_mail_server` -[Back to top](#top) - | Field | Value | |---|---| @@ -1087,8 +996,6 @@ Array format: `[{type="star", amount=100}, {type="gold", amount=50}, {type="frag ### Default Reward Schedule -[Back to top](#top) - Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. @@ -1102,8 +1009,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `claim_daily_reward` -[Back to top](#top) - | Field | Value | |---|---| @@ -1139,8 +1044,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `get_daily_reward_state` -[Back to top](#top) - | Field | Value | |---|---| @@ -1163,8 +1066,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `set_daily_reward_config` [Admin] -[Back to top](#top) - | Field | Value | |---|---| @@ -1180,8 +1081,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `get_daily_reward_config_admin` [Admin] -[Back to top](#top) - | Field | Value | |---|---| @@ -1198,8 +1097,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_kick_player` -[Back to top](#top) - | Field | Value | |---|---| @@ -1224,8 +1121,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_ban_player` -[Back to top](#top) - | Field | Value | |---|---| @@ -1252,8 +1147,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_unban_player` -[Back to top](#top) - | Field | Value | |---|---| @@ -1269,8 +1162,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_get_ban_list` -[Back to top](#top) - | Field | Value | |---|---| @@ -1280,8 +1171,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_get_server_stats` -[Back to top](#top) - | Field | Value | |---|---| @@ -1306,8 +1195,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_end_match` -[Back to top](#top) - | Field | Value | |---|---| @@ -1324,8 +1211,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_set_user_role` -[Back to top](#top) - | Field | Value | |---|---| @@ -1346,8 +1231,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_topup_gold` -[Back to top](#top) - | Field | Value | |---|---| @@ -1359,8 +1242,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_clear_global_chat` -[Back to top](#top) - | Field | Value | |---|---| @@ -1378,8 +1259,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_list_users` -[Back to top](#top) - | Field | Value | |---|---| @@ -1391,8 +1270,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_delete_users` -[Back to top](#top) - | Field | Value | |---|---| @@ -1414,8 +1291,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_get_user_detail` -[Back to top](#top) - | Field | Value | |---|---| @@ -1434,8 +1309,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_update_user_identity` -[Back to top](#top) - | Field | Value | |---|---| @@ -1458,8 +1331,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_set_user_password` -[Back to top](#top) - | Field | Value | |---|---| @@ -1480,8 +1351,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_get_player_list` -[Back to top](#top) - | Field | Value | |---|---| @@ -1491,8 +1360,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_get_chat_config` -[Back to top](#top) - | Field | Value | |---|---| @@ -1504,8 +1371,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_set_chat_config` -[Back to top](#top) - | Field | Value | |---|---| @@ -1525,8 +1390,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_purge_old_messages` -[Back to top](#top) - | Field | Value | |---|---| @@ -1543,8 +1406,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_list_channel_messages` -[Back to top](#top) - | Field | Value | |---|---| @@ -1563,8 +1424,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### RPC: `admin_delete_channel_message` -[Back to top](#top) - | Field | Value | |---|---| @@ -1588,8 +1447,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"shop_config"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1597,8 +1454,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"receipts"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1606,8 +1461,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"inventory"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1616,8 +1469,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"profiles"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1627,8 +1478,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"history"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1636,8 +1485,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"stats"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1646,8 +1493,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"inbox"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1656,8 +1501,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"daily_rewards"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1665,8 +1508,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"config"` (system-level) -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1676,8 +1517,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"bans"` -[Back to top](#top) - | Key | User | Permission Read | Permission Write | Schema | |---|---|---|---|---| @@ -1685,8 +1524,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Collection: `"matches"` (per-user) -[Back to top](#top) - | Key | User | Permission | Schema | |---|---|---|---| @@ -1717,8 +1554,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Auth errors (raised by utils) -[Back to top](#top) - | Error String | Trigger | |---|---| @@ -1728,8 +1563,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Economy errors -[Back to top](#top) - | Error String | Trigger | |---|---| @@ -1745,8 +1578,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### User errors -[Back to top](#top) - | Error String | Trigger | |---|---| @@ -1763,8 +1594,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Gacha errors -[Back to top](#top) - | Error String | Trigger | |---|---| @@ -1778,8 +1607,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Leaderboard errors -[Back to top](#top) - | Error String | Trigger | |---|---| @@ -1789,8 +1616,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Inbox errors -[Back to top](#top) - | Error String | Trigger | |---|---| @@ -1803,8 +1628,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Daily reward errors -[Back to top](#top) - | Error String | Trigger | |---|---| @@ -1814,8 +1637,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Admin errors -[Back to top](#top) - | Error String | Trigger | |---|---| @@ -1846,8 +1667,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Role Hierarchy -[Back to top](#top) - | Role | Can Call Admin RPCs | Can Modify Roles | Notes | |---|---|---|---| @@ -1858,8 +1677,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Auth Check Functions Summary -[Back to top](#top) - | Check | What It Allows | |---|---| @@ -1869,8 +1686,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### Storage Permission Bits -[Back to top](#top) - | Value | Meaning | |---|---| @@ -1880,8 +1695,6 @@ Days 1-31, each day gives `star` currency: `min(10 + (day-1)*5, 100)`. ### System User ID -[Back to top](#top) - ``` 00000000-0000-0000-0000-000000000000 diff --git a/Patch-Release-Workflow.-.md b/Patch-Release-Workflow.-.md index bdff32d..5693e9b 100644 --- a/Patch-Release-Workflow.-.md +++ b/Patch-Release-Workflow.-.md @@ -9,10 +9,23 @@ Complete guide for shipping updates to Tekton players — hot patches (`.pck`) f ## Table of Contents +- [Overview](#overview) +- [Infrastructure](#infrastructure) +- [Part 1: Hot Patch (content-only updates)](#part-1-hot-patch-(content-only-updates)) +- [[NEXT]](#next) +- [Part 2: Full Binary Release (platform updates)](#part-2-full-binary-release-(platform-updates)) +- [Part 3: Agent-Automated Release](#part-3-agent-automated-release) +- [Troubleshooting](#troubleshooting) +- [File Reference](#file-reference) +- [Key Gotchas](#key-gotchas) + [Back to top](#top) ## Overview +[Back to top](#top) + + Two automated CI pipelines handle all distribution: | Pipeline | Trigger | Output | Delivery | @@ -24,6 +37,9 @@ Two automated CI pipelines handle all distribution: ## Infrastructure +[Back to top](#top) + + ### Gitea instance - **URL:** https://git.klud.top - **API:** http://52.74.133.55:3000/api/v1 @@ -46,6 +62,9 @@ Old `raw.klud.top` (gitea-pages container) retired — Gitea raw endpoint is fas ## Part 1: Hot Patch (content-only updates) +[Back to top](#top) + + Use when: script changes, UI tweaks, balance patches, asset replacements, config changes. ### Step-by-step @@ -56,6 +75,9 @@ Edit `CHANGELOG_DRAFT.md` — add player-facing notes under `## [NEXT]`: ```markdown ## [NEXT] + +[Back to top](#top) + - Fixed playerboard desync in multiplayer. - Adjusted Gauntlet difficulty scaling. ``` @@ -128,6 +150,9 @@ curl -s -o /dev/null -w "%{http_code} %{size_download}B" \ ## Part 2: Full Binary Release (platform updates) +[Back to top](#top) + + Use when: engine upgrade, native plugin change, export template update, platform-specific build fix, or any change that needs a new `.exe`/`.app`. ### Step-by-step @@ -212,6 +237,9 @@ curl -X DELETE "http://52.74.133.55:3000/api/v1/repos/danchie/tekton/actions/run ## Part 3: Agent-Automated Release +[Back to top](#top) + + Agent (Hermes) can execute the full release flow from a single user request: ### Scenario: "Ship v2.4.3" @@ -244,6 +272,9 @@ Agent actions: ## Troubleshooting +[Back to top](#top) + + ### `zip: command not found` in CI Root cause: `ubuntu-latest` container doesn't have `zip` pre-installed. The install step must include `zip`: @@ -304,6 +335,9 @@ gitea-pages container uses a Gitea token to read files. If the token is dead: ## File Reference +[Back to top](#top) + + | File | Purpose | |---|---| | `.gitea/workflows/deploy_patch.yml` | Patch deploy CI — generates pck + pushes to patches branch | @@ -320,6 +354,9 @@ gitea-pages container uses a Gitea token to read files. If the token is dead: ## Key Gotchas +[Back to top](#top) + + - **`zip` must be in install step** — missing zip kills Windows/Linux export. Added in run 141 — do not remove. - **Tag format is `vX.Y.Z`** — `ci.yml` trigger is `v*`. A tag without `v` prefix won't build. - **Force-push tag = new CI run** — Always expect a new run on force-push. Old run keeps running. diff --git a/SSH-Setup-Linux.md b/SSH-Setup-Linux.md index e0c267f..1f4ae4f 100644 --- a/SSH-Setup-Linux.md +++ b/SSH-Setup-Linux.md @@ -5,10 +5,19 @@ ## Table of Contents +- [Generate an SSH key](#generate-an-ssh-key) +- [Add the public key to Gitea](#add-the-public-key-to-gitea) +- [Test SSH](#test-ssh) +- [Clone](#clone) +- [Troubleshooting](#troubleshooting) + [Back to top](#top) ## Generate an SSH key +[Back to top](#top) + + Open a terminal and run: ```bash @@ -19,6 +28,9 @@ Press Enter to accept the default path `/home//.ssh/id_ed25519`. Use a pass ## Add the public key to Gitea +[Back to top](#top) + + ```bash cat ~/.ssh/id_ed25519.pub ``` @@ -33,6 +45,9 @@ Paste it as a new SSH key. Title example: `linux-`. ## Test SSH +[Back to top](#top) + + ```bash ssh -T git@ssh.git.klud.top ``` @@ -47,6 +62,9 @@ Hi there, ! You've successfully authenticated with the key named linux ## Clone +[Back to top](#top) + + SSH is preferred: ```bash @@ -67,6 +85,9 @@ tea repos clone --git-protocol ssh danchie/tekton ## Troubleshooting +[Back to top](#top) + + - **`Permission denied (publickey)`** — Your key was not added in Gitea, or the agent has not loaded it. Run `ssh-add ~/.ssh/id_ed25519`. - **`Host key verification failed`** — Run the `ssh -T` command above interactively once. - **`Could not resolve hostname ssh.git.klud.top`** — DNS cache stale. Wait a few minutes or flush DNS. diff --git a/SSH-Setup-Windows.md b/SSH-Setup-Windows.md index ba67c77..163be16 100644 --- a/SSH-Setup-Windows.md +++ b/SSH-Setup-Windows.md @@ -5,16 +5,29 @@ ## Table of Contents +- [Install Git for Windows](#install-git-for-windows) +- [Generate an SSH key](#generate-an-ssh-key) +- [Add the public key to Gitea](#add-the-public-key-to-gitea) +- [Test SSH](#test-ssh) +- [Clone](#clone) +- [Troubleshooting](#troubleshooting) + [Back to top](#top) ## Install Git for Windows +[Back to top](#top) + + Download from https://git-scm.com/download/win and install with default options. This installs `git`, `ssh`, and **Git Bash**. ## Generate an SSH key +[Back to top](#top) + + Open **Git Bash** and run: ```bash @@ -25,6 +38,9 @@ Press Enter to accept the default path `C:\Users\\.ssh\id_ed25519`. Set a p ## Add the public key to Gitea +[Back to top](#top) + + ```bash cat ~/.ssh/id_ed25519.pub ``` @@ -39,6 +55,9 @@ Paste it as a new SSH key. Title example: `windows-`. ## Test SSH +[Back to top](#top) + + ```bash ssh -T git@ssh.git.klud.top ``` @@ -53,6 +72,9 @@ Hi there, ! You've successfully authenticated with the key named windo ## Clone +[Back to top](#top) + + SSH is preferred: ```bash @@ -73,6 +95,9 @@ tea repos clone --git-protocol ssh danchie/tekton ## Troubleshooting +[Back to top](#top) + + - **`Permission denied (publickey)`** — Your key was not added in Gitea, or Git Bash is not offering `~/.ssh/id_ed25519`. Run `ssh-add ~/.ssh/id_ed25519`. - **`Host key verification failed`** — Run the `ssh -T` command above interactively once. - **`Could not resolve hostname ssh.git.klud.top`** — DNS cache stale. Wait a few minutes or flush DNS. diff --git a/SSH-Setup-macOS.md b/SSH-Setup-macOS.md index 07ab20f..1834db6 100644 --- a/SSH-Setup-macOS.md +++ b/SSH-Setup-macOS.md @@ -5,10 +5,19 @@ ## Table of Contents +- [Generate an SSH key](#generate-an-ssh-key) +- [Add the public key to Gitea](#add-the-public-key-to-gitea) +- [Test SSH](#test-ssh) +- [Clone](#clone) +- [Troubleshooting](#troubleshooting) + [Back to top](#top) ## Generate an SSH key +[Back to top](#top) + + Open **Terminal** and run: ```bash @@ -19,6 +28,9 @@ Press Enter to accept the default path `/Users//.ssh/id_ed25519`. Use a pas ## Add the public key to Gitea +[Back to top](#top) + + ```bash cat ~/.ssh/id_ed25519.pub ``` @@ -33,6 +45,9 @@ Paste it as a new SSH key. Title example: `macos-`. ## Test SSH +[Back to top](#top) + + ```bash ssh -T git@ssh.git.klud.top ``` @@ -47,6 +62,9 @@ Hi there, ! You've successfully authenticated with the key named macos ## Clone +[Back to top](#top) + + SSH is preferred: ```bash @@ -67,6 +85,9 @@ tea repos clone --git-protocol ssh danchie/tekton ## Troubleshooting +[Back to top](#top) + + - **`Permission denied (publickey)`** — Your key was not added in Gitea, or the agent has not loaded it. Run `ssh-add ~/.ssh/id_ed25519`. - **`Host key verification failed`** — Run the `ssh -T` command above interactively once. - **`Could not resolve hostname ssh.git.klud.top`** — DNS cache stale. Wait a few minutes or flush DNS. diff --git a/Skin-Creation-Workflow.-.md b/Skin-Creation-Workflow.-.md index 960b67d..7d587db 100644 --- a/Skin-Creation-Workflow.-.md +++ b/Skin-Creation-Workflow.-.md @@ -2,7 +2,6 @@ [Back to Home](./Home) - How to author a new character skin, register it in the game's shop/gacha catalog, and ship it to players. --- @@ -10,10 +9,22 @@ How to author a new character skin, register it in the game's shop/gacha catalog ## Table of Contents +- [Overview](#overview) +- [Step 1: Create the Skin Material](#step-1-create-the-skin-material) +- [Step 2: Register the Skin in SkinManager (Client)](#step-2-register-the-skin-in-skinmanager-(client)) +- [Step 3: Register the Skin in Economy (Server)](#step-3-register-the-skin-in-economy-(server)) +- [Step 4 (Optional): Add Skin as Gacha Prize](#step-4-(optional)-add-skin-as-gacha-prize) +- [Step 5: Deploy](#step-5-deploy) +- [Full Flow Diagram](#full-flow-diagram) +- [Troubleshooting](#troubleshooting) + [Back to top](#top) ## Overview +[Back to top](#top) + + Each skin is defined in two places that must stay in sync: | Layer | File | What it stores | @@ -23,12 +34,14 @@ Each skin is defined in two places that must stay in sync: The item `id` in `economy.lua` must match the dictionary key in `skin_manager.gd` `SKIN_CATALOG` exactly -- the Godot client looks up the item ID from the wallet/inventory and applies the matching skin data. -[Back to top](#top) --- ## Step 1: Create the Skin Material +[Back to top](#top) + + Open the **Skin Shader Generator** at `res://scenes/tools/skin_shader_generator.tscn`. 1. Run the scene (F6). @@ -48,12 +61,14 @@ Open the **Skin Shader Generator** at `res://scenes/tools/skin_shader_generator. | glove | `res://assets/characters/skins/gloves/oldpop_mat_gloves_blue.tres` | | accessory | `res://assets/characters/skins/accessory/` | -[Back to top](#top) --- ## Step 2: Register the Skin in SkinManager (Client) +[Back to top](#top) + + Open `res://scripts/managers/skin_manager.gd` and add a new entry inside `SKIN_CATALOG` (between `[BEGIN_SKIN_CATALOG]` and `[END_SKIN_CATALOG]` markers). ### Entry format @@ -98,12 +113,14 @@ Costumes typically touch 3 meshes: - Leave `"material"` as `""` if the `.tres` file is not ready yet. The slot is skipped gracefully. - Use the **Skin Catalog Editor** (`res://scenes/tools/skin_catalog_editor.tscn`) to avoid manual edits. Click **Save & Generate** to rewrite both `skin_manager.gd` and `economy.lua`. -[Back to top](#top) --- ## Step 3: Register the Skin in Economy (Server) +[Back to top](#top) + + Open `server/nakama/lua/economy.lua` and add a new entry to `SHOP_CATALOG_DEFS`. ### Catalog entry format @@ -139,12 +156,14 @@ oldpop-red-gloves glove 75 gold Common Oldpop oldpop-yellow-gloves glove 75 gold Common Oldpop ``` -[Back to top](#top) --- ## Step 4 (Optional): Add Skin as Gacha Prize +[Back to top](#top) + + Gacha-only skins are registered in `server/nakama/lua/gacha.lua` inside `GACHA_DATA.real_prize_catalog`. ### Existing gacha skins (4 items) @@ -175,12 +194,14 @@ pools = { }, ``` -[Back to top](#top) --- ## Step 5: Deploy +[Back to top](#top) + + ### Hot patch (content only) -- recommended for skins 1. Commit changes to `experimental` branch: @@ -200,12 +221,14 @@ pools = { Tag a version (e.g. `v2.5.0`) and push. CI builds all platform binaries and uploads to the release. -[Back to top](#top) --- ## Full Flow Diagram +[Back to top](#top) + + ``` ┌──────────────────────┐ │ 1. Create Material │ @@ -245,12 +268,14 @@ Tag a version (e.g. `v2.5.0`) and push. CI builds all platform binaries and uplo └──────────────────────┘ ``` -[Back to top](#top) --- ## Troubleshooting +[Back to top](#top) + + | Symptom | Cause | Fix | |---|---|---| | Skin visible in editor but not in-game | Material path wrong or `.tres` not exported | Verify `res://` path in SKIN_CATALOG, run `--export-pack` | @@ -260,4 +285,3 @@ Tag a version (e.g. `v2.5.0`) and push. CI builds all platform binaries and uplo | Player downloads patch but skin missing | econmy.lua change didn't reach server | Nakama hot-reload: restart Nakama container or wait for next restart | | Outline shader lost on skin | next_pass not preserved | SkinManager preserves it automatically -- verify with latest `skin_manager.gd` | -[Back to top](#top)