chihya72
63cf9e04f2
Both index tools defaulted to one machine's absolute paths -- the game's
global-metadata.dat and an Il2CppInspector export under D:\GIT. Anyone else
cloning got a confusing failure pointing at a directory they do not have.
GKMS_METADATA and GKMS_INSPECTOR are now required, and an unset or dangling
variable says so and shows the assignment to run.
The docs listed the same paths as "current investigation machine inputs".
That framing was deliberate, but it does not survive publishing: the eleven
remaining absolute paths across six files are all prose pointing at a file
("deployed build", "log checked"), not verbatim tool output, so the drive
prefix carried no evidence and is now <game dir> / <repo>.
Also refreshes the hair thumbnail evidence, which still described the
ThumbnailViewBase.Set path removed on 2026-08-03.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Gakumas Mod Runtime
这是学园偶像大师本地 AssetBundle Mod 的独立游戏运行时。它通过 xinput1_3.dll 代理入口加载，
只负责扫描本地 Mod、拦截游戏资源加载并替换 Mesh、骨架映射和贴图。
本仓库不保存游戏提取资产、成品 Mod、旧测试 AB 包或生成报告。
当前能力
- 扫描
gakumas-mod/mods/<mod-id>/mod.json； - 支持 manifest v2 的
priority、part、renderers和贴图规则； - 支持
body=Geo_Body； - 支持
hair=Geo_Hair或Geo_Hair+Geo_HairProp； - 从本地 AssetBundle 懒加载替换资源；
- 启动时注册全部有效替换候选，并通过 Runtime API 在当前会话热切换有效规则；
- 标准
SkinnedMeshRenderer替换保存原 Mesh、材质和骨骼绑定；OFF 恢复当前实例与缓存 Prefab，ON 对对应资源子树重新应用； - 整对象替换与附加式规则暂不承诺即时逆转，仍按后续资源加载状态处理；
- 同一服装/发型目标只允许一个启用 Mod；运行中拒绝冲突开启，启动时若同组多项开启则自动持久化关闭整组；
- 在原始
SkinnedMeshRenderer上替换克隆后的 Mesh； - 按骨骼名重排 skinning 数据，失败时保留原始 Mesh；
- 按 renderer、材质槽和 shader property 替换贴图；
- 为贴图覆盖创建私有材质；保留
set_sharedMaterials/set_materials诊断与恢复路径， 同时保留当前MaterialPropertyBlock参数； - 写入
gakumas-mod/mod-plugin.log； - 输出 source profile，并提供离线 Validator 与 Author Doctor。
manifest 格式见 docs/manifest-v2.md，当前限制和后续任务见 docs/roadmap.md。
当前验证状态
2026-08-01 实机已经确认：
- 管理器通过
GmrGetRuntimeApiV1读取快照和切换 Mod； - Manifest 写回和当前会话有效 replacement map 同步更新；
- 标准服装替换可以热关闭、再热开启；
- 热重应用日志记录目标、应用数和活动 Animation Rig 刷新。
当前已恢复到 IDA MCP 调查前的已验证基线：标准服装 OFF/ON 热切换不崩溃，但热 ON 后 直接返回主页仍可能颜色错误；切换一次游戏页面后恢复正常。
已证伪：「Renderer 已有的每材质
MaterialPropertyBlock旧贴图覆盖克隆材质」这一 结论是错的。实机探针确认游戏在这些场景从不调用Renderer.SetPropertyBlock， 基于该结论的几轮修复改的是一条从未执行的路径。
2026-08-02 探针确认的真实写入者是：游戏在热重应用之后调用材质数组写回，换掉带 Mod
贴图的私有材质。IDA 后加入的底层 SetMaterialArray_Injected 实验钩子及其后续受限扫描
连续造成加载卡住或点击崩溃，现已从源码和部署版移除。完整的排除过程、证据和下一步见
管理器仓库的
docs/OPEN_DEFECTS.md。
当前游戏目录部署版（2026-08-02）：
xinput1_3.dll
大小：571904 字节
SHA-256：03C941E56788F066FEC5FABEE0A391D722E5D98F5B05E80183462FA2D40D43C6
手抄的哈希每次重编译就过期一次（这两行此前落后了一个构建）。核对用：
Get-FileHash <游戏目录>\xinput1_3.dll -Algorithm SHA256
构建
要求 Visual Studio 2022 与 C++ 桌面开发组件。
generate.bat
msbuild build\gakumas_mod_runtime.sln /p:Configuration=Release /p:Platform=x64
产物：
build/bin/x64/Release/xinput1_3.dll
generate.bat 使用仓库内固定的 Premake 5.0.0-beta1。第三方组件和许可证见
third-party-notices.md。
安装
把 xinput1_3.dll 放入游戏目录。每个 Mod 放在：
gakumas-mod/mods/<mod-id>/
mod.json
your-mod.bundle
gakumas-mod/config.json
两个键，都可省略：
{
"modManagerUi": true,
"logLevel": "error"
}
modManagerUi：游戏内 Mod 管理界面开关，默认开。只有明确写false才关闭 （Mod 替换照常工作）；文件不存在、JSON 写错或键名打错都按开启处理。logLevel："info"/"warn"/"error"，默认"error"。默认只记录错误， 排查问题时改成"info"拿完整 trace。mod-plugin.log和mod-manager.log共用这一个等级。
无论等级如何，启动都会写一行 [BOOT] 记录当前生效的等级——所以日志文件永远存在，
"没有日志"只可能意味着插件没被加载。
作者诊断
python tools\gakumas_mod_validator.py <mod-dir> --profile <source-profile.json>
python tools\gakumas_mod_doctor.py <mod-dir> --profile <source-profile.json>
默认报告会写入 <mod-dir>\reports。工具只检查 manifest、文件、renderer、材质槽和贴图声明，
目前不离线解析 AssetBundle 内部对象。
验证
python -m unittest discover -s tests -v
当前 Release 构建已通过，Python unittest discover 的 4 项测试通过。完整验收还应核对
xinput1_3.def 的 8 个导出，并在目标游戏复验热 ON/OFF/ON 后无需切换页面即可得到正确
Mesh、材质、骨骼和颜色。旧的 3DMigoto 暗色调查与本次热开关 MPB 提交缺陷是两个独立问题，
见 AB_DARK_RENDERING_INVESTIGATION.md。