From 77feff697b2a632f301eaa9a69eee6a743bb90b4 Mon Sep 17 00:00:00 2001 From: CAtlas0784 Date: Thu, 17 Sep 2026 23:49:12 +0700 Subject: [PATCH] docs(skills): add comprehensive ananta-ps-engine skill with architecture, runbooks, and reference guides --- .agents/skills/ananta-ps-engine/SKILL.md | 122 ++++++++++++++ .../references/binary_patching_guide.md | 48 ++++++ .../references/combat_and_switching_system.md | 44 +++++ .../references/debug_api_and_webui.md | 89 +++++++++++ .../references/npc_and_monster_system.md | 63 ++++++++ .../references/protocol_and_world_entry.md | 54 +++++++ .../references/proxy_and_security_bypass.md | 150 ++++++++++++++++++ .../references/scene_and_weather_system.md | 56 +++++++ 8 files changed, 626 insertions(+) create mode 100644 .agents/skills/ananta-ps-engine/SKILL.md create mode 100644 .agents/skills/ananta-ps-engine/references/binary_patching_guide.md create mode 100644 .agents/skills/ananta-ps-engine/references/combat_and_switching_system.md create mode 100644 .agents/skills/ananta-ps-engine/references/debug_api_and_webui.md create mode 100644 .agents/skills/ananta-ps-engine/references/npc_and_monster_system.md create mode 100644 .agents/skills/ananta-ps-engine/references/protocol_and_world_entry.md create mode 100644 .agents/skills/ananta-ps-engine/references/proxy_and_security_bypass.md create mode 100644 .agents/skills/ananta-ps-engine/references/scene_and_weather_system.md diff --git a/.agents/skills/ananta-ps-engine/SKILL.md b/.agents/skills/ananta-ps-engine/SKILL.md new file mode 100644 index 0000000..3f52043 --- /dev/null +++ b/.agents/skills/ananta-ps-engine/SKILL.md @@ -0,0 +1,122 @@ +--- +name: ananta-ps-engine +description: >- + Expert toolkit, procedures, and architectural patterns for reverse engineering, + proxying, and emulating NetEase Unity/il2cpp games (specifically Project Mugen / + Ananta CBT 4229938 and similar NetEase titles). Use when the user asks to analyze, + build, configure, debug, patch, or run private servers, proxies, authentication bypasses, + combat routers, NPC/monster spawners, weather engines, or protocol handlers. +--- + +# Ananta & NetEase Unity Private Server Engine Skill + +This skill provides the comprehensive architectural blueprint, protocol specifications, and operational runbooks for developing and maintaining private servers for **Project Mugen / Ananta (client 4229938)** and similar NetEase Unity/il2cpp titles. + +--- + +## Architecture Overview + +```mermaid +flowchart TD + subgraph Client["Ananta Client (Unity IL2CPP 4229938)"] + CA["GameAssembly.dll\n(TLS & Anti-Cheat Bypassed)"] + UI["Unity UI & MPay WebView"] + GameWorld["In-Game World\n(Combat / NPCs / Weather)"] + end + + subgraph Proxy["HTTPS Proxy Stack (:443, :80, :5801)"] + Cert["DRMK Local Proxy Root CA"] + AuthBypass["MPay JS Bridge Auth Bypass"] + ShaderOOM["Shader Warmup OOM Suppressor"] + ServerList["7-Column Server List Provider"] + end + + subgraph Server["Game Server (.NET 8 C#)"] + LoginGate["Login & Gate Service (:5200, :5201)"] + WorldRouter["UXRPC Game Router (:5202)"] + CombatRouter["Pure DRMK Combat Router"] + NpcRouter["Unified Agent & POI Spawner"] + DebugAPI["Embedded Debug WebUI (:5809)"] + end + + UI -->|HTTPS Login & Gateway| Proxy + CA -->|UXRPC Protocol| Server + Proxy -->|Redirect to Gate| LoginGate + LoginGate -->|Hand off to World| WorldRouter + WorldRouter --> CombatRouter + WorldRouter --> NpcRouter + DebugAPI -->|REST Controls| WorldRouter +``` + +--- + +## Core System Pillars & Reference Manuals + +### 1. Unified NPC & Monster Entity System +- **Single Agent Model**: Monsters, bosses, street citizens, police officers, and domestic animals all share the exact same entity schema defined in `AgentConfig.json` (9,347 records). +- **Faction Camps**: Camp `0`/`26` for hostile monsters/bosses, Camp `2` for civilians, Camp `11` for animals, Camp `16..25` for police/guards. +- **POI Actions**: Idle (`2`), Walk (`1`), Run (`4`), Phone Call (`11`), Lean on Wall (`10`), Sit (`12`/`13`), Clapping (`6`), and Panic (`3`). +- **Player-Relative Grid**: Spawns groups in front of the player based on live yaw angle and configurable X/Z spacing. +- 📖 [Detailed NPC & Monster System Guide](./references/npc_and_monster_system.md) + +### 2. Pure DRMK Combat & Character Switching +- **Unbroken Combos**: Eliminates artificial server-side cooldown ticks (`SkillCooldownUntilTicks`) so multi-hit light attacks, heavy attacks, and skills chain smoothly without animation stutter. +- **Authoritative Replenish**: Stamina and ultimate charge are replenished exclusively when the full combo chain finishes (`restoreResources == true`). +- **Clean Despawn (`SyncLogicAgentLeave`)**: Formally removes previous characters from the world when switching, completely preventing character lockups, ghost entities, and floating "F" interaction prompts. +- 📖 [Detailed Combat & Switching Architecture Guide](./references/combat_and_switching_system.md) + +### 3. Scene ("Raid") Switching, Weather & Map Warp +- **Triad ID Architecture**: Scene transitions require authoritative `raidId`, `instanceId`, and `universeId` matching `RaidConfig.json` and `MapentranceConfig.json`. +- **Hybrid Atmospheric Control**: 5 standard weather states (`WeatherCatalog4229938`) coupled with client overrides for GPU particle rain (`SetGPURainActive`) and Volumetric Exponential Fog (`SetFogDensity`). +- **2-Click Pin & Warp**: Click once to place pin, click pin again to warp. Protects against fallback to void coordinates `(0, 0, 0)`. +- 📖 [Detailed Scene, Weather & Map Warp Guide](./references/scene_and_weather_system.md) + +### 4. Embedded Debug API & Web Management Panel +- **Integrated Daemon**: Self-contained HTTP REST server on `http://127.0.0.1:5809/` with frontend `index.html` compiled into `Ananta.App.dll`. +- **Interactive Catalog Table**: Realtime search across all 9,347 agents with category tabs, pose picker, and `[➕ Add]` buttons to queue spawn commands instantly. +- 📖 [Detailed Debug API & WebUI Guide](./references/debug_api_and_webui.md) + +### 5. Multi-Domain HTTPS Proxy & Auth Bypass +- **Native MPay JS Bridge**: Auto-authenticates web logins without touching NetEase authentication servers. +- **Shader Warmup OOM Prevention**: Suppresses the 11k shader pre-warmup routine (`triggerWarmupBelowVersion: ""`) to prevent 19GB memory exhaustion. +- **7-Column Server List**: Passes client Contract MD5 verification. +- 📖 [Detailed Proxy & Security Bypass Guide](./references/proxy_and_security_bypass.md) + +### 6. Protocol Codec & V7 4-Step World Entry +- Strict handoff sequence: `SyncLogicAgentEnter` $\to$ `SyncManagedLogicAgent` $\to$ `SyncRaidBattleUnitSpirit` $\to$ `SyncPlayerCurrentSpirit` $\to$ `SyncSceneLoadCompleted`. +- 📖 [Detailed Protocol & World Entry Guide](./references/protocol_and_world_entry.md) + +### 7. Client Binary Patching (`GameAssembly.dll`) +- TLS certificate pinning bypass (`ValidateCertificate` $\to$ `31 C0 C3`). +- NEAC anti-cheat driver suppression. +- 📖 [Detailed Binary Patching Guide](./references/binary_patching_guide.md) + +--- + +## Standard Runbook + +### Step 1: Network & Certificate Preparation +1. Verify `C:\Windows\System32\drivers\etc\hosts` redirects `l50.update.netease.com` and related domains to `127.0.0.1`. +2. Ensure `DRMK Local Proxy Root` CA is installed in `Cert:\LocalMachine\Root`. +3. Verify ports `80`, `443`, `5801`, `5200`, `5201`, `5202`, and `5809` are free. + +### Step 2: Game Directory Verification +- `NtUniSdkBase.dll`: Must be original NetEase DLL (~6.16 MB), never a dummy stub. +- `GameAssembly.dll`: Patched with TLS pinning bypass (`31 C0 C3`). +- `boot.config`: Original game version (`pkg-version=20260804051818394p0`). + +### Step 3: Launching Stack +Run proxy and server together: +```powershell +# From workspace root: +.\START.cmd +``` + +### Step 4: Verification Checklist +- [ ] Proxy logs `[PX] listening on https://0.0.0.0:443`. +- [ ] Server prints `[READY] Приватный Сервер | client=4229938 | login=:5200,:5201 | game=:5202`. +- [ ] Launch `Ananta.exe`. +- [ ] No "Configuration content is corrupted" dialog. +- [ ] No 19GB RAM OOM crash. +- [ ] WebUI accessible at `http://127.0.0.1:5809/`. +- [ ] Entering world completes with active character controllable. diff --git a/.agents/skills/ananta-ps-engine/references/binary_patching_guide.md b/.agents/skills/ananta-ps-engine/references/binary_patching_guide.md new file mode 100644 index 0000000..12caabb --- /dev/null +++ b/.agents/skills/ananta-ps-engine/references/binary_patching_guide.md @@ -0,0 +1,48 @@ +# GameAssembly.dll (Il2Cpp) Binary Patching Reference + +This document outlines the standard binary patch patterns for NetEase Il2Cpp Unity clients to allow offline private server analysis. + +--- + +## 1. Unity TLS / Certificate Validation Bypass + +### Target: +`UnityEngine.Networking.CertificateHandler.ValidateCertificate` + +### Patch: +Replace function prologue with immediate return `true` / `0`: +```assembly +xor eax, eax +ret +``` +Opcode: `31 C0 C3` (or `B0 01 C3` for `mov al, 1; ret`). +This allows `UnityWebRequest` to communicate with custom local HTTPS proxies without certificate verification failures. + +--- + +## 2. PSO Warmup / Shader Compiling Stub + +### Target: +`UnityEngine.PSOWarmupAsyncOperation..ctor` + +### Patch: +```assembly +ret +``` +Opcode: `C3 CC CC CC` +Stubs out the engine-level warmup operation if boot configuration or remote JSON flags fail to suppress it. + +--- + +## 3. NetEase Anti-Cheat (NEAC) Stubbing + +### Target: +`NeacUtils.Initialize` or `AntiCheat` initialization routines. + +### Patch: +```assembly +xor eax, eax +ret +``` +Opcode: `31 C0 C3` +Prevents NEAC background thread monitoring and process termination during local debugging. diff --git a/.agents/skills/ananta-ps-engine/references/combat_and_switching_system.md b/.agents/skills/ananta-ps-engine/references/combat_and_switching_system.md new file mode 100644 index 0000000..ae90d6e --- /dev/null +++ b/.agents/skills/ananta-ps-engine/references/combat_and_switching_system.md @@ -0,0 +1,44 @@ +# Combat Combo & Character Switching Architecture Reference + +This document explains the technical implementation of Ananta's combat mechanics and character switching router (derived from the pure DRMK architecture). + +--- + +## 1. Combat System Architecture (`GameRouter.Combat.cs`) + +### Problem in Previous Implementations +In naive server implementations, servers artificially tracked server-side skill cooldowns (e.g. `SkillCooldownUntilTicks`) and rejected skill execution packets if sent within a cooldown window. Because Ananta's combat system relies on rapid, fluid multi-hit combo animations and animation cancel windows, artificial cooldowns resulted in: +- Interrupted combo chains (player character freezes after hit 2 or 3 of a light attack combo). +- Skills refusing to fire when triggered from a dodge/dash. +- Desynchronized charge energy meters. + +### The DRMK Pure Combat Solution +The DRMK model trusts the client-side animation state machine for combo continuity: +1. **Unconstrained Combo Chaining**: Remove artificial cooldown ticks on standard attacks and skills. +2. **`OnReportSkillEnd` Handling**: + - When a skill animation or combo phase completes, the client reports `report.newSkillId`. + - The server maintains the active skill context and avoids clearing resource snapshots mid-chain. +3. **Authoritative Resource Replenishment**: + - Stamina, ultimate gauge, and skill charges are only replenished when the full combo sequence finishes (`restoreResources == true`). + - This ensures continuous, uninterrupted combat combos while keeping resource states valid. + +--- + +## 2. Character Switching Architecture (`GameRouter.Switching.cs`) + +### The Floating "F" Prompt and Character Lockup Bug +When switching characters, naive implementations swapped the active character ID without formally despawning the previous character from the scene. This caused two major bugs: +1. **Ghost Unit Stalling**: The previous character remained in the scene hierarchy as a ghost entity. +2. **Floating "F" Key Interaction**: Because the previous character was an interactable NPC/companion, an "F: Switch Character" prompt hovered permanently over the active player's head. +3. **CharacterController Locking**: The newly spawned character had incomplete input authority, preventing movement, jumping, or turning. + +### The Clean Switch Solution +In `GameRouter.Switching.cs`: +1. **Authoritative Despawn of Previous Character**: + - Before bringing in the new character, the server sends `SyncLogicAgentLeave(oldUnitId)`. + - This forces the client to clean up the previous character's GameObject, SkinnedMeshRenderers, and interaction colliders. +2. **Clean Identity Assignment**: + - Spawns the incoming character with `isAgentSwitch: false` in `WorldCodec.CurrentSpirit`. + - Sends `SyncGamePause(false)` to guarantee the player controller receives unhindered input focus. +3. **Instant Responsiveness**: + - The player immediately gains 100% control over the new character (WASD, sprint, jump, attacks) with zero ghosting or floating UI elements. diff --git a/.agents/skills/ananta-ps-engine/references/debug_api_and_webui.md b/.agents/skills/ananta-ps-engine/references/debug_api_and_webui.md new file mode 100644 index 0000000..db5a13d --- /dev/null +++ b/.agents/skills/ananta-ps-engine/references/debug_api_and_webui.md @@ -0,0 +1,89 @@ +# Debug API & Web Management Panel Reference + +This document details the architecture and REST API of the embedded Debug Panel (`DebugApiServer.cs`) and WebUI (`index.html`). + +--- + +## 1. Architecture Overview + +The Debug API server is an embedded HTTP daemon running on `http://127.0.0.1:5809/`: +- **Self-Contained**: The web frontend (`index.html`) is embedded directly as an assembly resource inside `Ananta.App.dll`. +- **Zero-Dependency**: No external web server (Nginx/Apache/Node) is needed for debug operations. +- **Localhost Restricted**: Bound exclusively to loopback `127.0.0.1` for safety. + +--- + +## 2. Complete REST API Specifications + +### `GET /api/status` +Returns live state of the connected game session. +```json +{ + "online": true, + "player": { "x": 3142.7, "y": 0.0, "z": 2522.8, "yaw": 85.5 }, + "spawn": { "x": 3142.7, "y": 0.0, "z": 2522.8 }, + "ready": true, + "activeUnit": 1001 +} +``` + +### `GET /api/npc/catalog?cat={category}&q={query}&limit={limit}` +Queries the unified Agent database (`AgentConfig.json`) across 9,347 entities. +- **Parameters**: + - `cat`: `"all"` | `"monster"` | `"citizen"` | `"police"` | `"animal"` | `"ally"` + - `q`: Free-text search term (matches Chinese name, English name, or numeric ID) + - `limit`: Number of records (default `150`, max `300`) +- **Response**: + ```json + { + "categories": [ { "id": "monster", "label": "⚔️ Monsters & Bosses" }, ... ], + "poiActions": [ { "id": 2, "name": "🧍 Idle" }, { "id": 1, "name": "🚶 Walk" }, ... ], + "items": [ + { + "id": 40900579, + "name": "谜面帮哨兵 (Enigma Gang Sentry)", + "category": "monster", + "model": 86971020, + "camp": 26, + "defaultPoi": 0 + } + ] + } + ``` + +### `POST /api/npc/spawn` +Spawns a batch of NPCs or monsters in a player-relative grid. +- **Request Payload**: + ```json + { + "items": [ + { "npcFormworkId": 40900579, "poiActionId": 0 }, + { "npcFormworkId": 40130709, "poiActionId": 2 } + ], + "xSpacing": 1.5, + "zSpacing": 1.5, + "maxPerRow": 10 + } + ``` + +### `GET /api/scenes` +Returns dynamically parsed scene and raid entrance presets from `RaidConfig.json` and `MapentranceConfig.json`. + +### `POST /api/world/switch-scene` +Executes an authoritative world transition. +- **Payload**: `{ "preset": "longqi_temple" }` or custom `{ "raidId": 23300999, "instanceId": 20001223, "universeId": 76000888, "x": -4306.0, "y": 156.8, "z": -3240.8, "facing": 133 }`. + +### `POST /api/player/teleport` +Instantly teleports the player's active character. +- **Payload**: `{ "x": 100.0, "y": 20.0, "z": -50.0, "facing": 90.0 }`. + +### `POST /api/weather/set` & `POST /api/weather/fog` +- **Weather Payload**: `{ "weatherId": 3 }` (1: Sunny, 2: Cloudy, 3: Rain, 4: Storm, 5: Afterrain). +- **Fog Payload**: `{ "density": 0.08 }` (0.00 to 0.15). + +### `POST /api/player/toggle-clothes` +Toggles visibility of `SkinnedMeshRenderer` clothing meshes without hiding body geometry. + +### `POST /api/player/unstuck` & `POST /api/player/rollback-10s` +- **Unstuck**: Clears animation controller locks and restores player input. +- **Rollback**: Restores position from a rolling 10-second coordinate buffer. diff --git a/.agents/skills/ananta-ps-engine/references/npc_and_monster_system.md b/.agents/skills/ananta-ps-engine/references/npc_and_monster_system.md new file mode 100644 index 0000000..fcf8d2b --- /dev/null +++ b/.agents/skills/ananta-ps-engine/references/npc_and_monster_system.md @@ -0,0 +1,63 @@ +# Ananta NPC & Monster Entity System Reference + +This document details the unified Agent architecture for Project Mugen / Ananta CBT (Client 4229938), covering NPC civilians, hostile enemies/bosses, animals, and POI actions. + +--- + +## 1. Unified Agent Concept (`AgentConfig.json`) + +In Ananta (NetEase L50 engine), all living non-player entities in the world—whether they are street pedestrians, patrolling police officers, stray cats, or colossal bosses—share the exact same underlying entity model defined in `AgentConfig.json` (9,347 records). + +### Camp Classification (Factions) +The engine separates entity behaviors and combat hostility primarily using the `Camp` integer: + +| Camp | Category | Description & Examples | Default Behavior | +| :---: | :--- | :--- | :--- | +| **`0`, `26`** | **⚔️ Monsters & Enemies** | Hostile gangsters (谜面帮), thugs, mech bikers (狂飙引擎), TV-heads (电视脑), mutant bosses, and slime creatures. | Hostile, targets Player on sight, combat AI active. | +| **`2`** | **🚶 Citizens & Civilians** | Urban civilians, students, workers, passersby (e.g. Nanami McIntyre [40130709], Liam Brown [40130001], Fujiwara Kazuma [4065053]). | Neutral, wanders or plays idle/social POI animations. | +| **`11`** | **🐱 Animals & Mascots** | Domestic animals and quirky world mascots (e.g. Chaos Radio Duck [4065051], Squirrel Radio [4065052], Cats [40120100], Ducks [40120325], Pigeons [40120319]). | Ambient animal behaviors, flees or wanders, non-combatant. | +| **`1`** | **🤝 Allies & Story Companions** | Friendly NPCs, party members in narrative mode, quest givers. | Friendly to player, non-targetable by basic attacks. | +| **`16..25`** | **👮 Police & Security** | Baton patrol officers, shield riot guards, armed security enforcers. | Neutral/Law enforcement, attacks hostile gang factions. | + +--- + +## 2. POI Actions & Animation System (`UrbanDiversityPOIActionConfig.json`) + +NPCs and non-hostile entities can be spawned with specific Points of Interest (POI) action IDs that dictate their visual posture and interaction animation: + +| POI ID | Animation / Action Name | Description & Usage | +| :---: | :--- | :--- | +| **`0`** | `Auto / Default` | No specific POI; uses entity's default idle or combat stance. Ideal for monsters. | +| **`1`** | `走路 (Walk)` | Natural urban walking locomotion. | +| **`2`** | `idle (Idle Stand)` | Standard standing idle pose. Ideal for street citizens and guards. | +| **`3`** | `受惊 (Scared / Panic)` | Panic/frightened posture with hands raised. | +| **`4`** | `跑步 (Run)` | Jogging/running locomotion. | +| **`5`** | `围观 (Spectate)` | Standing and curiously watching an event / crowd gathering. | +| **`6`** | `站姿_通用_鼓掌 (Clap)` | Standing and applauding / cheering. | +| **`8`** | `使用售货机 (Vending Machine)` | Interaction with drinks/vending machines. | +| **`10`** | `站姿_通用_靠墙休息 (Lean Wall)` | Relaxed posture leaning back against a wall or lamp post. | +| **`11`** | `停驻拍照打电话 (Phone / Photo)` | Holding smartphone up to ear or taking photos. | +| **`12`** | `正式坐闲置 (Formal Sit)` | Sitting upright formally (on bench or chair). | +| **`13`** | `放松坐闲置 (Relaxed Sit)` | Casual sitting posture with relaxed limbs. | +| **`15`** | `坐着交谈 (Sit & Talk)` | Sitting while gesturing and talking to nearby companions. | + +--- + +## 3. Server-Side Spawning Pipeline (`GameRouter.Npc.cs`) + +When spawning an agent via `/api/npc/spawn`, the server executes the following pipeline: + +1. **Transform Calculation**: + - Computes player forward vector from player's current yaw rotation. + - Places the entity batch in an offset grid in front of the player (e.g. 5m forward, distributed with configurable X and Z spacing). + - Facing angle is rotated $180^\circ$ relative to player so spawned agents face toward the player. + +2. **Catalog Validation**: + - `NpcCatalog4229938.TryGet(npcFormworkId, out var npc)` ensures the ID exists in `AgentConfig.json`. + - Resolves model ID (`GeneralModelId`), anim set tag (`AnimStereotype` / `BattleAnimType`), and persona ID. + +3. **Packet Transmission Sequence**: + - **`SyncLogicAgentEnter`**: Instantiates entity ID, archetype, position (`Vec3`), rotation (`Vec3`), and base logic state. + - **`SyncManagedLogicAgent`**: Attaches AI controller, perception component, and behavior action group. + - **`SyncRaidBattleUnitSpirit`**: Links 3D visual model prefab and combat component asset. + - **`SyncNpcPoiAction`** (if POI ID > 0): Triggers POI animation cycle. diff --git a/.agents/skills/ananta-ps-engine/references/protocol_and_world_entry.md b/.agents/skills/ananta-ps-engine/references/protocol_and_world_entry.md new file mode 100644 index 0000000..2cbb1db --- /dev/null +++ b/.agents/skills/ananta-ps-engine/references/protocol_and_world_entry.md @@ -0,0 +1,54 @@ +# NetEase Unity / UX-RPC Protocol & World Entry Handoff Reference + +This document defines the packet framing, protocol conventions, and runtime handoff transactions required to successfully enter the world, switch characters, and manage gameplay state in Project Mugen / Ananta CBT 4229938. + +--- + +## 1. Frame Structure & Encryption + +The client communicates over TCP using binary packets: +- **Frame Header**: 4-byte payload length (big-endian). +- **Packet Structure**: + - `Header`: Packet Kind (`Invoke = 1`, `Return = 2`, `Notify = 3`) + Method ID (u32) + Sequence ID (u32). + - `Payload`: Binary serialized according to `RPCSerializeAuto.lua` / Il2Cpp `TypeSerializer`. +- **Encryption**: UxChaCha8 stream cipher. Disabled or transparently negotiated during local private server handshakes. + +--- + +## 2. The Strict 4-Step World Entry Handoff (V7 Protocol) + +When `Game_LoginGame` or `Game_RequestGameSceneData` is received, the server MUST NOT send presentation, buffs, or combat deltas until the canonical 4-step world entry transaction finishes: + +```text +Step 1: SyncLogicAgentEnter (Unit ID) +Step 2: SyncManagedLogicAgent (Unit ID, Player Pid, 0) +Step 3: SyncRaidBattleUnitSpirit (AOI / Position / Facing / Template) +Step 4: SyncPlayerCurrentSpirit (Player Pid, Template ID, Unit ID, isAgentSwitch: false) +``` + +### Loading Synchronization Sequence: +1. Server sends `SyncEnterScene`. +2. Client loads assets and sends `AskLoadSceneCompleted(sceneId, sessionId)`. +3. Server executes the 4-step handoff above. +4. Client sends `AskLoadingFinished(sceneId, sessionId)`. +5. Server sends `SyncSceneLoadCompleted(sceneId)` as the **first and only** response. +6. Once the client receives `SyncSceneLoadCompleted`, gameplay control is enabled! + +--- + +## 3. Character Switching & Position Persistence + +When switching spirits via `AskSwitchSpirit`: +1. Server saves current position & rotation from movement reports. +2. Server executes spirit swap without despawning or moving the actor. +3. Sends `SyncPlayerCurrentSpirit(pid, newTemplateId, newUnitId, isAgentSwitch: true)`. +4. The client plays the switch animation while preserving coordinate continuity. + +--- + +## 4. Web Traversal (Spider-Man Traversal Buffs) + +Ananta traversal mechanics (web swinging, wall-running, parkour) rely on persistent buff states applied to the player unit: +- `PersistentGrappleBuffId`: `52853760` +- `SharedBuffIds`: `[52607001, 52606154, 52606102, 52606124, 52853760, 52601457, 52601458, 52601459, 52800600, 52959514, 52959516, 52606105, 52605817]` +- When entering combat or traversal, server notifies `AskAddClientBuff` with these IDs. diff --git a/.agents/skills/ananta-ps-engine/references/proxy_and_security_bypass.md b/.agents/skills/ananta-ps-engine/references/proxy_and_security_bypass.md new file mode 100644 index 0000000..bdc0050 --- /dev/null +++ b/.agents/skills/ananta-ps-engine/references/proxy_and_security_bypass.md @@ -0,0 +1,150 @@ +# Proxy, SSL, UniSDK Auth, and Shader Warmup Bypass Reference + +This document details the exact mechanisms required to intercept, authenticate, and run NetEase Unity (il2cpp) clients (specifically Project Mugen / Ananta CBT 4229938 and similar NetEase titles) without modifying client binaries or using brittle fake DLLs. + +--- + +## 1. Two-Tier PKI Certificate Architecture + +Unity's modern HTTP/TLS stack rejects self-signed server certificates that have `CA=TRUE` directly on the leaf certificate. The correct solution is a clean two-tier PKI: + +1. **Root CA (`DRMK Local Proxy Root`)**: + - `Subject`: `CN=DRMK Local Proxy Root` + - `Basic Constraints`: `critical, CA=TRUE, pathlength=1` + - `Key Usage`: `CertSign, CRLSign, DigitalSignature` + - Installed into `Cert:\LocalMachine\Root` (Windows Trusted Root Certification Authorities). +2. **Leaf Certificate (`l50.update.netease.com`)**: + - `Subject`: `CN=l50.update.netease.com` + - `Basic Constraints`: `critical, CA=FALSE` + - `Enhanced Key Usage`: `1.3.6.1.5.5.7.3.1` (Server Authentication) + - Signed by the Root CA above. + - Includes full SAN (Subject Alternative Name) list for all NetEase update/auth domains. + +### Required Redirect Domains in `hosts`: +```text +127.0.0.1 l50.update.netease.com +127.0.0.1 serverlist-test.l50.leihuo.netease.com +127.0.0.1 l50.gdl.netease.com +127.0.0.1 l50.gph.netease.com +127.0.0.1 l50.gsgph.netease.com +127.0.0.1 service.mkey.163.com +127.0.0.1 qatest.g.mkey.163.com +127.0.0.1 bind-mobile.g.mkey.163.com +127.0.0.1 mpay-common-server.g.mkey.163.com +127.0.0.1 whoami.nie.netease.com +127.0.0.1 protocol.unisdk.netease.com +127.0.0.1 tpsl.nie.netease.com +127.0.0.1 applog.matrix.netease.com +127.0.0.1 mgbsdk.matrix.netease.com +127.0.0.1 mgbsdktest.matrix.netease.com +127.0.0.1 dns.update.netease.com +127.0.0.1 openapi.music.163.com +``` + +--- + +## 2. Authentic `NtUniSdkBase.dll` WebView Bridge Auth Bypass + +Do **NOT** replace `NtUniSdkBase.dll` with a fake stub DLL. Use the authentic NetEase DLL (6.16 MB) and intercept the WebView login request: + +1. In the HTTPS proxy (port 443), intercept: + - `GET /local-mpay-login` + - `GET /sdk/uni_sauth` + - `POST /sdk/check_enter` +2. When UniSDK requests `service.mkey.163.com/local-mpay-login`, return a lightweight HTML payload containing a client-side JavaScript bridge trigger: + ```javascript + const user = { /* account payload */ }; + const payload = { + methodId: "ngwebview_notify_native", + reqData: { + methodId: "onUserLogin", + device_id: user.device_id, + deviceid: user.deviceid, + udid: user.udid, + user: user + } + }; + + function sendLogin() { + try { + if (window.NeteaseMpayJSBridge?.Common?.onUserLogin) { + window.NeteaseMpayJSBridge.Common.onUserLogin(user); + } + } catch (e) {} + try { + if (window.UniSDKJSBridge?.postMsgToNative) { + window.UniSDKJSBridge.postMsgToNative(payload); + } + } catch (e) {} + } + window.addEventListener("NeteaseMpayJSBridgeReady", sendLogin); + setTimeout(sendLogin, 200); + ``` +3. This delivers the login callback straight into `NtUniSdkBase.dll` natively. + +--- + +## 3. Shader Warmup OOM & RAM 100% Suppression + +When `triggerWarmupBelowVersion` in `pc_netease_version.json` contains a version string, the engine triggers warmup for all 11,384 shaders simultaneously across all CPU threads at full speed (`d3d12-pso-warmup-full-speed=true`), causing a 19+ GB memory surge and a `CreateCommittedResource (8007000e)` crash. + +**Fix**: +In `pc_netease_version.json`: +```json +{ + "resUpdate": [{ + "minV": "0", + "maxV": "18446744073709551615", + "resV": "20260805061659654p0", + "resC": "b5481abf8e882801b424fe2c0bf0adfe", + "soResC": "", + "enableDlc": "False", + "triggerWarmupBelowVersion": "", + "codeV": "4229938", + "artifactV": "4221361", + "enableIBT": "False", + "enableIBTOneInN": "1" + }] +} +``` +Setting `triggerWarmupBelowVersion: ""` (empty string) completely skips full PSO shader compilation! + +--- + +## 4. ServerList Contract MD5 Bypass + +Client 4229938 calculates its runtime Contract MD5. If `serverlist.txt` includes extra columns (hash, artifact, branch), `LoginManager.CheckVersion` checks the hash and rejects the server with *"Server is under maintenance"*. + +**Fix**: +Serve exactly 7 basic columns: +```text +*,801,QA101,Outer,http://127.0.0.1:5801/LoginList,1,14 +``` +Omitting the hash/version columns causes `CheckVersion` to skip validation entirely. + +--- + +## 5. System.Text.Json Case-Insensitive Collision Fix + +In C# .NET 8, building an anonymous object with both `deviceid` and `deviceId` throws: +```text +System.ArgumentException: An item with the same key has already been added. Key: deviceid +``` +This causes `CheckAccount` to fail silently and send an empty response, trapping the client at the start menu. + +**Fix**: +Use `Dictionary` instead of anonymous objects: +```csharp +var loginJson = JsonSerializer.Serialize(new Dictionary +{ + ["deviceid"] = deviceId, + ["device_id"] = deviceId, + ["udid"] = deviceId, + ["unisdk_device_id"] = deviceId, + ["code"] = 200, + ["subcode"] = 0, + ["msg"] = "ok", + ["uid"] = Profile.AccountId, + ["pid"] = Profile.PlayerPid +}); +``` diff --git a/.agents/skills/ananta-ps-engine/references/scene_and_weather_system.md b/.agents/skills/ananta-ps-engine/references/scene_and_weather_system.md new file mode 100644 index 0000000..69b6094 --- /dev/null +++ b/.agents/skills/ananta-ps-engine/references/scene_and_weather_system.md @@ -0,0 +1,56 @@ +# Scene Switching, Weather Engine, and Map Warp Reference + +This document covers the mechanics for world region ("raid") switching, atmospheric/weather control, and the 2-click pin & warp map interaction. + +--- + +## 1. Scene ("Raid") Switching (`SceneCatalog4229938.cs`) + +Ananta's open world is partitioned into distinct sub-regions, instances, and raids defined in `RaidConfig.json` and `MapentranceConfig.json`: + +### Triad ID Architecture +Every scene transition requires three authoritative identifiers: +1. **`raidId`**: The specific map/dungeon region (e.g. `23300888` for Main City, `23300999` for Longqi Mountain). +2. **`instanceId`**: The active scene instance (e.g. `20001222`, `20001223`). +3. **`universeId`**: The overarching world universe context (standard: `76000888`). + +### Dynamic Presets +The server parses all valid map entrances dynamically into `SceneCatalog4229938.Presets`: +- **Main City Center**: `raid: 23300888`, `x: 3142.7`, `y: 0`, `z: 2522.8` +- **Airport District**: `raid: 23300888`, `x: -4468.3`, `y: -6.2`, `z: -2597.5` +- **Longqi Ancient Temple**: `raid: 23300999`, `x: -4306.0`, `y: 156.8`, `z: -3240.8` +- **Longqi Tea Plantation**: `raid: 23300999`, `x: -4818.4`, `y: 192.3`, `z: -2690.1` + +When a switch is requested, the server sends `SyncSceneLoadCompleted` and teleports the player's managed spirit into the new instance. + +--- + +## 2. Weather & Atmospheric Control (`WeatherCatalog4229938.cs`) + +Ananta features an advanced hybrid weather pipeline combining server RPC state with client shader/particle overrides: + +### Standard Weather States (`WeatherCatalog4229938`) +| ID | Weather Name | Environment Visuals | +| :---: | :--- | :--- | +| **`1`** | **☀️ Sunny (晴天)** | Clear sky, bright sunlight, natural shadows. | +| **`2`** | **⛅ Cloudy (多云)** | Overcast clouds, diffused indirect lighting. | +| **`3`** | **🌧️ Rain (小雨)** | Light precipitation, road puddle reflections. | +| **`4`** | **⛈️ Storm (暴风雨)** | Heavy rain, thunderstorm lighting, active wind vectors. | +| **`5`** | **🌤️ Afterrain (雨后)** | High-clarity atmosphere, wet asphalt specular glimmers. | + +### Hybrid GPU Rain & Volumetric Fog +To guarantee visual effects render immediately without waiting for client transition cycles: +- **`CMD:SET_WEATHER:`**: Dispatched via `SyncNotice` to activate client-side GPU particle rain (`SetGPURainActive`). +- **`CMD:SET_FOG:`**: Direct override for Unity's Volumetric Exponential Fog density (e.g. `0.08` for heavy fog, `0.00` for crystal clear). + +--- + +## 3. 2-Click Pin & Warp Map Interaction + +### Problem with Standard Teleport +In default CBT clients, clicking on the mini-map or full map frequently triggered coordinate conversion errors, causing players to teleport to $(0, 0, 0)$ (ocean fall or out-of-bounds void). + +### The 2-Click Pin & Warp Pattern +1. **Click 1**: Left-clicking anywhere on the map drops a navigation pin and notifies the player: `"Pin set! Click again to Warp"`. +2. **Click 2**: Clicking directly on the set pin executes the warp to those precise world coordinates and automatically dismisses the map screen. +3. **Zero-Coordinate Safety Interceptor**: Both client proxy and server packet handlers intercept any destination vector matching $(0, 0, 0)$ or invalid NaN/Infinity coordinates, protecting the player from void death.