Gacy-Srtool/docs/README_EN.md

GaCy-Srtool 🌌

Modern, High-Performance Web Dashboard & Management Tool for the GaCy Ecosystem

English | ภาษาไทย | 简体中文

---

Online web application available at GaCy Srtool on Vercel. Open Settings to connect to your running local or remote server SDK.

In GaCy mode under Character Settings / Special System Switches, configure Freecam or FaceCam mode and set the initial FaceCam zoom distance. After saving, press Tab in-game to toggle the camera; the mouse scroll wheel temporarily adjusts zoom distance, resetting to the configured default upon reactivation.

Unstuck / Emergency UI Unfreeze

When connected to a GaCy GO server, click the Unstuck button in the GM Command Console or type /unstuck. The web interface waits for game client confirmation before displaying success. The game must be running and actively connected to the server. This command safely clears full-screen UI blocks waiting on network packets via the heartbeat cycle without wiping CW progress, changing scenes, or fabricating gameplay results; it does not replace fixing missing protocol handlers. Requires an SDK server supporting /api/client/unstuck.

A 100% client-side web dashboard and management tool designed for character data configuration, lineup management, relic and light cone customization, real-time battle damage analysis, and save file management (freesr-data.json, persistent) for GaCy GO (and standard FreeSR) servers.

Runs entirely in your web browser with zero local dependencies or installations required.

---

⚡ Key Features

📊 1. Live Dashboard & Lineup

• Live Connection Status: Real-time server connectivity detection with a live ping latency monitor.
• 4-Slot Lineup Management: Displays team members alongside their Eidolon rank, equipped signature light cone, level, and world scene coordinates.
• Dynamic Git Branch Indicator: Accurately displays the active server/frontend branch (e.g. main, test-gay) in the header and browser title bar.
• Resource Summary: Total counts of owned characters, light cones, and relics in inventory.

⚔️ 2. Real-Time Damage Analyst

• Live Server Battle Reports: Fetches the most recent combat statistics directly from /api/battle_report.
• Comprehensive DMG Overview: Total DMG, Damage Per Second (DPS), and total action count.
• Damage Category Breakdown:
  • Normal DMG
  • Weakness Break DMG
  • Super Break DMG
  • Damage over Time (DoT)
• CRIT Performance Analysis: Evaluates actual in-combat CRIT Rate and CRIT DMG per character.
• Visual Analytics: Interactive bar charts illustrating each character's overall damage contribution.

👤 3. Character Inspector

• Real Stat Calculations: Calculates base stats plus relic/light cone bonuses (HP, ATK, DEF, SPD, CRIT Rate, CRIT DMG, Effect Hit Rate, Break Effect).
• Trace Tree Skill Levels: Inspect and modify skill levels for Basic ATK, Skill, Ultimate, Talent, and bonus ability nodes.
• One-Click Max Build: Instantly configure max levels, max Eidolons (E6), and fully unlocked Traces.

🛡️ 4. Relic & Light Cone Customizer

• Custom Relic Crafting: Freely select relic sets, main stats, and sub-stats with customized roll distribution.
• Light Cone Superimposition: Configure light cone levels and superimposition ranks (S1–S5).

🌌 5. Simulated Universe / Divergent Universe

• Browse blessings and curios, with direct support for writing gameplay buffs into persistent saves.

🎒 6. Inventory Materials & Monster Setting

• Batch Inventory Adjustment: Search item catalog IDs extracted directly from the game client and update multiple quantities in a single transaction.
• Isolated Safe Writes: Modifies only the materials field in freesr-data.json without overwriting characters, light cones, relics, or battle configs.
• Monster Setting & Wave Customization:
  • View stages, monsters, levels, and waves for Memory of Chaos (MoC), Pure Fiction (PF), Apocalyptic Shadow (AS), and Anomaly Arbitration (AA) using Nanoka metadata matching the server's client_version.
  • Customize monster waves for Golden and Crimson Calyx nodes.
  • Weekly Bosses, Stagnant Shadows, Caverns of Corrosion, and endgame challenges retain verified official assets.

💾 7. GaCy Persistent & FreeSR Save Management

• Trailblazer Configurator: Switch gender (Caelus / Stelle) and damage Path (Physical, Fire, Imaginary, Remembrance).
• March 7th Path Switcher: Toggle between Preservation (Ice) and The Hunt (Imaginary).
• EX-Rank Special Switches: Enable/disable special EX rank abilities for supported characters (Jing Yuan [1204], Dan Heng • IL [1213], Acheron [1308]).
• Raw JSON Editor: Inspect, format, edit, and backup freesr-data.json and persistent files directly.

💻 8. GM Command Console

• Integrated web command prompt to send GM instructions directly to the server with real-time response output.

🌐 9. Multi-Language Support (13 Languages)

• Instant, client-side language switching without page reload:
  • 🇹🇭 Thai
  • 🇺🇸 English
  • 🇨🇳 Simplified Chinese
  • 🇹🇼 Traditional Chinese
  • 🇯🇵 Japanese
  • 🇰🇷 Korean
  • 🇻🇳 Vietnamese
  • 🇮🇩 Indonesian
  • 🇪🇸 Spanish
  • 🇫🇷 French
  • 🇩🇪 German
  • 🇷🇺 Russian
  • 🇵🇹 Portuguese

---

THERES ONLY DARK MODE IF U ASK FOR LIGHT GO AWAY FROM ME

💻 Local Usage

1. Direct Browser Execution: Double-click and open index.html in any modern web browser.
2. Or run via local HTTP server:

   npx serve .
   

   Or with Python:

   python -m http.server 3000
   

---

🔗 GaCy GO Server Integration

GaCy-Srtool communicates with the GaCy GO server through its REST API:

Endpoint	Method	Description
/api/status	GET	Retrieve server status, active lineup, character stats, and player position
/api/freesr	GET, POST	Fetch or overwrite freesr-data.json
/api/inventory/materials	GET, POST	Read client item catalog and modify specific item counts without touching other data
/api/freesr/avatars	GET, POST	Read or update character statistics and progression
/api/persistent	GET, POST	Fetch or update persistent save records
/api/battle_report	GET, POST	Retrieve real-time combat damage logs and latest battle results
/api/battle_report/reset	POST	Clear logged battle statistics
/api/exrank/toggle	POST	Toggle EX-Rank special capabilities
/api/avatar/rank	POST	Modify a character's Eidolon rank
/api/avatar/max_all	POST	Set all owned avatars to E6 and max trace levels
/api/command	POST	Dispatch GM commands to the game server

Character & Trace Persistence

The Damage Analyst orders character cards according to report.avatars[].slot from the actual battle payload rather than the overworld lineup. Live data streaming requires the server SDK and damage_analyst_live.lua script reading the combat StatisticsComponent.

Saving from the character detail panel dispatches the complete avatar payload through /api/freesr in a single request, including data.skills and data.skills_by_anchor_type for Traces, preventing partial synchronization from disrupting Trace data.

Build Guides & Data Sources

The Character Details → Build Guides section displays high-usage endgame equipment and main stat recommendations derived from Prydwen sample data, indicating player sample proportions and capture dates.

Prebuilt data in js/build-guides-data.js is licensed under MIT from LvlUrArti/MocDataProcessed. Please credit LvlUrArti when redistributing. Update snapshots using npm run sync-build-guides, matching characters by ID against js/avatars-data.js.

---

📖 Item Book

The Item Book scans the pinned game-data revision across all ItemConfig-named tables containing item definitions. In this revision, 26 candidate tables were evaluated and 18 supplied item rows: 5,472 total rows resolving to 5,414 unique item IDs. Items badged GaCy supported are linked to the Go server's InventoryItemConfig.json; other entries are browse-only.

Click any item icon to open its details dialog, showing its ID, source table, item category, official localized in-game description, and a quantity selector. Selected quantities are local to the dialog and do not directly modify server state. Where the game data defines a PileLimit, the selector enforces that ceiling.

Item names and descriptions cover all 13 supported languages. Icons are loaded from the aligned StarRailRes asset repository.

Regenerate assets/item-catalog.json from the server inventory config:

python tools/build-item-catalog.py --inventory-config <path-to-GaC-hkrpg-go>/resources/InventoryItemConfig.json

---

⚔️ Currency Wars (CW) GM Commands

In the connected GM Console, enter: /cw status, /cw gold <total>, /cw hp <total>. Values apply strictly to the active CW run. Commands are queued and processed during the Preparation phase; they wait while in combat. Gold sets the absolute total rather than incrementing. HP must remain within the stage ceiling. Check server logs for CW_GM applied or use /help in the console.

---

⌨️ GM Command Assistant

The console input field includes a real-time command preview and argument hint system supporting standard GM commands, /unstuck, /faketime, and all /cw subcommands:

• Use ↑ / ↓ arrow keys to navigate suggestions.
• Press Tab to autocomplete the highlighted candidate and proceed to the next argument.
• Press Shift + Tab to reverse candidate selection, or Esc to close suggestions.
• Click any suggestion item to autofill.
• Tab only autocompletes; press Enter or click Run to execute.

Filter characters by typing names or numeric IDs. Items, Maps, Planes, Floors, and CW assets are fetched dynamically from SDK's GET /api/command-completions. CW star options dynamically filter based on the chosen Role.

Run headless verification tests: node --test tools/command-assistant.test.mjs

---

📜 License & Attribution Notice

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.