G28 模型接入问题总结与新模型检查清单
更新时间：2026-10-14
本次目标
把 Sketchfab 作者trolosqlfod的 HK G28 模型接入 Source SDK 2013 Multiplayer 的mod_hl2mp，让第一人称视图中：
- 枪位于屏幕右下方；
- 枪口朝准星方向；
- 使用原始模型的颜色和贴图；
$scale保持1；- 不添加手臂、不改变玩法。
原始资产授权：SketchfabHK G28 Sniper Rifle，作者trolosqlfod，许可证CC-BY-4.0。
最终文件和路径
源文件：
F:\game_素材\hkg28-convert\source_qc_smd\v_hkg28.qcF:\game_素材\hkg28-convert\source_qc_smd\v_hkg28_ref.smdF:\game_素材\hkg28-convert\source_qc_smd\w_hkg28_ref.smd
最终视图模型 QC 关键参数：
$scale 1.0 $origin -14 8 8 -90编译目录：
H:\cfgame\Steam\steamapps\common\Source SDK Base 2013 Multiplayer\hl2mp运行时目录：
H:\cfgame_test\origin-of-fps\source-sdk-2013\game\mod_hl2mp最终视图模型文件已复制到：
H:\cfgame_test\origin-of-fps\source-sdk-2013\game\mod_hl2mp\models\weapons\包括：v_hkg28.mdl、v_hkg28.vvd、v_hkg28.dx90.vtx、v_hkg28.dx80.vtx、v_hkg28.sw.vtx。
遇到的问题和根因
1. 模型消失或顶在头上
最初的$origin -6 5 12不适合这个模型的坐标系。模型本身的几何包围盒大约为：
X = -12 .. 28 Y = -4.68 .. 4.68 Z = -6.88 .. 6.88模型长轴实际在 SMD 的X方向，经过视图模型坐标转换后，枪口方向需要通过 QC 的旋转参数对齐 Source 第一人称坐标。最终使用：
$origin -14 8 8 -90其中：
-14：把枪沿枪口方向向前移，避免枪身过于靠后；8：保持合适的横向和高度偏移；-90：把模型长轴旋转到准星前方。
2. 枪的颜色像掉漆，瞄准镜出现错误颜色
这不是原始 BaseColor 损坏，主要是两个转换问题叠加：
UV 的 V 坐标方向错误。原始 glTF 贴图和 Source SMD 的 V 轴方向相反，导致模型采样到图集的上下错误位置。修复方法是对视图和世界 SMD 的每个顶点执行：
v = 1 - v材质名中的点号被 StudioMDL 处理成扩展名分隔符。原始材质名为
mat0.001到mat0.006，编译后的模型最终只剩一个mat0材质，导致枪身、瞄准镜、脚架和镜片错误地共用枪身材质。已改为没有点号的唯一材质名：
hkg28_body hkg28_magazine hkg28_receiver hkg28_scope hkg28_bipod hkg28_lens_front hkg28_lens_rear重新编译后，
v_hkg28.mdl和w_hkg28.mdl都确认包含 7 个材质。镜片 Alpha 透明度需要保留。原始镜片 PNG 是 RGBA，前后镜片 Alpha 分别为 92 和 84。已使用 RGBA 源图重新生成镜片 VTF，并确认 VTF 使用带 Alpha 的格式。
3. 编译目录错误
studiomdl.exe -game不能指向这个模组的gameinfo.txt。正确做法是对 SDK 自带的 HL2MP 目录编译：
studiomdl.exe-game"H:\cfgame\Steam\steamapps\common\Source SDK Base 2013 Multiplayer\hl2mp"v_hkg28.qc然后把生成的模型文件复制到mod_hl2mp\models\weapons。
新模型接入时必须检查
几何和坐标
- 先确认原始模型的长轴、枪口方向和上下方向。
- 先测量 SMD 顶点包围盒，再决定
$origin，不要凭感觉连续试错。 - 视图模型和世界模型分别确认坐标；不能直接假设两者使用同一套偏移。
$scale只有在确认尺寸错误时才修改；本项目要求保持1。- 第一人称验收标准是枪身在右下方、枪口指向准星，不以第三人称世界模型画面代替。
UV 和贴图
- glTF、OBJ、FBX 转 SMD 时，明确检查 V 轴是否需要翻转。
- 编译前后抽取少量 UV 或比较 VTF 解码图，确认贴图没有上下错位。
- 原始 BaseColor 应尽量原样转换，不要把 BaseColor 当成法线或粗糙度图。
- 法线图要使用
$bumpmap，并在 VTF 中设置 Normal 标志。 - 透明镜片必须保留 RGBA Alpha；不要用 RGB-only 转换覆盖它。
- 重新生成 VTF 后检查尺寸、格式、Alpha 和是否被错误压成 DXT1。
材质命名
- 不要使用
mat0.001、material.002这类带点号的材质名。 - 使用字母、数字和下划线，例如
g28_scope、g28_lens_front。 - 每个视觉部件必须拥有唯一材质名和对应 VMT。
- 编译后从 MDL 读取材质表，确认材质数量和名称与 SMD 一致。
- VMT 中的
$basetexture、$bumpmap必须和实际 VTF 文件名逐字匹配。
VMT 参数
- 先用简单的
VertexLitGeneric + $basetexture验证贴图对应关系。 - 确认颜色正确后，再逐项加入
$bumpmap、$phong、$envmap和 rim light。 - 不要一开始同时启用很强的
$phongboost、$envmap、$rimlight，否则很难判断是贴图错还是光照过强。 - 如果画面出现紫色，优先检查 VMT/VTF 路径和文件是否缺失。
- 如果画面出现灰绿反光或像掉漆，检查环境贴图、法线 Alpha 遮罩和 Phong 强度。
编译和部署
- 修改
source_qc_smd中的 QC、SMD 和材质源。 - 对 SDK 的
hl2mp目录运行studiomdl.exe。 - 同时编译视图模型和世界模型。
- 把
.mdl、.vvd、.dx90.vtx、.dx80.vtx、.sw.vtx复制到运行时模型目录；世界模型另外复制.phy。 - 把 VMT/VTF 复制到运行时
materials目录。 - 重启游戏或换图，避免旧模型和旧材质仍在内存中。
- 进入
dm_lockdown，确认右下角模型、准星朝向、颜色、镜片透明度和开火/换弹动画。
推荐的验收顺序
1. 模型可见 2. 枪口朝向正确 3. 位置在右下方 4. BaseColor 对应正确 5. 瞄准镜和镜片材质独立 6. 镜片 Alpha 正常 7. 法线和高光正常 8. 开火、换弹、切枪动画正常 9. 世界模型和物理文件正常 10. 重启后仍能正常加载本次最终验收结果
- 第一人称模型已在
dm_lockdown中显示。 - 枪位于屏幕右下方，枪口朝向准星。
- UV 翻转问题已修复。
- 模型材质已从错误的单材质恢复为 7 个独立材质。
- 枪身颜色恢复为原始黑灰和沙色风格。
- 瞄准镜使用独立贴图，镜片保持蓝色透明效果。
- 未添加手臂，未改变玩法，
$scale仍为1.0。
