给人物、车辆、地图物件加上 头发 / 布料 / 身体软组织 的顶点物理。 物理数据可以来自模型顶点色,也可以来自外部
.dat文件(推荐,模型不会被染色)。
版本:ASI v1.0(本文档对应源码状态) / Blender 插件 v1.6.0
适用:GTA San Andreas 1.0 US(MSVC x86 编译,输出 .asi)
- 它能做什么 / 不能做什么
- 安装
- 快速开始(5 分钟)
- 顶点色编码
- ini 配置详解
- 三种数据来源
- dump 精确流程(顶点顺序 100% 对齐)
- Blender 插件教程
- 多部件模型(车辆)
- 支持的模型类型 × 物理类型
- 日志与排错
- 已知限制(引擎层面)
- 性能建议
| 类型 | R 值 | 表现 |
|---|---|---|
| Hair 头发 | 64 |
挂在头皮/帽子上,走路转身有滞后甩动,会受风 |
| Cloth 布料 | 128 |
披风、裙摆、旗帜:重力下垂 + 摆动 + 滞后 |
| Body 身体软组织 | 192 |
胸部/臀部等:跟随骨骼运动时的弹簧抖动,带边界渐隐 |
| SoftBody 软体 | 254 |
类似布料但更硬,适合软装饰 |
- ✅ 人物角色(ped):三类物理都能用
- ✅ 车辆(vehicle):三类物理都能用(每个部件独立 rig)
⚠️ 地图静态物件:只有风摆(头发/布料/软体都按风摆处理), 地图物件的192(Body)不工作(没有骨骼可驱动)
- ❌ 给模型加新骨骼(GTA SA 骨架固定 32 根,加骨骼会崩)
- ❌ 让顶点脱离蒙皮(人物原子必须带 skin,去掉就崩)
- ❌ UE/Blender 那种“一缕缕发丝飘动”(需要发丝结构或骨骼链)
- ❌ 运行时导入 FBX/OBJ(引擎只认 DFF)
详细原因见 12. 已知限制。
-
确认已安装 CLEO(提供
.asi加载)或任何 ASI Loader; -
把
Vertex Physics mod放到:<游戏目录>\modloader\例如
A:\Vanilla GTASA\modloader\Vertex Physics mod -
启动游戏 → 首次运行会在游戏目录生成配置与日志。
<游戏目录>\
├─ VertexPhysics.asi (或 modloader 下)
├─ vertexphysics.ini ← 配置文件
├─ vertexphysics\ ← 物理数据目录(自动创建)
│ ├─ wfyro.dat ← 单部件模型
│ ├─ admiral\ ← 多部件模型(车辆)
│ │ ├─ chassis.dat
│ │ └─ wheel.dat
│ └─ dump\ ← dumpGeometry=1 时导出的几何体
│ └─ wfyro_1094.txt
- Blender → 编辑 → 偏好设置 → 插件 → 安装…;
- 选择
blender vertexphysics addon.py; - 勾选启用 VertexPhysics Exporter;
- 3D 视图按
N→ 侧栏 VertexPhysics 标签页。
目标:让一个人物的披风有物理。
-
Blender 里给披风顶点刷色:
128, 200, 255(= Cloth / 软度 200 / 锚定全关) -
导出 DFF,放进游戏(modloader);
-
打开
vertexphysics.ini:datonly=0 ; 先用顶点色测试 wfyro ; 追加模型名(与 gta3.img 内模型名一致)
-
启动游戏 → 看
vertexphysics.log:[Config] resolved wfyro -> modelId=92 [Entity] rig created modelId=92 ... cloth=221 ... -
进游戏看披风是否摆动。
想避免顶点色被“染”到模型上?用第 6 节的
.dat方案。
三个通道各自含义:
| 通道 | 含义 | 取值 |
|---|---|---|
| R | 物理类型 | 0/64/128/192/254 |
| G | 软度(越大越软) | 0~255 |
| B | 锚定强度(越大越自由) | 0~255 |
| G | 刚度 | 回位强度 | 手感 |
|---|---|---|---|
| 0 | 1.00 | 0.50 | 很硬 |
| 64 | 0.77 | 0.38 | 偏硬 |
| 128 | 0.55 | 0.26 | 中等 |
| 192 | 0.32 | 0.14 | 软 |
| 255 | 0.10 | 0.02 | 很软 |
| B | 效果 |
|---|---|
0 |
硬锚定:完全固定在骨骼上(适合发根、裙腰) |
30~80 |
强锚定:跟着身体,摆动小 |
150 |
中等 |
255 |
完全不锚定:只靠挂点/约束/重力/风 |
| 部位 | 颜色 | 说明 |
|---|---|---|
| 披风/裙摆上沿 | 128,120,60 |
固定在腰部 |
| 披风/裙摆中段 | 128,180,150 |
过渡 |
| 披风/裙摆下摆 | 128,200,255 |
自由摆动 |
| 头发根部 | 64,120,40 |
固定在头皮 |
| 头发中段 | 64,160,150 |
过渡 |
| 发梢 | 64,200,255 |
自由甩动 |
| 胸部软组织 | 192,40,40 |
轻微抖动(G 小=幅度小) |
| 臀部软组织 | 192,90,60 |
明显一些 |
纯白
255,255,255和纯灰(三通道相等)不参与物理, 所以“不刷色”或“刷白”的顶点就是完全跟随骨骼。
文件:<游戏目录>\vertexphysics.ini(修改后需重启游戏)
datonly=0
worldRadius=2.5
interactRadius=60
maxInstances=24
wind=1.0
mapphysics=1
mapconvert=2
dumpGeometry=0| 键 | 默认 | 范围 | 说明 |
|---|---|---|---|
datonly |
1 | 0/1 | 1=只读 .dat;0=读模型顶点色 |
worldRadius |
2.5 | 0.5~20 | 跨模型碰撞收集半径(米)。披风很长时调到 6~10 |
interactRadius |
8 | 1~50 | 地图物件物理扫描半径(米) |
maxInstances |
8 | 0~64 | 地图物件物理实例上限,0=关闭 |
wind |
1.0 | 0~5 | 全局风力倍率(乘到天气强度上) |
mapphysics |
0 | 0/1 | 地图物件物理开关 |
mapconvert |
0 | 0/1/2 | 0=关 / 1=换入换回 / 2=常驻换入(推荐) |
dumpGeometry |
0 | 0/1 | 1=把白名单模型几何体导出成 dump |
# 每行一个模型名(小写,与 gta3.img 里一致)
wfyro
admiral
test
没在白名单里的模型完全不处理(日志会提示
[MarkerModel])。
wind<天气ID>=角度,强度,湍流频率
winddefault=0,0.6,0.15
| 字段 | 含义 |
|---|---|
| 角度 | 0~360°,0=+X(东),90=+Y(北) |
| 强度 | 0 无风 / 1 微风 / 3 大风 / 6 强风 |
| 湍流 | 0 平稳 / 0.3 缓慢 / 1.5 快速(Hz) |
常用天气 ID:
| ID | 天气 | ID | 天气 |
|---|---|---|---|
| 0~3 | 洛杉矶晴 | 12 | LV 多云 |
| 4 | LA 多云 | 15 | 郊外多云 |
| 8 | SF 雨 | 16 | 郊外雨 |
| 9 | SF 雾 | 19 | 沙漠沙尘暴 |
| 20 | 水下 |
- 优点:不用生成额外文件,改完刷色导出 DFF 就能测;
- 缺点:顶点色同时是模型预光照色,刷物理颜色会让模型整体变色;
- 用法:
datonly=0,白名单加模型名。
- 刷完顶点色;
- Blender 插件点 「导出 .dat」;
- 把
<模型名>.dat放到vertexphysics\; datonly=1。
mod 会临时把 dat 颜色写进克隆体做物理计算,用完立刻恢复原色,所以模型不会被染色。
vertexphysics\admiral\
chassis.dat
wheel.dat
...
mod 会按顶点数把每个 dat 匹配给车辆的每个 atomic,顶点数相同时用 # bbox: 判定。
什么时候需要:Blender 的顶点和游戏里的顶点顺序/数量对不上(常见于车辆、多材质模型)。
-
ini 打开 dump
datonly=1 dumpGeometry=1 wfyro
-
进游戏让模型出现一次(走到它旁边 / 刷出来),然后退出。
生成:
vertexphysics\dump\wfyro_1094.txt -
回到 Blender:刷好顶点色 → 点 「从游戏 dump 生成 dat(精确)」 → 选择那个
.txt。插件会用 KDTree 按坐标把颜色映射到 dump 的顶点顺序上,生成顶点数完全一致的
.dat。 -
把 dat 放到
vertexphysics\wfyro.dat(或wfyro_1094.dat,两种都认),重启游戏。
[Dat] loaded A:\Vanilla GTASA\vertexphysics\wfyro.dat vertices=1094
[Entity] rig created modelId=92 ... hair=... cloth=...
面板:3D 视图 N → VertexPhysics 标签页
右上角按钮:English / 中文 切换界面语言(提示气泡固定双语显示)
| 项 | 说明 |
|---|---|
| 模型名 | 与 IDE/CModelInfo 一致(例如 test),也用于 dat 文件名 |
| 输出目录 | dat 输出位置,默认 //vertexphysics(相对 blend 文件) |
| 坐标轴 | 位置坐标转换(索引匹配为主,位置仅校验) |
| 应用物体变换 | 导出时把 Object 变换烘进坐标 |
| 导出后清空顶点色 | 导出成功后把顶点色刷白(默认关,别开,否则再导出会得到空数据) |
| 输出到模型子目录 | 多部件模型用:输出到 <输出目录>/<模型名>/ |
| 目标物体名前缀 | 名字以此开头的物体当作“目标”(导入回来的 DFF) |
| 文件名去掉 .001 后缀 | 物体名末尾 .001 去掉再命名 |
| 按 part_01 编号命名 | 生成 part_01.dat、part_02.dat… |
| dump 文件夹 | 游戏导出的几何体 dump 目录 |
| 按钮 | 用途 |
|---|---|
| 导出 .dat | 当前物体 → 一个 dat |
| 导出全部选中物体 | 每个选中的网格各导出一个 dat |
| 清空顶点色 | 顶点色刷白 |
| 给选中顶点刷类型色 | 编辑模式下给选中顶点刷指定类型色 |
| 按 DFF 顶点顺序导出(推荐) | 选两个物体:源(带色)+ 重新导入的 DFF,按 DFF 顺序生成 dat |
| 批量按 DFF 顺序导出 | 多部件批量版本 |
| 给选中物体加此前缀 | 给选中网格加“目标前缀” |
| 从游戏 dump 生成 dat(精确) | 用 dump 文件生成顶点顺序完全一致的 dat |
| 从 dump 文件夹批量生成 | 一次处理整个 dump 文件夹 |
给选中顶点刷类型色:编辑模式选中顶点 → 选择类型(Hair/Cloth/Body/SoftBody)+ 软度 + 锚定 → 点按钮。
- 选中所有部件物体;
- 勾选 输出到模型子目录;
- 点 导出全部选中物体(或批量按 DFF 顺序导出);
- 得到
<输出目录>\admiral\*.dat; - 整个文件夹复制到
vertexphysics\admiral\。
没有物理颜色的部件不要放 dat,否则 mod 会为它创建 rig(克隆几何体、每帧碰撞收集), 车辆部件一多就会明显掉帧。
新版本已经会自动跳过“dat 全白”的部件,但最省事的做法仍是只给需要的部件导出。
[Entity] skip modelId=445 verts=105 (dat has no physics colors)
[Entity] rig created modelId=445 verts=1802 cloth=63 ...
只有一条 rig created 说明配置正确。
| 模型 | Hair(64) | Cloth(128) | Body(192) | SoftBody(254) |
|---|---|---|---|---|
| 人物 ped | ✅ | ✅ | ✅ | ✅ |
| 车辆 vehicle | ✅ | ✅ | ✅ | ✅ |
| 地图物件 | ❌ 无效 |
说明:
- 人物/车辆走 世界空间:有骨骼锚点、挂点约束、风力、Body 弹簧;
- 地图物件走 模型空间:没有骨骼,只有风 + 湍流 + 重力 + 形状记忆,
且
invMass=0的 Body 粒子在该分支会被跳过。
| 文件 | 内容 |
|---|---|
wfyro_hair.log |
配置、模型扫描、dat 加载、rig 创建、渲染钩子 |
geophys_debug.log |
颜色分类 [ColorHist]、步进 [Step]、身体分组 [BodyGroups] |
| 日志 | 含义 |
|---|---|
[Config] resolved wfyro -> modelId=92 |
白名单解析成功 |
[Dat] loaded ... vertices=1094 |
dat 已加载 |
[Dat] not found: ... |
dat 路径/文件名不对 |
| `[ColorHist] unique=3 | (128,200,255)=990` |
[Entity] rig created ... hair=/cloth=/body= |
rig 创建成功 |
[Entity] init FAILED ... |
初始化失败(通常是没物理颜色) |
[Entity] skip modelId=... (dat has no physics colors) |
该部件没有物理,已跳过 |
[VER_82][Step] ... hair(n,max=x m) |
每类粒子的最大偏移(判断摆幅) |
| 现象 | 原因 | 解决 |
|---|---|---|
| 完全没有物理 | 模型不在白名单 / 没有 dat / 顶点全白 | 看 [ColorHist] 与 [Dat] 日志 |
| 物理只在几个点上 | 只刷了几个顶点 | 重刷,确认 (128,200,255) 数量足够 |
| 模型整体变色 | 用顶点色方案 | 改用 .dat(datonly=1) |
| 布料/头发整体跟着转 | 锚定 B 太大 | 提高 B 到 255,让锚定关闭 |
| 披风/头发被拉长 | 约束链太长 | 优先用 B=255 + 挂点;必要时降低软度 |
| 车辆一出现就卡 | 每个部件都建了 rig | 只给需要的部件导 dat(新版本会自动跳过全白 dat) |
| 地图物件不动 | mapphysics=0 / 不在扫描半径 |
打开 mapphysics=1,调大 interactRadius |
| 头发/布料穿过身体 | 碰撞半径太小 | 调大 worldRadius |
GTA SA 的 RenderWare 3.7 是 2004 年为 PS2 内存预算设计的预编译架构:
| 限制 | 原因 |
|---|---|
| 不能加新骨骼 | 人物骨架在 clump 创建时按固定 32 根分配,动画(IFP)按索引存关键帧 |
| 不能去掉蒙皮 | 人物渲染分支假定原子带 RpSkin,去掉直接崩 |
| 不能运行时导入 FBX/OBJ | 只有 DFF/TXD/IFP/COL 解析器 |
| 改蒙皮权重会撕裂 | RpSkin 在创建时预编译骨骼索引重映射,改数据不改缓存会不一致 |
| 头发无法做到发丝级飘动 | 顶点物理 + 蒙皮回写的组合限制 |
要做“真正的飘逸头发”,需要配套的骨骼扩展器(独立的引擎级 mod), 这不是本文档这个 ASI 的范畴。
| 建议 | 原因 |
|---|---|
| 车辆只给需要的部件导出 dat | 每个部件一个 rig,开销成倍增加 |
地图物件 maxInstances 控制在 16~32 |
每个实例一份克隆几何体 |
interactRadius 不要设太大 |
扫描范围内所有建筑都会建实例 |
| 布料粒子数控制在 1000 以内 | 每帧约束迭代 12 次 × 边数 |
| 披风很长时只给边缘做物理 | 中间顶点固定可省大量计算 |
不要用 datonly=0 + 大面积刷色做最终版本 |
顶点色会染色,且物理颜色占用顶点数据 |
| 标识 | 意思 |
|---|---|
[VER_82] |
物理模块通用前缀 |
[Entity] |
实体(人物/车辆/道具)处理 |
[MapPhysics] / [MapInst] |
地图物件物理 |
[RenderHook] |
逐实例渲染钩子统计 |
[Dat] |
外部 dat 加载 |
[ColorHist] |
顶点色分类统计 |
[WeightInherit] |
无权重顶点继承邻居权重 |
[Pinned] |
挂点统计 |
[BodyGroups] |
身体软组织分组 |
Add Hair / Cloth / Body Soft-Tissue vertex physics to peds, vehicles, and map objects. Physics data can be read from model vertex colors or external
.datfiles (recommended, as it prevents tinting the model).
Version: ASI v1.0 (matches current source code) / Blender Add-on v1.6.0
Compatibility: GTA San Andreas 1.0 US (MSVC x86 build, outputs .asi)
- What It Can / Cannot Do
- Installation
- Quick Start (5 Minutes)
- Vertex Color Encoding
- INI Configuration Details
- Three Data Sources
- Exact Dump Workflow (100% Vertex Order Alignment)
- Blender Add-on Tutorial
- Multi-Part Models (Vehicles)
- Supported Model Types × Physics Types
- Logs & Troubleshooting
- Known Limitations (Engine-Level)
- Performance Tips
| Type | R Value | Behavior |
|---|---|---|
| Hair | 64 |
Anchored to the scalp/hat; exhibits lag and sway when walking or turning, and reacts to wind |
| Cloth | 128 |
Capes, skirts, flags: gravity droop + swaying + inertia lag |
| Body | 192 |
Chest/glutes, etc.: spring jiggle driven by bone movement with boundary falloff |
| SoftBody | 254 |
Similar to Cloth but stiffer; suitable for soft accessories |
- ✅ Peds (Characters): Supports all physics types
- ✅ Vehicles: Supports all physics types (each component gets an independent rig)
⚠️ Static Map Objects: Wind sway only (Hair/Cloth/SoftBody are all processed as wind sway).192(Body) does not work on map objects (no skeleton bones to drive motion).
- ❌ Adding new bones to models (GTA SA skeletons are fixed at 32 bones; adding bones causes crashes)
- ❌ Detaching vertices from skinning (ped atomics require
RpSkin; removing it crashes the game) - ❌ Strand-by-strand hair simulation like UE/Blender (requires hair card/strand structures or bone chains)
- ❌ Importing FBX/OBJ at runtime (the engine only supports DFF)
See 12. Known Limitations (Engine-Level) for technical details.
-
Ensure CLEO (which loads
.asifiles) or any standard ASI Loader is installed. -
Place the
Vertex Physics modfolder into:<Game Directory>\modloader\For example:
A:\Vanilla GTASA\modloader\Vertex Physics mod -
Launch the game → configuration and log files will be automatically generated in the game directory on first run.
<Game Directory>\
├─ VertexPhysics.asi (or inside modloader)
├─ vertexphysics.ini ← Configuration file
├─ vertexphysics\ ← Physics data directory (auto-created)
│ ├─ wfyro.dat ← Single-part model
│ ├─ admiral\ ← Multi-part model (vehicle)
│ │ ├─ chassis.dat
│ │ └─ wheel.dat
│ └─ dump\ ← Exported geometry when dumpGeometry=1
│ └─ wfyro_1094.txt
- In Blender, go to Edit → Preferences → Add-ons → Install…
- Select
blender vertexphysics addon.py - Check the box to enable VertexPhysics Exporter
- Press
Nin the 3D Viewport → open the VertexPhysics tab in the sidebar.
Goal: Add physics to a character's cape.
-
In Blender, paint the cape vertices with color:
128, 200, 255(= Cloth / Softness 200 / Anchoring completely off) -
Export the DFF and place it into your game (
modloader). -
Open
vertexphysics.ini:datonly=0 ; Test with vertex colors first wfyro ; Append model name (must match the model name in gta3.img)
-
Launch the game → check
vertexphysics.log:[Config] resolved wfyro -> modelId=92 [Entity] rig created modelId=92 ... cloth=221 ... -
Check in-game to see if the cape sways.
Want to avoid tinting your model with vertex colors? Use the
.datworkflow in Section 6.
Meaning of the three RGB channels:
| Channel | Meaning | Value Range |
|---|---|---|
| R | Physics Type | 0 / 64 / 128 / 192 / 254 |
| G | Softness (higher = softer) | 0~255 |
| B | Anchor Strength (higher = freer movement) | 0~255 |
| G | Stiffness | Return Strength | Feel |
|---|---|---|---|
| 0 | 1.00 | 0.50 | Very stiff |
| 64 | 0.77 | 0.38 | Moderately stiff |
| 128 | 0.55 | 0.26 | Medium |
| 192 | 0.32 | 0.14 | Soft |
| 255 | 0.10 | 0.02 | Very soft |
| B | Effect |
|---|---|
0 |
Hard Anchor: Completely locked to the bone (ideal for hair roots, waistbands) |
30~80 |
Strong Anchor: Follows the body closely with minimal sway |
150 |
Medium |
255 |
Unanchored: Driven solely by pinned vertices, constraints, gravity, and wind |
| Region | Color (R, G, B) | Description |
|---|---|---|
| Upper cape / skirt waist | 128,120,60 |
Anchored near the waist |
| Mid cape / skirt | 128,180,150 |
Transition zone |
| Lower cape / hem | 128,200,255 |
Free flowing |
| Hair roots | 64,120,40 |
Anchored to the scalp |
| Mid hair | 64,160,150 |
Transition zone |
| Hair tips | 64,200,255 |
Free swinging |
| Chest soft tissue | 192,40,40 |
Subtle jiggle (lower G = smaller amplitude) |
| Glute soft tissue | 192,90,60 |
Slightly more pronounced jiggle |
Pure white
255,255,255and pure grayscale (where R = G = B) are excluded from physics, meaning unpainted or white-painted vertices will strictly follow standard bone skinning.
File: <Game Directory>\vertexphysics.ini (requires game restart after editing)
datonly=0
worldRadius=2.5
interactRadius=60
maxInstances=24
wind=1.0
mapphysics=1
mapconvert=2
dumpGeometry=0| Key | Default | Range | Description |
|---|---|---|---|
datonly |
1 | 0/1 | 1 = read .dat files only; 0 = read model vertex colors |
worldRadius |
2.5 | 0.5~20 | Cross-model collision collection radius (meters). Increase to 6~10 for long capes |
interactRadius |
8 | 1~50 | Map object physics scan radius (meters) |
maxInstances |
8 | 0~64 | Max active map object physics instances (0 = disabled) |
wind |
1.0 | 0~5 | Global wind multiplier (multiplied onto weather wind strength) |
mapphysics |
0 | 0/1 | Toggle physics for map objects |
mapconvert |
0 | 0/1/2 | 0 = off / 1 = swap in & out / 2 = persistent swap-in (recommended) |
dumpGeometry |
0 | 0/1 | 1 = dump geometry of whitelisted models to text files |
# One model name per line (lowercase, matching gta3.img)
wfyro
admiral
test
Models not listed in the whitelist are completely ignored (logged as
[MarkerModel]).
wind<WeatherID>=Angle,Strength,TurbulenceFreq
winddefault=0,0.6,0.15
| Field | Meaning |
|---|---|
| Angle | 0~360°, 0 = +X (East), 90 = +Y (North) |
| Strength | 0 calm / 1 breeze / 3 strong wind / 6 gale |
| Turbulence | 0 steady / 0.3 slow / 1.5 rapid (Hz) |
Common Weather IDs:
| ID | Weather | ID | Weather |
|---|---|---|---|
| 0~3 | Los Santos Sunny | 12 | Las Venturas Cloudy |
| 4 | LS Cloudy | 15 | Countryside Cloudy |
| 8 | San Fierro Rain | 16 | Countryside Rain |
| 9 | SF Fog | 19 | Desert Sandstorm |
| 20 | Underwater |
- Pros: No extra files needed; paint, export DFF, and test immediately.
- Cons: Vertex colors also act as pre-lighting colors in GTA SA, so painting physics colors will tint the model in-game.
- Usage: Set
datonly=0and add the model name to the whitelist.
- Paint vertex colors in Blender.
- Click Export .dat in the Blender add-on.
- Place
<model_name>.datinsidevertexphysics\. - Set
datonly=1.
The mod temporarily writes the .dat colors into a cloned mesh for physics simulation and immediately restores original vertex colors afterward, leaving your model's appearance unaffected.
vertexphysics\admiral\
chassis.dat
wheel.dat
...
The mod matches each .dat file to the vehicle's atomics by vertex count, using # bbox: bounding box checks as a tie-breaker when vertex counts match.
When to use: When Blender's vertex order or count does not match the game's runtime mesh (common with vehicles and multi-material meshes).
-
Enable dump in
vertexphysics.ini:datonly=1 dumpGeometry=1 wfyro
-
Launch the game and spawn/encounter the model once, then exit the game.
This generates:
vertexphysics\dump\wfyro_1094.txt -
Back in Blender: Paint your vertex colors → click Generate dat from game dump (Exact) → select the generated
.txtfile.The add-on uses a KDTree to spatially map your vertex colors onto the exact vertex order of the dump, producing a
.datwith a 100% matching vertex count and order. -
Place the
.datfile atvertexphysics\wfyro.dat(orwfyro_1094.dat— both are recognized) and restart the game.
[Dat] loaded A:\Vanilla GTASA\vertexphysics\wfyro.dat vertices=1094
[Entity] rig created modelId=92 ... hair=... cloth=...
Panel location: 3D Viewport N → VertexPhysics tab
Top-right button: English / 中文 toggles UI language (tooltips are always bilingual).
| Property | Description |
|---|---|
| Model Name | Matches IDE/CModelInfo name (e.g., test); also used as the .dat filename |
| Output Directory | Destination folder for .dat files; defaults to //vertexphysics (relative to .blend file) |
| Coordinate Axes | Axis conversion for positions (matching relies primarily on vertex index; positions are used for validation) |
| Apply Object Transform | Bakes object transforms into vertex coordinates upon export |
| Clear Vertex Colors After Export | Resets vertex colors to white after exporting (off by default — keep off, or subsequent exports will be blank) |
| Export to Model Subdirectory | For multi-part models: outputs to <Output Directory>/<Model Name>/ |
| Target Object Prefix | Objects starting with this prefix are treated as "targets" (re-imported DFF meshes) |
| Strip .001 Suffix | Removes trailing .001 from object names when naming .dat files |
| Name as part_01, part_02… | Sequentially names exported files as part_01.dat, part_02.dat, etc. |
| Dump Folder | Directory containing geometry dumps exported by the game |
| Button | Function |
|---|---|
| Export .dat | Exports the active object to a single .dat file |
| Export All Selected Objects | Exports each selected mesh as its own .dat file |
| Clear Vertex Colors | Resets vertex colors to pure white |
| Paint Selected Vertices | Assigns the chosen physics type, softness, and anchor color to selected vertices in Edit Mode |
| Export by DFF Vertex Order (Recommended) | Select two objects: Source (painted) + Re-imported DFF; generates a .dat matching the DFF's vertex order |
| Batch Export by DFF Order | Multi-part batch version of the DFF order exporter |
| Add Prefix to Selected | Prepends the "Target Object Prefix" to selected meshes |
| Generate dat from Game Dump (Exact) | Uses a game dump file to generate a .dat with identical vertex ordering |
| Batch Generate from Dump Folder | Processes an entire folder of dump files at once |
Paint Selected Vertices: Enter Edit Mode → select vertices → choose Type (Hair / Cloth / Body / SoftBody) + Softness + Anchoring → click the button.
- Select all vehicle component objects.
- Enable Export to Model Subdirectory.
- Click Export All Selected Objects (or Batch Export by DFF Order).
- You will get
<Output Directory>\admiral\*.dat. - Copy the entire folder to
vertexphysics\admiral\.
Do not include .dat files for parts with no physics colors. Otherwise, the mod will still create a physics rig for them (cloning geometry and running per-frame collision checks), which can noticeably drop FPS on complex vehicles.
Newer versions automatically skip
.datfiles that are all-white, but exporting only the necessary parts remains best practice.
[Entity] skip modelId=445 verts=105 (dat has no physics colors)
[Entity] rig created modelId=445 verts=1802 cloth=63 ...
Seeing rig created only for the intended part confirms your setup is optimal.
| Model Type | Hair (64) | Cloth (128) | Body (192) | SoftBody (254) |
|---|---|---|---|---|
| Ped (Character) | ✅ | ✅ | ✅ | ✅ |
| Vehicle | ✅ | ✅ | ✅ | ✅ |
| Map Object | ❌ Inactive |
Notes:
- Peds & Vehicles simulate in World Space: supports bone anchoring, pinned vertices, wind forces, and Body spring dynamics.
- Map Objects simulate in Model Space: no bones are present, so simulation uses wind + turbulence + gravity + shape memory; Body particles (
invMass=0) are skipped in this branch.
| File | Contents |
|---|---|
wfyro_hair.log |
Configuration loading, model scanning, .dat loading, rig creation, render hooks |
geophys_debug.log |
Color classification ([ColorHist]), simulation steps ([Step]), body soft-tissue grouping ([BodyGroups]) |
| Log Entry | Meaning |
|---|---|
[Config] resolved wfyro -> modelId=92 |
Whitelist model name resolved successfully |
[Dat] loaded ... vertices=1094 |
.dat file loaded |
[Dat] not found: ... |
Incorrect .dat path or filename |
| `[ColorHist] unique=3 | (128,200,255)=990` |
[Entity] rig created ... hair=/cloth=/body= |
Physics rig initialized successfully |
[Entity] init FAILED ... |
Initialization failed (usually due to zero physics-colored vertices) |
[Entity] skip modelId=... (dat has no physics colors) |
Part skipped because it has no physics colors |
[VER_82][Step] ... hair(n,max=x m) |
Max particle displacement per category (useful for judging sway amplitude) |
| Symptom | Cause | Solution |
|---|---|---|
| No physics at all | Model not in whitelist / missing .dat / vertices are all white |
Check [ColorHist] and [Dat] entries in the log |
| Physics only affects a few points | Only a few vertices were painted | Repaint and verify sufficient (128,200,255) vertex counts |
| Entire model changes color | Using vertex color mode (datonly=0) |
Switch to .dat files (datonly=1) |
| Cloth/hair rotates rigidly with body | Anchor B value is too low |
Increase B up to 255 to disable bone anchoring |
| Cape/hair stretches excessively | Constraint chain is too long | Use B=255 + pinned root vertices; reduce Softness (G) if needed |
| Game stutters when vehicle spawns | Every vehicle component created a rig | Only export .dat files for parts that actually need physics |
| Map objects don't move | mapphysics=0 or object is out of scan range |
Set mapphysics=1 and increase interactRadius |
| Hair/cloth clips through body | Collision radius is too small | Increase worldRadius in vertexphysics.ini |
GTA SA runs on RenderWare 3.7, a pre-compiled engine architecture designed in 2004 for PS2 memory budgets:
| Limitation | Reason |
|---|---|
| Cannot add new bones | Ped skeletons are allocated at a fixed 32 bones during clump creation; IFP animations store keyframes by fixed bone index |
| Cannot remove skinning | The ped rendering pipeline assumes RpSkin is present on atomics; removing it causes an immediate crash |
| Cannot import FBX/OBJ at runtime | The engine only includes parsers for DFF, TXD, IFP, and COL |
| Modifying skin weights causes tearing | RpSkin pre-compiles bone index remapping tables at creation; altering weights without rebuilding caches causes desync |
| Cannot achieve strand-level hair flow | Inherent limitation of vertex-level simulation written back onto rigid bone skinning |
Achieving true multi-strand flowing hair requires a dedicated bone extender (a separate engine-level mod), which is outside the scope of this ASI plugin.
| Tip | Reason |
|---|---|
Only export .dat files for vehicle parts that need physics |
Each .dat creates an independent rig, multiplying CPU/memory overhead |
Keep map object maxInstances between 16~32 |
Every active map instance allocates a cloned geometry buffer |
Avoid setting interactRadius too high |
Every building/prop within range will instantiate a physics rig |
Keep cloth particle counts under 1,000 |
Constraints iterate 12 times per edge every single frame |
| For very long capes, apply physics only to the outer edges | Keeping inner vertices anchored saves substantial computation |
Do not ship final mods using datonly=0 with large painted areas |
Tints model pre-lighting and consumes vertex color data |
| Prefix | Meaning |
|---|---|
[VER_82] |
General physics module prefix |
[Entity] |
Entity processing (peds / vehicles / props) |
[MapPhysics] / [MapInst] |
Static map object physics |
[RenderHook] |
Per-instance render hook statistics |
[Dat] |
External .dat file loading |
[ColorHist] |
Vertex color classification histogram |
[WeightInherit] |
Unweighted vertices inheriting neighbor bone weights |
[Pinned] |
Pinned anchor vertex statistics |
[BodyGroups] |
Body soft-tissue island grouping |