神力科莎开发文档

简体中文

English

简体中文

English

主题

05. 动画类 ​

① 文件结构 ​

动画文件路径

content

└─ cars

└─ car_name

  ├─ extension

  │  ├─ ext_config.ini

  └─ animations

     ├─ animation_reverse.ksanim

② 普通 KSAnim 动画 ​

最简样板 ​

ini
[ANIMATION_...] ; 倒车触发动画
INPUT = REVERSE ; 绑定倒车状态
FILE = animation_reverse.ksanim ; 动画文件名

标准样板 ​

ini
[ANIMATION_...] ; 通用车辆动画
BIND_TO_EXTRA_A = 1              ; 绑定 Extra A 开关
FILE = car_door.ksanim         ; 动画文件
TIME = 1.0                       ; 动画时长
INPUT_AS_PROGRESS = 0            ; 开关触发模式
LOOP_WHILE_ACTIVE = 0            ; 不循环播放
LOOP_KEEP_UNTIL_DONE = 0         ; 关闭时允许反向播放
TICK_TOCK_MODE = 1               ; 开启/关闭正反播放

③ 触发型动画 ​

ini
[ANIMATION_...] ; 弹出屏幕动画
INPUT = EXTRA_A ; Extra A 开启时触发
FILE = animation_popup_screen.ksanim ; 屏幕弹出动画
TIME = 0.6 ; 动画时长
INPUT_AS_PROGRESS = 0 ; 使用触发模式
HOLD_STATE = 1 ; 保持开启状态

适用：

弹出屏幕

升降尾翼

开关按钮

隐藏灯罩

车门装饰件

④ 输入进度型动画 ​

ini
[ANIMATION_...] ; 油门踏板动画
INPUT = GAS ; 绑定油门踏板
FILE = animation_gas_pedal.ksanim ; 油门踏板动画
TIME = 1 ; 动画参考时间
INPUT_AS_PROGRESS = 1 ; 输入直接作为动画进度
INPUT_LAG_UP = 0.85 ; 踏板下压平滑
INPUT_LAG_DOWN = 0.9 ; 踏板回弹平滑

适用：

油门踏板

刹车踏板

离合踏板

机械连杆

液压杆

进度条式机械件

⑤ 循环动画 ​

ini
[ANIMATION_...] ; 风扇循环动画
INPUT = EXTRA_B ; Extra B 开启时播放
FILE = animation_fan_loop.ksanim ; 风扇动画
TIME = 1.0 ; 单次循环时间
LOOP_WHILE_ACTIVE = 1 ; 开启时循环播放
LOOP_KEEP_UNTIL_DONE = 0 ; 关闭后直接停止
TICK_TOCK_MODE = 0 ; 正常循环

适用：

风扇旋转
警示灯旋转机构
车内小风扇
可循环机械件

往返循环动画 ​

ini
[ANIMATION_...] ; 往返摆动动画
INPUT = EXTRA_C ; Extra C 开启时播放
FILE = animation_warning_flap.ksanim ; 摆动动画
TIME = 0.8 ; 单次动画时间
LOOP_WHILE_ACTIVE = 1 ; 开启时循环
LOOP_KEEP_UNTIL_DONE = 1 ; 关闭后回到起点
TICK_TOCK_MODE = 1 ; 使用往返模式

适用：

摆动机构
机械翻板
往复开关
装饰件摆动

⑥ Extra 按键动画 ​

Extra 开关设置 ​

🐜

Cars – Extra switches 页面说明车辆可定义 Extra A、Extra B 等额外开关，这些开关能作为动画、仪表、发光对象和 Lua 脚本输入使用；0.1.76 起还可以给开关设置角色和 flags。

Extra 开关命名 ​

( EXTRA按住的时候显示提示文本 ）

ini
[EXTRA_SWITCHES] ; Extra 开关设置
SWITCH_A = Popup Screen ; Extra A 显示名称
SWITCH_A_FLAGS = HOLD_MODE ; 按住才生效
SWITCH_B = Cooling Fan ; Extra B 显示名称
SWITCH_B_FLAGS = KEEP_ON_RESET ; 重置后保持状态

Extra 动画样板 ​

ini
[ANIMATION_...] ; Extra A 控制动画
INPUT = EXTRA_A ; 绑定 Extra A
FILE = animation_extra_a.ksanim ; 动画文件
TIME = 0.5 ; 动画时间
HOLD_STATE = 1 ; 保持状态

长按控制动画 ​

作用

按住指定 Extra 按键时播放或循环动画，松开后停止。

适合需要“按住才动作”的可动部件。

ini
[ANIMATION_...] ; Extra 长按控制动画
INPUT = EXTRA_A ; 绑定 Extra A 按键
FILE = animation_extra_hold.ksanim ; 动画文件
TIME = 6.3 ; 单次动画播放时间
INPUT_AS_PROGRESS = 0 ; 按键作为开关触发
LOOP_WHILE_ACTIVE = 1 ; 按住时循环播放
LOOP_KEEP_UNTIL_DONE = 0 ; 松开后不强制播完
TICK_TOCK_MODE = 0 ; 不使用往返循环
ini
[EXTRA_SWITCHES] ; Extra 开关设置
SWITCH_A = Extra Hold Animation ; Extra A 显示名称
SWITCH_A_FLAGS = HOLD_MODE ; Extra A 按住才生效

按住时往返播放 ​

ini
[ANIMATION_...] ; Extra 长按往返动画
INPUT = EXTRA_A ; 绑定 Extra A 按键
FILE = animation_extra_hold.ksanim ; 动画文件
TIME = 6.3 ; 单次动画播放时间
INPUT_AS_PROGRESS = 0 ; 按键作为开关触发
LOOP_WHILE_ACTIVE = 1 ; 按住时循环播放
LOOP_KEEP_UNTIL_DONE = 0 ; 松开后不强制播完
TICK_TOCK_MODE = 1 ; 启用往返播放

按住播放，松开等播完

ini
[ANIMATION_EXTRA_HOLD_FINISH] ; Extra 长按完成动画
INPUT = EXTRA_A ; 绑定 Extra A 按键
FILE = animation_extra_hold.ksanim ; 动画文件
TIME = 6.3 ; 单次动画播放时间
INPUT_AS_PROGRESS = 0 ; 按键作为开关触发
LOOP_WHILE_ACTIVE = 1 ; 按住时循环播放
LOOP_KEEP_UNTIL_DONE = 1 ; 松开后等待当前动画播完
TICK_TOCK_MODE = 0 ; 不使用往返循环

常用开关限制 ​

HOLD_MODE ; 按住才生效

STATIONARY_ONLY ; 车辆静止时才能切换

NEURAL_GEAR_ONLY ; 空挡时才能切换

REQUIRES_BRAKE ; 踩刹车时才能切换

KEEP_ON_RESET ; 车辆重置后保持状态

⑦ 档位动画 ​

R 档动画 ​

ini
[ANIMATION_...] ; R 档动画
INPUT = GEAR_R ; 挂 R 档触发
FILE = animation_reverse_gear.ksanim ; N 档动画文件
TIME = 0.5 ; 动画时间
HOLD_STATE = 1 ; 保持状态

N 档动画 ​

ini
[ANIMATION_...] ; N 档动画
INPUT = GEAR_N ; 挂 N 档触发
FILE = animation_drive_gear.ksanim ; D 档动画文件
TIME = 0.5 ; 动画时间
HOLD_STATE = 1 ; 保持状态

D 档动画 ​

ini
[ANIMATION_...] ; D 档动画
INPUT = GEAR_D ; 挂 D 档触发
FILE = animation_drive_gear.ksanim ; D 档动画文件
TIME = 0.5 ; 动画时间
HOLD_STATE = 1 ; 保持状态

可用档位输入 ​

GEAR_R
GEAR_N
GEAR_D
GEAR_1
~
GEAR_9

⑧ 车灯状态动画 ​

联动车灯动画 ​

ini
[ANIMATION_...] ; 车灯机构动画
INPUT = LIGHT ; 绑定车灯开启状态
FILE = animation_headlight_mechanism.ksanim ; 车灯机构动画
TIME = 0.6 ; 动画时间
HOLD_STATE = 0 ; 保持状态

常用灯光输入 ​

LIGHT / HEADLIGHTS ; 车灯

LOWBEAM ; 近光

HIGHBEAM ; 远光

DRL ; 日行灯

BRAKE / BRAKE_LIGHTS ; 刹车

REVERSE / REVERSE_LIGHTS ; 倒车

TURNSIGNAL_LEFT ; 左转向

TURNSIGNAL_RIGHT ; 右转向

HAZARD ; 双闪

⑨ 踏板和手刹动画 ​

踏板 ​

油门踏板 ​

ini
[ANIMATION_...] ; 油门踏板动画
INPUT = GAS ; 绑定油门
FILE = animation_gas_pedal.ksanim ; 油门踏板动画
INPUT_AS_PROGRESS = 1 ; 油门值控制动画进度
INPUT_LAG_UP = 0.85 ; 下压平滑
INPUT_LAG_DOWN = 0.9 ; 回弹平滑

刹车踏板 ​

ini
[ANIMATION_...] ; 刹车踏板动画
INPUT = BRAKE ; 绑定刹车
FILE = animation_brake_pedal.ksanim ; 刹车踏板动画
INPUT_AS_PROGRESS = 1 ; 刹车值控制动画进度
INPUT_LAG_UP = 0.85 ; 下压平滑
INPUT_LAG_DOWN = 0.9 ; 回弹平滑

离合踏板 ​

ini
[ANIMATION_...] ; 离合踏板动画
INPUT = CLUTCH ; 绑定离合
FILE = animation_clutch_pedal.ksanim ; 离合踏板动画
INPUT_AS_PROGRESS = 1 ; 离合值控制动画进度
INPUT_LAG_UP = 0.85 ; 下压平滑
INPUT_LAG_DOWN = 0.9 ; 回弹平滑

手刹 ​

汽车手刹动画 ​

作用

手刹拉起或放下时，车辆手刹模型播放动画。

ini
[ANIMATION_...] ; 汽车手刹动画
INPUT = HANDBRAKE ; 绑定手刹状态
FILE = handbrake.ksanim ; 汽车手刹动画文件
TIME = 1.0 ; 动画播放时间
INPUT_AS_PROGRESS = 0 ; 手刹作为开关触发
LOOP_WHILE_ACTIVE = 0 ; 激活时不循环
LOOP_KEEP_UNTIL_DONE = 0 ; 不强制播放到完成
TICK_TOCK_MODE = 0 ; 不使用往返循环

驾驶员手刹动画 ​

作用

手刹状态触发时，驾驶员播放拉手刹动作。

ini
[ANIMATION_...] ; 驾驶员手刹动画
INPUT = HANDBRAKE ; 绑定手刹状态
FILE = driver_handbrake.ksanim ; 驾驶员手刹动作动画文件
TIME = 1.0 ; 动画播放时间
INPUT_AS_PROGRESS = 0 ; 手刹作为开关触发
LOOP_WHILE_ACTIVE = 0 ; 激活时不循环
LOOP_KEEP_UNTIL_DONE = 0 ; 不强制播放到完成
TICK_TOCK_MODE = 0 ; 不使用往返循环

⑩‌ 雨刷高速抖动 ​

🌧️

参考官方 Cars – Wobbly wipers 页面：
这个功能不是普通雨刷动画，而是在已有雨刷动画基础增加高速风压抖动，让雨刷在高速时有轻微震动。

基础代码

ini
[ANIMATION_...] ; 雨刷动画
INPUT = WIPERS_PROGRESS ; 绑定雨刷进度
FILE = wipers.ksanim ; 雨刷动画文件
INPUT_AS_PROGRESS = 1 ; 雨刷进度控制动画

样板代码

ini
[WIPERS] ; 雨刷高速抖动
WIND_THRESHOLDS_KMH = 60, 150 ; 开始抖动速度 / 最大抖动速度
WIND_AMPLITUDE_MULT = 1 ; 抖动幅度倍率
WIND_FREQUENCY_MULT = 1 ; 抖动频率倍率
WIND_OFFSET = 0.03 ; 抖动基础偏移

⑪ 晃动物件 ​

🌧️

参考官方 Cars – Wobbly bits 页面：
让指定节点根据 G 力和重力产生晃动，适合后视镜吊饰、软挂件、天线、轻微震动的前翼等物体。

普通晃动样板 ​

ini
[WOBBLY_BIT_0] ; 晃动物件
NAME = node_hanging_accessory ; 需要晃动的节点
CONNECTED_TO = 0, 0.8, 0.2 ; 连接点坐标
MAX_RANGE = 0.05 ; 最大移动范围
DAMPENING_LAG = 0.93 ; 阻尼平滑
G_GAIN = 2 ; G 力影响强度
GRAVITY_GAIN = 3 ; 重力影响强度
OFFSET_GAIN = 2000 ; 回弹强度
STIFF_AXIS = 0, 0, 1 ; 限制晃动轴
STIFF_AXIS_STIFFNESS = 0.7 ; 限制轴刚性
G_FILTER = 0 ; G 力过滤
DEFAULT_GRAVITY_INCLUDED_ALREADY = 1 ; 默认姿态不额外下垂

软挂件样板 ​

ini
[WOBBLY_BIT_1] ; 软挂件晃动
NAME = node_soft_hanging_part ; 软挂件节点
CONNECTED_TO = 0, 0.8, 0.2 ; 连接点坐标
MAX_RANGE = 1 ; 放大活动范围
DAMPENING_LAG = 0.99 ; 降低阻尼
OFFSET_GAIN = 0 ; 关闭回弹刚性
G_GAIN = 2 ; G 力影响
GRAVITY_GAIN = 3 ; 重力影响
G_FILTER = 0 ; 不过滤 G 力
DEFAULT_GRAVITY_INCLUDED_ALREADY = 0 ; 允许重力影响默认姿态
STIFF_AXIS_STIFFNESS = 0 ; 不限制晃动轴

适用

后视镜吊饰

车内挂件

软胶装饰件

天线晃动

小扰流件震动

⑫ 可视化可调尾翼 ​

🪰

参考官方 Cars – Visually adjustable wings 页面：
这个功能用于让车辆设置里的翼片角度在模型上可视化变化，主要用于可调尾翼或赛车翼片。

样板代码 ​

ini
[ADJUSTABLE_WING_0] ; 可视化可调尾翼
NAME = node_rear_wing ; 尾翼节点
WING = 2 ; aero.ini 中对应翼片编号
ANGLE_BASE = 0 ; 基础角度偏移
ANGLE_MULT = 0.8 ; 角度倍率
DEBUG_MODE = 0 ; 关闭调试模式
ROTATION_PIVOT = 0, 0.0, -0.035 ; 旋转中心
ROTATION_AXIS = -1, 0, 0 ; 旋转轴

禁用自动尾翼猜测

ini
[ADJUSTABLE_WING_0] ; 禁用自动尾翼可视化
NAME = non_existent_node ; 使用不存在节点避免自动生效

适用

可调后翼

赛车翼片

DRS 类视觉部件

空气套件角度显示

⑬ 节点调整 ​

👁️

参考官方 Cars – Node adjustments 页面：
这个功能可以移动节点、隐藏节点或调整节点归属，常用于修正模型层级、隐藏多余物体、把内饰物体移到正确节点下。

移动节点 ​

ini
[NODE_ADJUSTMENT_MOVE] ; 节点移动
NODES = node_interior_part ; 需要移动的节点
MOVE_TO = COCKPIT_HR ; 移到目标节点下
IS_ACTIVE = 1 ; 启用调整

隐藏节点 ​

ini
[NODE_ADJUSTMENT_HIDE] ; 隐藏节点
NODES = node_unused_part ; 需要隐藏的节点
IS_ACTIVE = 0 ; 关闭节点显示

适用

隐藏多余模型

移动内饰层级

修正 COCKPIT_HR 层级

临时关闭某个部件

⑭ 驾驶员重量偏移 ​

🧔‍♂️

参考官方 Cars – Driver weight shift 页面：
这个功能主要让驾驶员身体产生视觉偏移，常用于卡丁车、轻量车或需要驾驶员身体随操作移动的车辆。

ini
[_EXTENSION_DRIVER] ; 驾驶员重量偏移
MASS = 75 ; 驾驶员质量
SHIFT_RANGE = 0.3 ; 物理偏移范围
SHIFT_VISUAL_RANGE = 0.5 ; 视觉偏移范围
NEGATIVE_MASS = 1 ; 不额外增加默认重心偏移
SHIFT_MULTIPLIER = 0.25 ; 实际参与移动倍率

适用

卡丁车

轻量车

驾驶员身体左右移动

驾驶员视觉偏移

动画输入参数 ​

样板代码 ​

ini
[ANIMATION_...] ; 动画输入修正样板
INPUT = TYRE_PRESSURE ; 绑定胎压输入
INPUT_SELECTOR = X ; 选择第一个值
INPUT_ADD = 0.0 ; 输入加值
INPUT_MULT = 1.0 ; 输入倍率
INPUT_MIN = 10.0 ; 输入最小限制
INPUT_MAX = 40.0 ; 输入最大限制
INPUT_MOD = 5.0 ; 输入取模
INPUT_LUT = (|0=0|10=20|) ; 输入映射表
INPUT_LAG_UP = 0.9 ; 输入上升平滑
INPUT_LAG_DOWN = 0.95 ; 输入下降平滑
INPUT_ROUND = 0.1 ; 输入取整精度
INPUT_ROUND_MODE = ROUND ; 取整模式
INPUT_THRESHOLD = 20 ; 触发阈值
INPUT_THRESHOLD_INVERSE = 0 ; 反向触发
INPUT_DEBUG = 30 ; 调试固定输入值
FILE = animation_test.ksanim ; 动画文件

常用参数 ​

常用动画 INPUT ​

灯光 / 状态 ​

ini
LIGHT / HEADLIGHTS              ; 车灯开启
LOWBEAM                         ; 近光灯
HIGHBEAM                        ; 远光灯
DRL                             ; 日行灯
BRAKE / BRAKE_LIGHTS            ; 刹车
REVERSE / REVERSE_LIGHTS        ; 倒车
HAZARD                          ; 双闪
TURNSIGNAL_LEFT                 ; 左转向
TURNSIGNAL_RIGHT                ; 右转向
OPENDOORS                       ; 开门
SEATBELT                        ; 安全带

Extra 开关 ​

ini
EXTRA_A 到 EXTRA_T ; 自定义功能开关

踏板 / 操作 ​

ini
GAS        ; 油门
BRAKE      ; 刹车
CLUTCH     ; 离合
HANDBRAKE  ; 手刹
STEER      ; 方向盘角度
HORN       ; 喇叭

档位 ​

ini
GEAR_R
GEAR_N
GEAR_D
GEAR_1 到 GEAR_9

数值型 ​

text
SPEED               ; 车速
RPM                 ; 转速
FUEL                ; 油量
WATER_TEMPERATURE   ; 水温
TURBO               ; 涡轮压力
G_FORCE             ; G 力
TYRE_PRESSURE       ; 胎压
BODY_DAMAGE         ; 车身损伤

Debug 排错 ​

动画不播放

→ 检查 FILE 是否在 animations 文件夹

动画没有触发

→ 检查 INPUT 是否写对

动画方向反了

→ 检查 ksanim，或用 LUT 反转

动画太快 / 太慢

→ 调 TIME

动画跳变明显

→ 加 INPUT_LAG_UP / INPUT_LAG_DOWN

踏板动画不跟脚

→ 检查 INPUT_AS_PROGRESS = 1

循环动画不循环

→ 检查 LOOP_WHILE_ACTIVE = 1

关闭后不回位

→ 检查 LOOP_KEEP_UNTIL_DONE / HOLD_STATE

Extra 按键不生效

→ 检查 EXTRA_SWITCHES 和 INPUT = EXTRA_A

雨刷抖动太大

→ 降低 WIND_AMPLITUDE_MULT

吊饰晃动太夸张

→ 降低 MAX_RANGE / G_GAIN / GRAVITY_GAIN

尾翼旋转轴不对

→ 调 ROTATION_AXIS / ROTATION_PIVOT

节点隐藏不生效

→ 检查 NODES 名称和 IS_ACTIVE