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.
- **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 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.
Warp advertises only pools captured from this Client whose prefabs were verified in `resources/GachaSandboxPolicy.json`. The Client log reports that handoff ID 2120 is absent from its `GachaBasicInfo` table; the limited pool prefabs checked are also missing. Sending those IDs prevents the page from opening. Imported historical banners are therefore not unlocked, and draws are disabled until pool data, item grants and protocol fields are verified against this Client. The `/unlockall warp` and `/reload banner` commands do not make unverified banners visible.
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.
- 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.
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.
`AGENTS.md` strictly prohibits hardcoding machine-specific paths, usernames, IP addresses, ports, or game deployment URLs directly into source code or startup scripts.
`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:
- 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.
- 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>
- NPC placement coordinates and stage overrides for all 40 nodes of Challenge Peak / Anomaly Arbitration (AA) in `resources/ChallengePeakSceneOverrides.json`.
- 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`.
This project is made available in accordance with the **Apache License 2.0** and **GNU General Public License v3 (GPL-3.0)** frameworks, strictly enforcing **Attribution** and **State Changes Notices**.
If you use, fork, modify, redistribute, or create derivative works from any part of this repository, you **MUST** strictly comply with the following conditions:
1.**Mandatory Attribution (Credit the Original Source):**
- You must provide prominent credit and include a direct link back to this original repository.
- You must retain all existing copyright notices, developer credits, and original license headers in all copies or substantial portions of the software.
2.**Explicit State Changes Requirement (Document All Modifications):**
- In accordance with Section 4(b) of Apache 2.0 and Section 5(a) of GPL v3, any files that you modify **must carry prominent notices stating clearly that you changed the files, what modifications were made, and the date of modification**.
- You must not claim modified versions as wholly original works, nor remove attribution to obscure the software origin.
3.**Non-Commercial Educational Purpose:**
- This project is provided strictly for academic research, protocol analysis, and educational purposes. Commercial exploitation, sale, or paywalling of this project or its derivatives is strictly prohibited.
