Patch Release Workflow

How to ship new features and assets to live players.

1. Write the Changelog

Document your changes in CHANGELOG_DRAFT.md in player-friendly language under the ## [NEXT] section.

2. Bump the Version

Run the version script from a terminal:
```
python generate_version_json.py --bump patch
```
Use --bump minor or --bump major for larger updates.

3. Commit and Push

git add .
git commit -m "Release version X.Y.Z"
git push origin main

The GitHub Actions workflow (.github/workflows/deploy_patch.yml) detects the push, builds the patch manifest (version.json), and deploys it to the public gh-pages branch.

4. Players Receive the Patch

Live game clients detect the new version on boot, download the updated files, and apply the patch seamlessly.

How the Patch System Works

When a player downloads an in-game patch, Godot fetches a patch.pck file into the system's user:// directory.

Virtual File System: Godot mounts the .pck over res:// purely in memory. It does not physically overwrite your local source files (e.g. assets/data/version.json).
Editor Bypass: When testing locally in the Godot Editor, BootScreen skips the remote download and reads your local assets/data/version.json directly.
Previewing Changelogs:
- Add your notes under ## [NEXT] in CHANGELOG_DRAFT.md.
- Run py tools/generate_version_json.py.
- Run the BootScreen scene — it instantly renders the updated local UI.
Syncing: After CI builds a release online, run git pull origin main to sync your local project with the CI-generated files.

Architecture

flowchart TD
    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]
    end

    subgraph CI/CD Pipeline
        B -->|git push| E[GitHub Actions]
        E -->|Builds| F[patch.pck]
        F -->|Deploys| G((Public Repo))
    end

    subgraph Player Client
        G -.->|HTTP Download on Boot| H[user://patch.pck]
        H -->|load_resource_pack| I[Godot Virtual File System]
        I -.->|Overrides res://| J[Game Starts Updated]
    end