tekton/README.md

# Tekton Dash Armageddon


## 🛠️ Developer Workflows

### Creating a Skin Material
To create dynamic, color-maskable 3D materials for new character skins:
- Open the **Skin Shader Generator** tool in the editor: `res://scenes/tools/skin_shader_generator.tscn`
- Run the scene. 
- Import your base albedo and mask textures.
- Use the UI to visualize UV overlays and adjust color channels (Red, Green, Blue, Alpha masks).
- Export the configured material as a `.tres` file into the `assets/materials/skins/` directory.

### Adding a Skin to the Shop
Once your material is ready, you need to update the game's catalog and deploy the changes to the Nakama server.

#### Using the Catalog Editor Tool
- Open the **Skin Catalog Editor** tool in the Godot Editor: `res://scenes/tools/skin_catalog_editor.tscn`
- Press **F6** (or Right-click -> Run Current Scene).
- **Manage Skins:**
   - Click **"＋ New Skin"** to create a new entry.
   - Fill in the **ID**, **Name**, **Category**, and **Price** (Gold/Stars).
   - Assign the `.tres` material path generated in Step 1.
- Click **"💾 Save & Generate"**. This automatically rewrites:
   - `res://scripts/managers/skin_manager.gd` (Local catalog)
   - `res://server/nakama/tekton_admin.js` (Server-side shop logic)

#### Nakama VPS Deployment
After generating the updated `tekton_admin.js` locally, you must sync it with your remote server.

- **Copy the latest script:** Open `server/nakama/tekton_admin.js` locally and copy its updated contents (including your new skin).
- **Connect to your VPS** via SSH.
- **Create/Edit the file on the remote server:**
   ```bash
   nano ~/tekton_admin.js
   # Or use micro (recommended): micro ~/tekton_admin.js
   ```
   Paste the copied contents and save the file.
- **Find your Nakama Container ID:**
   It is highly recommended to use **lazydocker** to manage containers.
   *(To install on Ubuntu: `curl https://raw.githubusercontent.com/jesseduffield/lazydocker/master/scripts/install_update_linux.sh | bash`)*
   Open lazydocker or run `docker ps` to find the Container ID for your Nakama server.
- **Copy the file into the Nakama container:**
   ```bash
   # Replace ed21ac5d442a with your actual Container ID
   docker cp ~/tekton_admin.js ed21ac5d442a:/nakama/data/modules/tekton_admin.js
   ```
- **Restart the container** (via lazydocker or `docker restart <Container ID>`) for Nakama to load the new modules. Live game clients will fetch this new catalog automatically upon booting.

#### 🎨 Skin Creation & Deployment Flow
```mermaid
flowchart TD
    %% Creation Phase
    subgraph phase1 [Skin Material Creation]
        A[Albedo & Mask Textures] --> B{Skin Shader Generator}
        B -->|Export| C[material.tres]
    end

    %% Catalog Phase
    subgraph phase2 [Catalog Definition]
        C --> D{Skin Catalog Editor}
        D -->|Save & Generate| E[tekton_admin.js]
        D -->|Save & Generate| F[skin_manager.gd]
    end

    %% Deployment Phase (Dual Path)
    subgraph phase3 ["Shop Backend (VPS)"]
        E -->|SSH & nano| G[VPS: ~/tekton_admin.js]
        G -->|docker cp| H[Nakama Container]
        H -->|Restart| I[Live Shop Logic Sync]
    end

    subgraph phase4 ["Asset Delivery (CI/CD)"]
        C --> J[Git Push]
        F --> J
        J -->|GitHub Actions| K[patch.pck]
        K -->|Automatic Download| L[Player Client Assets Sync]
    end
```

### Pushing a New Version (Automated Patching)
When you're ready to deploy new features or assets to players:
- Document your changes in `CHANGELOG_DRAFT.md` using player-friendly language.
- Run the version generation script from the terminal:
   ```bash
   python generate_version_json.py --bump patch
   ```
   *(Use `--bump minor` or `--bump major` for larger updates.)*
- Commit and push your changes to the `main` branch on GitHub:
   ```bash
   git add .
   git commit -m "Release version X.Y.Z"
   git push origin main
   ```
- The **GitHub Actions Workflow** (`deploy_patch.yml`) will automatically detect the push, build the patch manifest (`version.json`), and deploy it to the public `gh-pages` branch.
- Live game clients will detect the new version on boot, download the updated files, and apply the patch seamlessly.

### Local Testing & Understanding the Patch System
When a player (or you) downloads an in-game patch, Godot downloads a `patch.pck` file to the system's `user://` directory. 
- **Virtual File System:** Godot mounts this `.pck` file over the `res://` directory purely in memory. **It does not physically overwrite your local source files** (like `assets/data/version.json`).
- **Editor Bypass:** When testing locally in the Godot Editor, the `BootScreen` is configured to skip the remote network download and instead automatically parse your *local* `assets/data/version.json`.
- **Previewing Changelogs:** To preview how your changelog will look before pushing to GitHub:
  - Add your notes under the `## [NEXT]` section in `CHANGELOG_DRAFT.md`.
  - Run `py tools/generate_version_json.py` from the terminal.
  - Run the `BootScreen` scene in the Godot Editor. It will instantly display the updated local UI!
- **Syncing:** After the GitHub Actions CI builds a release online, remember to run `git pull origin main` to sync your local project files with the CI-generated files.

#### 🗺️ Architecture Flowchart
```mermaid
flowchart TD
    %% Local Dev Flow
    subgraph Local Dev Environment
        A[📝 CHANGELOG_DRAFT.md] -->|py tools/generate_version_json.py| B[(📄 version.json)]
        B -.->|Test in Editor| C{BootScreen}
        C -- Editor Bypass --> D[Reads Local version.json directly]
    end

    %% CI Pipeline
    subgraph "CI/CD Pipeline"
        B -->|git push| E[⚡ GitHub Actions]
        E -->|Compiles & Builds| F[📦 patch.pck]
        F -->|Deploys| G((🌍 Public Repository))
    end

    %% Live Client Flow
    subgraph Player Client
        G -.->|HTTP Download on Boot| H[📂 user://patch.pck]
        H -->|ProjectSettings.load_resource_pack| I[🧠 Godot Virtual File System]
        I -.->|Overrides res:// in Memory| J[Game Starts Updated!]
    end
```

---

## 🚀 Ongoing Features (Incoming)

### 🎰 Gacha System Backend Editor
Currently in development: A dedicated backend editor tool (similar to `skin_catalog_editor.tscn`) specifically for managing the Gacha System.
- **Nakama Syncing:** Will allow developers to push updated gacha pools, rates, and fragment costs directly to Nakama Storage.
- **Dynamic Banners:** Will support updating specific slots on the gacha banner dynamically.
- **Seasonal Rotations:** Will introduce automated scheduling so banners rotate based on active seasons and automatically remove themselves when the season ends.