docs: add English and Chinese readmes

2026-11-01 16:26:07 +07:00
1 parent 76986eed4a
commit 53a5a99325
@@ -1,5 +1,11 @@
 # GaCy-Srtool 🌌

+<div align="center">
+
+[English](docs/README_EN.md) | [ภาษาไทย](README.md) | [简体中文](docs/README_ZH.md)
+
+</div>
+
 ใช้งานเว็บได้ที่ [GaCy Srtool บน Vercel](https://gacy-srtool.vercel.app/) เปิดหน้าตั้งค่าเพื่อเชื่อมต่อ SDK ของเซิร์ฟเวอร์ที่ใช้งานอยู่

 ในโหมด GaCy หน้า **ตั้งค่าตัวละคร / สวิตช์ระบบพิเศษ** เลือก Freecam หรือ FaceCam และตั้งระยะเริ่มต้นของ FaceCam ได้ หลังบันทึกให้กด Tab ในเกมเพื่อเปิดหรือปิดกล้อง; ลูกกลิ้งปรับระยะชั่วคราวและกลับเป็นค่าที่ตั้งไว้เมื่อเปิดใหม่
@@ -0,0 +1,175 @@
+# GaCy-Srtool 🌌
+
+<div align="center">
+
+**Modern, High-Performance Web Dashboard & Management Tool for the GaCy Ecosystem**
+
+[English](README_EN.md) | [ภาษาไทย](../README.md) | [简体中文](README_ZH.md)
+
+</div>
+
+---
+
+Online web application available at [GaCy Srtool on Vercel](https://gacy-srtool.vercel.app/). 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:**
+   ```bash
+   npx serve .
+   ```
+   Or with Python:
+   ```bash
+   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](https://huggingface.co/datasets/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:
+
+```bash
+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`
@@ -0,0 +1,160 @@
+# GaCy-Srtool 🌌
+
+<div align="center">
+
+**专为 GaCy GO 及 FreeSR 生态打造的现代化高性能 Web 仪表盘与管理工具**
+
+[English](README_EN.md) | [ภาษาไทย](../README.md) | [简体中文](README_ZH.md)
+
+</div>
+
+---
+
+网页端在线访问：[Vercel 部署版 GaCy Srtool](https://gacy-srtool.vercel.app/)。打开设置页面即可连接正在运行的本地或远程服务端 SDK。
+
+在 GaCy 模式下的 **角色设置 / 特殊系统开关** 页面，可选择开启 Freecam（自由视角）或 FaceCam（面部跟随视角），并预设 FaceCam 的初始视距。保存后在游戏内按下 `Tab` 键即可开启或关闭镜头；鼠标滚轮可临时调节视距，重新开启时将恢复设定值。
+
+## Unstuck / 紧急解卡（解除转圈卡死）
+
+连接 GaCy GO 服务端后，可直接在 GM 命令控制台点击 **Unstuck** 按钮或输入 `/unstuck` 指令。网页端会等待客户端响应确认后提示成功。此操作需在游戏运行且连接服务端时生效。该指令通过心跳机制安全清除等待网络数据包的全屏 UI 阻断，不重置 CW 进度、不切换地图，也不会伪造通关状态；主要用于解救协议等待导致的 UI 卡死。服务端需支持 `/api/client/unstuck` 接口。
+
+本工具为 100% 纯客户端运行的 Web 应用，可直接通过浏览器访问，无需在本地安装额外的复杂依赖环境。支持管理角色数据、配队编排、遗器/光锥属性定制、实战伤害分析，以及深度编辑管理 **GaCy GO**（及标准 FreeSR）的存档文件（`freesr-data.json`, `persistent`）。
+
+---
+
+## ⚡ 核心功能 (Features)
+
+### 📊 1. 实时仪表盘与编队管理 (Live Dashboard & Lineup)
+- **实时连接状态监测:** 实时检测与服务端的连通状态，并展示低延迟 Ping 监控指示条。
+- **4 人队伍编排管理:** 直观展示当前队伍成员的星魂阶数、专属武器、等级及在大世界场景中的坐标位置。
+- **动态 Git 分支显示:** 在页面顶栏与浏览器标头中准确展示当前运行的服务端/前端分支名称（如 `main`, `test-gay`）。
+- **资产概览统计:** 统计并展示仓库内的角色总数、光锥储备及遗器收藏规模。
+
+### ⚔️ 2. 实战伤害分析系统 (Real-time Damage Analyst)
+- **实时拉取战斗报告:** 从服务端直接获取最新一轮战斗统计日志 (`/api/battle_report`)。
+- **核心伤害维度统揽:** 全队总伤害 (Total DMG)、每秒平均伤害 (DPS)、总行动轮次与行动频次 (Action Count)。
+- **伤害流派深度解析:**
+  - 常规伤害 (Normal DMG)
+  - 弱点击破伤害 (Break DMG)
+  - 超击破伤害 (Super Break DMG)
+  - 持续伤害 (DoT / Damage over Time)
+- **暴击与期望分析:** 统计单角色的实际暴击率 (CRIT Rate) 与暴击伤害 (CRIT DMG) 表现。
+- **可视化图表与队员贡献比:** 柱状图直观呈现各角色的伤害占比。
+
+### 👤 3. 角色全属性检视 (Character Inspector)
+- **真实面板属性计算:** 计算并展示基础属性与遗器/光锥加成后的综合面板（生命上限、攻击力、防御力、速度、双暴、效果命中、击破特攻等）。
+- **行迹与技能等级调整:** 完整支持普攻、战技、终结技、天赋以及额外能力分支等级的检视与调节。
+- **一键极品配置:** 提供一键满级、满命座 (E6) 及满行迹的便捷配装通道。
+
+### 🛡️ 4. 遗器与光锥深度定制 (Relic & Light Cone Customizer)
+- **遗器属性自选打造:** 自由选择遗器套装、主词条与副词条组合，并支持自定义副词条强化点数。
+- **光锥叠影与等级配置:** 自由设定光锥等级与叠影等阶 (S1–S5)。
+
+### 🌌 5. 差分宇宙 / 模拟宇宙系统扩展
+- 祝福图鉴与奇物库检视，支持直接为当前存档写入特定玩法增益。
+
+### 🎒 6. 背包材料与怪物配置 (Monster Setting & Materials)
+- **背包道具批量调整:** 支持直接从服务端提取的客户端道具目录中搜索物品 ID，批量设定数量后单次提交保存。
+- **数据安全隔离:** 仅修改 `freesr-data.json` 中的 `materials` 字段，不破坏或覆盖已有的角色、光锥、遗器与战斗配置。
+- **怪物场景与波次自选 (Monster Setting):**
+  - 支持分别查看混沌回忆 (MoC)、虚构叙事 (PF)、末日幻影 (AS) 与幽影歧路 / 裁决之巅 (AA) 的关卡/怪物图鉴与数据。
+  - 支持在黄金之茧与赤红之茧 (Calyx) 中自定义敌人波次。
+  - 历战余响、凝滞虚影、侵蚀隧洞及常规高难本保持官方资源配置，避免非法波次导致逻辑紊乱。
+
+### 💾 7. GaCy 专属持久化与存档管理 (Persistent & FreeSR Data)
+- **主角开拓者定制:** 自由切换性别（星 Stelle / 穹 Caelus）与命途属性（物理、火、虚数、记忆）。
+- **三月七命途切换:** 随时切换存护（冰）与巡猎（虚数）形态。
+- **EX 星魂特权开关:** 管理特定角色（如景元 [1204]、丹恒·饮月 [1213]、黄泉 [1308]）的专属 EX 扩展星魂能力。
+- **原始 JSON 在线编辑器:** 实时查看、格式化校验、修改并导出 `freesr-data.json` 及 `persistent` 存档。
+
+### 💻 8. GM 调试控制台 (GM Command Console)
+- 网页内集成交互式 GM 指令输入框，支持直接向服务端发送管理调试命令并查看实时响应回执。
+
+### 🌐 9. 全球 13 种语言国际化支持 (Multi-Language Support)
+- 无需刷新页面即可即时切换语言：中文（简体/繁体）、英语、泰语、日语、韩语、越南语、印尼语、西班牙语、法语、德语、俄语、葡萄牙语。
+
+---
+
+# THERES ONLY DARK MODE IF U ASK FOR LIGHT GO AWAY FROM ME
+
+## 💻 本地运行指南 (Local Usage)
+
+1. **直接双击运行:** 直接使用现代浏览器打开项目根目录下的 `index.html` 即可。
+2. **或通过本地静态服务器启动:**
+   ```bash
+   npx serve .
+   ```
+   或使用 Python 内置 HTTP 服务：
+   ```bash
+   python -m http.server 3000
+   ```
+
+---
+
+## 🔗 与 GaCy GO 服务端连接机制
+
+GaCy-Srtool 通过 REST API 与 GaCy GO 服务端保持通讯：
+
+| 接口端点 (Endpoint) | 请求方法 | 作用说明 |
+| --- | --- | --- |
+| `/api/status` | GET | 获取服务状态、当前队伍、角色信息及场景坐标 |
+| `/api/freesr` | GET, POST | 读取或完整写入更新 `freesr-data.json` |
+| `/api/inventory/materials` | GET, POST | 读取客户端物品清单并指定更新材料数量（不覆盖其他字段） |
+| `/api/freesr/avatars` | GET, POST | 查询或保存角色数据与养成状态 |
+| `/api/persistent` | GET, POST | 读取或持久化写入 `persistent` 扩展存档 |
+| `/api/battle_report` | GET, POST | 获取实时战斗伤害报告与历史战斗结果 |
+| `/api/battle_report/reset` | POST | 清空当前已记录的战斗数据统计 |
+| `/api/exrank/toggle` | POST | 开启或关闭 EX-Rank 特权扩展状态 |
+| `/api/avatar/rank` | POST | 变更指定角色的星魂阶数 |
+| `/api/avatar/max_all` | POST | 一键将全角色设为满命 (E6) 及全技能满级 |
+| `/api/command` | POST | 派发 GM 调试指令至游戏服务器 |
+
+### 角色与行迹数据保存机制
+
+伤害分析模块根据真实战斗回执中的 `report.avatars[].slot` 对角色卡片进行排序，不跟随大世界预设队伍顺序变动。包含欢愉伤害、真实伤害等细分维度的统计需配合服务端 SDK 及注入了 `StatisticsComponent` 的 `damage_analyst_live.lua` 探针脚本共同使用。
+
+在角色详情页面进行保存时，会通过 `/api/freesr` 单次请求打包提交整套角色数据，包括行迹树对应的 `data.skills` 与 `data.skills_by_anchor_type`，避免行迹数据写入中途被服务端的星魂同步打断。
+
+### 配装推荐与数据来源说明
+
+角色详情中的 **配装指南 / 推荐方案** 展示了基于 Prydwen 统计的当期深渊实战高频配装、遗器主副词条取向，并标注了样本采集日期。该数值代表高难环境中的实用占比统计，并非绝对强度的官方定义。
+
+`js/build-guides-data.js` 内置数据基于 MIT 协议引用自 [LvlUrArti/MocDataProcessed](https://huggingface.co/datasets/LvlUrArti/MocDataProcessed)。使用或二次分发时请保留对 LvlUrArti 的致谢。可通过执行 `npm run sync-build-guides` 自动拉取上游最新发布版本并与本地 `js/avatars-data.js` 的角色 ID 进行索引对齐。
+
+---
+
+## 📖 物品图鉴 (Item Book)
+
+**Item Book** 深度扫描了固定游戏数据版本中所有带 `ItemConfig` 命名的定义数据表。在当前版本中，扫描了 26 个候选表并成功解析出 18 个包含物品定义的表：共计 5,472 行数据对应 5,414 个独立物品 ID。带有 **GaCy supported** 徽标的物品直接与 Go 服务端的 `InventoryItemConfig.json` 保持联动；其余条目仅供图鉴浏览。
+
+点击物品图标可唤起详情弹窗，查看其专属 ID、来源数据表、类别分类、游戏内原版文本描述以及数量选择器。在图鉴弹窗内选择的数量属于本地交互，不会自动调用服务端或直接增发物品。若原版数据表定义了 `PileLimit`（堆叠上限），选择器将严格受限于该上限值。
+
+物品的名称与描述文本覆盖了 Srtool 支持的全部 13 种本地化语言。图标资产直接引用自对齐版本的 StarRailRes 索引库。
+
+可通过以下命令根据 Go 服务端的库存配置重新生成 `assets/item-catalog.json`：
+
+```bash
+python tools/build-item-catalog.py --inventory-config <path-to-GaC-hkrpg-go>/resources/InventoryItemConfig.json
+```
+
+---
+
+## ⚔️ 货币战争 (CW) GM 调试指令
+
+在已连接的 GM 控制台中，支持输入：`/cw status`, `/cw gold <总额>`, `/cw hp <总额>`。
+修改值仅对当前正在进行的 CW 局内生效。指令会被放入队列并在 Preparation（备战）阶段统一消费执行；战斗期间将保持等待。金币指令会直接设定当前总额，而非循环递增。HP 设定值不得超出当局关卡上限。可在服务端日志中确认 `CW_GM applied` 确认下发状态，或通过控制台输入 `/help` 与联想提示进行查看。
+
+---
+
+## ⌨️ GM 智能命令助手 (Command Assistant)
+
+控制台输入框内置了指令实时语法预览与参数即时提示功能。完整支持官方 GM 命令、`/unstuck`、`/faketime` 以及当前 SDK 支持的所有 `/cw` 子命令：
+- 使用 ↑ / ↓ 键可在候选联想列表中导航。
+- 按 `Tab` 键可自动补全当前高亮参数并跳转至下一参数位。
+- 按 `Shift + Tab` 可回退列表选择，按 `Esc` 键可快速关闭补全提示。
+- 也可直接使用鼠标点击补全项填充。
+- `Tab` 仅用于补全，需按下 `Enter` 回车键或点击 `Run` 按钮发送命令。
+
+输入角色名称或数字 ID 即可模糊检索对应角色。物品清单、大地图 Plane 与 Floor 索引以及 CW 专属数据均实时拉取自 SDK 的 `GET /api/command-completions` 接口。CW 角色星级也会根据已选定的 Role 动态收窄过滤范围。
+
+无游戏运行时单元测试命令：`node --test tools/command-assistant.test.mjs`