+
+
+
+
+ + Knowledge Base & Production Deployment Blueprint +
++ A highly descriptive, production-centric strategy for engineering global, multi-store authentication, + transaction validation, and regulatory compliance networks utilizing Godot 4 and Heroic Labs Nakama. +
+ +
+
+
+
+
+
+
+
+ Core Jurisdictions +
+
+
+
+
+
+
+ Europe, Mainland China Transit & APAC
+ Networks
+
+
+
+
+
+
+ IAP Validation
+Asynchronous, Server-to-Server, Ledger-Signed + Receipt Verification
+
+
+
+
+
+ Store Integration
+Steamworks, Google Play, Apple App Store, TapSDK + (Zero-Commission)
+
+
+
+ 1. Regional Infrastructure & Regulatory Compliance
++ Deploying cross-border games requires careful partitioning of databases and game nodes to satisfy + extreme technical boundaries (e.g., latency issues caused by the Great Firewall) and data protection + statutes (e.g., GDPR, local municipal privacy mandates). +
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+ Europe
+ (EU) - Webdock
+
+
+ GDPR & DMA Pipeline
+-
+
- Central + Cluster: Host on high-density Webdock.io Ryzen-powered VPS + profiles located in Frankfurt or Vienna. +
- + Sovereignty: Webdock offers EU-owned infrastructure with strict + hardware insulation and zero overseas sub-processor data leaks. +
- User + Control: Integrate explicit game-level telemetry opt-out flags which halt + outgoing Nakama analytics scripts instantly. +
+
+
+
+
+
+
+
+
+ China
+ Transit - HostHatch
+
+
+ HostHatch HK Edge Gateway
+-
+
- GFW + Proximity: Deploy regional proxy logic to HostHatch.com + Hong Kong nodes, featuring direct low-latency peering tunnels. +
- Regulatory + Separation: Standalone DB instances keep Mainland China data segregated + from Western clusters while resolving network hops near the target audience. +
- NPPA + Integrations: Route localized traffic from HK edge to Chinese validation + and anti-addiction registry backends efficiently. +
+
+
+
+
+
+
+
+ Asia
+ (Ex-CN) - Following CN
+
+
+ APAC Edge Arrays
+-
+
- Transit + Integration: Set up edge nodes in Tokyo, Seoul, and Singapore configured to + capture traffic spills when cross-border HK connections are saturated. +
- Latency + Optimization: Run high-performance CockroachDB clusters to maintain global + synchronization while serving nearby regional users under 45ms. +
- Data + Privacy: Satisfy local guidelines (Japan's APPI, South Korea's PIPA) using + explicit user data deletion interfaces inside Nakama profile routes. +
+
+
+
+ Critical GFW Operational Warning:
+ Real-time WebSocket and UDP connection signals across the Great Firewall suffer massive packet
+ losses (≥ 25%). Incorporating HostHatch's Hong Kong node acts as an indispensable entry buffer;
+ however, complete logical segregation of the Chinese client backend instance is still mandatory.
+
+
+
+
+
+
+ 2. Storefront Commissions & Licensing Pipeline
++ Operating margins rely on optimizing each storefront's fee parameters. Before collecting gross revenue, + publishers must clear the initial platform entry fees. +
+ + +
+
+
+ + + Initial Publishing Costs & First Fee Settlement Grid +
++ Below is the required capital breakdown needed to register your identity and prepare storefront + slots before pushing your initial Godot client build to production channels. +
+
+
+
+
+
+ | Platform | +First Fee Amount | +Market Flag | +Fee Recurrence Type | +Refundability Status | +Settlement Methods | +
|---|---|---|---|---|---|
| Steamworks (PC) | +$100.00 USD (per product) | ++ + | +One-time per App Slot | +Yes (Refunded after $1,000 in gross sales) + | +Credit Card, PayPal, Steam Wallet, Wire Transfer | +
| Itch.io (PC) | +$0.00 USD (Zero entry fee) | ++ + | +None | +Not Applicable | +None (Optional tax documentation verification) | +
| Google Play | +$25.00 USD | ++ + | +One-time per Developer Identity | +No | +Credit/Debit Card (requires Google Pay Profile) | +
| Apple App Store | +$99.00 USD | ++ + | +Annual Subscription Renewal | +No | +Credit Card (linked to Apple ID Developer Account) | +
| TapTap Developer | +$0.00 USD (Corporate validation) | ++ + + | +None | +Not Applicable | +Requires legal corporate identity / ICP verification | +
+ Net Yield Production
+ Formula
+
+
+
+
+ R_net = R_gross × (1 - C_store - T_tax) - F_fees
+
+ + Where C_store matches the target store platform commission, T_tax matches regional withholding taxes, and F_fees encapsulates external server transaction margins and API + query operations. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Steamworks Implementation Matrix
+| Commission Rate | +30% (Default) | +
| Volume Scaling | +25% at $10M | 20% at $50M | +
| First Fee | +$100 USD (Steam Direct + App Deposit) | +
| Nakama Verification | +Server Authenticated + Session Ticket | +
+
+ Technical + Execution
+
+ Initialize GodotSteam
+ dynamically inside your client. The user retrieves their secure hex session ticket
+ locally, passing it down to Nakama using the native client driver hook to eliminate
+ credential spoofing risks.
+
+
+
+ 3. Monetization Architecture & Secure IAP Loop
++ Client-side reporting is inherently untrustworthy. Memory injectors (e.g., Lucky Patcher on Android, + memory editing tools on PC) can manipulate the client runtime to simulate successful purchases. + Implementing a robust, asynchronous verification cycle ensures validation is handled strictly by the + server. +
+ + +
+
+ Asynchronous Verification Topology
+ +
+
+
+
+
+
+
+ 1
+ Purchase & Tokenization
+The Godot client requests checkout. The player submits payment + to the store network, which issues an encrypted, signed platform transaction token.
+
+
+
+
+ 2
+ Nakama RPC Ingestion
+The client forwards the raw transaction token securely to
+ Nakama via an RPC function call: verify_purchase.
+
+
+
+ 3
+ Server Validation Check
+Nakama blocks immediate user manipulation. It connects + server-to-server with Google, Apple, or Steam APIs to verify status and signatures.
+
+
+
+ 4
+ Ledger Provisioning
+Upon verification, Nakama updates the persistent storage + wallet data and broadcasts confirmation back to the Godot client.
+
+
+
+ 4. Core Architecture: Unified Identity Manager Decision Flow + Chart
++ The Unified Identity Manager dynamically discovers platforms at runtime, resolving features and + singletons without breaking compilations on platforms lacking those SDK wrappers. Click the platform + modes below to preview the path execution, safety hooks, and token routing. +
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Game
+ Initialization
+ _ready() / dispatch_platform_auth()
+Queries environment architecture and singletons
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+ PC
+ Steam Target
+
+
+ PC
+ Steam Target
+
+
+
+
+ Class Check
+ ClassDB.has_singleton("Steam")
+
+
+
+ Ticket Retrieval
+ Grabs session hex ticket asynchronously +
+
+
+
+ Nakama Endpoint
+ authenticate_steam_async()
+
+
+
+
+
+ 
+ Android
+ OS Target
+
+
+ Android
+ OS Target
+
+
+
+
+ Feature Gating
+ OS.has_feature("taptap")
+
+ YesNo
+
+
+
+
+ TapSDK
+ Fetch OAuth Token
+
+
+ Google Play
+ Fetch Auth Code
+
+
+
+ Nakama Endpoint
+ authenticate_custom_async()
OR
authenticate_google_async()
+
+
+
+
+
+ 
+ iOS
+ OS Target
+
+
+ iOS
+ OS Target
+
+
+
+
+ Feature Gating
+ OS.has_feature("taptap")
+
+ YesNo
+
+
+
+
+ TapSDK
+ Fetch OAuth Token
+
+
+ Apple Auth
+ Fetch Identity Token
+
+
+
+ Nakama Endpoint
+ authenticate_custom_async()
OR
authenticate_apple_async()
+
+
+
+
+ 
+ PC/Itch.io
+ Standalone
+
+
+ PC/Itch.io
+ Standalone
+
+
+
+
+ Device Hardware ID
+ OS.get_unique_id()
+
+
+
+ Hardware Hashing
+ Generate hardware fingerprint
+
+
+
+ Nakama Endpoint
+ authenticate_device_async()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Nakama Server Response Node
+
+ NakamaSession Established
++ Session token decoded & validated, persistent profiles resolved, and socket pipelines + opened. Global matching/telemetry gates unlocked. +
+
+
+
+
+
+ 5. Project Management (PR) Board & AI Checklist
++ This section serves as a fully detailed tracking board. It merges production readiness, backend reconstruction, gameflow audit, and Steam depot release tasks. + Every task is fully expanded with checklists and automated testing criteria so you can track AI execution seamlessly. +
+ +
+
+
+
+ Priority Rule
++ Do not spend release time on Steam depot upload, signing polish, or branch promotion until P0 backend authority + is fixed. Current audit found client-authoritative economy, gacha paths, and sync loopholes. + Those are launch blockers because they can corrupt wallet, inventory, match state, and account identity before first public build. +
+
+
+
+
+
+
+
+
+
+
+ P0
+ PRD-P0-1
+ Economy Authority
+
+
+
+
+
+
+ Economy Authority
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ server/nakama/tekton_admin.js, user_profile_manager.gd
+
+
+
+
+ Goal / Risk
+Stop trusting client prices, categories, package IDs. Reconstruct server-authoritative economy.
+
+
+ Execution Checklist
+-
+
- Create server catalog mapping item IDs to category, price, currency type, stack rules.
- Change purchase request so client sends only item ID, quantity, and optional idempotency key.
- Validate balance and inventory capacity server-side before mutation.
- Replace fake currency purchase with receipt verification placeholder interface per platform.
- Write wallet/inventory mutation audit entry with user ID, request ID, before/after values. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Analyze current Tekton economy flow in server/nakama/tekton_admin.js and Godot callers. Reconstruct shop purchase authority so the client no longer sends trusted price_gold, price_star, category, or reward data. Add a server-side item catalog and update rpcPurchaseItem to accept only item_id, quantity, and idempotency_key. Replace rpcBuyCurrency behavior with a receipt-verification-safe interface that records pending/verified transactions and never grants premium currency from package ID alone. Preserve existing profile/wallet behavior where possible. Add validation, normalized errors, and audit ledger writes. Update Godot callers to match new payload shape. Acceptance: no wallet or inventory mutation depends on client-submitted price/category/package intent; duplicate idempotency key does not duplicate grant; existing shop UI can still request purchases.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Call `rpcPurchaseItem` with modified price/category from client. Assert server rejects or ignores client price and uses catalog price. Assert duplicate idempotency keys return the exact same transaction result without deducting twice.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P0-1]: Economy Authority** +- **Goal:** Stop trusting client prices, categories, package IDs. Reconstruct server-authoritative economy. +- **Status:** Integrated & verified. Code changes applied to: server/nakama/tekton_admin.js, user_profile_manager.gd+ +
+
+
+
+
+
+
+ P0
+ PRD-P0-2
+ Gacha Authority
+
+
+
+
+
+
+ Gacha Authority
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ gacha_manager.gd, Nakama economy RPCs
+
+
+
+
+ Goal / Risk
+Move RNG, pity, cost consume, and rewards server-side.
+
+
+ Execution Checklist
+-
+
- Add server RPC for gacha pull with banner ID, pull count, and idempotency key.
- Store pity and banner state server-side.
- Server consumes cost, rolls reward, writes item/fragment result, and returns canonical result.
- Client only animates returned result; no local grant or deduction.
- Add migration note for existing local pity/fragment data. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Refactor Tekton gacha so authority lives in Nakama. Read scripts/managers/gacha_manager.gd, user_profile_manager.gd, and server/nakama/tekton_admin.js before editing. Add server-side RPCs for gacha_pull and any needed banner/profile state. Server must own RNG, pity counter, cost deduction, reward choice, inventory/fragment writes, and audit/idempotency. Client must become presentation-only: it sends banner_id, pull_count, and idempotency_key, then animates the canonical server response. Remove local reward grant and local currency deduction from gacha_manager.gd. Acceptance: editing client RNG/pity code cannot change real rewards; duplicate pull request cannot duplicate rewards; profile refresh after pull shows server state.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Trigger `rpcGachaPull`. Assert client currency deduction happens only upon server response. Assert client cannot specify reward or manipulate RNG seed.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P0-2]: Gacha Authority** +- **Goal:** Move RNG, pity, cost consume, and rewards server-side. +- **Status:** Integrated & verified. Code changes applied to: gacha_manager.gd, Nakama economy RPCs+ +
+
+
+
+
+
+
+ P0
+ PRD-P0-3
+ Auth & Secrets Lock
+
+
+
+
+
+
+ Auth & Secrets Lock
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ auth_manager.gd, nakama_manager.gd, project.godot
+
+
+
+
+ Goal / Risk
+Remove insecure Steam fallback, default App ID 480, hardcoded release secrets.
+
+
+ Execution Checklist
+-
+
- Replace production Steam App ID placeholder only when real ID exists.
- Fail hard in Steam build if Steam ticket cannot be acquired.
- Remove fallback email/custom auth from Steam release path.
- Externalize server host, scheme, key, encryption key, and secrets.
- Delete or environment-gate admin topup RPC and admin UI entry points. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Audit and harden Tekton authentication and admin mutation paths. Read project.godot, scripts/services/steamworks_manager.gd, scripts/managers/auth_manager.gd, scripts/nakama_manager.gd, scripts/ui/admin_panel.gd, and server/nakama/tekton_admin.js. Remove insecure Steam release fallback behavior so Steam builds authenticate only with valid Steam tickets. Add clear release guards for Steam App ID 480 so production export fails or warns loudly if still using test ID. Externalize backend config and local encryption material away from hardcoded production defaults. Remove or environment-gate rpcAdminTopupGold and ensure admin panel scenes/scripts are not included in player exports unless explicitly feature-flagged. Acceptance: Steam build cannot silently fall back to insecure auth; test App ID 480 is blocked for production; admin mint path is unavailable in production runtime.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Export project with Steam features. Disconnect Steam client. Assert game fails to authenticate and does NOT fallback to custom/device auth. Assert admin UI is entirely hidden in release builds.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P0-3]: Auth & Secrets Lock** +- **Goal:** Remove insecure Steam fallback, default App ID 480, hardcoded release secrets. +- **Status:** Integrated & verified. Code changes applied to: auth_manager.gd, nakama_manager.gd, project.godot+ +
+
+
+
+
+
+
+ P0
+ PRD-P0-4
+ Backend Deploy Safety
+
+
+
+
+
+
+ Backend Deploy Safety
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ server/, Nakama runtime module
+
+
+
+
+ Goal / Risk
+Replace manual module copy/restart with staging/prod deploy, health check, rollback.
+
+
+ Execution Checklist
+-
+
- Separate dev/staging/prod Nakama config and secrets.
- Script module package/copy/restart with version label.
- Add health check RPC after deploy.
- Keep previous module artifact for rollback.
- Add smoke checklist: auth, profile, shop, mail, gacha, friends, leaderboard. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Create a production-safe Nakama deployment workflow for Tekton. Review server/docker-compose.yaml, server/nakama/README.md, and current runtime module layout. Replace manual docker cp guidance with scripts or documented commands for staging and production deploys. Include environment-specific config/secrets, module version labeling, restart procedure, health check, smoke test commands, and rollback to previous module. Do not commit real secrets. Acceptance: a developer can deploy to staging, verify health, promote to production, and rollback using documented repeatable steps without manually editing containers.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Run deploy script. Assert Nakama server restarts without losing data. Trigger health check RPC to verify new module loaded successfully.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P0-4]: Backend Deploy Safety** +- **Goal:** Replace manual module copy/restart with staging/prod deploy, health check, rollback. +- **Status:** Integrated & verified. Code changes applied to: server/, Nakama runtime module+ +
+
+
+
+
+
+
+ P0
+ PRD-GF-P0-1
+ Spawn/Sync Authority Lock
+
+
+
+
+
+
+ Spawn/Sync Authority Lock
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ main.gd, player.gd
+
+
+
+
+ Goal / Risk
+Retain: deterministic pre-spawn sync. Remove: client-trusted teleport/update paths.
+
+
+ Execution Checklist
+-
+
- Keep deterministic pre-spawn strategy (client pre-creates lobby roster).
- Remove client-trusted position mutation path that can move authoritative state without server validation.
- Introduce server-owned spawn_revision and state_revision integers.
- Reject stale updates on client and server.
- Ensure reconnect flow requests full player sync, then grid sync, then mode-specific sync. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Audit and harden player spawn/sync authority in scenes/main.gd and scenes/player.gd. Keep deterministic pre-spawn strategy and existing server-authoritative item randomization pattern, but remove any client-trusted position mutation path that can move authoritative state without server validation. Introduce server-owned spawn_revision and state_revision integers sent with spawn and full-sync payloads. Reject stale updates on client and server. Ensure reconnect flow requests full player sync first, then full grid sync, then mode-specific sync (Stop n Go / Tekton Doors) with explicit ack step. Acceptance: client cannot force authoritative teleport; reconnecting client converges to identical player positions/goals/playerboards after one sync cycle; stale packets no longer overwrite newer state.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Simulate client sending stale spawn_revision. Assert server rejects. Reconnect mid-match, assert player converges to exact same grid position as before.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-GF-P0-1]: Spawn/Sync Authority Lock** +- **Goal:** Retain: deterministic pre-spawn sync. Remove: client-trusted teleport/update paths. +- **Status:** Integrated & verified. Code changes applied to: main.gd, player.gd+ +
+
+
+
+
+
+
+ P0
+ PRD-GF-P0-2
+ Lobby Start Gate Hardening
+
+
+
+
+
+
+ Lobby Start Gate Hardening
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ lobby.gd, lobby_manager.gd
+
+
+
+
+ Goal / Risk
+Add preflight checklist RPC, check ready-state and host authority.
+
+
+ Execution Checklist
+-
+
- Preserve LAN/Nakama dual-mode behavior and tutorial fast path.
- Add preflight readiness checks before _on_game_starting transition.
- Verify session valid, host authority true, all player records present, mode config validated.
- Add one typed preflight result object and render actionable errors. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Rework lobby game-start gating in scenes/lobby.gd and scripts/managers/lobby_manager.gd. Preserve LAN/Nakama dual-mode behavior and tutorial fast path, but add preflight readiness checks before _on_game_starting transition: session valid (or explicit guest/LAN mode), host authority true, all required player records present, mode config validated, and scene dependencies reachable. Add one typed preflight result object and render actionable errors in connection_status/status_label. Acceptance: start button cannot trigger broken scene load with partial state; host and clients see same preflight result; loading screen transition only occurs after preflight pass.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Attempt to start match without full player records. Assert UI blocks start and shows specific error string from preflight check.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-GF-P0-2]: Lobby Start Gate Hardening** +- **Goal:** Add preflight checklist RPC, check ready-state and host authority. +- **Status:** Integrated & verified. Code changes applied to: lobby.gd, lobby_manager.gd+ +
+
+
+
+
+
+
+ P0
+ PRD-GF-P0-3
+ RPC Sender Identity & Contract Clamp
+
+
+
+
+
+
+ RPC Sender Identity & Contract Clamp
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ main.gd, player.gd, lobby_manager.gd
+
+
+
+
+ Goal / Risk
+Remove payload fields that claim identity. Validate sender natively.
+
+
+ Execution Checklist
+-
+
- Read all any_peer RPC entry points.
- Remove payload fields that pretend to identify requester/authority (use get_remote_sender_id).
- Verify sender identity and authority explicitly for state-mutation RPCs.
- Normalize RPC contracts to carry stable error codes. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Clamp multiplayer RPC trust boundaries across scenes/main.gd, scenes/player.gd, and scripts/managers/lobby_manager.gd. Read all any_peer RPC entry points before editing. Keep fast RPC update flow, but remove payload fields that pretend to identify requester/authority when sender can be derived from multiplayer.get_remote_sender_id(). For room info, start flow, rematch, and state-mutation RPCs, verify sender identity and authority explicitly. Normalize RPC contracts so request payloads contain only data the caller is allowed to propose, and response payloads carry canonical server state plus stable error codes. Acceptance: spoofed requester IDs are ignored; unauthorized peers cannot mutate host/server-owned state; RPC errors are debuggable and consistent.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Call state-mutation RPC pretending to be another peer ID in payload. Assert server overrides payload with actual `get_remote_sender_id()` and blocks if unauthorized.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-GF-P0-3]: RPC Sender Identity & Contract Clamp** +- **Goal:** Remove payload fields that claim identity. Validate sender natively. +- **Status:** Integrated & verified. Code changes applied to: main.gd, player.gd, lobby_manager.gd+ +
+
+
+
+
+
+
+ P0
+ PRD-GF-P0-4
+ Chat/DM Abuse Control
+
+
+
+
+
+
+ Chat/DM Abuse Control
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ lobby.gd, Nakama chat
+
+
+
+
+ Goal / Risk
+Add moderation, throttling, sanitation, flood guard, and permission matrix.
+
+
+ Execution Checklist
+-
+
- Keep current channel UX, DM tabs, and history pull.
- Add per-user send cooldown and max payload length limits.
- Add command permission matrix (/clear admin only, all other slash commands explicit).
- Mark unsent/failed messages in UI with retry policy. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Harden global chat and DM flow in scenes/lobby.gd and related Nakama chat policy. Keep current channel UX, DM tabs, and history pull, but add abuse controls: per-user send cooldown, max payload length, profanity/moderation hook placeholder, and command permission matrix (/clear admin only, all other slash commands explicit). Fix any DM append/state bug found during read-through. Prevent silent local-only divergence by marking unsent/failed messages in UI and retry policy. Acceptance: flood attempts are throttled; unauthorized command execution blocked server-side; message rendering sanitized and bounded; chat remains responsive under burst traffic.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Send 50 chat messages in 1 second. Assert Nakama throttles request and UI shows 'failed to send/cooldown' UI marker. Attempt `/clear` as non-admin, assert blocked.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-GF-P0-4]: Chat/DM Abuse Control** +- **Goal:** Add moderation, throttling, sanitation, flood guard, and permission matrix. +- **Status:** Integrated & verified. Code changes applied to: lobby.gd, Nakama chat+ +
+
+
+
+
+
+
+ P1
+ PRD-P1-1
+ Module Split & RPC Validation
+
+
+
+
+
+
+ Module Split & RPC Validation
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ tekton_admin.js
+
+
+
+
+ Goal / Risk
+Split monolith into auth, economy, admin, mail, social, leaderboard, validation helpers.
+
+
+ Execution Checklist
+-
+
- Refactor tekton_admin.js into domain modules without changing external RPC names.
- Create modules for auth, economy, admin, mail, social, leaderboard, storage, validation.
- Add central validators for payload shape, types, limits.
- Add normalized error responses with stable error codes. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Refactor server/nakama/tekton_admin.js into maintainable domain modules without changing external RPC names unless necessary. Create or plan modules for auth, economy, admin, mail, social, leaderboard, storage, and validation helpers. Add central validators for payload shape, types, limits, and allowed enum values. Add normalized error responses with stable error codes. Keep behavior compatible while moving code in small steps. Acceptance: RPC registration remains clear; each RPC validates payload before mutation; error responses are consistent; module split does not break existing smoke tests.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Call split RPC with missing payload fields. Assert central validator catches it and returns `INVALID_ARGUMENT` standard error code.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P1-1]: Module Split & RPC Validation** +- **Goal:** Split monolith into auth, economy, admin, mail, social, leaderboard, validation helpers. +- **Status:** Integrated & verified. Code changes applied to: tekton_admin.js+ +
+
+
+
+
+
+
+ P1
+ PRD-P1-2
+ Ledger, Idempotency & Storage Model
+
+
+
+
+
+
+ Ledger, Idempotency & Storage Model
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ Wallet, inventory, fragments, mail rewards
+
+
+
+
+ Goal / Risk
+Add mutation audit ledger, idempotency keys, and canonical fragment storage path.
+
+
+ Execution Checklist
+-
+
- Define one canonical fragment storage location and migration path.
- Add idempotency keys for mail claim, daily reward, purchase, gacha, and admin adjustments.
- Add audit records with source, user_id, mutation type, request_id.
- Make mail claim transactional (claim, mark, return canonical state). +
+
+
+
+
+ AI Execution Prompt
+
+
+ Implement a canonical mutation ledger and idempotency policy for Tekton live-service rewards. Read server/nakama/tekton_admin.js, scripts/managers/user_profile_manager.gd, scripts/managers/mail_manager.gd, and gacha/profile storage code. Define one canonical fragment storage location and migration path. Add idempotency keys for mail claim, daily reward, purchase, gacha, and admin adjustments. Add audit records with source, user_id, mutation type, request_id, before/after summary, and timestamp. Make mail claim transactional: claim rewards, mark claimed, and return canonical updated state in one server response. Acceptance: repeated claim/purchase/reward requests do not duplicate grants; fragments read/write from one canonical path; mail UI refreshes from server-returned state.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Send identical mail claim RPC twice simultaneously. Assert only one processes successfully and the second returns 'already claimed'.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P1-2]: Ledger, Idempotency & Storage Model** +- **Goal:** Add mutation audit ledger, idempotency keys, and canonical fragment storage path. +- **Status:** Integrated & verified. Code changes applied to: Wallet, inventory, fragments, mail rewards+ +
+
+
+
+
+
+
+ P1
+ PRD-P1-3
+ Client Backend Facade
+
+
+
+
+
+
+ Client Backend Facade
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ nakama_manager.gd, auth_manager.gd, backend_service.gd
+
+
+
+
+ Goal / Risk
+Make one typed backend owner for session, socket, RPC calls, and central errors.
+
+
+ Execution Checklist
+-
+
- Decide whether BackendService becomes the sole typed backend facade or is deleted.
- Implement one owner for client/session/socket.
- Add typed methods for RPCs, central error handling.
- Remove direct UI RPC scatter for economy/auth/mail/gacha/social flows. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Clean up Tekton client backend ownership. Read scripts/nakama_manager.gd, scripts/managers/auth_manager.gd, scripts/services/backend_service.gd, and UI/manager scripts that call NakamaManager.client.rpc_async directly. Decide whether BackendService becomes the sole typed backend facade or is deleted. Implement chosen direction in small steps: one owner for client/session/socket, typed methods for RPCs, central error handling, and no direct UI RPC scatter for economy/auth/mail/gacha/social flows. Acceptance: UI calls typed service/manager methods, not raw client.rpc_async; session/socket ownership is clear; duplicate auth/bootstrap code is removed or delegated.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Global search for `client.rpc_async` in `scripts/ui/`. Assert 0 results found (all go through facade).
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P1-3]: Client Backend Facade** +- **Goal:** Make one typed backend owner for session, socket, RPC calls, and central errors. +- **Status:** Integrated & verified. Code changes applied to: nakama_manager.gd, auth_manager.gd, backend_service.gd+ +
+
+
+
+
+
+
+ P1
+ PRD-GF-P1-1
+ Tutorial Isolation Contract
+
+
+
+
+
+
+ Tutorial Isolation Contract
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ tutorial_manager.gd
+
+
+
+
+ Goal / Risk
+Remove multiplayer-side effects during pause/freeze phases. Isolate tutorial boundaries.
+
+
+ Execution Checklist
+-
+
- Keep onboarding sequence and camera storytelling.
- Enforce contract: no persistent wallet/profile mutation during tutorial.
- Ensure no shared lobby state leakage.
- Ensure clean bot/timer restore on exit, deterministic return-to-lobby handshake.
- Replace broad pause/freeze side effects with scoped tutorial-state toggles. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Isolate tutorial runtime from multiplayer/session side effects. Review scripts/managers/tutorial_manager.gd and match lifecycle hooks. Keep onboarding sequence and camera storytelling, but enforce tutorial contract: no persistent wallet/profile mutation, no shared lobby state leakage, clean bot/timer restore on exit, deterministic return-to-lobby handshake. Replace broad pause/freeze side effects with scoped tutorial-state toggles where possible. Acceptance: exiting tutorial leaves no stale bot freeze, no leaked paused systems, and no corrupted room/session flags.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Abort tutorial midway. Assert main game tree is fully unpaused, bots are reset, and no 'tutorial_active' flags leak into lobby.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-GF-P1-1]: Tutorial Isolation Contract** +- **Goal:** Remove multiplayer-side effects during pause/freeze phases. Isolate tutorial boundaries. +- **Status:** Integrated & verified. Code changes applied to: tutorial_manager.gd+ +
+
+
+
+
+
+
+ P1
+ PRD-GF-P1-2
+ Mode Config Completeness
+
+
+
+
+
+
+ Mode Config Completeness
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ main.gd, lobby mode configs
+
+
+
+
+ Goal / Risk
+Remove duplicated/inconsistent option toggles. Add schema-driven validation.
+
+
+ Execution Checklist
+-
+
- Keep existing Stop n Go custom UI.
- Remove duplicated/fragile control toggles.
- Implement Tekton Doors options with same host-authoritative lock and sync callbacks.
- Introduce schema-driven config validation shared by host, client, and bootstrap. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Complete mode-configuration parity between Stop n Go and Tekton Doors in lobby and match bootstrap flow. Keep existing Stop n Go custom UI, but remove duplicated/fragile control toggles and implement Tekton Doors options with same host-authoritative lock and sync callbacks. Introduce schema-driven config validation shared by host, client display logic, and match bootstrap. Acceptance: both modes expose full validated config; non-host clients always mirror host values; invalid config rejected before match start.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Join as client, attempt to spoof mode config RPC. Assert host rejects invalid mode config changes and overrides client.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-GF-P1-2]: Mode Config Completeness** +- **Goal:** Remove duplicated/inconsistent option toggles. Add schema-driven validation. +- **Status:** Integrated & verified. Code changes applied to: main.gd, lobby mode configs+ +
+
+
+
+
+
+
+ P1
+ PRD-GF-P1-3
+ Backend Facade & Flow Decoupling
+
+
+
+
+
+
+ Backend Facade & Flow Decoupling
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ backend_service.gd, UI panels
+
+
+
+
+ Goal / Risk
+Improve service ownership and typed errors. Add one backend facade.
+
+
+ Execution Checklist
+-
+
- Identify remaining UI/manager scripts calling client.rpc_async.
- Migrate calls to the central BackendService or unified manager.
- Implement central error mapping and retry policy.
- Verify all gameflow-adjacent UI uses new typed methods. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Finish client backend decoupling for gameflow-adjacent live-service features. Read scripts/services/backend_service.gd plus UI/manager scripts that still call NakamaManager.client.rpc_async directly (profile, social, leaderboard, daily reward, mail, admin, friend flows). Decide whether BackendService becomes real facade or is removed. Implement one typed backend owner for auth/session/socket/RPC calls, central error mapping, and retry policy. Acceptance: gameflow-adjacent UI does not call raw client.rpc_async directly for production paths; backend ownership is obvious; future auth/RPC changes touch one service layer first, not many UI panels.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Trigger network failure during profile fetch. Assert BackendService retry policy handles it gracefully without UI hard-crashing.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-GF-P1-3]: Backend Facade & Flow Decoupling** +- **Goal:** Improve service ownership and typed errors. Add one backend facade. +- **Status:** Integrated & verified. Code changes applied to: backend_service.gd, UI panels+ +
+
+
+
+
+
+
+ P1
+ PRD-P1-4
+ Versioning & Patch Integrity
+
+
+
+
+
+
+ Versioning & Patch Integrity
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ tools/, export_presets.cfg, version.json
+
+
+
+
+ Goal / Risk
+Single release version source, checksums, compatibility rules, changelog archive.
+
+
+ Execution Checklist
+-
+
- Create one release version source (version.json or python script).
- Update project version, export versions, Android version deterministically.
- Update patch manifest and changelog archive.
- Add patch integrity fields: checksum, size, minimum compatible app version. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Rebuild Tekton versioning workflow. Review tools/generate_version_json.py, tools/build_patch.gd, export_presets.cfg, project.godot, assets/data/version.json, README.md, and CHANGELOG_DRAFT.md. Create one release version source and update all platform metadata deterministically: project version, export versions, Android version/code, patch manifest, changelog archive, and Git tag instructions. Add patch integrity fields such as checksum, size, minimum compatible app version, and signature placeholder if signing is not available yet. Acceptance: one command or documented flow bumps release version; generated metadata matches across files; patch manifest can reject incompatible or corrupted patch.pck.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Run version bump script. Assert export_presets.cfg Android version code increments correctly and patch manifest checksum is updated.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P1-4]: Versioning & Patch Integrity** +- **Goal:** Single release version source, checksums, compatibility rules, changelog archive. +- **Status:** Integrated & verified. Code changes applied to: tools/, export_presets.cfg, version.json+ +
+
+
+
+
+
+
+ P2
+ PRD-P2-1
+ Steam Depot & Store Packaging
+
+
+
+
+
+
+ Steam Depot & Store Packaging
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ tools/steam/, export presets
+
+
+
+
+ Goal / Risk
+Create SteamPipe VDFs, branch SOP, signing/notarization, platform filters.
+
+
+ Execution Checklist
+-
+
- Create tools/steam/app_build_
.vdf and per-platform depot templates. - Document steamcmd upload command, branch promotion path.
- Add guidance for Windows signing, macOS notarization, Android package name.
- Configure store-specific export filters. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Add Steam and storefront release packaging workflow for Tekton after P0/P1 backend gates are complete. Review export_presets.cfg, docs/STEAMWORKS_SETUP.md, README.md, and current build output conventions. Create tools/steam/app_build_+ +.vdf and per-platform depot VDF templates using placeholders only. Document steamcmd upload command, branch promotion path internal -> beta -> default, and smoke tests required before promotion. Add guidance for Windows signing, macOS bundle/team/notarization, Android final package name/version code, and store-specific export filters so Steam libraries are not shipped in non-Steam builds. Acceptance: no real IDs/secrets committed; SteamPipe templates exist; release checklist blocks default branch promotion until smoke tests pass.
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Trigger dry-run of SteamPipe VDF. Assert paths resolve to output directory without committing real credentials.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-P2-1]: Steam Depot & Store Packaging** +- **Goal:** Create SteamPipe VDFs, branch SOP, signing/notarization, platform filters. +- **Status:** Integrated & verified. Code changes applied to: tools/steam/, export presets+ +
+
+
+
+
+
+
+ P2
+ PRD-GF-P2-1
+ Dead Path, Debug Gate & Telemetry Cleanup
+
+
+
+
+
+
+ Dead Path, Debug Gate & Telemetry Cleanup
+
+
+
+
+
+
+
+
+
+
+ Files / Areas
+
+ main.gd, player.gd, placeholders
+
+
+
+
+ Goal / Risk
+Remove release-noisy debug hooks. Add safe-remove candidate matrix + SLO dashboard.
+
+
+ Execution Checklist
+-
+
- Build matrix: keep, safe-remove, needs-runtime-proof, feature-flag.
- Remove or feature-gate release-only noise (e.g., debug key hooks, excessive prints).
- Instrument events: room_joined, preflight_pass, loading_screen, match_sync.
- Do not delete autoload/runtime-loaded scripts without proof. +
+
+
+
+
+ AI Execution Prompt
+
+
+ Create dead-path/debug-path cleanup and telemetry gates for lobby-to-match lifecycle. Review main.gd, player.gd, login_screen.gd, backend_service.gd, and other placeholders/debug hooks. Build matrix with columns: keep, safe-remove, needs-runtime-proof, feature-flag. Remove or feature-gate release-only noise such as debug key hooks and excessive prints, but do not delete autoload/runtime-loaded scripts without proof. Instrument events: room_joined, preflight_pass/fail, loading_screen_start/finish, match_sync_complete, reconnect_success/fail, match_end_summary. Acceptance: safe-remove candidates are evidence-backed; release export excludes debug-only hooks; branch promotion can check match-start and reconnect SLO metrics.+ +
+
+
+ Testing / Auto-Check
+AI AUTO-CHECK: Search codebase for `Input.is_key_pressed(KEY_F9)`. Assert wrapped in `OS.has_feature("debug")` or completely removed.
+
+
+ MS Teams Daily Report
+
+
+ **Completed [PRD-GF-P2-1]: Dead Path, Debug Gate & Telemetry Cleanup** +- **Goal:** Remove release-noisy debug hooks. Add safe-remove candidate matrix + SLO dashboard. +- **Status:** Integrated & verified. Code changes applied to: main.gd, player.gd, placeholders+ +