========================================================
 kk2ec  ——  把 Koikatsu 的 zipmod 转成 EmotionCreators 能用的
            （道具 Item  /  地图 Map   都能转，自动识别）
========================================================

【怎么用】（三种任选）

 1) 拖拽（最常用）
    把 KK 的 .zipmod 直接拖到  kk2ec.bat  上面，松手就行。
    道具包、地图包都一样拖 —— 程序会自己判断是哪种，不用你选。

 2) 丢进 in 目录
    把 .zipmod 复制到本目录的  in\  下面，然后双击  kk2ec.bat
    （不带参数时会自动处理 in\ 里所有 *.zipmod）。

 3) 批量转 mods\addzipmod 里的
    双击  kk2ec.bat 之后它是空跑的；批量请开命令行执行：
        kk2ec.bat --scan-mods

    特殊情况想强制指定（一般用不到）：
        kk2ec.bat --map  <文件>      强制当地图
        kk2ec.bat --item <文件>      强制当道具

【产物在哪】

    out\<原文件名>.EC.zipmod

    把它丢进  G:\emotioncreator\mods\addzipmod\  （以及 S 盘那份），重启游戏即可。

【注意】

 * **转换完之后，请把 KK 原版 zipmod 从 mods\addzipmod\ 里挪走。**
   两个都放着不会崩（我改了 guid 避免冲突），但原版那份的 bundle 会被
   白白加载进内存，而且 EC 里本来也读不了 KK Studio 的道具。

 * 转换是**离线**改 bundle，不是运行时兜底。改完的 zipmod 在没装
   EC_ItemMapLoader 的机器上也能用（但装上它才能让道具出现在「道具」列表里，
   地图出现在地图列表里）。

 * 游戏里去找：
     道具  -> 场景编辑器 → 道具 → 分类「アイテム / Item」
     地图  -> 地图 / 场景选择列表（和 EC 自带的地图排在一起）


========================================================
 它到底改了什么（为什么会失败、这里怎么修的）
========================================================

EC 和 KK 都是 Unity + Illusion 的 AssetBundle，但 KK 的道具直接拿到 EC 里会：

 ① 点不上、work 面板不出来
      KK 的 Studio 物品挂的脚本是 `Studio.ItemComponent`（配饰是
      `ChaAccessoryComponent`），EC 里根本没这个类 -> 组件 missing。
      -> 转成 EC 的 `Map.ItemComponent @ Assembly-CSharp.dll`，
         数据按 EC 的字段布局重写，并把 SerializedType 里声明的
         类型树 + script_id + old_type_hash 一起换掉。

 ② 模型全黑
      KK 用的 `Shader Forge/main_item*` 的 GPU program 是 Unity 5.6 编译的，
      2017.4 的 EC 加载不了。
      -> 把 EC_MaterialEditor 插件自带的那份「EC 可用」shader 整体搬进 bundle
        （ref\ec_shaders.unity3d，属性名和 KK 那份一模一样），
        并改名成 `ECItem/xxx`（见下）。

 ③ 发暗 / 光照不对
      KK 的道具在 Layer 10，而 EC 的 Layer 10 = Chara、Layer 11 = Map。
      -> 全部 GameObject 改成 L11。

 ④ 顺手修掉 AssetBundle 预加载表里指向 EC 不存在的内置资源
    （resources/unity_builtin_extra 的 path 10752）的悬空引用。

 ⑤ CSV
      KK Studio 格式（abdata/studio/info/**/ItemList_*.csv，17 列）
      -> EC Map 格式（abdata/map/info/itemlist_<P>.csv，26 列）
         ＋ itemcategory_<P>.csv
      已经是 EC 格式的（abdata/map/info/itemlist_*.csv）就原样保留，只转 bundle。

      管理番号 P 由 manifest 的 guid 哈希推出来（2000~2999），
      同一个 mod 每次转都是同一个号，不会越转越多。


========================================================
 为什么 shader 要改名成 ECItem/xxx
========================================================
EC_ItemMapLoader 插件里有个 IsShaderBroken()：名字以 "Shader Forge/" 开头、
或者含 "main_item" 的 shader 一律判成坏的，会拿它自己的库去替换。
改名既躲开这个启发式，也避免和 EC_MaterialEditor 已加载的同名 shader 撞车。
材质是按 PPtr 引用 shader 对象的，改名不影响绑定。


========================================================
 已知限制
========================================================
 * 道具在 KK 里如果靠 ItemBoneList 绑在角色身上（武器、头盔之类），
   到了 EC 只能当「立在场景里的静态模型」——EC 的 Map 物品系统没有
   绑定角色骨骼这套。模型本身的骨骼/蒙皮是好的（探针已验证）。
 * 只处理 .unity3d 资源包 + ItemList CSV。prefab 之外的东西
   （材质编辑器参数、KKPE 数据之类）不会跟过来。
 * 转换不改材质颜色。EC 的 Map.ItemComponent 只在 info[].useColor = 1 时
   才用道具颜色覆盖材质的 _Color/_Color2/_Color3；KK 的 CSV 里
   颜色开关都是 FALSE，所以材质原色会保留。


========================================================
 目录结构
========================================================
   kk2ec.bat          双击 / 拖拽入口
   kk2ec.py           转换主程序
   verify_ec.py       校验产物（转完想自检就跑它）
   使用说明.txt        本文件
   lib\               Python 依赖（UnityPy），别删
   ref\
       ec_item_template.unity3d   EC 原生物品，提供 Map.ItemComponent 模板
       ec_shaders.unity3d         从 EC_MaterialEditor 提取的、EC 能用的 shader 库
   in\                丢待转 zipmod 的地方
   out\               产物
   log\               每次转换的日志
   work\              转换时的临时目录（可随时删）


========================================================
 地图（Map）—— 自动识别，代码上走的是另一条线
========================================================
判据：zipmod 里只要有 `abdata/map/scene/*.unity3d`，就按地图处理；
没有就按道具处理。所以拖进来什么都不用管。

**为什么地图不用改 bundle：**
KK 地图的 scene bundle **本身就是 EC 能直接读的 Unity Scene** ——
里面的 MonoScript 本来就是 EC 的类型（SunLightInfo / H.HPointData /
H.HPointOmitObject）。它在 EC 里「用不了」的唯一原因是**没被登记**：
EC 只认 `abdata/map/info/maplist_<P>.csv` 里注册过的地图，
躺在 mods\ 里的 zipmod 不会被自动扫成地图。

所以地图转换 = **原地搬运 bundle** + 写一份 15 列的 maplist CSV：

    abdata/map/scene/<名>.unity3d        原样搬（一个字节都不改）
    abdata/map/thumbnail/<名>.unity3d    原样搬
    abdata/map/info/maplist_<P>.csv      新写
    manifest.xml                         新写

zipmod 里的 `h/common/purpleroom.unity3d`、`map/list/mapinfo/*.unity3d`
这些**不搬** —— EC 本体有同名文件，搬过去反而可能顶掉 EC 自己的。
（实测不搬也能正常切进去。）

**两个必须对上的点（错一个就切不过去）：**
 * CSV 第 8 列「ファイルパス」必须 == bundle 内 SerializedFile 的名字，
   也就是 `AssetBundle.GetAllScenePaths()` 那条路径的文件名去扩展名。
   ★ **不是** bundle 的文件名 —— `vszh.unity3d` 对应的是 `VSZH`（大写）。
   程序直接从 bundle 的 `m_Container` 里读出来，不猜。
 * 第 6/7 列 = manifest(空) / bundlePath(`map/scene/vszh.unity3d`)。
   缩略图同理放 9~11 列（Sprite 名优先取 `*_00`）。

**管理番号 P = 1000 + md5(guid) % 1000（1000~1999）。**
EC 原生地图占用 0~222，1000 以后是空的。地图表（dicMapLoadInfo）和
道具表（dicItemLoadInfo）是两个独立的字典，所以和道具的 2000~2999 不冲突。
分类（第 1 列）固定 0 —— EC 原生 223 张地图的分类全是 0，而且地图列表 UI
的分类是运行时从 dicMapLoadInfo 动态收集的，不需要额外写 category CSV。

**没带缩略图会怎样：** 自动指向 EC 自带的占位图
（`map/thumb/00.unity3d` / `non`），不用往 zipmod 里塞东西。

【实测（2026-10-04）】进游戏后的日志：
```
[EC Item & Map Loader] 已注入 MapList package=1339 <- abdata/map/info/maplist_1339.csv
[EC Item & Map Loader] 进入新场景: VSZH
[EC Item & Map Loader] 在场景 VSZH 中找到了 Map 实例，直接执行注入！
[EC Map Probe] dicMapLoadInfo 条目数 = 224
[EC Map Probe] ★ 找到 1 个 mod 地图条目 → no=1339 category=0 package=1339
[EC Map Probe]   objPath: bundlePath=map/scene/vszh.unity3d fileName=VSZH check=True
[EC Map Probe] ★★ scene 名匹配：「VSZH」正确，Map.LoadMap 能切过去
[EC Map Probe] ★ 缩略图 OK：name=vszh_13370_00 rect=320x180 tex=320x180
```
整局 `LogOutput.log` 只有 2 条 Error，全来自 JetPack 插件，和转换无关。
（Sideloader 那几条 failed archive 是别的既有坏包；Extended Save 的
NotSupportedException 是 EC 环境噪音。）

想再自检：探针源码 `itemmapload\src\EC_MapProbe\`，dll 在
`itemmapload\dist\probe\`（拷回 BepInEx\plugins\ 即可，**用完记得删**）。
v1.1 起它**不再写死番号/路径**，而是自动列出 dicMapLoadInfo 里所有
`no >= 1000` 的条目（= mod 注入的地图）并逐个核对，所以换地图不用改代码。


========================================================
 附：这次已经转好的
========================================================
   [Anna Anon] Chief.EC.zipmod      （original: [Anna Anon] Chief.zipmod）
   已在 2026-10-04 实机验证：
     GameObject 加载 OK / Map.ItemComponent 挂上 / 3 个 SkinnedMeshRenderer
     骨骼 93+6+1 根完整 / shader ECItem/item_studio supported=1 passCount=3
     / Avatar isValid=True / 零 Error 零 Warning。

   （那次验证用的一次性探针 EC_PhoneProbe.dll 已撤掉。）

   [The Lucky Freeman] Post-soviet Building Staircase.EC.zipmod
     （original: mods\kkbunengyongdmapmod\[The Lucky Freeman][KK] ...v1.0.zipmod）
     2026-10-04 实机验证：
       第一版用 1000 号 → `进入新场景: VSZH` + `在场景 VSZH 中找到了 Map 实例`。
       并入 kk2ec 后用 1339 号重转 → 再验一遍：注入成功 / 探针四项全绿 /
       scene 名匹配 / 缩略图 OK / 零转换相关报错。
     两份编号不同但等价；**别把两份同时装进去**（会变成两张同名地图）。
     现在部署的是 kk2ec 转的 1339 版（G: 与 S: 两侧都已替换）。
