diff --git a/Architecture-Client.md b/Architecture-Client.md new file mode 100644 index 0000000..7046b56 --- /dev/null +++ b/Architecture-Client.md @@ -0,0 +1,67 @@ +# Tekton Dash Armageddon - Client Architecture + +## Core Game Flow + +Tekton uses a heavily decoupled Singleton (Autoload) architecture mixed with standard Godot High-Level Multiplayer RPCs. + +1. **Boot:** `boot_screen.tscn` is the entry point. It verifies version via `GameUpdateManager`, downloads `patch.pck` if available, and then loads `login_screen.tscn`. +2. **Auth:** `AuthManager` handles Nakama login/sessions. Upon success, loads `lobby.tscn`. +3. **Lobby:** Players form parties, select game modes, and pull Gacha. `LobbyManager` holds the selected `game_mode` string. +4. **Match Start:** Host transitions to `main.tscn`. The `Main` script inspects `LobbyManager.game_mode` and dynamically instantiates the correct Mode Manager (`GauntletManager`, `StopNGoManager`, etc.). +5. **Spawning:** `main.gd` asks `PlayerManager` to instantiate `player.tscn` for all connected peers based on `GameStateManager` player IDs. + +## Singletons & Autoloads (`scripts/managers/`) + +There are ~74 manager scripts. Key singletons include: + +### State & Networking +- **`NakamaManager` / `AuthManager`:** Connects to the backend VPS for authentication, leaderboards, storage (friends, inbox), and matchmaking. +- **`LobbyManager`:** Tracks pre-match state, chat, room configuration, and connected peers. +- **`GameStateManager`:** Tracks active players, bots, and the authoritative "match active" flags. + +### Actor Control (`player.gd` delegates) +- **`PlayerMovementManager`:** Validates and executes GridMap translation. `try_push()` handles collision/smacking mechanics. +- **`PlayerInputManager`:** Reads keyboard/gamepad and touch inputs, polling every frame to instruct `PlayerMovementManager`. +- **`PlayerActionManager`:** Handles grid interactions (grabbing, dropping) and tracks Action Points (AP). + +### Economy & Meta +- **`UserProfileManager`:** Manages the authoritative `wallet` (Gold/Star balances), cosmetic inventory, and fragments. Fetches from Nakama Storage. +- **`GachaManager`:** Reads backend gacha configs, calls Lua RPCs to roll, and grants fragments/skins. +- **`SkinManager`:** Dynamically applies unlocked materials to base meshes. + +### Game Modes +- **`StopNGoManager`:** Classic mode — green light / red light movement blocking. +- **`GauntletManager`:** Candy Pump Survival — waves of expanding sticky bubbles, center cannon shooting projectiles, invisible ghost mechanics. +- **`PortalModeManager`:** Tekton Doors — maze running and teleporters. + +### UI & Render +- **`UIManager`:** Binds `player.gd` state to CanvasLayers. Specifically handles the 5x5 Grid `playerboard_ui`. +- **`SfxManager` / `MusicManager`:** Global audio pooling. + +## Major UI Components (`scenes/ui/`) + +- `lobby_main_menu.tscn`: Holds the primary game mode selection, Shop, and Gacha buttons. +- `shop_panel.tscn`: Reads `UserProfileManager` to buy Gold (IAP) or convert Gold to Stars. +- `gacha_panel.tscn`: 1x/10x pulls for Skins and Fragments. +- `daily_reward_panel.tscn`: Daily login progression matrix. +- `admin_panel.tscn`: Server moderation tools (requires Admin flag from Nakama). + +## Dependency Graph + +```mermaid +flowchart TD + LobbyManager -->|Match Start| Main[main.tscn] + Main -->|Instantiates| PlayerManager + PlayerManager -->|Spawns| Player[player.tscn] + + Main -->|Game Logic| ModeManagers[StopNGo/Gauntlet/Portal] + + Player -->|Delegates Input| PlayerInputManager + PlayerInputManager -->|Commands| PlayerMovementManager + PlayerMovementManager -->|Collisions| SfxManager + + Lobby[lobby.tscn] -->|Meta| UserProfileManager + Lobby -->|Pulls| GachaManager + UserProfileManager <--> NakamaManager + GachaManager <--> NakamaManager +``` diff --git a/Architecture-Server.md b/Architecture-Server.md new file mode 100644 index 0000000..1ff5da3 --- /dev/null +++ b/Architecture-Server.md @@ -0,0 +1,58 @@ +# Tekton Dash Armageddon - Server Architecture + +## Nakama Backend (`server/nakama/lua/`) + +The backend runs on Nakama, written in Lua. It provides authoritative server-side logic for the economy, anti-cheat, mail, and gacha pulls. + +Godot clients call these endpoints via `BackendService.api_rpc_async()`. + +### Key Lua Modules +- **`economy.lua`:** + - `buy_currency`: Validates mock/Google/Apple receipts and directly adds Gold or subtracts Gold for Stars via `nk.wallet_update`. + - `purchase_item`: Buys cosmetic items from the shop catalog. Validates wallet funds and writes to `inventory` storage. +- **`gacha.lua`:** + - `perform_gacha_pull`: Reads banner drop rates, rolls RNG on the server, manages pity counters, and deducts the pull cost from the wallet. Prevents client-side RNG manipulation. +- **`inbox.lua`:** + - `get_mail` / `claim_mail_reward`: Server-authoritative mail system. Rewards attached to mail are granted directly to the wallet on claim. +- **`user.lua` & `admin.lua`:** + - `admin_topup_gold`: Admin-only RPC to grant 999,999 gold. + - `admin_ban_player`: Banning tool. + - Profile and friend sync logic. + +## Client / Server Wallet Synchronization + +There is **only one authoritative wallet** per user stored on the Nakama backend. + +1. Lua calls `nk.wallet_update(changeset)` upon any transaction. +2. The Godot client calls `UserProfileManager._reload_wallet()`. +3. Godot fetches the new JSON string from `account.wallet`. +4. `UserProfileManager` emits `profile_updated`. +5. All connected UI components (Lobby Top Bar, Shop Panel, Gacha Panel) instantly update their text labels to reflect the unified `gold` and `star` balances. + +## CI/CD and Hot-Patching Pipeline (`.gitea/workflows/`) + +The game features two distinct automated deployment pipelines. + +### Full Releases (`ci.yml`) +- **Trigger:** Pushing a git tag (e.g. `v3.0.0`). +- **Purpose:** Compiling heavy native binaries (Windows `.exe`, Linux binaries, macOS `.app`). +- **Flow:** + 1. Clones repository. + 2. Pulls cached Godot 4.7 binary and export templates from `/cache/` on the runner to skip the 1.3GB download. + 3. Runs `godot --headless --export-release` for each platform. + 4. Zips outputs and uploads to Gitea's release asset API. +- **Player Experience:** Must download and replace their entire game folder/executable. + +### Hot-Patching (`deploy_patch.yml`) +- **Trigger:** Manual `workflow_dispatch` button from the Gitea UI. +- **Purpose:** Pushing lightweight Godot asset changes (Scripts, Scenes, VFX, Sounds) instantly. +- **Flow:** + 1. Python script `generate_version_json.py` consumes `CHANGELOG_DRAFT.md` and bumps `version.json`. + 2. Runs `godot --headless --export-pack` to build a single, shared `patch.pck` file. + 3. Force-pushes `patch.pck` and `version.json` to the orphan `patches` git branch. + 4. A `gitea-pages` Docker container serves this branch publicly at `https://raw.klud.top`. +- **Player Experience:** + 1. Game boots to `boot_screen.tscn`. + 2. Fetches `https://raw.klud.top/danchie/tekton/version.json`. + 3. Downloads `patch.pck` if the version is newer. + 4. Mounts it into `user://` to override the base `res://` filesystem seamlessly. diff --git a/Home.md b/Home.md index 41d1913..6d7520a 100644 --- a/Home.md +++ b/Home.md @@ -24,6 +24,8 @@ First-time SSH setup: ## Pages +- [Architecture - Client](./Architecture-Client) — Core Godot game loop, Singletons, and Node dependencies. +- [Architecture - Server](./Architecture-Server) — Nakama Lua backend, Wallets, and CI/CD Build pipelines. - [Skin Creation Workflow](./Skin-Creation-Workflow) — Authoring skin materials and registering them in the catalog. - [Nakama Deployment](./Nakama-Deployment) — Pushing the shop/gacha backend to the Nakama VPS. - [Patch Release Workflow](./Patch-Release-Workflow) — Building, versioning, and shipping patches to live clients.