Style Guide

本文档将介绍基岩版Wiki附加包创作风格指南。本指南旨在推广附加包创作的最佳实践，并为所有人提供统一的格式规范。

文件夹结构 ​

• 文件路径中不要使用空格，应使用下划线。
• 标识符、文件名和文件夹名中不要使用大写字母。"BP"和"RP"文件夹名称可以使用大写。
• 任何路径的总字符长度不得超过80个字符（控制台限制）。
• 内容文件夹应保持一致的复数形式：要么全部使用复数，要么全部使用单数，不要混用。例如：

✅️ 一致：

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是单数。

标识符 ​

不要使用以数字开头的标识符，尤其不要使用纯数字的标识符。这适用于实体、组件组、事件以及任何使用命名空间:名称对的内容。

文件和文件夹命名 ​

命名空间 ​

合适的命名空间应该是您或您的团队独有的。像mob、cars、content或custom这样的命名空间是不好的，因为其他开发者可能会使用相同的命名空间。

minecraft和minecon是保留的命名空间，请不要使用。

对于个人项目，请使用您玩家名的变体；对于团队项目，请使用团队名称的合适变体。

当多个开发者共同参与一个项目时，命名空间应该始终共享。如果需要注明贡献者，可以使用子索引：minetite.wiki:dragon

使用命名空间的场景：

• 实体
• 粒子效果
• 组件组
• 事件

不使用命名空间的场景：

• 不要在文件夹路径或文件名中包含命名空间。
• 注意： 以下文件夹例外：functions、structures、loot_tables、trade_tables、sounds和textures。
  • 建议在这些文件夹中使用命名空间，以防止与其他包冲突。
  • 示例： BP/functions/namespace/test.mcfunction

子索引 ​

子索引使用.来分隔链式概念。子索引应按从大到小的顺序排列：

✔️ animation.controller.dragon.flying.taking_off

❌ animation.controller.dragon_take_off_flying

使用子索引时，用_代替空格，而不是另一个.。

✔️ animation.controller.dragon.flying.taking_off

❌ animation.controller.dragon.flying.taking.off

您可以在实体中使用子索引： wiki:dragon.drake

组和事件应相互对应 ​

短名称应通用 ​

短名称是文件特定的标识符，用于在标识符和友好名称之间建立映射。它们非常有用，因为它们允许我们重用动画控制器和渲染控制器。因此，您的短名称应该是通用的。

✔️ "sit": "animation.dragon.sit"

❌ "dragon_sitting": "animation.dragon.sit"

当我们使用这种形式的短名称时，可以为所有实体使用通用的"sit"动画控制器，因为我们可以使用sit短名称来播放坐下的动画。

函数 ​

1. 所有.mcfunction文件必须放在函数文件夹内带命名空间的根文件夹中。在基岩版Wiki上，我们使用wiki命名空间。但您可以根据自己的名称或项目选择命名空间。更多信息请参考命名空间页面。
   • ✅️ BP/functions/wiki/random_number.mcfunction
   • ❌️ BP/functions/random_number.mcfunction
2. 必须正确嵌套：
   • ✅️ BP/functions/wiki/teleport/zone/hell.mcfunction
   • ❌ BP/functions/wiki/teleport_hellzone.mcfunction
3. 名称必须遵循动作_对象结构。即动词应在主语之前。
   • ✅️ add_all
   • ❌️ all_add
   • ✅️ shuffle_position
   • ❌️ position_shuffle

函数中的注释 ​

• 当处理包含多个命令的函数时，使用多个井号(#)在注释中标记不同的标题级别有助于保持代码组织。
• 可选地，为了进一步区分这些级别，可以应用不同的样式：
  • 一级标题 - # 大写
  • 二级标题 - ## 首字母大写
  • 三级标题 - ### 句子大小写
• 尽量避免使用超过三个标题级别或过多的标题，因为这会使代码看起来杂乱。参考示例如下：

# 玩家丢弃物品时

## 给予效果
### 火焰抗性
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

注意一级标题前使用两行间距，二级标题前使用一行间距以提高可读性。

这种做法有助于创建一致的格式，使每个人更容易遵循，并保持函数的统一性。

记分板目标与标签 ​

• 必须以命名空间开头并使用蛇形命名法。
  • 这可以防止与其他使用相同标签或目标的包发生冲突。
• 只能使用小写字母(a-z)、下划线(_)和点号(.)作为特殊字符。

目标示例：

• wiki:blocks_travelled.overworld
• wiki:q.is_sneaking
• wiki:q.is_armed_any

标签示例：

• wiki:inventory.full
• wiki:inventory.empty
• wiki:is_flying

记分板持有者 ​

• 必须以点号(.)或井号(#)为前缀，并使用帕斯卡命名法。
  • 这可以防止与使用相同名称的游戏标签冲突，并提供清晰的视觉区分，因为记分板持有者与目标紧密相关。
  • 使用前缀而不是命名空间是为了保持简洁，因为带命名空间的目标已经可以防止与其他包冲突。
• 除点号(.)外，不要使用其他特殊字符。

示例：

• .Ores.Iron
• .Ores.DeepslateIron
• .200

尽可能分组动画文件 ​

示例：

{
    "format_version": "1.8.0",
    "animations": {
        "animation.dragon.sit": {...},
        "animation.dragon.fly": {...},
        "animation.dragon.roar": {...},
  }
}

按路径而非名称拆分纹理 ​

✔️ textures/dragon/red

❌ textures/dragon_red_skin

✔️ textures/npc/dragon_hunter/archer

❌ textures/npc/dragon_hunter_archer

.lang文件注释 ​

为本地化人员准备的注释应始终内联，格式如下：

the.key=字符串<\t>## 注释，供本地化人员参考。

<\t>代表制表符。

行内注释可用于组织目的，但不应存储对本地化至关重要的信息。

讨论时使用的缩写 ​

定义格式顺序 ​

方块、实体和物品应遵循以下格式顺序。

方块 ​

• format_version
• minecraft:block
  • description
    • identifier
    • menu_category
      • category
      • group
    • states
    • traits
  • components
  • permutations
    • condition
    • components

实体 ​

• format_version
• minecraft:entity
  • description
    • identifier
    • spawn_category
    • is_spawnable
    • is_summonable
    • properties
  • component_groups
  • components
  • events

物品 ​

• format_version
• minecraft:item
  • description
    • identifier
    • menu_category
      • category
      • group
  • components

自定义组件 ​

变量命名 ​

应使用帕斯卡命名法，以Block或Item作为前缀，以Component作为后缀。例如，使用const BlockMeltableComponent = { ... }而不是const meltable = { ... }。

这有助于区分我们在registerCustomComponent中使用的内容和在其他地方使用的值。