GaCy-GO/docs

🚂 GaCy GO

Modern, High-Performance Honkai: Star Rail Game Server Emulator in Go
Ported from GaC-hkrpg-ps with protocol references from PearlSR & Currency-War-SR.

English | ภาษาไทย

---

🇬🇧 English

Documentation • Getting Started • Features & In-Game Systems • Configuration • Credits & Acknowledgments

Honkai: Star Rail game server emulator implemented in Go, ported from GaC-hkrpg-ps and referencing PearlSR. 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). 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, 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 and CW route continuation audit.
• 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.
• 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. 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:

🏛️ Server Architecture & Protocol

• PearlSR (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):

  • 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):

  • 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):

  • Open-source server emulation research and protocol oracle referenced for network workflow transitions, command sequencing, and packet compatibility verification.

🎮 Game Modes & Simulation

• Currency-War-SR (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):

  • NPC placement coordinates and stage overrides for all 40 nodes of Challenge Peak / Anomaly Arbitration (AA) in resources/ChallengePeakSceneOverrides.json.

📦 Game Data & Tooling

• Dimbreath (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):

  • Character build recommendations, optimal relic main/sub-stats, and tier lists for team composition guidance in resources/PrydwenRecommendations.json.

• AstralOS (Ma3-OS/AstralOS):

  • High-performance protocol analysis suite, IL2CPP metadata dumpers, network hook tooling, and reverse-engineering utilities utilized for architectural analysis.