# Hit2dll 真實遊戲資料需求清單

這份文件整理「之後要把 fixture / dry-run 換成真實 provider 時，需要從遊戲 runtime 取得的資料」。

重要註解：
- 這裡只列資料需求，不列記憶體位址、hook 點、反偵測或繞過方式。
- 需要遊戲記憶體或實機狀態的欄位可以先空著，但 schema 名稱先保留，避免主程式反序列化失敗。
- 「已多筆化」代表目前已可用 fixture 模擬多筆資料；後續主要缺真實資料 provider。
- 「尚未多筆化」代表目前多半只有單筆 schema sample；後續還要補真實 list 來源與多筆輸出。

## 最高優先級資料

如果要先讓主程式能接近真實運作，最先需要的是這些：

1. 角色基本狀態：血量、魔力、等級、經驗、角色名、伺服器、貨幣、背包格數與重量。
2. 角色所在位置：`MapID`、`ZoneID`、`ZoneType`、地圖名、區域名、`x`、`y`、`z`。
3. 目前目標：目標 `id` / `obj`、類型、名稱、血量、死亡狀態、座標、怪物資料 ID。
4. 場景 actor list：附近怪物、NPC、玩家、object id、血量、座標、是否正在攻擊我。
5. 背包 item list：物品 ID、數量、位置、名稱、綁定、品級、是否裝備、是否鎖定。
6. 技能 / buff / warning：技能冷卻、是否可用、buff 列表、地面技能警告範圍。
7. UI 樹與畫面資料：UI 文字、link/path、obj、座標大小、可見/可用狀態、截圖與像素。
8. 任務 / 隊伍 / boss / 地圖事件 list：主程式自動流程會讀這些 list 來判斷下一步。

## 共用欄位

所有真實資料 provider 建議都要附帶或能推導下列資訊：

| 資料 | 中文註解 |
| --- | --- |
| 取得時間 | 用來判斷資料是否過期。 |
| 資料來源 | 例如 runtime、UI、截圖、fixture、空資料。 |
| 是否有效 | 例如還沒進遊戲、換圖中、角色死亡、UI 未開啟時要能回報 invalid / empty。 |
| list 數量 | 主程式讀 list 時需要穩定回傳陣列，即使沒有資料也回 `[]`。 |
| map / zone / x / y / z | 很多 class 會 fallback 到角色座標，所以位置資料是共用基礎。 |
| object id / static id / unique id | 目標鎖定、NPC、boss、採集物、玩家都會用到。 |

## 程序、視窗與遊戲外層狀態

這類資料不是遊戲角色資料，但主程式會用它判斷 DLL 是否正常、目標視窗在哪裡。

| 資料 | 對應 handler | 需要的真實欄位 |
| --- | --- | --- |
| 綁定資訊 / GameInfo | `type 88` | PID、HWND、`hwnd64`、視窗標題、DLL/模組路徑、本機 IP、版本字串、是否已找到遊戲視窗。 |
| 本機 IP | `type 98` | local IPv4、來源、是否成功取得。 |
| 目標 process 查詢 | primary `203` | process name、PID、Android package / activity 對應關係。 |
| module loaded 查詢 | primary `202` | process id、module name、是否已載入。 |
| top activity | primary `204` / shell `dumpsys activity top` | package name、activity name、目前前景狀態。 |
| run app 狀態 | primary `205` | package / process name、啟動是否成功、啟動後 top activity。 |
| Android / 模擬器資訊 | primary `206` | `wm size` 寬高、`/proc/meminfo`、package versionCode / versionName、build.prop、shared prefs 需要讀取的檔案內容。 |
| 視窗大小與位置 | `type 250` | client rect、window rect、x/y/w/h、是否能移動或調整大小。 |

## 角色與座標

### Position / MapCoor

對應：`type 3`、raw `GetMyPos`、Lua state。

需要資料：
- `MapID`：目前地圖 ID。
- `ZoneID`：目前 zone / channel / scene ID。
- `ZoneType`：區域類型。
- `Map`：主程式相容顯示名稱，通常可用區域名或地圖名。
- `MapName`：地圖名稱。
- `ZoneName`：區域 / 分流 / 場景名稱。
- `x`、`y`、`z`：角色世界座標。
- 換圖 / loading / 未進遊戲狀態：避免回傳舊座標。

### PlayerInfoClass

對應：`type 2`、raw `ReadPlayerInfo`。

需要資料：
- 生存狀態：`hp`、`maxhp`、`mp`、`maxmp`。
- 等級與經驗：`Lv`、`EXP`、`MaxEXP`。
- 身分：`name`、`Server`。
- 戰鬥狀態：`IsPK`、`PvpType`、`MoveState`、`CanPlayerReturn`、`WarpableBuffState`、`IsFakeFight`。
- 目標摘要：`Atkname`、`AtkPtr`、`TargetName`、`NowTargetID`。
- 貨幣與資源：`gold`、`Diamond`、`Leaf`、`isUseLeaf`。
- 背包狀態：`NowBagCount`、`MaxBagCount`、`NowBagWeight`、`MaxBagWeight`、`Weight`。
- 自動戰鬥 / 跟隨：`IsAuto`、`AutoMode`、`AutoType`、`FollowType`。
- 任務與場景：`AutoQuestID`、`IsVillage`、`MapID`、`ZoneID`、`ZoneType`、`MapName`、`ZoneName`、`x`、`y`、`z`。
- 省電 /特殊狀態：目前 dry-run 只記錄 `RuntimeSavePowerEnabled`，真實 provider 需要讀到遊戲內實際狀態。

### SelectedMonsterInfoClass

對應：`type 10`、`cmd:"Get"`。

需要資料：
- `id` / `obj`：目前選中目標的 object id。
- `Type`：目標類型，需能區分怪物、NPC、玩家、boss 等。
- `Name`：目標名稱。
- `hp`、`maxhp`：目標血量。
- `IsDeadState`：是否死亡。
- `AttackPlayerid`：正在攻擊的玩家 ID，若遊戲有此資料。
- `MonsterDataId`：靜態怪物資料 ID。
- `x`、`y`、`z`：目標座標。

## Actor、NPC、玩家列表

### ActorClass[]

對應：`type 4`、raw `GetActorList`。目前已多筆化，主要缺真實 provider。

每個 actor 需要：
- `id`：actor id。
- `ObjectID`：遊戲 object id。
- `Type`：actor 類型。
- `Lv`：等級。
- `Name`：名稱。
- `GuildName`：公會名，玩家 actor 會用到。
- `IsBoss`：是否 boss。
- `MonsterGrade`：怪物品級。
- `NowHP`、`MaxHP`：目前 / 最大血量。
- `Ptr`：相容原 DLL 的 actor pointer 字串；若不提供真實 pointer，可先給穩定識別字。
- `TargetPtr`：actor 目前目標 pointer / id。
- `IsAttackMe`：是否正在攻擊我。
- `x`、`y`、`z`：座標。

### NpcListClass[]

對應：legacy `GetMonsterInfoList()`。目前尚未多筆化。

每個 NPC / 怪物資訊需要：
- `id`、`StaticId`、`uid`。
- `name`。
- `curhp`、`maxhp`、`Hp`。
- `NpcID`。
- `IsMonster`。
- `x`、`y`、`z`。

### StaticNpcListClass[]

對應：legacy `GetSceneNpcList(...)`。目前尚未多筆化。

每筆需要：
- `staticId`。
- `uniqueid`.
- `name`.
- `x`、`y`、`z`.

### PlayerListClass[]

對應：legacy `GetNearbyPlayers()`。目前尚未多筆化。

每個附近玩家需要：
- `id`。
- `name`。
- `curhp`、`maxhp`。
- `x`、`y`、`z`。

## 背包、倉庫、商店、交易

### ItemClass[]

對應：`type 8` `Bag`、raw `GetItemData`、部分 `StorageList` schema。已多筆化，主要缺真實 provider。

每個物品需要：
- `id`：list index / slot id。
- `Pos`：背包位置。
- `isEquipWear`：是否穿戴中。
- `Type`：物品類型。
- `Bag`：背包分類。
- `obj`：物品物件識別。
- `BuffID`：相關 buff id，若有。
- `ItemID`：靜態物品 ID。
- `BindType`：綁定狀態。
- `Count`：數量。
- `Grade`：品級。
- `NameID`：名稱 ID。
- `NameHex`：目前相容欄位名，實際內容是物品名稱或原 DLL 名稱編碼。
- `OriName`：原始名稱。
- `isEquiped` / `isEquip`：是否已裝備。
- `EquipType`：裝備部位。
- `BLv`：強化 / 等級類欄位。
- `isLock`：是否鎖定。
- `Wei`：重量。
- `IsSelected`：是否選中。
- `CanTrade`：是否可交易。
- `IsCool`：是否冷卻中。

### StorageItemClass[] / WarehouseClass[]

對應：`type 8 StorageList`、legacy `GeWarehouseItemList()`。

需要資料：
- 倉庫物品與背包 item 同源欄位。
- 額外欄位：`count`、`enchant`、`grade`、`id`、`obj`、`isEquip`、`item`、`mounted`、`name`。
- 倉庫頁面 / 格子 / 是否已載入完畢。

### Sellable ItemClass[]

對應：legacy `GetCanSellProductList`。

需要資料：
- 可販售物品清單。
- 每筆使用 `ItemClass` 欄位。
- 額外需要是否可販售、販售價格或遊戲端實際販售限制；目前 schema 尚未列價格欄位，但 provider 需要知道以便判斷。

### ShopItemClass[] / GoodsListClass[]

對應：`type 8 GetShopList`。

需要資料：
- `Name` / `name`：商品名。
- `obj`：商品 object id。
- 商品靜態 ID、價格、貨幣類型、購買限制；目前相容 schema 只保留名稱與 obj，真實 provider 建議保留完整原始資料。

### TradeItemClass[]

對應：`type 8 GetTradeList`。

需要資料：
- `index`。
- `enchantLevel`。
- `itemId`。
- `Grade`。
- `Name`。
- `Count`。
- `RemainTime`。
- 價格、賣家、交易所狀態；目前相容 schema 未完全展開，但實作 provider 時建議保留。

## 技能、Buff、警告

### SkillClass[]

對應：`type 15` list read。

每個技能需要：
- `id`：list index。
- `SkillID`：技能 ID。
- `Name`：技能名。
- `CDTime`：冷卻剩餘時間。
- `NowComboIndex`：combo 階段。
- `IsAttackSkill`：是否攻擊技能。
- `IsChanged`：是否變化技能。
- `CanUse`：是否可用。
- `IsLearned`：是否已學習。
- 目標限制、消耗、距離、施法條件；目前 schema 未完整列出，但真實動作會需要。

### BuffClass[]

對應：`type 25` `ReadBuff`、raw `GetEffectData`、team nested buff。已多筆化。

每個 buff 需要：
- `Name`。
- `Type`。
- `id`。
- 建議額外保留剩餘時間、堆疊數、來源、是否 debuff；目前相容 schema 尚未展開。

### SkillWarningClass[]

對應：`type 52` `GetSkillWarningList`。已多筆化。

每個地面 / 範圍警告需要：
- `MainActor`。
- `type`、`type2`。
- 警告中心 `x`、`y`、`z`。
- 主 actor 座標 `MainActorx`、`MainActory`、`MainActorz`。
- 方向角 `AngleX`、`AngleY`、`AngleZ`。
- 命中範圍 `HitRange1`、`HitRange2`。

### FxWarningClass[]

對應：`type 2` 搭配 `ReadFxWarningList` / `GetFxWarningList` hint。

每個 FX warning 需要：
- `singHang`。
- `animationHang`。
- `channelHang`。
- `singTime`。
- `targetRelationType`。
- `targetType`。
- `uid`。
- `targetx`、`targety`。
- `SkillName`。

## 任務、委託、隊伍

### MissionClass[]

對應：`type 7` `ReadMission`、legacy `GerCurTasInfo()`。已多筆化。

每個任務需要：
- `index`。
- `Questid`。
- `type`。
- `NowCount`、`MaxCount`。
- `NowStep`。
- `State`。
- `Step`。
- `SubQuestCount`。
- `task_id`。
- `StepName`。
- `Name`。

### TrusrMissionClass[] / TrustMissionClass[]

對應：`type 70` `ReadTrustMission`。已多筆化。

每個委託任務需要：
- `index`。
- `Questid`。
- `type`。
- `NowCount`、`MaxCount`。
- `NowStep`。
- `QuestType`。
- `State`。
- `Step`。
- `SubQuestCount`。
- `task_id`。
- `StepName`。
- `Name`。

### TeamClass[]

對應：`type 30` `GetTeamList`。已多筆化。

每個隊員需要：
- `ChannelID`。
- `IsLeader`。
- `NowHP`、`MaxHP`。
- `NowMP`、`MaxMP`。
- `ObjectID`。
- `ZoneID`。
- `ZoneName`。
- `Name`。
- `mapid`。
- `x`、`y`、`z`。
- `buff`：隊員 buff list，使用 `BuffClass[]` schema。

## 卡片與收藏

### TransformationCardClass[]

對應：`type 37` `GetPetList`、`GetCharacterCardList`。已多筆化。

每張卡需要：
- `CardID`。
- `Index`。
- `id`。
- `name`。
- `grade`。
- `Amount`。
- `isActivating`。

### BuffCardClass[]

對應：`type 37` generic `Get`、`GetEquipShape`、`GetVehicle`。已多筆化。

每張卡 / 外觀 / 坐騎資料需要：
- `id`。
- `name`。
- `grade`。
- `Amount`。
- `isActivating`。

### CollectItemListClass[]

對應：`type 50` `ReadCollectItemList`。已多筆化。

每個收藏項目需要：
- 外層：`Grade`、`Index`、`IsCompleted`、`IsValidPeriodItem`、`EquipCollectionid`、`Name`、`SubType`、`Type`、`UIOrder`、`Parameter`。
- 需求物品 `ItemList`：`CollectItemName`、`ItemName`、`TargetLevel`、`IsReg`、`GroupType`、`Grade`、`BLv`。
- 獎勵 `Reward`：`Name`、`TypeNo`、`Value`。

## Boss、地圖、天氣、事件

### WorldBossClass[]

對應：`type 51` `ReadWorldBossList`。已多筆化。

每個世界 boss 需要：
- `IsAppear`。
- `LuckyGoblinSpawnId` / spawn id。
- `index`。
- `type`。
- `SummonerIndex`。
- `MapID`。
- `ZoneID`。
- `NPCID`。
- `ZoneName`。
- `MapName`。
- `NPCName`。
- `x`、`y`、`z`。
- `RemainTime`。
- `BossObjectIDList`。

### ShadowDungeonBossClass[]

對應：`type 57`。目前尚未多筆化。

每個 shadow dungeon boss 需要：
- `index`。
- `BossID`。
- `IsAppear1`。
- `IsAppear2`。
- `MapID`。
- `ZoneID`。
- `ZoneName`。
- `BossName`。
- `x`、`y`、`z`。
- `MonsterGrade`。

### MVPBossClass[]

對應：`type 56` 預設 boss schema。目前尚未多筆化。

每個 MVP boss 需要：
- `index`。
- `type`。
- `SpawnIndex`。
- `Pageindex`。
- `BossID`。
- `MapID`、`MapID2`。
- `ZoneID`。
- `ZoneChannelType`。
- `Grade`。
- `IsWaiting`。
- `ZoneName`。
- `BossName`。
- `NPCName`。
- `x`、`y`、`z`。
- `BossTime`。
- `IsSkipSkill`、`SkipSkillType`。
- `IsCheckAttackGroup`。
- `IsMVPCapScreen`。
- `IsTeamOnlyHelper`。
- `IsDelayGo`、`DelayGoTime`。
- `StopWaitTime`。
- `IsFightCenter`、`FightCenterStr`。
- `IsWaitSkip`、`WaitSkipTime`。

### VariantClass[]

對應：`type 56` 搭配 `ReadVariantList` / `GetVariantList`。目前尚未多筆化。

每個 variant 需要：
- `BossID`。
- `MapID`、`MapID2`。
- `NPCName`。
- `ZoneChannelType`。
- `ZoneID`。
- `ZoneName`。
- `index`。
- `type`。
- `x`、`y`、`z`。

### MVPDataClass[]

對應：legacy `GetBossList()`。目前尚未多筆化。

每個 boss 狀態需要：
- `name`。
- `BossType`。
- `alive`。
- `sceneId`。
- `id`。
- `time`。
- `DailyRefreshLimit`。
- `aliveSoon`。

### AllMapInfoClass[] / MapInfoClass[]

對應：`type 66`。目前尚未多筆化。

每張地圖 / 區域需要：
- `MapID`。
- `MapName`。
- `Type`。
- `Type2`。
- `Type3`。
- `ZoneID`。
- `ZoneName`。

### WeatherClass[]

對應：legacy `GetWeatherList()`。目前尚未多筆化。

每筆天氣資料需要：
- `dayNightIndex`。
- `i`。
- `weather`。
- `Name`。
- `Time`。
- `PickCDSpeedUp`。

### GroundCollectClass[]

對應：legacy `GetHorticultureList()`。目前尚未多筆化。

每個地面採集 / 栽培物件需要：
- `sceneId`。
- `respawnTime`。
- `respawnCooldown`。
- `availableToGrow`。
- `ktime`。
- `PlayerCount`。
- `id`。
- `name`。
- `x`、`y`、`z`。

### AdItemClass[]

對應：`type 68`。目前尚未多筆化。

每個廣告 / UI item 需要：
- `IsRunn`。
- `link`。
- `obj`。
- `x`、`y`、`w`、`h`。

## UI、截圖與像素

### UI node / UI list

對應：`type 0`、raw UI command、primary `207`。

每個 UI 節點需要：
- `Result`。
- `txt` / `Txt`：顯示文字。
- `link` / `path`：主程式尋找 UI 的路徑。
- `name` / `Name`。
- `clsname` / `Type`。
- `obj`：可用於後續 click / press / set text 的物件識別。
- `Hex`：handle / object 的 hex 表示。
- `IsRunn` / `IsShow`：是否顯示。
- `IsEn` / `IsEnabled`：是否可用。
- `SetSelected`：選取狀態。
- `x`、`y`、`w`、`h`。
- `son`：children list。
- UI XML：完整 XML tree、畫面寬高、package/class/resource-id/text/bounds。

### Screenshot / pixel

對應：primary `type 4` / `type 5` / `type 15`、UI `CapScreen`。

需要資料：
- 目前畫面截圖 bitmap / PNG。
- 指定座標 RGB：`red`、`green`、`blue`。
- 區域比色結果：目標色、相似度、採樣數、命中數。
- 圖色特徵點：多點座標與顏色。
- 截圖來源、截圖時間、目標視窗大小。

## 需要真實副作用確認的 action 狀態

目前這些 handler 多數是 dry-run。若要變成真實遊戲操作，除了發出動作，還要能讀回「動作是否成功」。

| 動作 | 對應 handler | 需要的真實資料 |
| --- | --- | --- |
| UI click / press / set text / scroll / checkbox | `type 1 UI` | 目標 UI 是否存在、點擊座標、操作前後 UI 狀態、失敗原因。 |
| touch / swipe | `type 101-105` | 螢幕尺寸、座標縮放、touch 是否送達、操作後角色/UI 是否變化。 |
| PC mouse / keyboard | `type 200` / wrapper `202` | 目標視窗、前景狀態、座標縮放、按鍵送達結果。 |
| 移動 / GroundMove | `type 9`、raw `GroundMove` | 目標座標、移動中狀態、到達結果、卡住/不可達原因。 |
| 傳送 | `type 11` | 目標 map/zone、傳送前後 map/zone、冷卻、費用、失敗原因。 |
| 自動戰鬥 | `type 14` | 自動戰鬥開關、模式、目標類型、跟隨類型、遊戲內實際開關狀態。 |
| 省電 | `type 18` | 省電開關前後狀態。 |
| 鎖定目標 / 不攻擊鎖定 | `type 26` / `type 55` | 目標 obj/id 是否有效、是否已選中、是否開始攻擊。 |
| 定點戰鬥 | `type 35` | 定點座標、範圍、是否啟用、角色是否偏離。 |
| 掃描間隔 | `type 39` | interval、enabled、目前掃描狀態。 |
| 設定類 | `type 53` | search range、各 setting key 的舊值與新值。 |
| 快捷列捲動 | `type 54` | 目前 quickslot 頁/位置、捲動後頁/位置。 |
| dump / diagnostic | `type 89` | dump 是否真的產生、檔案位置。 |
| item action | `type 8` action | item id/obj、數量、選取狀態、使用/丟棄/販售/選取是否成功。 |
| skill action | `type 15` action | skill id、目標 id、是否可施放、CD、施放後結果。 |
| legacy Lua action | raw `type 1` Lua | Lua command 名稱、參數、執行結果、失敗原因。 |

## Legacy raw / Lua list 需要資料

這些不是新 type 的主要路徑，但主程式或工具仍可能送來：

| Lua / raw command | 對應資料 |
| --- | --- |
| `GetWeatherList()` | `WeatherClass[]`。 |
| `GerCurTasInfo()` | `MissionClass[]`。 |
| `GetSceneNpcList(...)` | `StaticNpcListClass[]`。 |
| `GetHorticultureList()` | `GroundCollectClass[]`。 |
| `GetMonsterInfoList()` | `NpcListClass[]`。 |
| `GetBossList()` | `MVPDataClass[]`。 |
| `GetNearbyPlayers()` | `PlayerListClass[]`。 |
| `GetEffectData` | `BuffClass[]`。 |
| `GetActorList` | `ActorClass[]`。 |
| `GetItemData` | `ItemClass[]`。 |
| `GeWarehouseItemList()` | warehouse-compatible item list。 |
| `GetCanSellProductList` | sellable `ItemClass[]`。 |
| `GetFishing()` | 釣魚是否成功、結果碼、狀態訊息。 |

## 目前最缺的真實資料 provider

依照目前重構進度，缺口可以這樣排：

1. P0：真實 `PlayerInfoClass`、`MapCoor`、`SelectedMonsterInfoClass` provider。
2. P0：真實 `ActorClass[]`、`ItemClass[]`、`BuffClass[]` provider。
3. P0：真實 UI tree / UI XML / screenshot / pixel provider。
4. P1：真實 `MissionClass[]`、`TeamClass[]`、`SkillClass[]`、`SkillWarningClass[]` provider。
5. P1：真實 `WorldBossClass[]`、`CollectItemListClass[]`、card lists provider。
6. P2：`type 57` ShadowDungeonBoss、`type 66` AllMapInfo、`type 68` AdItem、`type 56` MVPBoss / Variant 多筆來源。
7. P2：legacy weather、static NPC、ground collect、NPC info、MVP data、nearby player 多筆來源。
8. P3：所有 action handler 的真實副作用與 readback 驗證。

## 可先空著的資料

在沒有實際遊戲或記憶體資料時，這些可先維持空值、`0`、`[]` 或 fixture：

- pointer 類欄位：`Ptr`、`TargetPtr`、`AtkPtr`。
- boss 稀有事件資料：MVP、shadow dungeon、variant、world boss object id list。
- 地圖完整清單：`AllMapInfoClass[]`。
- 天氣、採集物、廣告 item。
- 商店 / 交易所價格與限制。
- 實際 action 成功判定。
- 反映遊戲內部狀態但目前主程式不一定立即使用的額外欄位。