函数

简介 ​

由基岩版命令社区(BCC) Discord提供

函数是包含多行命令的.mcfunction文件，可通过游戏中的/function命令运行。

函数创建于行为包中的functions文件夹内。一个函数包可以仅用函数文件构建完整系统。

函数能有效减少调试系统时在命令方块间来回切换的时间，还能帮助打包系统供多个世界使用，并提供多种改变游戏运行方式的功能。

函数包文件夹结构 ​

为保持格式统一、便于他人理解并维持函数间一致性，建议遵循以下文件夹结构最佳实践：

1. 所有.mcfunction文件必须放在functions文件夹内的命名空间根目录下。Bedrock Wiki使用wiki命名空间，但您可以根据项目或个人命名。详情参考命名空间页面。
   • ✅️ BP/functions/wiki/random_number.mcfunction
   • ❌️ BP/functions/random_number.mcfunction
2. 包内文件夹和文件名必须使用snake_case
   • 仅允许使用小写字母数字和下划线(_)
   • ✅️ BP/functions/wiki/scoreboard/objectives/add_all.mcfunction
   • ❌️ BP/functions/wiki/scoreboard/objectives/Add-All.mcfunction
3. 必须正确嵌套：
   • ✅️ BP/functions/wiki/teleport/zone/hell
   • ❌ BP/functions/wiki/teleport_hellzone
4. 名称应遵循动作_对象结构，动词应位于主语前：
   • ✅️ add_all
   • ❌️ all_add
   • ✅️ shuffle_position
   • ❌️ position_shuffle
5. 路径总字符长度不得超过80个字符（控制台限制）
6. 内容文件夹应保持单复数形式一致：
   • 统一使用复数或单数名称，不要混用

✅️ 正确示范：

BP/functions/wiki/ability/ice_blast.mcfunction
BP/functions/wiki/ability/fire_trail.mcfunction
BP/functions/wiki/event/players/on_death.mcfunction
BP/functions/wiki/event/worlds/on_initialise.mcfunction

• 内容文件夹ability和event均为单数
• event内的players和worlds均为复数

❌️ 错误示范：

BP/functions/wiki/abilities/ice_blast.mcfunction
BP/functions/wiki/abilities/fire_trail.mcfunction
BP/functions/wiki/event/players/on_death.mcfunction
BP/functions/wiki/event/world/on_initialise.mcfunction

• abilities为复数而event为单数
• event中players为复数而world为单数

新手须知 ​

以下是供新手参考的函数文件示例：

# 这些效果适用于出生点
effect @a[tag=wiki:at_spawn] regeneration 12 255 true
effect @a[tag=wiki:at_spawn] saturation 12 255 true
effect @a[tag=wiki:at_spawn] weakness 12 255 true

# 这些效果适用于下界
effect @a[tag=wiki:in_nether] fire_resistance 12 255 true

• 函数中的命令不能以斜杠(/)开头。文件中每新一行代表一个新命令（空行会被忽略）。可以用井号(#)开头添加注释——#后的空格仅为格式偏好。关于函数注释风格指南，请查看下方**注释风格指南**章节。

• 函数中所有命令都在同一游戏刻执行。因此，导致大规模变化的函数可能造成突然的卡顿，建议尽可能将部分命令分配到多个游戏刻执行。但函数中的命令仍会按顺序执行。

• 在Minecraft基岩版中，单个函数文件不能运行超过10,000条命令，这包括原始文件中执行的其他函数文件。

• 无法运行条件命令。这些仍需以某种方式使用命令方块，或利用1.19.50版本的execute语法。

• 要在函数中实现延迟命令执行，需使用记分板计时器逐步计数，直到特定时刻在文件中执行命令。详见记分板计时器页面了解设置方法。

注释风格指南 ​

• 当处理包含许多命令的函数时，使用多级井号注释有助于保持组织性：
  • 可选为区分级别，可应用不同样式：
    • 一级标题 - # 大写字母
    • 二级标题 - ## 首字母大写
    • 三级标题 - ### 句子格式
• 尽量避免使用超过三级标题或过多标题，这会使代码显得杂乱。参考示例如下：

# 玩家丢弃物品时

## 给予效果
### 火焰抗性
execute at @e[type=item,name="Fire Trail Ability"] run effect @p[r=3] fire_resistance 10 255
### 速度
execute at @e[type=item,name="Fire Trail Ability"] run effect @p[r=3] speed 10 1 true

## 添加粒子时间(10秒)
execute at @e[type=item,name="Fire Trail Ability"] run scoreboard players set @p[r=3] abilities.fire_trail 200

## 删除物品
kill @e[type=item,name="Fire Trail Ability"]


# 实体计时器

## 生成粒子轨迹
execute at @a[scores={wiki:ability.fire_trail=1..}] run particle minecraft:basic_flame_particle ~~~

## 倒计时
scoreboard players remove @a [scores={wiki:ability.fire_trail=1..}] wiki:ability.fire_trail 1

注意一级标题前空两行，二级标题前空一行以提升可读性。

这种做法有助于创建统一格式，便于他人理解并保持函数间一致性。 关于记分板和标签规范，请参阅**风格指南**页面。

创建函数 ​

1. 找到📁 com.mojang文件夹并进入📁 development_behavior_packs

   • 开发文件夹用于快速重新加载包，因为这些包不会被缓存到世界文件中。

2. 为函数包创建任意名称的文件夹（称为行为包或BP）

3. 在BP文件夹内创建📄 manifest.json文件和可选的🖼 pack_icon.png文件

   • 清单文件包含注册包所需的所有信息，而包图标会显示在包菜单中。包图标通常为128x128或256x256图像，但任何2的幂次方分辨率均可，它们会相应缩放。

{
    "format_version": 2,
    "header": {
        "description": "在此填写您的包描述",
        "name": "在此填写您的包名称",
        "uuid": "00000000-0000-0000-0000-000000000000",
        "version": [1, 0, 0],
        "min_engine_version": [1, 19, 73]
    },
    "modules": [
        {
            "description": "§r",
            "type": "data",
            "uuid": "00000000-0000-0000-0000-000000000000",
            "version": [1, 0, 0]
        }
    ]
}

4. 创建📁 functions文件夹。此文件夹内任何以**.mcfunction**结尾的文件都会在游戏中注册为函数，可通过/function <函数名称>运行。

   • 允许嵌套函数，只需列出相对于functions文件夹的文件路径，如函数包文件夹结构所示。

5. 在游戏中应用行为包并测试函数。通过运行/reload或重新登录可反映函数文件的更改。

:::提示 注意：

函数有版本要求，因此它们将在📄 manifest.json中列出的版本运行，例如：

• min_engine_version 1.19.50及以上版本将采用新的execute语法
• min_engine_version 1.19.70及以上版本将要求用方块状态替换辅助值

:::

执行 ​

在游戏中输入/function 函数名称可执行函数。这将在一个游戏刻内执行函数文件中的所有命令。

例如嵌套函数BP/functions/wiki/teleport/zone/hell可以通过嵌套文件夹路径运行，即/function wiki/teleport/zone/hell

Tick JSON ​

functions文件夹中的最后一个文件是**tick.json。该文件指定了每个游戏刻服务器端运行的函数（类似于循环型命令方块）。它位于BP/functions文件夹中。默认情况下，此文件中运行的函数在主世界的原点(0, 0, 0)执行。示例tick.json**文件：

{
  "values": [
    "wiki/function_1",
    "wiki/function_2"
  ]
}

注意：此文件中的函数会在世界初始化后立即运行，无论玩家是否已加载。如果使用不当可能导致意外行为。

示例函数包 ​

下载

函数故障排除 ​

使用/function时，您的函数可能不会出现在命令建议中。这通常是由于函数中一个或多个命令存在错误。

在创作者设置中启用内容日志可以查看函数包中是否存在错误，包括错误所在的函数、行号以及具体的语法错误。

每次加载世界或运行/reload反映文件更改后，都会生成错误列表。该列表可在屏幕上显示几秒钟，也可在设置的内容日志历史记录中查看。