docs(skills): add comprehensive ananta-ps-engine skill with architecture, runbooks, and reference guides

.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.

.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.

.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.

.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.

.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.

.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.

.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<string, object?>` instead of anonymous objects:
+```csharp
+var loginJson = JsonSerializer.Serialize(new Dictionary<string, object?>
+{
+    ["deviceid"] = deviceId,
+    ["device_id"] = deviceId,
+    ["udid"] = deviceId,
+    ["unisdk_device_id"] = deviceId,
+    ["code"] = 200,
+    ["subcode"] = 0,
+    ["msg"] = "ok",
+    ["uid"] = Profile.AccountId,
+    ["pid"] = Profile.PlayerPid
+});
+```

.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:<id>`**: Dispatched via `SyncNotice` to activate client-side GPU particle rain (`SetGPURainActive`).
+- **`CMD:SET_FOG:<density>`**: 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.