Habitica 装备描述文案规范:gear_README.md 风格指南深度解读与源码实现
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 中数千行实际条目一一对应。
元素顺序:描述 → 属性效果 → 出处
指南规定的装备描述结构固定为三段式:
- Description(描述):用一句有画面感的文字描述装备的外观或来历;
- Stat Effect(属性效果):说明装备提供的属性加成,遵循固定的句式模板;
- 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 %> 并非静态文本,而是国际化模板占位符。它们的渲染链路如下:
- 装备数据定义在 content/gear 各文件中,例如 armoire.js 中
lunarArmor定义str: 7, int: 7,并调用t('armorArmoireLunarArmorNotes', { str: 7, int: 7 })传入数值; - 翻译函数 translation.js 将字符串与变量打包为一个接收语言参数的函数,最终调用 i18n.js 中的
t(); - 模板渲染在 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(从右到左)语言做特殊文案处理。这说明描述规范不仅约束英文文本,也需在数据层面适配多语言展示。
给贡献者的实战清单
在新增或修改装备描述时,可按以下清单自检:
- 顺序:描述 → 属性效果 → 出处(如需),三段缺一不可、次序不可颠倒;
- 无加成:使用 "Confers no benefit.",不要自创措辞;
- 单属性/全属性:使用
<%= str %>、<%= int %>、<%= con %>、<%= per %>或全属性<%= attrs %>; - 双属性同数值:使用
"Increases A and B by <%= attrs %> each."; - 双属性不同数值:分别列出两个属性各自的占位符;
- 出处:订阅物品写
[Month] [Year] Subscriber Item.,季节限定写Limited Edition [Year] [Season] Gear.; - 占位符语法:确保使用
<%= 变量 %>(与 i18n.js 的渲染标签一致),并在装备数据文件中为对应属性传入真实数值; - 复用自动生成逻辑:若装备属于 Armoire 或季节活动体系,优先利用 armoire.js 与 special/index.js 的自动填充,避免手工拼写不一致的文案。
遵循上述规范,即可保证装备描述在 Habitica 全仓库范围内(gear.json 及各语言副本)保持统一的风格、结构与国际化兼容性。