GaCy-GO/docs/README_EN.md

🚂 GaC hkrpg 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 • 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 GaC-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 GaC-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 GaC-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.

🚀 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

GaC-hkrpg-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:

  • 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.