Cataclysm-DDA 地形/家具检查行为（examine_action）完全指南：硬编码动作与 Examine Actors 详解

Cataclysm-DDA 地形/家具检查行为examine_action完全指南硬编码动作与 Examine Actors 详解【免费下载链接】Cataclysm-DDACataclysm - Dark Days Ahead. A turn-based survival game set in a post-apocalyptic world.项目地址: https://gitcode.com/GitHub_Trending/ca/Cataclysm-DDA本篇技术指南以 Cataclysm-DDACDDA官方 JSON 文档 doc/JSON/EXAMINE.md 为主体系统讲解检查行为examine action这一数据驱动系统如何在地形terrain与家具furniture上挂接交互逻辑涵盖全部硬编码动作的语义、四种 JSON Examine Actorappliance_convert/cardreader/effect_on_condition/mortar的完整参数与实战示例。读完本文你将能够为自定义地形、家具编写可运行、可调试的检查交互并理解其在 C 源码层面的分派机制与真实 Mod 中的典型用法。一、什么是检查行为Examine Action当玩家在地图上对着某个地形或家具按下检查键默认e时游戏会查找该物件的examine_action字段并执行对应逻辑。CDDA 提供了两种表达方式硬编码检查动作以字符串形式指定如examine_action: aggie_plant对应 C 源码中预实现的固定函数检查 ActorExamine Actors以 JSON 对象形式指定如examine_action: { type: mortar, ... }通过type字段选择行为类型其余字段填充具体参数完全数据驱动、无需改动源码。二者可以混合使用examine_action字段同时接受字符串与对象且允许写成数组让同一格地形同时具备多个交互examine_action: [ locked_object_pickable, chainfence, { type: effect_on_condition, ... } ]从源码结构看这一设计在 C 侧由iexamine_actor抽象基类及其派生类承载见 src/iexamine_actors.h每个 Actor 类实现load()JSON 加载、call()触发逻辑、finalize()加载完成后校验三个核心接口并通过clone()支持复制。目前仓库中派生类与文档四种 Actor 一一对应appliance_convert_examine_actor、cardreader_examine_actor、eoc_examine_actor、mortar_examine_actor。二、硬编码 Examine Actions 全表当examine_action取值为下列字符串之一时触发的是 C 中写死的固定逻辑。文档 doc/JSON/EXAMINE.md 所列动作如下动作名行为说明aggie_plant收获作物Harvest plants。autodoc打开自动医疗台Autodoc菜单。需要地形/家具带AUTODOC标志且相邻格有带AUTODOC_COUCH标志的家具配合。autoclave_empty启动高压灭菌锅循环若锅内有受污染的 CBM 且玩家有足够的水。autoclave_full检查灭菌进度循环完成后取回无菌 CBM。bars利用AMORPHOUS特质从栏杆缝隙中挤过去。bulletin_board为派系营地安排任务。chainfence翻越链式围栏。controls_gate控制相连的大门。dirtmound种植种子与植物。elevator使用电梯切换楼层。finite_water_source饮用或从有限水源取液体。与普通water_source不同该动作对应的液体在 mapgen 时以物品形式放置在格子上取尽后即失效须与liquid_source标志成对使用。flower_poppy采摘变异罂粟。fswitch扳动开关使岩石移动。fungus地形崩解时释放孢子。gaspump使用加油泵。harvest_plant_ex收获可收获植物适用于大田作物与种植箱玉米、小麦等。locked_object上锁物件可被撬开添加PICKABLE标志后也可用开锁器打开撬锁/开锁结果由硬编码逻辑决定。locked_object_pickable上锁物件可用开锁器打开需要PICKABLE标志开锁结果硬编码。none无操作。pedestal_temple持有石化之眼时打开神庙。pedestal_wyrm召唤巨蠕虫wyrms。pit_covered揭开盖住的坑。pit若有木板则盖住坑。portable_structure拆除帐篷等便携结构。recycle_compactor将纯金属物件压缩为基本形状。rubble有铲子时清除瓦砾。safe尝试破解保险箱。shelter拆除避难所。shrub_marloss采摘 Marloss 灌木。shrub_wildveggies采摘野生蔬菜灌木。slot_machine赌博。water_source从家具/地形处饮水或取液体须与liquid_source标志成对使用。mortar发射抛射物见下文mortarActor。源码侧的分派注册表硬编码动作在源码中并非魔法字符串而是通过一张动作名 → 函数指针的注册表完成分派。在 src/iexamine.cpp 的iexamine_functions_from_string()中动作名经std::mapstd::string, function_data查表命中后返回对应的iexamine_examine_function函数指针同时会为每个动作附加一个前置条件函数none恒为always_false不可检查invalid会触发debugmsg警告可收获类动作harvest_furn、harvest_ter等使用harvestable_now判断收获时机其余动作恒为always_true未命中时会调用debugmsg( Could not find an iexamine function matching %s! )并回退到none——这意味着 Mod 中写错动作名不会崩溃但会在 debug 日志中明确报错便于排查。值得注意该注册表function_map实际包含的动作比文档列表更丰富例如atm使用 ATM、vending使用售货机、intercom对讲机、deployed_furniture部署/拆除家具、genemill、nanofab、keg、kiln_empty/kiln_full、arcfurnace_empty/arcfurnace_full、curtains、sign、pay_gas、ledge、workbench等供 Mod 制作者直接复用。三、Examine Actors 通用结构所有 Examine Actor 共享两个公共键type必填字符串指定 Actor 类型appliance_convert/cardreader/effect_on_condition/mortarname动作显示名称用于交互菜单。{ type: appliance_convert, name: Take down ... }与硬编码动作不同Actor 的所有行为参数都可直接在 JSON 中声明是 Mod 定制交互的推荐方式。四、appliance_convert拆解电器为物品该 Actor 用于拆下已放置的电器冰箱、烤箱、太阳能板等将其还原为可携带的物品并把所在格替换为指定地形/家具。这是 CDDA 中可搬运电器系统的核心交互。参数说明键必填类型说明furn_set可选字符串拆解后本格设置的家具 id默认不改变。ter_set可选字符串拆解后本格设置的地形 id默认不改变。item必填字符串该电器的基底物品 id拆解后生成并放入背包。从源码看src/iexamine_actors.hfurn_set与ter_set以std::optionalfurn_str_id/std::optionalter_str_id存储缺省即nullopt不改变而appliance_item为必填的itype_id与文档要求一致。示例{ type: appliance_convert, furn_set: f_null, ter_set: t_floor, item: fridge }即检查后本格家具变为f_null、地形变为t_floor同时获得一个fridge物品。仓库内真实用例appliance_convert在基础数据中广泛使用例如 data/json/furniture_and_terrain/furniture-appliances.json 中的洗碗机、洗衣机、烤箱、地面太阳能板、制氧机、油炸锅等如examine_action: { type: appliance_convert, furn_set: f_null, item: household_dishwasher }以及 data/json/furniture_and_terrain/furniture-tools.json 中的电弧炉、钻床data/json/furniture_and_terrain/furniture-decorative.json 中的落地灯等。可以看到实际数据通常只写furn_set: f_null省略ter_set让地形保持原样。五、cardreader门禁读卡器该 Actor 模拟智能卡读卡器玩家持有带指定物品标志flag的卡片即可刷卡开门还支持电子黑客攻击、怪物清场与区域地形批量转换是实验室、军事设施等场景的标配交互。参数说明键必填类型默认值说明flags必填字符串数组—物品上带有的标志列表凡携带其中任一标志的物品都可当卡使用。consume_card可选布尔true是否在激活时消耗所用卡片。allow_hacking可选布尔true是否允许用电击开锁器electrohack黑入。若允许将忽略本 JSON 中其余变换数据直接把半径 3 格内的所有t_door_metal_locked变为t_door_metal_c。despawn_monsters可选布尔true是否移除带ID_CARD_DESPAWN标志的敌对怪物。omt_allowed_radius可选整数(≥0)无穷大对带PRESERVE_SPAWN_OMT标志的卡片允许卡片生成点距读卡器多少个 overmap 格超出则不可用。不带该标志的卡片忽略此字段。mapgen_id可选字符串—开门时应用的更新 mapgen ID整格重建。与radius、terrain_changes、furn_changes互斥。radius可选整数3读卡器周围应用变换的区域半径半径为 3 表示向四周各扩展 3 格。terrain_changes可选JSON 对象无地形变换映射键为原地形 id值为变换后地形 id可写多组如{ a: b, x: y }。furn_changes可选JSON 对象无家具变换映射语义同terrain_changes。query可选布尔true激活/消耗卡片前是否询问玩家确认。query_msg可选字符串无询问玩家时的提示文本。success_msg必填字符串—成功激活时打印到日志的文本。redundant_msg必填字符串—已激活后再尝试激活时打印的文本。示例完整{ type: cardreader, flags: [ SCIENCE_CARD ], consume_card: true, allow_hacking: true, despawn_monsters: true, omt_allowed_radius: 3, radius: 3, terrain_changes: { t_door_metal_locked: t_door_metal_c }, furn_changes: { f_crate_c: f_crate_o }, query: true, query_msg: Are you sure you want to open this door?, success_msg: You opened the door!, redundant_msg: The door is already open. }两种生效路径源码佐证src/iexamine_actors.h 的cardreader_examine_actor明确注释了两种互斥实现路径恰好印证文档中mapgen_id与radius/terrain_changes/furn_changes冲突的规则Option 1遍历地图逐格变换——使用radiusterrain_changesfurn_changes在指定半径内把匹配的旧地形/家具替换为新 idOption 2整格重生成——使用mapgen_id直接对整个当前 overmap 区块重新执行 mapgen配合omt_allowed_radius限制卡片来源距离。仓库内真实用例data/json/furniture_and_terrain/terrain-mechanisms.json 中的读卡器地形是教科书级范例。例如t_card_science科学门禁examine_action: { type: cardreader, flags: [ SCIENCE_CARD ], terrain_changes: { t_door_metal_locked: t_door_metal_c }, query_msg: Swipe your ID card?, success_msg: You insert your ID card.\ncolor_light_greenThe nearby doors unlock./color, redundant_msg: The nearby doors are already opened. }同文件还有t_card_militaryMILITARY_CARD、t_card_industrialINDUSTRIAL_CARD等变体而t_card_fp则直接复用了硬编码动作examine_action: cardreader_fp对应源码注册表中的iexamine::cardreader_foodplace展示了两套体系的混用方式。六、effect_on_condition接入事件条件系统该 Actor 让检查这一事件直接触发一组 Effect On ConditionEOC是把任意自定义逻辑挂到地形/家具上的最灵活途径。键必填类型说明effect_on_conditions必填字符串数组可含 EOC 对象被检查时运行的全部 EOC执行时u为检查者npc为null。EOC 的完整语法与上下文变量体系见仓库文档 doc/JSON/EFFECT_ON_CONDITION.md。从源码看src/iexamine_actors.heoc_examine_actor内部以std::vectoreffect_on_condition_id持有 EOC 列表call()时按序执行。典型用法示例examine_action: { type: effect_on_condition, effect_on_conditions: [ EOC_MY_TERRAIN_INTERACTION ] }七、mortar固定式迫击炮射击mortarActor 把地形/家具变成一门可操作的迫击炮玩家装填指定弹药、瞄准、等待瞄准时间后发射支持自定义精度偏差、飞行时间与命中后的 EOC 回调是间接火力系统的完整实现。参数说明键必填类型默认值说明ammo必填字符串数组—该迫击炮可用的弹药类型列表。range必填整数—最大射程单位米。condition可选Conditiontrue使用炮塔的自定义条件角色必须通过该条件才能使用。condition_fail_msg可选字符串You cannot use this mortar.条件不满足时打印的提示。aim_deviation可选整数或变量对象0瞄准偏差为你与瞄准点距离的百分比0.02表示瞄准 1000 米外目标时可能偏 20 米两个坐标轴各 10 米。aim_duration可选时长或变量对象0秒开火前的瞄准耗时。flight_time可选时长或变量对象0秒弹丸飞行时间到爆炸为止。effect_on_conditions可选JSON 对象—射击结束时触发的 EOC。附加上下文变量this字符串家具 id、pos字符串家具坐标、target字符串所选目标格坐标。示例完整含 EOC 回调examine_action: { type: mortar, ammo: [ mortar_60mm ], condition: { math: [ u_skill(launcher) 1 ] }, condition_fail_msg: You have absolutely no idea how to use this mortar., range: 3490, aim_duration: { math: [ u_effect_duration(aimed_60mm) 1, ? max(5, 16 / u_skill(launcher)), : max(60, 190 / u_skill(launcher)) ] }, aim_deviation: { math: [ max(0.02, 0.1 / u_skill(launcher)) ] }, flight_time: 15 seconds, effect_on_conditions: [ { id: EOC_60MM_SHOT, effect: [ { u_add_effect: aimed_60mm, duration: 3 minutes }, { math: [ u_skill_exp(launcher, format: percentage) ] }, { if: { math: [ distance(u, _target) 400 ] }, then: { u_spawn_item: 60mm_propellant } }, { if: { math: [ distance(u, _target) 1340 ] }, then: { u_spawn_item: 60mm_propellant } }, { if: { math: [ distance(u, _target) 2150 ] }, then: { u_spawn_item: 60mm_propellant } }, { if: { math: [ distance(u, _target) 2890 ] }, then: { u_spawn_item: 60mm_propellant } } ] } ] }注意aim_duration与aim_deviation使用了math表达式数学函数语法见 doc/JSON/MATH.md 对应章节使瞄准时间与精度随launcher发射器技能动态变化这是变量对象variable object字段的典型用法duration_or_var/dbl_or_var类型在源码 src/iexamine_actors.h 中对应aim_duration、flight_time、aim_deviation成员证实了字符串时长与数学对象两种写法都受支持。仓库内真实用例M224 迫击炮data/json/furniture_and_terrain/furniture_military.json 的f_m224_mortar家具完整复现了上述配置且其//range注释详细记录了射表设计4 档装药charge 0~4对应 70~3490 米的不同射程区间、初始瞄准偏差为总距离的 10%随launcher技能最高降到 2%、首次射击瞄准需 190 秒技能高时降到 60 秒、已正确瞄准后仅需 16 秒可降到 5 秒。EOC_60MM_SHOT中按距离返还推进药60mm_propellant的逻辑正是射程越近、未消耗的推进药越多这一游戏机制的实现——用distance(u, _target)与四个阈值比较并u_spawn_item达成。八、实战要点与调试建议字符串 vs Actor 的选择固定、无参数、与玩法强耦合的交互收获、翻越、取水优先用硬编码动作需要自定义参数或 Mod 专属逻辑时用 Actor两者可数组混用。成对标志不可遗漏water_source/finite_water_source必须与liquid_source标志搭配否则取液逻辑无法定位液体来源autodoc需要AUTODOC 相邻AUTODOC_COUCH。相关标志的完整清单见 doc/JSON/JSON_FLAGS.md。警惕拼写错误硬编码动作名写错不会导致加载失败但会在运行时通过debugmsg输出Could not find an iexamine function matching xxx!见 src/iexamine.cpp并静默回退为none。开发 Mod 时应开启 debug 日志尽早发现。cardreader的互斥约束mapgen_id整格重生成与radius/terrain_changes/furn_changes逐格变换不可同时使用二者在源码中对应两条独立执行路径。EOC 是万能扩展点任何需要检查时跑一段复杂逻辑给 buff、传送、刷怪、改全局变量的需求都优先考虑effect_on_conditionActor配合 doc/JSON/EFFECT_ON_CONDITION.md 中u作为检查者、npc为null的上下文约定编写。参考与延伸阅读本文主依据doc/JSON/EXAMINE.mdActor 源码实现src/iexamine_actors.h、src/iexamine_actors.cpp硬编码动作分派注册表src/iexamine.cpp真实数据示例data/json/furniture_and_terrain/terrain-mechanisms.json、data/json/furniture_and_terrain/furniture-appliances.json、data/json/furniture_and_terrain/furniture_military.json关联系统文档doc/JSON/EFFECT_ON_CONDITION.md、doc/JSON/JSON_FLAGS.md【免费下载链接】Cataclysm-DDACataclysm - Dark Days Ahead. A turn-based survival game set in a post-apocalyptic world.项目地址: https://gitcode.com/GitHub_Trending/ca/Cataclysm-DDA创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考