# Honkai Impact 3 - Patcher

Patcher for Windows clients and Android APKs.

> [!WARNING]
> This repository contains AI-generated code.

| Patch | Platform | Target | Effect |
| --- | --- | --- | --- |
| Dispatch & SDK | Windows, Android | Unity assets, SDK bundle, CN DEX | Rewrites dispatch/SDK URLs to a chosen server |
| RSA | Windows, Android | `UserAssembly.dll`, passport DEX | Replaces the passport login RSA public key |
| ACE | Windows (≤ 8.9) | `BH3.exe` | Removes Anti-Cheat Expert via a local init capture |
| HoYoKProtect | Windows (9.0+) | `UserAssembly.dll` | Forces the client-side MHYP loader off |
| Protection | Android | 4 ELF libs, startup DEX | Removes AnoSDK (overseas) or Mobile ACE/TSS (CN) |

Unknown client layouts are refused; repeat runs are no-ops where
detectable. Windows patches edit the client in place; Android patches
write a separate signed `<name>_patched.apk`.

> [!CAUTION]
> Windows clients below 9.0 must apply the ACE Patch first!

## Build

Requires [Rust](https://rustup.rs/) (edition 2024). Build on the OS you
run it on:

```sh
cargo build --release --locked
```

Output: `target/release/Hi3-Patcher` (`.exe` on Windows). Android patches
need extra tools at patch time; see [Environment](#environment).

## Usage

### Interactive

```sh
Hi3-Patcher
```

Arrow or number keys select, Enter confirms, Esc/`0` goes back.

### Command line

```
Hi3-Patcher <command> [options]

dispatch   --platform <windows|android> --input <path> --server <host[:port]> [--https]
rsa        --platform <windows|android> --input <path> [--key <base64-der>]
ace        --input <BH3.exe|folder> [--yes]
hoyok      --input <BH3.exe|folder>
protection --input <app.apk> [--variant <ano|tss|auto>]

--json                 Emit one JSON result object as the last stdout line
-h, --help             Usage
-V, --version          Version
```

- Windows input: the game folder or its `BH3.exe`. Android input: an APK.
- `rsa --key` takes a Base64 DER public-key body; omitted (or empty in the
  menu) uses the built-in PemukulPaku key. It must match
  `Passport:RsaPrivateKey` in the server's `appsettings.json`.
- `ace` launches the client once to capture its initialized state. On
  the command line this needs `--yes`; without it, nothing is changed.
- `protection --variant auto` (default) picks AnoSDK or Mobile ACE/TSS
  from the libraries in the APK.

### Exit codes and JSON

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | Patch or runtime error |
| 2 | Usage error (unknown command or option, missing or invalid value); nothing is changed |

With `--json`, the last stdout line is one JSON object; progress lines
come before it.

```json
{"ok": true,  "command": "protection", "output": "/path/App_patched.apk"}
{"ok": false, "error": "no production BH3 SDK URLs found"}
```

`output` is the written APK path for Android patches, `null` for Windows.

### Environment

Android signing needs Build-Tools 35 (`zipalign`, `lib/apksigner.jar`)
and Java 17+ (`java`, `keytool`). To use existing installs:

| Variable | Use |
| --- | --- |
| `HI3_ANDROID_TOOLS` | Build-Tools directory |
| `ANDROID_HOME`, `ANDROID_SDK_ROOT` | Scanned for `build-tools/*` |
| `JAVA_HOME` | Preferred Java runtime |

Otherwise the interactive menu (Platform > Android) offers to download
Build-Tools (~60 MB) and a Temurin JDK 17 (~190 MB) beside the binary,
SHA-256 verified; the command line then finds them there.

The signing keystore `Hi3-Patcher.keystore` is created beside the input
on first use. Keep it: updates must be signed with the same key.

## Layout

```
src/
  format/      Binary-format primitives (shared, no patch logic)
    bytes      Bounds-checked LE/BE integer access
    pe         PE32+ (x86-64) reader
    elf        ARM64 ELF reader
    dex        DEX field access, checksum fix-up, CN string growth
    unity      UnityFS bundles and serialized TextAssets (read, rebuild, resize)
  patch/
    region     Windows client region identity (ChannelConfig)
    dispatch/  Dispatch & SDK URL rewrite (windows, android, cn_android)
    rsa/       Passport RSA key replacement (windows, android, cn_android)
    ace/       ACE removal (discovery, capture, process, runtime, generate)
    hoyokprotect/  MHYP loader switch (discovery)
    protection/    AnoSDK + Mobile ACE/TSS, one profile-driven pipeline
  android/     APK signing: toolchain discovery/download, sign workflow
  util/        Atomic verified file replacement
  cli/         Interactive menu, args interface
```

## Documentation

| Document | Contents |
| --- | --- |
| [docs/architecture.md](docs/architecture.md) | Crate structure and shared format primitives |
| [docs/dispatch.md](docs/dispatch.md) | URL rewrite rules and asset containers |
| [docs/rsa.md](docs/rsa.md) | Passport RSA patch points and wrapper |
| [docs/ace.md](docs/ace.md) | ACE discovery, capture and rebuild |
| [docs/hoyokprotect.md](docs/hoyokprotect.md) | MHYP loader location and edit |
| [docs/protection.md](docs/protection.md) | ELF restore, native neutralize, DEX edits |