G-Launcher/README.md

🚀 G-Launcher

A lightweight, modern, and high-performance game launcher for Anime & Hoyoverse games.
Built with Go, Wails v3, React 19, and Tailwind CSS v4.

English | ภาษาไทย

---

🇹🇭 ภาษาไทย

✨ ฟีเจอร์เด่น (Key Features)

• 🎮 Game Process & Environment Management:
  • ตรวจสอบและเปิดเกมพร้อมพารามิเตอร์ที่ถูกต้องผ่านระบบจัดการ Console ของ Windows (CREATE_NEW_CONSOLE | CREATE_BREAKAWAY_FROM_JOB)
  • ตรวจจับสถานะการทำงานของตัวเกมและเซิร์ฟเวอร์แบบ Real-time พร้อมแจ้งเตือนเมื่อเกมปิดตัวลง
• 🌐 ระบบหลายภาษา (Multi-Language UI & Game Patcher):
  • หน้า UI รองรับ ภาษาไทย (TH), English (EN), 日本語 (JA), 한국어 (KO), Tiếng Việt (VI), และ 中文 (ZH)
  • เครื่องมือสลับภาษาภายในเกมผ่าน Binary ExcelData Patcher (EN, JP, CN, KR) และรองรับ Thai Mod Pack สำหรับตัวเกม Beta
• 📦 ระบบอัปเดตไฟล์เกมแบบลดขนาด (Incremental Diff Patching):
  • รองรับไฟล์อัปเดตแบบ HDiffPatch โดยตรงจาก Chunk Protobuf Manifest ของเกม (proto/firefly.proto)
  • รองรับการลงแพตช์ไฟล์นามสกุล .ziff ด้วย Zift Tool (zift.exe)
  • ตรวจสอบความถูกต้องของไฟล์ผ่าน Checksum (MD5 / SHA-256)
• 🔄 ระบบอัปเดต Launcher อัตโนมัติ (Smart Self-Update):
  • อัปเดตผ่าน Manifest latest.json พร้อมตรวจสอบความสมบูรณ์ด้วย SHA-256
  • มีระบบ Fallback ไปยัง Gitea/GitHub Releases API
  • ป้องกันการทับไฟล์ในโหมด Development อัตโนมัติ
• 🛡️ ความปลอดภัยของข้อมูล (Safe Data & Atomic Operations):
  • จดจำโฟลเดอร์เกมใน AppData (%APPDATA%/g-launcher/game-selection.json) ด้วย Windows API MoveFileEx แบบ Atomic ป้องกันไฟล์เสียหาย
  • สำรองไฟล์ตัวจริงเป็น .backup ก่อนลงแพตช์ และมีระบบ Rollback คืนสภาพไฟล์อัตโนมัติหากการลงแพตช์ล้มเหลว
• 🧰 พร้อมใช้งานแบบไม่ต้องติดตั้งเครื่องมือเสริม (Zero-Dependency):
  • Portable MinGit: ดาวน์โหลด Git แบบพกพามาติดตั้งในตัวอัตโนมัติหากตรวจไม่พบ Git ในเครื่องผู้ใช้
  • บรรจุ Binary Tools สำคัญ (7za.exe, hpatchz.exe, zift.exe) ไว้ในตัวโปรแกรมและแตกไฟล์ใช้งานอัตโนมัติ
• 🎨 ปรับแต่งหน้าตาได้ตามใจ (Customization & Themes):
  • หน้าต่างไร้ขอบ (Frameless Glassmorphism) พร้อมถาดระบบ (System Tray Menu)
  • ระบบเปลี่ยนภาพพื้นหลัง (Background Selector) รองรับทั้งคลังภาพในตัว, อัปโหลดจากเครื่อง หรือใส่ Image URL

---

🏗️ สถาปัตยกรรมระบบ (Architecture)

flowchart TD
    subgraph Frontend["Frontend (React 19 + TypeScript + Vite)"]
        UI["UI Pages & Modals<br>(Launcher, Diff, Language, Analysis, Tools)"]
        Router["TanStack Router"]
        Store["Zustand Stores<br>(Launcher, Settings, Modal, Diff)"]
        I18n["i18next (EN, TH, JA, KO, VI, ZH)"]
        Bindings["@bindings/g-launcher/*"]
        UI --> Router --> Store --> Bindings
        UI --> I18n
    end

    subgraph IPC["Wails v3 IPC & Event Gateway"]
        IPCBridge["Bidirectional Events & Go Service Bindings"]
        Bindings <--> IPCBridge
    end

    subgraph Backend["Backend (Go 1.24+)"]
        AppSvc["AppService<br>(Window Controls & App Version)"]
        FSSvc["FSService<br>(Process Management & Persistent Storage)"]
        GitSvc["GitService<br>(Self-Update, Proxy/Server, MinGit)"]
        DiffSvc["DiffService<br>(HDiffPatch, Zift, Chunk Protobuf)"]
        LangSvc["LanguageService<br>(ExcelData Binary & Thai Mod)"]
        IPCBridge <--> AppSvc & FSSvc & GitSvc & DiffSvc & LangSvc
    end

    subgraph OS["Windows System / Game Files"]
        GameExe["StarRail.exe / Game Process"]
        GameFiles["Game Assets / .backup / .zon"]
        Config["%APPDATA%/g-launcher"]
        Tools["bin/ (7za, hpatchz, zift, MinGit)"]
        FSSvc & GitSvc & DiffSvc & LangSvc --> OS
    end

---

💻 ข้อกำหนดของระบบและเครื่องมือพัฒนา (Prerequisites)

• Go 1.24+
• Node.js 22+
• Wails v3 CLI:

  go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.74
  

---

🛠️ วิธีการรันและบิลด์ (Development & Build)

1. ติดตั้ง Dependencies

# ติดตั้งแพ็กเกจ Frontend
cd frontend
npm install
cd ..

# ติดตั้งโมดูล Go
go mod tidy

2. รันในโหมดพัฒนา (Development Mode)

# รัน Wails dev (มี Hot Reload ทั้ง Frontend และ Backend)
wails3 dev

# หรือรันสคริปต์
.\run.bat

3. บิลด์สำหรับใช้งานจริง (Production Build)

# บิลด์แบบปกติผ่าน Wails Task
wails3 task build PRODUCTION=true

# หรือใช้สคริปต์ Build พร้อมบีบอัดขนาดไฟล์ด้วย UPX
.\build.bat

4. สร้างตัวติดตั้ง (Installer Packaging)

wails3 task package

---

🇬🇧 English

✨ Features

• Game Process Orchestration: Launch games with decoupled console execution flags (CREATE_NEW_CONSOLE | CREATE_BREAKAWAY_FROM_JOB) with active process lifecycle hooks.
• Full Multi-Language Support: Fully localized in English, Thai, Japanese, Korean, Vietnamese, and Chinese with live switching in the header. Includes game asset translation utilities.
• Smart Incremental Patching: Parse Hoyoverse manifest protobuf chunks, apply .hdiff delta patches with hpatchz, and apply .ziff archives via zift.
• Reliable CI/CD Self-Updating: Integrated release workflows via .github/workflows/build-launcher.yml and scripts/launcher-release.mjs verifying SHA-256 hashes against latest.json.
• Zero-Dependency Tooling: Auto-configures MinGit portable and extracts required binaries (7za.exe, hpatchz.exe, zift.exe) automatically.
• Data Safety First: Atomic config updates with Windows MoveFileEx and automatic rollback on patch failure.

---

📁 Project Structure

G-Launcher/
├── .github/workflows/       # GitHub Actions release & build workflows
├── assets/                  # Embedded binary tools (7za, hpatchz, zift, appicon)
├── build/                   # Wails build configurations & OS templates
│   ├── config.yml           # App metadata (CompanyName, ProductName, AppID)
│   └── windows/             # Windows manifests, icons, info.json
├── frontend/                # React 19 Frontend application
│   ├── bindings/            # Auto-generated Wails TypeScript bindings
│   ├── public/              # Static assets, backgrounds, locales (en, th, ja, ko, vi, zh)
│   └── src/                 # React components, pages, stores, hooks
├── internal/                # Go Backend Services
│   ├── app-service/         # Window lifecycle & version management
│   ├── diff-service/        # HDiffz, Ziff, and LDiff chunk patching
│   ├── fs-service/          # File dialogs, process runner, persistent storage
│   ├── git-service/         # Self-update, server/proxy downloader, portable MinGit
│   └── language-service/    # ExcelData binary patcher & Thai mod engine
├── pkg/                     # Shared Go packages & constants
│   ├── constant/            # Centralized URLs & configuration
│   ├── firefly/             # Protobuf parser & chunk loader
│   ├── hpatchz/             # HPatchz wrapper
│   └── sevenzip/            # 7-Zip archive utilities
├── proto/                   # Protobuf definitions
├── scripts/                 # Release & version calculation scripts (launcher-release.mjs)
├── AGENTS.md                # Engineering guidelines & development rules
├── build.bat                # Windows build & UPX compression script
├── main.go                  # Application entry point & service registration
└── Taskfile.yml             # Wails build tasks definition

---

📜 Engineering Guidelines

1. System-First Rule: Always implement and verify changes in the Go Backend (internal/, pkg/) first. Run go vet ./... and generate bindings before touching Frontend UI.
2. Strict No-Hardcoding: Do not hardcode URLs, IP addresses, ports, or absolute drive paths. Centralize constants in pkg/constant/constant.go.
3. Branch Workflow: All active development takes place on branch Dev.

---

🤝 Credits & Acknowledgments

• Firefly Shelter — The original upstream foundation, proxy architecture, and UI design.
• Horoyoi-san — Architectural enhancements (portable MinGit, safe rollback, Zig integration patterns, and update workflows).
• Wails — Next-generation desktop application framework for Go.
• Developed with ❤️ by GaCy.