ModAPI-ModUtil

本文的函数定义在游戏脚本跟目录下的modutil.lua，是一系列适用于Mod环境的API，它们是klei专门提供给Mod开发者的，在Mod环境内不需要引用全局变量即可使用。这些API作用非常丰富，掌握好了可以让你的Mod开发水平更上一层楼。

API列表

其中可用范围的含义，全部是指可以在modmain和modworldgenmain中使用。

函数名	输入参数	作用	分类	可用范围	已解析
GetModConfigData	optionname, get_local_config	获取模组配置数据	Mod系统	全部	否
ReloadFrontEndAssets	(无参数)	重新加载前端资源	Mod系统	全部	否
ReloadPreloadAssets	(无参数)	重新加载预加载资源	Mod系统	全部	否
AddGameMode	game_mode, game_mode_text	[已废弃]添加游戏模式。此功能转移到了modinfo中进行定义	地图	全部	否
AddLevel	arg1, arg2, ...	添加level	地图	全部	否
AddLevelPreInit	levelid, fn	修改level	地图	全部	否
AddLevelPreInitAny	fn	修改全部level	地图	全部	否
AddLocation	arg1, ...	添加location	地图	全部	否
AddRoom	arg1, ...	添加room	地图	全部	否
AddRoomPreInit	roomname, fn	修改room	地图	全部	否
AddStartLocation	arg1, ...	添加startlocation	地图	全部	否
AddTask	arg1, ...	添加task	地图	全部	否
AddTaskPreInit	taskname, fn	修改task	地图	全部	否
AddTaskSet	arg1, ...	添加taskset	地图	全部	否
AddTaskSetPreInit	tasksetname, fn	修改taskset	地图	全部	否
AddTaskSetPreInitAny	fn	修改全部taskset	地图	全部	否
AddCustomizeGroup	category, name, text, desc, atlas, order	添加自定义分组	建房UI	全部	否
AddCustomizeItem	category, group, name, itemsettings	添加自定义项目	建房UI	全部	否
GetCustomizeDescription	description	获取自定义描述	建房UI	全部	否
RemoveCustomizeGroup	category, name	删除自定义分组	建房UI	全部	否
RemoveCustomizeItem	category, name	删除自定义项目	建房UI	全部	否
AddClassPostConstruct	package, fn	[猜测]与类修改有关，常用于UI组件修改	其它	全部	否
AddGamePostInit	fn	[猜测]添加游戏后初始化函数，较少用到	其它	全部	否
AddGlobalClassPostConstruct	package, classname, fn	[猜测]与类修改有关，可指定单个类，常用于UI组件修改	其它	全部	否
AddSimPostInit	fn	[猜测]添加模拟后初始化函数，较少用到	其它	全部	否
AddBrainPostInit	brain, fn	修改brain	AI	仅modmain	否
AddLoadingTip	stringtable, id, tipstring, controltipdata	添加加载提示	Mod系统	仅modmain	否
AddModCharacter	name, gender, modes	添加Mod角色	Mod系统	仅modmain	否
RegisterInventoryItemAtlas	atlas, prefabname	注册物品栏物品图集	Mod系统	仅modmain	否
RemoveDefaultCharacter	name	移除默认角色	Mod系统	仅modmain	否
RemoveLoadingTip	stringtable, id	移除加载提示	Mod系统	仅modmain	否
SetLoadingTipCategoryIcon	category, categoryatlas, categoryicon	设置加载提示类别图标	Mod系统	仅modmain	否
SetLoadingTipCategoryWeights	weighttable, weightdata	设置加载提示类别权重	Mod系统	仅modmain	否
AddStategraphActionHandler	stategraph, handler	给指定sg添加ActionHandler	SG	仅modmain	否
AddStategraphEvent	stategraph, event	给指定sg添加Event	SG	仅modmain	否
AddStategraphPostInit	stategraph, fn	修改指定sg	SG	仅modmain	否
AddStategraphState	stategraph, state	给指定sg添加state	SG	仅modmain	否
AddAction	id, str, fn	添加动作	动作	仅modmain	否
AddComponentAction	actiontype, component, fn	添加组件动作	动作	仅modmain	否
AddComponentPostInit	component, fn	修改指定组件	基础修改	仅modmain	否
AddPlayerPostInit	fn	修改玩家	基础修改	仅modmain	否
AddPrefabPostInit	prefab, fn	修改指定prefab	基础修改	仅modmain	否
AddPrefabPostInitAny	fn	修改任意Prefab	基础修改	仅modmain	否
AddPopup	id	添加弹窗，未知用途	其它	仅modmain	否
AddUserCommand	command_name, data	添加用户命令	其它	仅modmain	否
AddVoteCommand	command_name, init_options_fn, process_result_fn, vote_timeout	添加投票命令	其它	仅modmain	否
ExcludeClothingSymbolForModCharacter	name, symbol	为模组角色排除服装符号	其它	仅modmain	否
LoadPOFile	path, lang	加载翻译文件	其它	仅modmain	否
SetModHUDFocus	focusid, hasfocus	设置ModHUD焦点	其它	仅modmain	否
AddModShadersInit	fn	添加shader初始化函数	特效	仅modmain	否
AddModShadersSortAndEnable	fn	添加shader排序和启用函数	特效	仅modmain	否
AddClientModRPCHandler	namespace, name, fn	添加客户端ModRPCHandler	网络	仅modmain	否
AddModRPCHandler	namespace, name, fn	添加ModRPCHandler	网络	仅modmain	否
AddReplicableComponent	name	添加replica	网络	仅modmain	否
AddShardModRPCHandler	namespace, name, fn	添加分片ModRPCHandler	网络	仅modmain	否
GetClientModRPC	namespace, name	获取客户端ModRPC	网络	仅modmain	否
GetClientModRPCHandler	namespace, name	获取客户端ModRPCHandler	网络	仅modmain	否
GetModRPC	namespace, name	获取ModRPC	网络	仅modmain	否
GetModRPCHandler	namespace, name	获取ModRPCHandler	网络	仅modmain	否
GetShardModRPC	namespace, name	获取分片ModRPC	网络	仅modmain	否
GetShardModRPCHandler	namespace, name	获取分片ModRPCHandler	网络	仅modmain	否
SendModRPCToClient	id_table, ...	向客户端ModRPC	网络	仅modmain	否
SendModRPCToServer	id_table, ...	向主机端发送ModRPC	网络	仅modmain	否
SendModRPCToShard	id_table, ...	向分片发送ModRPC	网络	仅modmain	否
RemapSoundEvent	name, new_name	重映射声音事件	音效	仅modmain	否
RemoveRemapSoundEvent	name	移除重映射声音事件	音效	仅modmain	否
AddMinimapAtlas	atlaspath	添加小地图图标	游戏UI	仅modmain	否
AddCharacterRecipe	name, ingredients, tech, config, extra_filters	添加角色专属制作配方	制作	仅modmain	是
AddCookerRecipe	cooker, recipe	添加烹饪配方	烹饪	仅modmain	否
AddDeconstructRecipe	name, return_ingredients	添加拆解配方	制作	仅modmain	否
AddIngredientValues	names, tags, cancook, candry	添加食材属性值(批量修改)	烹饪	仅modmain	否
AddPrototyperDef	prototyper_prefab, data	[待测试]添加原型制作器定义	制作	仅modmain	否
AddRecipe	arg1, ...	[已废弃]添加新制作配方	制作	仅modmain	是
AddRecipe2	name, ingredients, tech, config, filters	添加新制作配方	制作	仅modmain	是
AddRecipeFilter	filter_def, index	添加制作配方分类过滤器	制作	仅modmain	是
AddRecipePostInit	recipename, fn	修改指定制作配方	制作	仅modmain	否
AddRecipePostInitAny	fn	修改任意制作配方	制作	仅modmain	否
AddRecipeTab	rec_str, rec_sort, rec_atlas, rec_icon, rec_owner_tag, rec_crafting_station	[已废弃]添加制作栏分类	制作	仅modmain	是
AddRecipeToFilter	recipe_name, filter_name	将制作配方添加到分类过滤器	制作	仅modmain	是
Recipe	...	[已废弃]创建配方	制作	仅modmain	是
RemoveRecipeFromFilter	recipe_name, filter_name	从过滤器中移除制作配方	制作	仅modmain	是

物品制作

AddRecipe2

作用: 添加一个新的制作配方

参数

• name (string): 配方的名称。
• ingredients (table): 配方所需的原料列表。
• tech (string): 解锁该配方所需的科技名称。
• (可选)config (table): 一个可选的配置表，包含以下字段:
  • (可选)placer(string): 放置物 prefab，用于显示一个建筑的临时放置物，在放下建筑后就会消失。
  • (可选)min_spacing (num): 建造物的最小间距。
  • (可选)nounlock (bool): 如果为 false，只能在对应的科技建筑旁制作。否则在初次解锁后，就可以在任意地点制作。
  • (可选)numtogive (num): 制作成功后，玩家将获得的物品数量。
  • (可选)builder_tag (string): 要求具备的制作者标签。如果人物没有此标签，便无法制作物品，可以用于人物的专属物品。
  • (必须)atlas (string): 物品图标所在的 atlas 文件路径，用于制作栏显示图片，其实不填也行，但图标会是空的。
  • (可选)image (string): 物品图标的文件名，其实 atlas 中已包含，不必再填。
  • (可选)testfn (function): 放置时的检测函数，比如有些建筑对地形有特殊要求，可以使用此函数检测。
  • (可选)product (string): 产出物，表示制作成功后产生的物品。默认
  • (可选)build_mode (string): 建造模式，必须使用常量表BUILDMODE，形如BUILDMODE.LAND，具体取值为无限制（NONE）、地上（LAND）和水上（WATER）。
  • (可选)build_distance (num): 建造距离，表示玩家与建筑之间的最大距离。
• (可选)filters (table): 一个可选的过滤器列表，包含要将配方添加到的过滤器名称。

代码示例

-- 文件: modmain.lua
local recipe_name = "lotus_umbrella" -- 配方唯一名称，不可重复，通常用prefab名
local ingredients = {Ingredient("cutgrass", 1), Ingredient("twigs", 1)} -- 原料表
local tech = TECH.NONE -- 所需科技，必须使用常量表TECH的值
local config = {
    atlas = "images/inventoryimages/lotus_umbrella.xml",
}
AddRecipe2(recipe_name, ingredients, tech, config)
STRINGS.RECIPE_DESC.LOTUS_UMBRELLA = "荷叶做的雨伞" -- 制作栏描述

AddCharacterRecipe

作用: 添加角色专属制作配方。实际上参数和作用都和AddRecipe2一样，专属体现在config中的builder_tag

参数 - name (string): 配方的名称。 - ingredients (table): 配方所需的原料列表。 - tech (string): 解锁该配方所需的科技名称。 - (可选) config (table): 一个可选的配置表，同AddRecipe2 - (可选) filters (table): 一个可选的过滤器列表，包含要将配方添加到的额外过滤器名称。

返回值:

• rec (Recipe2): 创建的 Recipe2 对象。

代码示例

-- 创建一个角色专属配方，只有可读书的人才能使用
local config2 = {
    atlas = "images/inventoryimages/lotus_umbrella.xml",
    builder_tag = "reader",
    product = "lotus_umbrella", -- 当recipe名不是prefab名时，需要显式指定
}
AddCharacterRecipe("lotus_umbrella_few", {Ingredient("cutgrass", 1)}, TECH.NONE, config2, {"SAMANSHA"})

AddRecipeFilter

作用: 添加一个新的配方过滤器。

参数

• filter_def (table): 过滤器定义，包括以下字段:
  • name (string): 过滤器的ID。主要用于两处，一是 STRINGS.UI.CRAFTING_FILTERS[name]。赋值给出在UI界面上显示的过滤器名字，二是在其它API使用过滤器作为参数时用于指代，请参考示例代码。
  • atlas (string 或 function): 图标的图集，可以是字符串或函数。
  • image (string 或 function): 显示在制作菜单中的图标，可以是字符串或函数。
  • (可选) image_size (table): 自定义图像尺寸，默认64。
  • (可选) custom_pos (table): 自定义的过滤器位置，默认为false。 如果为 true，则过滤器图标不会被添加到网格中，而是把这个分类下的物品都放在mod物品分类下。
  • recipes (table): 不支持此字段！ 请创建过滤器后，将过滤器传递给 AddRecipe2() 或 AddRecipeToFilter() 函数。
• (可选) index (number): 插入过滤器定义的索引。如果提供，将在指定索引处插入过滤器定义；否则，将过滤器定义添加到列表末尾。

代码示例

-- 加载资源
Assets = {
    Asset("ATLAS", "images/craft_samansha_icon.xml"),
}
-- 定义一个新的过滤器对象
local filter_samansha_def = {
    name = "SAMANSHA",
    atlas = "images/craft_samansha_icon.xml",
    image = "craft_samansha_icon.tex"
}
-- 添加自定义过滤器
AddRecipeFilter(filter_samansha_def, 1)
STRINGS.UI.CRAFTING_FILTERS.SAMANSHA ="自定义过滤器" -- 制作栏中显示的名字
-- 创建一个配方，并将其添加到自定义过滤器中，注意用的是过滤器的name参数值
AddRecipe2("my_custom_recipe", ingredients, tech, config, {"SAMANSHA"})

AddRecipeToFilter

作用: 将配方添加到指定的过滤器中。

参数

• recipe_name (string): 要添加的配方名称。
• filter_name (string): 要添加配方的过滤器名称。

代码示例

-- 将荷叶伞放到「雨具」分类
AddRecipeToFilter("lotus_umbrella","RAIN")

RemoveRecipeFromFilter

作用: 从指定的过滤器中移除配方。

参数

• recipe_name (string): 要移除的配方名称。
• filter_name (string): 要从中移除配方的过滤器名称。

代码示例

-- 将斧头移出「工具」分类
RemoveRecipeFromFilter("axe", "TOOLS")

AddDeconstructRecipe

作用: 添加分解配方，不会在任何过滤器下出现，这只是供「分解法杖」或敲碎不可制作的物品而设计的。

参数

• name (string): 要添加配方的prefab名。
• return_ingredients (string): 返还的材料

代码示例

-- 分解斧头得到一个燧石
AddDeconstructRecipe("axe", {Ingredient("flint", 1)})

AddPrototyperDef

作用: 自定义原型机(研究或制作站)在制作菜单中的显示方式。光看这个名字有点难理解，其实原型机就是指科学机器、炼金机器、远古制作台这类东西，过年活动时的神龛也算此类。角色站在旁边时可以制作对应的物品 参数

• prototyper_prefab (string): 用于原型机的prefab名
• prototyper_def (table)
  • icon_atlas (string): 图标文档
  • icon_image (string): 图标图片
  • action_str (string): 「建造」按钮显示的字符串，比如神龛显示的是「供奉」
  • is_crafting_station (bool): 是否是制作站，也就是是否只能在停留附近时才能制作对应物品
  • filter_text (string): 在过滤器上的名称

代码示例

local prototyper_prefab = "moon_altar"
prototyper_def = {
    icon_atlas = "images/xxxx.xml", 
    icon_image = "moon_altar.tex",
    is_crafting_station = true,
    action_str = "生产",
    filter_text = "月之产品“
},

AddPrototyperDef(prototyper_prefab, prototyper_def) 

AddRecipePostInit

作用: 修改指定的Recipe

参数

• recipe (string): 要修改的recipe名
• fn (function): 修改函数，传入参数为这个recipe对象

代码示例

local function fn(recipe)
    -- 修改制作栏描述
    recipe.description = "适合砍树"
end

AddRecipePostInit("axe", fn)

AddRecipePostInitAny

作用: 修改任意Recipe

参数

• fn (function): 修改函数，传入参数为recipe对象。这个修改会对所有的recipe生效

代码示例

local function fn(recipe)
    -- 统一修改制作栏描述
    local old_str = recipe.description
    recipe.description = "描述: " ... old_str
end

AddRecipePostInitAny(fn)

已废弃

以下API已废弃，不推荐在新的Mod制作中使用

• AddRecipe 添加新制作配方
• Recipe 创建配方
• AddRecipeTab 添加制作栏分类

其它

AddUserCommand

作用: 向游戏中添加一个自定义用户命令。

参数

• name (string): 命令的名称。
• data (table): 命令的详细信息，包括以下字段:
  • (可选) aliases (table): 命令的别名列表。
  • (可选) prettyname (string): 写在UI上的名称。
  • (可选) desc (string): 命令的描述。
  • permission (string): 命令所需的权限（如：COMMAND_PERMISSION.USER）。
  • (可选) slash (boolean): 是否在命令前加斜杠。
  • (可选) usermenu (boolean): 是否在用户菜单中显示命令。
  • (可选) servermenu (boolean): 是否在服务器菜单中显示命令。
  • (可选) params (table): 命令的参数列表。
  • (可选) paramsoptional (table): 参数是否可选的布尔值列表。
  • (可选) localfn (function): 本地函数，当命令被调用时执行。
  • (可选) serverfn (function): 服务器函数，当命令被调用时执行。
  • (可选)vote (boolean): 是否允许对此命令进行投票，默认为false。
  • (可选)votetimeout (number): 投票持续时间（秒）。
  • (可选)voteminstartage (number): 用户必须在服务器上待至少多少秒才能开始投票。
  • (可选)voteminpasscount (number): 投票通过所需的最小票数。
  • (可选)votecountvisible (boolean): 投票结果是否对玩家可见。
  • (可选)voteallownotvoted (boolean): 是否允许未投票的玩家看到投票结果。
  • (可选)voteoptions (table): 投票选项
  • (可选)votetitlefmt (string): 投票标题的格式
  • (可选)votenamefmt (string): 投票名称的格式
  • (可选)votepassedfmt (string): 投票通过后的显示信息
  • (可选)votecanstartfn (function): 检查投票是否可以开始的函数
  • (可选)voteresultfn (function): 根据投票结果执行相应操作的函数

代码示例

AddUserCommand("hello", {
    aliases = {"hi", "hey"},
    prettyname = "Hello Command",
    desc = "Say hello to the server",
    permission = GLOBAL.COMMAND_PERMISSION.USER,
    slash = true,
    usermenu = false,
    servermenu = false,
    params = {"intro"},
    paramsoptional = {true},
    vote = false,
    serverfn = function(params, caller)
        if params.intro ~= nil then
            GLOBAL.TheNet:Say("Hello, everyone! "..params.intro)
        else
            GLOBAL.TheNet:Say("Hello, everyone!")
        end
    end,
})

评论