Godot
Nakama x Godot 4 Production Blueprint
Production Ready

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.

Endpoint: client.authenticate_steam_async(ticket)

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

Steam PC Steam Target
Class Check
ClassDB.has_singleton("Steam")
Ticket Retrieval

Grabs session hex ticket asynchronously

Nakama Endpoint
authenticate_steam_async()
Google Play 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()
Apple 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()
Itch.io 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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