GaCy-GO/docs/README_EN.md

# 🚂 GaCy GO

<div align="center">

**Modern, High-Performance Honkai: Star Rail Game Server Emulator in Go**  
Ported from [`GaC-hkrpg-ps`](https://github.com/CAtlas0784/GaC-hkrpg-rust) with protocol references from `PearlSR` & `Currency-War-SR`.

[English](README_EN.md) | [ภาษาไทย](../README.md)

</div>

---

## 🇬🇧 English

<div align="center">

[Documentation](./) • [Getting Started](#-getting-started-on-windows) • [Features & In-Game Systems](#-features--in-game-systems) • [Configuration](#-configuration--anti-hardcoding-policy-agentsmd) • [Credits & Acknowledgments](#-credits--acknowledgments)

</div>

Honkai: Star Rail game server emulator implemented in Go, ported from [`GaC-hkrpg-ps`](https://github.com/CAtlas0784/GaC-hkrpg-rust) and referencing [PearlSR](https://git.xeondev.com/HonkaiSlopRail/pearl-sr). It includes the Game Server, SDK/Dispatch Server, and REST API for GaCy-Srtool.

The project is currently under active development, targeting Client **4.6.53 OS**. Command tables and recent handlers reference PearlSR commit `005d2c12db4781071f4b5b68e8f364587886a710` (see [protocol update documentation](protocol-update.md)). Schema parity does not imply that every in-game feature is fully operational.

### 🎮 Currency Wars (CW) — In Development

- **Autochess Simulation Engine**: Ported from [Currency-War-SR by xaodev](https://gaytea.cod-algieba.ts.net/xaodev/Currency-War-SR), implementing encounter generation following supply nodes, difficulty/selection matrix, and mode/chapter/boss EXP progression while maintaining verified battle paths. Full audit details in [CW xaodev handoff](CW-XAODEV-CLAUDE-HANDOFF.md) and [CW route continuation audit](cw-route-continuation-audit.md).
- **Time Simulation (FakeTime)**: In GaCy-Srtool, use `/faketime status` to view current game time, `/faketime <Unix seconds>` or `/faketime <RFC3339 datetime>` to set simulated time, and `/faketime off` to restore real-time clock. Persisted in `game_clock.state_file` (override with `GAC_GAME_CLOCK_STATE_FILE`). Affects login and heartbeats without altering OS system clocks or network timeouts.
- **Cyrene Train Login Scene**: Operational via `LoginShow_UP` manifest and bound to animation finish events, rendering the white train, pink-purple sky, petals, and clean logout/re-login transitions. Details in [Login scene notes](login-cyrene-investigation.md).
- **Emergency Unstuck via GaCy-Srtool**: The **Unstuck** button in the GM Command Console issues `POST /api/client/unstuck`, executing `UIManager.ClearWaitNetPacketFullScreenBlock()` on the next client heartbeat. Safely unfreezes UI blocks without clearing CW saves or fabricating gameplay states.
- **Roster & Star Merging**: Automatic 3-copy star promotion for duplicate avatars, equipment binding and tracking from Preparation screen, and protagonist spotlight selection policies.

#### CW Preparation Commands
- `/cw status`: Display saved round, gold, HP, and player level.
- `/cw gold <amount>`: Set CW currency (e.g. `/cw gold 1000`).
- `/cw hp <amount>`: Set current HP within maximum stage allowance.
- `/cw exp <gain>`: Add EXP and apply captured level/capacity/shop-weight rules.
- `/cw list role`: List captured RoleID, AvatarID, and supported star ratings.
- `/cw role <RoleID> <star> [count]`: Add bench roles with automatic star merges; a full bench cancels the entire transaction.
- `/cw list equip`: List captured equipment IDs.
- `/cw equip <ItemID> [count]`: Add equipment into the CW inventory bag.
- `/cw list orb|consumable|forge`: List captured reward and forge IDs.
- `/cw orb|consumable|forge <ItemID> [count]`: Grant those items during Preparation.
- `/cw help`: Display full command syntax.

---

### ✨ Features & In-Game Systems

#### Aha's Help

GaCy-Srtool's Persistent settings include an independent Aha's Help selector. Levels come from `resources/AhaHelpConfig.json`, based on the supplied buff table. `GET /api/aha-help` returns available levels; `POST /api/aha-help` accepts `{"level":1}`, zero to disable, or null to use the existing FreeSR invasion-support setting. The setting is stored atomically in `persistent.aha_help_level`, preserving CW and EX state.

The selected buff applies at the start of the next battle containing an actual Corruption buff from `BattleRules.json`'s invasion mapping. This includes srtool custom battles with imported Corruption buffs. Official challenges continue to resolve their Corruption from `StageInvasionConfig.json`; reusing a stage ID alone does not inject Corruption into a custom battle. The selected level replaces other Aha support levels; explicit zero removes support for that Corruption battle. Null follows FreeSR's `enable_invasion_support`; the web selector shows whether that legacy switch is enabled. This setting is separate from Aha Global and does not change an ongoing battle. `AHA_HELP` in `server_debug.log` records the corruption and support IDs sent. The table's `BuffLevel` selects the distinct buff ID; the existing protocol buff-level encoding is retained. Progress thresholds are metadata, not an invented dynamic key. Client behavior and animations still require gameplay verification.

#### Stella Jump, Event Previews & Featured Gacha

`resources/StellaJumpConfig.json` contains the 16 ChenLing GameBoy cases captured from the current Client. The sandbox exposes each case's challenge packs and saves actual best times/completions under `persistent.stella_jump`. Opening a menu is read-only. Cheats have separate saved flags; their obfuscated request/response names remain tied to the checked-in command revision and require Client verification.

`resources/ActivityPreviewPolicy.json` selects event-panel prefabs from `PreviewGameplayCatalog.json`. Additional previews are currently withheld: Client logs showed missing reward assets and invalid item lookups in ActiveActivity. Re-enable individual panels only after validating their installed assets, module identity and reward dependencies. Event-specific battles and reward claims remain incomplete.

Featured gacha candidates come from captured character-banner prefab rows. The current capture has two candidates, but the installed Client could not load the Seele prefab and left the UI transition incomplete. Runtime `AssetMgr.Exists` checks confirmed Standard and Beginner assets, but none of the four captured limited assets. `GachaSandboxPolicy.json` currently exposes only the verified Standard panel for browsing; draws return `RET_GACHA_NOT_SUPPORT` until usable featured assets are verified. An empty verified list rejects entry as well. A table row alone is insufficient evidence of an installed asset; verify the Client bundle before adding a path to that list. The grant implementation returns the pictured character and configured duplicate Eidolon material, preserving rank/EX/Traces; it is not yet verified in the Client. An avatar absent from the imported roster is rejected. The sandbox policy uses free draws and does not reproduce official rates or conversion rules.

Runtime table captures and current verification limits are recorded in [docs/offline-gameplay-continuation.md](offline-gameplay-continuation.md). Compiling these handlers does not confirm the corresponding Client screens or gameplay.

#### Freecam & FaceCam Controls

- `Tab`: Toggle Freecam / FaceCam; Arrow keys: Move camera; Hold Right Mouse Button and move mouse to rotate orientation.
- `Page Up` / `Page Down`: Raise / lower elevation; `+` / `-`: Increase / decrease camera speed.
- FaceCam aligns the viewport with the active character's animated head direction and follows transformed battle characters (e.g., Khaslana). Scroll wheel adjusts zoom distance.
- While Freecam is active in battle, UI click interception is safely suspended via `InControlInputModule.allowMouseInput` and temporary mouse bindings in memory, while keyboard skill activation remains functional.

---

### 🚀 Getting Started on Windows

#### Requirements
1. Windows with PowerShell and an internet connection for the initial build. The launcher validates the Go toolchain against the minimum version in `go.mod`; if missing or outdated, it prompts to automatically download, verify (SHA-256), and extract the official archive into `launcher.go_install.directory`.
2. Prepare Client, launcher/proxy, and redirect dispatch to the addresses configured in `server.json`.
3. For standard binaries, keep data files and the `resources/` folder in the project root. For standalone distribution, binaries under `for ship` bundle embedded runtime resources.
4. Execute `run.bat` and select the desired menu option:

| Option | Function |
| :---: | :--- |
| `1` or Enter | Build both servers, launch servers, and launch the game client |
| `2` | Launch both servers from existing `.exe` binaries |
| `3` | Launch SDK server only |
| `4` | Launch Game server only |
| `5` | Launch both servers from existing `.exe` binaries and start Gay Proxy |
| `6` | Build both `.exe` binaries only |
| `7` | Exit |
| `8` or `stop` | Stop all project server processes |
| `9` or `requirements` | Verify Go toolchain and prompt for automatic installation |

SDK and Game servers launch in separate visible console windows displaying live logs. The interactive launcher menu closes automatically after 5 seconds while server processes remain running. Use `run.bat stop` or close console windows to terminate.

---

### ⚙️ Configuration & Anti-Hardcoding Policy (`AGENTS.md`)

`AGENTS.md` strictly prohibits hardcoding machine-specific paths, usernames, IP addresses, ports, or game deployment URLs directly into source code or startup scripts.

Priority Order: **Environment Variables > `server.local.json` > `server.json`**

- `server.json`: Central shared configuration across launcher, game server, and SDK server.
- `server.local.json`: Local machine overrides (ignored by Git). Create by copying `server.local.example.json`.
- `GAC_CONFIG`: Custom config path override.

| Config Key | Environment Override | Purpose |
| :--- | :--- | :--- |
| `account_name` | `GAC_ACCOUNT_NAME` | Username returned in SDK login response and in-game player name |
| `player_uid` | `GAC_PLAYER_UID` | Player UID (1–4294967295) shared between SDK and Game server |
| `client_version` | `GAC_CLIENT_VERSION` | Version string displayed in logs and API |
| `game_host`, `game_port` | `GAC_GAME_HOST`, `GAC_GAME_PORT` | Game server bind host and port |
| `sdk_host`, `sdk_port` | `GAC_SDK_HOST`, `GAC_SDK_PORT` | SDK server bind host and port |
| `public_game_host` | `GAC_PUBLIC_GAME_HOST` | Gateway address advertised to the client |
| `public_sdk_url` | `GAC_PUBLIC_SDK_URL` | Base URL advertised by dispatch |
| `launcher.client_path` | `GAC_CLIENT_PATH` | Path to game client executable or launcher |
| `launcher.proxy_path` | `GAC_PROXY_PATH` | Path to proxy executable |
| `launcher.go_command` | `GAC_GO_COMMAND` | Custom Go executable path |

---

### 💖 Credits & Acknowledgments

`GaCy GO` is built upon the collective research, tools, and pioneering reverse-engineering efforts of the open-source and Star Rail research communities. We extend our sincere gratitude and recognition to the following projects and authors:

<details open>
<summary><b>🏛️ Server Architecture & Protocol</b></summary>

- **PearlSR ([HonkaiSlopRail/pearl-sr](https://git.xeondev.com/HonkaiSlopRail/pearl-sr))**:
  - Reference Go server emulator providing dispatch architecture, gateway connection management, and base packet handler implementations.
  - Upstream opcode and Command ID definitions (`protocol/proto/upstream_cmdids.go`).

- **LunarCore ([Melledy/LunarCore](https://github.com/Melledy/LunarCore))**:
  - Pioneering Java-based Star Rail game server emulator by Melledy and contributors — the industry-standard reference for battle mechanics, packet definitions, and gacha probability curves.

- **FreeSR Team**:
  - Foundational player JSON schema specifications (`freesr-data.json`) utilized for loading and persisting player roster and inventory data.

- **March7thHoney ([Mar7thLover/March7thHoney-OpenSource](https://github.com/Mar7thLover/March7thHoney-OpenSource))**:
  - High-performance C#/.NET server oracle referenced for gacha pull algorithms, pity system math, shop mechanics, and Muip admin protocols.

- **FFGO ([git.kain.io.vn](https://git.kain.io.vn/))**:
  - Open-source server emulation research and protocol oracle referenced for network workflow transitions, command sequencing, and packet compatibility verification.

</details>

<details open>
<summary><b>🎮 Game Modes & Simulation</b></summary>

- **Currency-War-SR ([xaodev/Currency-War-SR](https://gaytea.cod-algieba.ts.net/xaodev/Currency-War-SR))**:
  - Partial port imported under the AGPL-3.0 license (retained under `third_party/currency-war-sr`).
  - Core simulation engine for Currency Wars (Grid Fight autochess) 4.6.53.
  - Role/traits matrix, post-supply encounter generation logic, difficulty scaling, and EXP progression rules (`internal/common/currency_wars_xaodev.go`, `internal/gameserver/currency_wars_xaodev.go`, `resources/CurrencyWarsXaodev.json`).

- **minatoSR ([haltinggoalies/minatoSR](https://github.com/haltinggoalies/minatoSR))**:
  - NPC placement coordinates and stage overrides for all 40 nodes of Challenge Peak / Anomaly Arbitration (AA) in `resources/ChallengePeakSceneOverrides.json`.

</details>

<details open>
<summary><b>📦 Game Data & Tooling</b></summary>

- **Dimbreath ([DimbreathBot/TurnBasedGameData](https://github.com/DimbreathBot/TurnBasedGameData))**:
  - Master Excel game tables (`ExcelBinOutput`), hash verification digests, and identifier indices for characters, items, relics, and skills in `resources/`.

- **Prydwen Institute ([Prydwen.gg](https://www.prydwen.gg/star-rail/))**:
  - Character build recommendations, optimal relic main/sub-stats, and tier lists for team composition guidance in `resources/PrydwenRecommendations.json`.

- **AstralOS ([Ma3-OS/AstralOS](https://gaytea.cod-algieba.ts.net/AstralOS/AstralOS))**:
  - High-performance protocol analysis suite, IL2CPP metadata dumpers, network hook tooling, and reverse-engineering utilities utilized for architectural analysis.

</details>