同志是制作第三方工具的Habitica用户。第三方工具包括但不限于：基于网络的工具、应用、浏览器扩展、任何使用Habitica API的代码、CSS模板等等。如果你想制作这样的工具，务必先通读全文；文中列出的链接也会为你提供很多有用的资源。成为同志也是对Habitica做出贡献的一种方式。
成为一名同志[]
首先，欢迎你加入Habitica的大家庭！Habitica是一个开源项目，热烈欢迎任何社区用户在现有的基础体验之上施展才华。为了你的制作进展顺利，也为了在官方应用和非官方应用之间画出明确的界线，我们设立了以下这些准则。
务必在开始制作工具前先通读全文，这样以后你就不用再修修改改了。此外，最好先看看扩展和插件页面有没有类似的工具再动手。应用程序接口页面会指导你如何使用API。
你可以加入Aspiring Comrades公会。在这里，你可以分享成果、获取反馈，和其他贡献者一同讨论想法，还可以找人帮忙测试你的工具。
你可能会需要参考GitHub仓库中Habitica各平台的代码，或使用其中的资源文件：
寻求帮助[]
关于使用Habitica API的问题，如果应用程序接口页面中没有解答，可以到Aspiring Comrades公会中提问。为了方便他人帮助，请附上你使用的仓库（如GitHub）中源代码的分享链接。
关于Habitica网站的CSS，以及使用浏览器扩展（如Stylus）编写用户样式对其进行修改调整的问题，可以到Aspiring Tailors公会中提问。
至于一般性的编程问题，Habitica中有很多关于编程和编程语言的公会。
第三方工具规定
本章节的规定由Habitica工作人员共同制定，涵盖了工具命名、图标、配色、服务器调用等方面，以确保你的工具能良好运行，同时保证官方应用和非官方应用之间的界线明确。
所有的第三方工具（样式、自定义、扩展、应用等等）都必须遵循命名、图标和配色、将工具告知工作人员这三个章节的规定。此外，使用Habitica API的工具还必须遵守API调用章节的所有下属规定。
命名[]
要想让潜在用户了解你的应用或扩展的确切功能，起一个好名字相当重要。我们建议命名越清晰越好，这样才能充分传达出你的工具的用途和价值。
命名在引用Habitica时，要避免改动“Habitica”这一名称。在项目名称中使用“Habitica”一词的各种变形，可能会使用户感到混乱而困惑，导致用户更难找到你的应用，因为这样搜索引擎可能会将你的项目名称当作拼写错误处理。请尽量使用类似“Habitica聊天扩展”和“Habitica皮肤”这样的名称。
严禁在你的工具的名称和介绍中滥用“官方”一词。
建议你选一个和所有已有工具都不同的名称。相似的名称并非不能接受，但是独特的名称才能最好地避免混淆和困惑。
图标和配色[]
Habitica的官方调色板及十六进制色码（Hex color code）。同志可以任意使用紫色以外的其他配色。
为自己的工具设计logo、图标和选择配色时，很重要的一点是，一定要和Habitica本身的logo和主要配色有足够的差异。这是为了方便区分Habitica官方支持的应用和第三方应用，也能让用户清楚如果遇到bug时，应该向谁反馈漏洞。
右侧图片展示了Habitica官方的调色板，你可以随意使用其中的绝大多数配色，当然这也包括其中未列出的配色。但有一个例外——在使用其中标记为紫色（purple）和相近紫色色调的配色时，请加以限制。你可以在工具中小范围地使用这些紫色，但不能作为主要配色，也不能在logo、图标和标题中全用这些紫色。
如果你想给自己的应用、扩展或工具设计图标，避免使用Habitica的狮鹫logo（“Melior”）及任何类似或修改过的logo。
Habitica的工作人员提供了使用Habitica调色板和Habitica界面中常见图标制作的一系列iOS、Android和通用图标的模型（mock-up），任何人都可以免费使用。下方的图片提供了预览。使用黑白单色，或者自己混合搭配，创造出你自己独有的调色板吧！祝玩得开心！
API调用[]
此章节对于使用Habitica API的工具至关重要。如果你的工具并没有使用API，可以忽略此章节。
第三方应用调用API的频率会极大地影响所有Habitica用户的使用体验，即使用户并没有使用第三方应用，同样会受到影响！应用在两次调用之间没有停顿、过于频繁地调用服务器，很可能导致服务器的大面积故障。因此，我们总结了以下规定，以确保你的应用不会造成这方面的问题。
API调用规定[]
此章节对于使用Habitica API的工具至关重要。如果你的工具并没有使用API，可以忽略此章节。
- 请勿在无限循环内调用API。不允许在单次调用后立即无休止地重复调用。
- API调用需要用到Habitica数据时，如果操作确实无法完成，应当添加限制条件停止下次自动请求。举个例子，自动购买物品时用完了金币、自动施放技能时没有足够的魔法值，这时就应停止调用。
- 后台运行（不需要用户干预）的自动脚本，例如在魔法值充足时自动施放技能，两次调用之间应停顿30秒，尤其是写入和修改数据的POST请求和PUT请求。GET请求可以稍微频繁一些，但两次调用间仍需有几秒钟的停顿。考虑到API调用是自动而持久的，因此，两次调用间的停顿时长，不应少于玩家手动操作调用API时的间隔时长。这样才能防止过多玩家运行自动脚本，导致大量API调用同时进行造成故障。
- 如果你的第三方应用需要更频繁地调用API，或者你预计应用将有大量用户，请提前通过电子邮件admin@habitica.com和我们取得联系。
- 如下文所述，所有API调用都应包括“X-Client”标头。
- 如果你的工具除了自己之外，还有其他用户使用，则必须公开工具的全部代码。我们推荐托管在诸如GitHub的公共平台。
X-Client标头[]
此章节对于使用Habitica API的工具至关重要。如果你的工具并没有使用API，可以忽略此章节。
所有第三方应用或扩展的API请求都应包括“X-Client”的HTTP标头（header），内容为扩展名称加上作者的Habitica用户ID，格式为“用户ID-应用名称”。注意，这里的用户ID应当属于制作工具的作者，而非使用者！下方给出了一个范例。将你的用户ID写在工具中并没有风险，因为用户ID基本上和用户名一样，都是公开的身份标识（但绝不能将API令牌写在工具中，因为API令牌相当于账户密码）。
如果出现问题，Habitica工作人员需要排查故障时，X-Client标头将有助于工作人员辨别请求的来源、判断你的应用或扩展是否存在问题，这样他们就可以联系到你，然后帮助你修改工具、解决问题。
例如，用户ID为“12345678-90ab-416b-cdef-1234567890ab”的玩家开发了名为“我的Habitica应用”的应用，则可以按下方范例JavaScript代码的方式设定X-Client标头。X-Client标头并不需要因为使用者不同而修改，其值恒为工具作者的用户ID。
const AUTHOR_ID = '12345678-90ab-416b-cdef-1234567890ab';
const SCRIPT_NAME = 'One Spell to Rule Them All';
const HEADERS = {
'x-client' : AUTHOR_ID + ' - ' + SCRIPT_NAME,
'x-api-user' : 12345678-90ab-416b-cdef-1234567890ab,
'x-api-key' : 7fbfafe4-e60c-4486-960f-f8e49daa5001, // 编造的API令牌。绝不能和别人分享API令牌！
};
const params = {
'method' : 'POST',
'headers' : HEADERS,
'contentType' : 'application/json',
};
速率限制[]
为保证Habitica运行稳定、避免故障，所有第三方工具的API请求都会受到速率限制（rate limit，也有译作频次限制）。这么做的目的在于，即使某个第三方工具突然短时间内发送大量请求，也不会导致Habitica服务器性能下降甚至故障。Habitica工作人员设定的速率限制经过仔细的考虑，既不会影响大多数第三方工具的运行，也能允许在特定情况下短时间内小规模的大量突发请求。自2020年7月20日起，速率限制开始生效。
具体的速率限制为：每个用户的每个第三方工具，60秒内最多能发送30次请求（从第一次请求发送时开始算起）。对于不需要身份验证的那一小部分API请求，同样存在速率限制，只不过针对的是发送请求的特定IP地址。
API的所有响应都包括以下HTTP标头：
X-RateLimit-Limit：60秒内最多能发送的请求次数（总是30）X-RateLimit-Remaining：当前请求所在60秒时间段内剩余的请求次数X-RateLimit-Reset：当前请求所在60秒时间段结束的时刻
如果超出60秒内30次的限制，此用户ID或此IP地址后续发送的请求将会收到429 Too Many Requests（429 请求过多）的HTTP错误，响应中会额外加上一个HTTP标头：Retry-After，表示在下次可以发送请求前需要等待的秒数。
对于需要获取公会/挑战成员的工具，为缓解速率限制造成的卡顿，这类工具可以在获取挑战成员（Get members for a challenge）或获取队伍成员（Get members for a group）时加上limit的查询参数（query parameter）。这一参数可以使每次请求返回的成员数目提高到60个，而不是默认的30个。2020年7月起，limit参数被标记为BETA功能，但Habitica工作人员决定，除非出现意料之外的问题，否则暂时不会移除这一功能。
储存用户ID和API令牌[]
如果你创建了自己的数据库或类似的数据储存空间，用于储存其他用户的API令牌，让所有用户清楚地知道这一点至关重要。在工具主页和所有的介绍文档中，必须在显眼的地方明确指出，你的工具将会长期储存用户的用户ID和API令牌。API令牌就像密码一样，储存他人的API令牌就意味着，你有能力像使用自己账号那样，随意使用他人账号。因此，务必让用户在使用工具前，清楚这一点并谨慎决定。
这样的警示也应当写在工具的维基页面中。
获取内容、介绍和图片[]
如果你希望展示宠物、背景、装备等的名称、介绍之类的信息，可以通过API调用获取内容（Content）。值得注意的是，这一调用有一个语言选项的参数，可以返回英语外的其他语言的内容。获取的内容直接来源于Habitica本身。
Habitica的图片可以获取自https://habitica-assets.s3.amazonaws.com/mobileApp/images/。
完整的网址由以下几部分构成：
- 上方的网址：
https://habitica-assets.s3.amazonaws.com/mobileApp/images/ - 要获取的图片类型的前缀。图片名称的具体列表参见 https://github.com/HabitRPG/habitica/tree/develop/website/raw_sprites/spritesmith
- 要获取的物品的键（key）
- .png扩展名
例如，要显示幼熊宠物蛋的图片，网址应当是：
https://habitica-assets.s3.amazonaws.com/mobileApp/images/Pet_Egg_BearCub.png
其中各组成部分是：
https://habitica-assets.s3.amazonaws.com/mobileApp/images/- Pet_Egg_
- BearCub
- .png
再举个例子，幼熊宠物的图片网址是：
https://habitica-assets.s3.amazonaws.com/mobileApp/images/Pet-BearCub-Base.png
记住，除特殊宠物外的所有宠物，之后应加上颜色，因此这里物品的键应当是BearCub-Base。
职业名称（使用mage而非wizard）[]
获取的内容中并未使用目前的职业名称。内容提供的索引只有键，因此你需要根据键当中的职业名称进行硬编码。目前唯一存在差异的是法师（mage）。在内容的键中，法师的英文是wizard，但在游戏中实际名称是mage。
当前GitHub上有一个已打开的议题提供了详细信息。
2019年Kickbacker图片[]
目前这些图片并没有符合命名规范，因此需要手动硬编码。这些图片的键和名称是：
| 内容中的键 | 图片名称 |
|---|---|
| armor_special_ks2019 | BackerOnly-Equip-MythicGryphonArmor.gif |
| eyewear_special_ks2019 | BackerOnly-Equip-MythicGryphonVisor.gif |
| head_special_ks2019 | BackerOnly-Equip-MythicGryphonHelm.gif |
| armor_special_ks2019 | BackerOnly-Equip-MythicGryphonArmor.gif |
| shield_special_ks2019 | BackerOnly-Equip-MythicGryphonShield.gif |
| weapon_special_ks2019 | BackerOnly-Equip-MythicGryphonGlaive.gif |
将工具告知工作人员[]
当你已经准备好运行你的代码时，请填写Habitica第三方应用提交表单，填入你的应用、扩展或工具的相关信息——无论是个人使用还是公开发布。这有助于Habitica工作人员关注新出现的第三方工具，使你的贡献为他们所知，如果将来出了什么问题，也能让他们及时联系到你。提交表单后，你并不会收到回复；只有在发现你的工具出了什么问题时，Habitica的工作人员才会联系你。
一旦工具可以运行，就应当及时提交表单，这一点很重要。即使你打算持续开发工具，也应先提交表单，因为工具在开发阶段中，可能会对Habitica的服务器造成影响。
创建维基页面[]
一旦你的工具能良好运行，就可以开始着手编写介绍工具的维基页面，将页面添加到扩展和插件中了。这样，Habitica用户就能轻松找到你的工具。如果你不太想自己编写，也可以把你的工具链接发到Wizards of the Wiki公会中。这样，抄写员就能帮你编写维基页面。
创建维基页面时，请使用Template:Infobox software这一模板，确保信息的格式整齐、明确。
注意，在创建维基页面前，请确保你的工具遵守了上方“第三方工具规定”章节中的所有相关规定。如果某一工具需要调整以遵守规定，Habitica工作人员可能会临时移除这一工具的维基页面。如果对规定落实的哪方面有疑惑，可以在Aspiring Comrades公会中提问！
申请贡献者等级[]
要申请贡献者等级：
- 检查你的工具是否符合上方“第三方工具规定”章节中的所有相关规定，包括“将工具告知工作人员”子章节。
- 如果工具将要公开发布，在Aspiring Comrades公会中发布以下链接：
- 工具
- 工具的源代码（若工具使用了Habitica API）
- 工具介绍文档（若有）
- 工具的维基页面（若有）
其他同志便能够据此给出反馈，帮助你修改工具。你不一定要完全接受他人的建议，但考虑一下总是值得的。
这时，你就可以发送邮件到admin@habitica.com了，邮件主题应为“Comrade Tier Requested”（申请同志头衔）。这能确保邮件分给负责评定的人来处理。邮件应当包括以下内容：
- 开始开发时将工具告知工作人员的证明
- 你的用户ID和用户名
- 工具名称
- 源代码的链接
- 工具介绍文档（若有）
- 工具维基页面（若有）
尽管在写邮件时附上说明和讨论可以接受，但如果工作人员要求你修改工具的代码或外观，建议还是在评定头衔之前做出修改。
工作人员经过谨慎决定，将工具是否适用于Habitica广大用户、是否提升了Habitica的使用体验、是否顺应社区倡导价值等等方面纳入考量，才会授予贡献者头衔。
一旦得到工作人员的肯定，你就能得到贡献积分，或是直接获得头衔。记住，越高的头衔等级，越需要更多的付出。因此，如果你已经有了高于1级的头衔，有可能只能获得贡献积分。
另见[]
- 应用程序接口
- 扩展和插件
- Pro Git Book——学习如何使用Git和GitHub仓库的优秀指南。
- Hello World Tutorial——使用GitHub的快速上手指南。