Habitica 装备描述文案规范:gear_README.md 风格指南深度解读与源码实现

原创2026-10-15 09:55:481,217 阅读
文章标签:后端前端项目管理

Habitica 装备描述文案规范:gear_README.md 风格指南深度解读与源码实现

导读

本文围绕 Habitica 仓库中 装备描述风格指南 展开,系统讲解游戏装备(Gear)文本描述的书写规范:元素顺序、属性加成(Stat Effect)的四种句式模板、以及出处(Event/Origin)措辞约定。文章同时深入 website/common/locales/en/gear.json 的实际条目与 装备数据定义 的源码实现,说明模板变量 <%= str %>、<%= attrs %> 如何被渲染为最终文案。读完本文,你将掌握为 Habitica 新增或修改装备描述时应遵循的完整写作规则,以及描述文本从翻译文件到界面展示的底层调用链。

文档定位:为什么需要一份装备描述规范

Habitica 是一款把目标管理当作角色扮演游戏的习惯追踪应用,装备是其核心游戏化元素之一。装备条目分散在武器、护甲、头部、盾牌、背部、身体、头饰、眼镜等多个槽位(weapon、armor、head、shield、back、body、headAccessory、eyewear,参见 gear 定义),且由社区翻译成几十种语言。如果没有统一的写作范式,会出现描述顺序混乱、属性加成写法五花八门、来源信息缺失等问题。

为此,装备描述风格指南 应运而生,它源自一次社区提案(PR),目的是保证所有装备描述在结构、措辞和国际化模板使用上的一致性。这份文档篇幅虽短,却是装备文案写作的"宪法",与 gear.json 中数千行实际条目一一对应。

元素顺序:描述 → 属性效果 → 出处

指南规定的装备描述结构固定为三段式:

  1. Description(描述):用一句有画面感的文字描述装备的外观或来历;
  2. Stat Effect(属性效果):说明装备提供的属性加成,遵循固定的句式模板;
  3. Event/Origin(事件/出处,如需要):说明该装备的获取来源(如订阅奖励、限定季节装备)。

以 gear.json 中的真实条目为例,结构一目了然:

  • weaponWarrior6Notes:"Bane of creatures of darkness. Increases Strength by <%= str %>."(描述 + 属性效果)
  • weaponSpecialSpringWarriorNotes:"This mighty sword can slice foes with ease! It also makes a delicious mid-battle snack. Increases Strength by <%= str %>. Limited Edition 2014 Spring Gear."(描述 + 属性效果 + 出处)

需要特别指出:Stat Effect 与 Event/Origin 的次序是固定的——属性效果在前,出处说明在后。读者可以先获知装备"有什么加成",再了解"从哪来",信息层级清晰。

Stat Effect 句式模板:四种情况的统一写法

指南将属性加成划分为四种情况,每种都有标准的英文句式。以下结合 gear.json 中的真实条目逐一对应。

情况一:无属性加成

统一写作 "Confers no benefit."(不提供任何加成)。

实际应用:新手装备、部分订阅/特殊装备均使用此句式。例如:

  • weaponWarrior0Notes:"Practice weapon. Confers no benefit."(训练剑)
  • weaponWizard0Notes:"Practice staff. Confers no benefit."(学徒法杖)
  • weaponMystery201411Notes:"...Confers no benefit. November 2014 Subscriber Item."(订阅奖励亦可无属性加成)

情况二:单属性或全属性加成

单属性写法为:

Increases (Strength/Intelligence/Constitution/Perception/all Stats) by (<%= str %>/<%= int %>/<%= con %>/<%= per %>/<%= attrs %>).

括号中的占位符按需取其一。实例:

  • weaponWarrior1Notes:"...Increases Strength by <%= str %>."(单属性 Strength)
  • weaponHealer4Notes:"...Increases Intelligence by <%= int %>."(单属性 Intelligence)
  • weaponSpecial1Notes:"...Increases all Stats by <%= attrs %>."(全属性)

注意:全属性时使用统一变量 <%= attrs %>,表示四项属性获得相同数值。

情况三:双属性、加成数值相同

写法为:

Increases (Strength/Intelligence/Constitution) and (Intelligence/Constitution/Perception) by <%= attrs %> each.

即两个属性获得相同的加成值,用 each(各)和统一变量 <%= attrs %>。实例:

  • weaponSpecial2Notes:"...Increases Strength and Perception by <%= attrs %> each."
  • weaponSpecialCriticalNotes:"...Increases Strength and Perception by <%= attrs %> each."
  • weaponSpecialTaskwoodsLanternNotes:"...Increases Perception and Intelligence by <%= attrs %> each."

情况四:双属性、加成数值不同

写法为:

Increases (Strength/Intelligence/Constitution) by (<%= str %>/<%= int %>/<%= con %>) and (Intelligence/Constitution/Perception) by (<%= int %>/<%= con %>/<%= per %>).

两个属性分别携带各自的数值变量。原文档此条末尾存在一处多余的 ] 符号,属于笔误,实际意图即上述句式。实例(来自 gear.json 第 14 行附近的武器描述):

  • weaponWizard1Notes:"...Increases Intelligence by <%= int %> and Perception by <%= per %>."(Wooden Staff,INT 与 PER 数值不同)
  • weaponWizard2Notes 至 weaponWizard6Notes 均沿用同一模板。

Event/Origin 出处措辞:两种标准说法

当装备具有特殊来源时,在描述末尾附加出处说明。指南给出两种标准措辞:

订阅物品(Subscriber Item)

[Month] [Year] Subscriber Item.

例如:"November 2014 Subscriber Item."。实例见 gear.json 的订阅奖励条目:

  • weaponMystery201411Notes:"...Confers no benefit. November 2014 Subscriber Item."
  • weaponMystery201611Notes:"...Confers no benefit. November 2016 Subscriber Item."
  • weaponMystery202212Notes:"...Confers no benefit. December 2022 Subscriber Item."

可见订阅装备按月标注,格式固定为"月份 + 年份 + Subscriber Item"。

限定版季节装备(Limited Edition Seasonal Gear)

Limited Edition [Year] [Season] Gear.

例如:"Limited Edition 2014 Spring Gear."。实例(同文件中的季节活动装备):

  • weaponSpecialWinter2015WarriorNotes:"...Limited Edition 2014-2015 Winter Gear."
  • weaponSpecialSummerRogueNotes:"...Limited Edition 2014 Summer Gear."
  • weaponSpecialFallMageNotes:"...Limited Edition 2014 Fall Gear."

跨年冬季装备采用"2014-2015"这样的区间年份写法,夏季、春季、秋季则直接标注单一年份。

模板变量如何渲染:从 gear.json 到界面文本

gear.json 中的 <%= str %>、<%= int %>、<%= con %>、<%= per %>、<%= attrs %> 并非静态文本,而是国际化模板占位符。它们的渲染链路如下:

  1. 装备数据定义在 content/gear 各文件中,例如 armoire.js 中 lunarArmor 定义 str: 7, int: 7,并调用 t('armorArmoireLunarArmorNotes', { str: 7, int: 7 }) 传入数值;
  2. 翻译函数 translation.js 将字符串与变量打包为一个接收语言参数的函数,最终调用 i18n.js 中的 t();
  3. 模板渲染在 i18n.js 中通过 micromustache 的 render(template, vars, { tags: ['<%= ', '%>'] }) 完成:hrender 显式指定 <%= 与 %> 作为插值标签,恰好匹配 gear.json 中所有占位符的书写形式。若模板渲染失败,会兜底返回"Please see Help > Report a Bug"提示。

因此,写作装备描述时只需在翻译文件中使用 <%= 变量名 %> 占位符,实际数值由装备数据文件在运行时注入,文案与数值得以解耦。

源码层面的自动生成逻辑

除手工撰写外,部分装备的描述由源码自动生成,理解这些逻辑有助于把握规范的实际落地。

属性默认值与扁平化

gear/index.js 的 populateGear 为每个装备项补全 type、key、set、klass、index,并将 str/int/per/con 默认置为 0。这意味着未显式声明属性的装备(如 "Confers no benefit" 的新手装备)天然获得四项零值,无需在数据中重复书写。

魔幻衣橱(Armoire)装备的自动描述

armoire.js 遍历所有 Armoire 装备,按属性数量自动选择模板变量:

  • 若装备只有一项属性,或有多项属性但数值不同,则传入具体属性对象 gearStats(对应"单属性"或"双属性不同数值"句式);
  • 若装备有多项属性且数值完全相同,则传入 { attrs: gearStatValues[0] }(对应"双属性/多属性相同数值"句式,即 <%= attrs %> each)。

这一逻辑与风格指南中 attrs 的用法完全吻合:只有多个属性加成数值一致时才使用 <%= attrs %>。

季节活动装备的自动填充

special/index.js 的 fillSpecialGear 根据键名是否包含 spring/summer/fall/winter 识别季节装备,自动生成 text、notes、value、season 等字段,并按职业(warrior/rogue/wizard/healer)填充各自属性数值。这就是 gear.json 中 weaponSpecialSpringWarriorNotes 等条目名称的由来,也解释了"Limited Edition [Year] [Season] Gear"这类出处文案为何在数据定义中无需手工书写。

与描述规范相关的周边机制

classBonus(职业加成)

装备描述只反映基础数值,但实际游戏中同职业装备另有 1.5 倍属性乘算。相关文案定义在 gear.json 的 classBonus:"(This item matches your class, so it gets an additional 1.5 Stat multiplier.)"。前端在 mixins/stats.js 中通过 getClassBonus 计算该加成,并在 stats.vue 中展示。写作装备描述时无需也不应把 1.5 倍写进数值,它由系统自动结算。

双手武器与 RTL 语言

weapon.js 为所有双手武器(如 wizard 的双手法杖)追加 twoHandedItem 提示,并对阿拉伯语、希伯来语等 RTL(从右到左)语言做特殊文案处理。这说明描述规范不仅约束英文文本,也需在数据层面适配多语言展示。

给贡献者的实战清单

在新增或修改装备描述时,可按以下清单自检:

  1. 顺序:描述 → 属性效果 → 出处(如需),三段缺一不可、次序不可颠倒;
  2. 无加成:使用 "Confers no benefit.",不要自创措辞;
  3. 单属性/全属性:使用 <%= str %>、<%= int %>、<%= con %>、<%= per %> 或全属性 <%= attrs %>;
  4. 双属性同数值:使用 "Increases A and B by <%= attrs %> each.";
  5. 双属性不同数值:分别列出两个属性各自的占位符;
  6. 出处:订阅物品写 [Month] [Year] Subscriber Item.,季节限定写 Limited Edition [Year] [Season] Gear.;
  7. 占位符语法:确保使用 <%= 变量 %>(与 i18n.js 的渲染标签一致),并在装备数据文件中为对应属性传入真实数值;
  8. 复用自动生成逻辑:若装备属于 Armoire 或季节活动体系,优先利用 armoire.js 与 special/index.js 的自动填充,避免手工拼写不一致的文案。

遵循上述规范,即可保证装备描述在 Habitica 全仓库范围内(gear.json 及各语言副本)保持统一的风格、结构与国际化兼容性。

登录后查看全文
habitica