In conjunction with this, the Comrade contributor path also ceased to exist. Tiers will no longer be awarded for Comrade activities.
This page intentionally contains outdated links to one or more guilds on Habitica. Guilds and the Tavern were removed from Habitica on August 8, 2023 and these links will no longer work.
The reason provided for keeping these links was: Links have been left in place for historical reference.
Comrades are Habiticans who create third-party tools. This includes but is not limited to: web-based tools, apps, browser extensions, any code that uses Habitica's API, and CSS templates. If you would like to create such tools, it is important to read all of this page. The other resources that it links to will also be of use to you. Being a Comrade is one way of Contributing to Habitica.
Becoming a Comrade[]
First of all, welcome to the Habitica family! As an open source project, Habitica fully welcomes anyone in our community who wants to offer their skills to build upon the Habitica experience. To help your creation roll out smoothly and to keep the divide between official and unofficial apps clear to our players, we've put together these guidelines.
Please read this whole page before starting work on your tool to ensure that you don't need to change it later. You may also want to check that a similar tool has not already been created at the Extensions, Add-Ons, and Customizations page. The Application Programming Interface page will teach you how to use the API.
You can join the Aspiring Comrades guild to share your work, get feedback, discuss ideas with fellow contributors, and get your tool tested by other players.
Our GitHub repositories for each platform can be used to check out our code and pull any assets you may need from them:
Seeking Assistance[]
For questions about using Habitica's API that are not answered in Application Programming Interface, feel free to ask in the Aspiring Comrades guild. To ensure easy assistance, post a link to your raw code from your preferred repository (e.g., GitHub).
For questions regarding the Habitica website's CSS and modifying it with user styles using browser extensions like Stylus, ask in the Aspiring Tailors guild.
For general programming questions, there are many guilds in Habitica about Programming and Programming Languages.
Rules for Third-Party Tools
The rules in this section about tool names, icons, colors, and server calls have been put together by Habitica's staff to ensure that your creation runs well and to keep the divide between official and unofficial apps clear to all Habiticans.
All third-party tools (styles, customizations, extensions, apps, etc) must follow the "Naming", "Iconography and Colors", and "Notifying Staff about your Tool" sections. Tools that use Habitica's API must also follow the "API Server Calls" section including all of its subsections.
Naming[]
Choosing the right name can be very important for communicating to potential users exactly what your app or extension does. We recommend being as explicit as possible to communicate the value and use of your creation.
When referencing Habitica itself, avoid altering the name of the product. Using a variation of "Habitica" for your name can confuse users and prevent them from finding your app as search engines may think it's a typo. Try names like "Habitica Chat Extension" or "Skin for Habitica".
Do not use the word "official" in your tool's name or description.
It's recommended that you choose a name different from all other known tools. Similar names are acceptable but identical ones are best avoided to prevent confusion.
Iconography and Colors[]
Habitica's official color palette, including hex color codes. Comrades are welcome to use any except the Purple colors.
When choosing logos, icons, and colors for your tool, it's important that they are sufficiently dissimilar from Habitica's own primary colors and logo. This is to help differentiate the official apps that Habitica supports from third-party supported apps. This will also help bug reports go to the correct person, should any pop up.
Habitica's official color palette is displayed in the image to the right. You can use any color from it or any colors not listed in it. However please limit your use of the several colors labelled as purple or other purple shades that are similar to them. You can use those purples to a small degree in your tool but not as one of your primary colors and not at all in your tool's logos, icons, or header.
If your app, extension, or contribution needs an icon, avoid using the Habitica's gryphon logo ("Melior") or logos that are similar to it or modifications of it.
Habitica's staff have provided a set of iOS, Android, and generic icon mock-ups that use Habitica's palette and various icons from Habitica's user interface. Anyone is free to use them. For a preview, see the image below. Go monochrome or mix and match to create a palette unique to you! Have fun!
API Server Calls[]
This section is essential for any tool that uses Habitica's API. It is not relevant if your tool does not use the API.
The number of server calls that a third-party app makes can drastically impact the user experience of all Habitica users, regardless of whether or not they use that particular third-party app! An app that has no delay between calls or that calls the server too frequently can quickly cause major server outages. We've included some general rules here that should help make sure your app has no problems.
Rules for API Calls[]
This section is essential for any tool that uses Habitica's API. It is not relevant if your tool does not use the API.
- Don't allow your app to run an infinite loop of API calls where one call is immediately followed by the same one again indefinitely.
- When API calls require some data in Habitica, add a condition that stops automatic calls if the action can no longer be completed. For example, running out of Gold when automatically buying items should make the calls stop, or not having enough Mana when automating Skills.
- For automated scripts that run in the background (no user intervention needed) like one that automatically casts Skills until your Mana is depleted, we ask you to keep a delay of 30s between different calls, in particular POST and PUT calls that write or update data. GET calls can be made more often if needed but still with a few seconds of delay between them. Since the API calls are being made automatically and consistently, we're asking for a longer delay than a player may be able to manually initiate through acting. This is to prevent any compounding problems of too many players letting the automatic calls run.
- If your third-party app requires you to make calls more often or if you expect many players to use your tool please contact us in advance at [email protected].
- All API calls must include an "X-Client" Header as described below.
- If your tool will be used by anyone apart from yourself, all of its code must be reviewable. We recommend placing it in a public repository such as GitHub.
X-Client Header[]
This section is essential for any tool that uses Habitica's API. It is not relevant if your tool does not use the API.
We require all third-party apps or extensions to include an "X-Client" HTTP header with every API request. The content of the header should be the name of the extension and the creator's Habitica User ID in the format "UserID-appname". Note that this is the User ID of the person who wrote the tool, not the player who is using it! An example is given below. Placing your own User ID in your tool is not a security risk for you as your User ID is a public identifier in the same way that your Username is (however you should never write your API Token in your tool as it is like a password).
If something does go wrong and Habitica staff need to troubleshoot the source, the X-Client header will help them identify requests and let them know if it is or isn't your app or extension causing the problem. They will then contact you to help you adjust your tool so that it runs without problems.
As an example, if a player with the User ID "12345678-90ab-416b-cdef-1234567890ab" writes an app called "My Habitica App", they could specify the X-Client header as shown in the sample JavaScript code below. The User ID in the X-Client header would not change depending on which player was using the tool; it is always the User ID of the author of the tool.
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, // not a real API key; you should NEVER share this!
};
const params = {
'method' : 'POST',
'headers' : HEADERS,
'contentType' : 'application/json',
};
Rate Limiting[]
To improve the stability of Habitica and to avoid outages, there is a rate limiting mechanism for all API requests from third-party tools. The aim is to ensure that a surge in requests from a third-party tool won't result in degraded server performance or outages for the Habitica userbase. Habitica's staff have taken care to choose limits that should not impact most third-party tools and that will allow small bursts of requests when necessary. Rate limiting started on July 20, 2020.
The limit allows 30 requests every 60 seconds (counting from when the first request is made) for each user from third-party tools. The few API requests that do not require authentication have the same limits applied to each IP address from which they're originating.
All responses from the API include these HTTP headers:
X-RateLimit-Limit: the total amount of requests that can be made in a 60 second period (will always be 30)X-RateLimit-Remaining: the number of remaining requests that can be made in the current 60 second periodX-RateLimit-Reset: when the current 60 second period will end
If the limit of 30 requests in a 60 second period is exceeded, subsequent requests made using the same User ID for authentication or the same IP address will return a 429 Too Many Requests HTTP error and an extra HTTP header will be added to the response, Retry-After, indicating how many seconds to wait before making a new request.
To mitigate the slowness that rate limiting causes for tools that fetch Guild or Challenge members, the tools can optionally use the limit query parameter with the Get members for a challenge and Get members for a group routes. It can be used to specify that up to 60 members should be returned with each request, instead of the default 30. As of July 2020 the limit parameter is marked as BETA but Habitica's staff do not plan to remove it unless an unforeseen issue occurs.
Storing Players' User Ids and API Tokens[]
If you create your own database or other data store that contains other players' API Tokens, it's essential that you make it very clear that you are doing this. Make it obvious on the tool's front page and in any documentation about the tool that the tool stores User IDs and API Tokens permanently. API Tokens are like passwords and having your own store of them means that you would be able to use anyone's account as if it were your own so it's important that people can make an informed decision about whether to allow this.
This information should be also noted on the wiki page created for the tool.
Fetching Content Descriptions and Images[]
If you wish to display names, description and other information regarding, pets, backgrounds, equipment etc. This information can be source from the API Call Content. Please note it has an language option which allows you to display the text in another language other than English. This is source directly from the app itself.
Images for the product can be sourced https://habitica-assets.s3.amazonaws.com/mobileApp/images/.
The complete url is made up of few components.
- The url from above:
https://habitica-assets.s3.amazonaws.com/mobileApp/images/ - Prefix indicating the type of image you are after. For a complete list review the image names in https://github.com/HabitRPG/habitica/tree/develop/website/raw_sprites/spritesmith
- The Key for the item you're after
- The suffix of .png.
For example, to show Pet Egg for the Bear, the url will be:
https://habitica-assets.s3.amazonaws.com/mobileApp/images/Pet_Egg_BearCub.png
Where each item is
https://habitica-assets.s3.amazonaws.com/mobileApp/images/- Pet_Egg_
- BearCub
- .png
For example the actual Pet for Base Bear will be
https://habitica-assets.s3.amazonaws.com/mobileApp/images/Pet-BearCub-Base.png
Remember the key will be BearCub-Base as all pets except special always have colour associated with them.
Class Name (State Mage Instead of Wizard)[]
Currently classes are not stated in the Content pull. Only the keys are available, so you will need to hard-code the class names from the key, currently the only one different is mage. The current key is wizard throughout the content, when the name is actually mage.
There is currently an open issue on GitHub for more information.
2019 Kickbacker images[]
Currently the images do not follow the naming convention and require to be hard-coded. The key and the image names are as:
| Content Key | Image name |
|---|---|
| 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 |
Notifying Staff About Your Tool[]
As soon as your code is ready to be used by you, please fill out the Habitica 3rd Party Application Submission form with the relevant information about your app, extension, or tool--including whether it is for personal use only or intended for public release. This will help Habitica's Staff keep track of new third party tools, alert them about your contribution, and let them know how to reach out to you if anything goes wrong in the future. You will not receive a reply when you submit the form; Habitica's Staff will contact you only if they see that something has gone wrong with your tool.
It is important to do this as soon as the tool is able to be run by you, even if you are planning to do more work on it because the development stage of a tool is one of the times when it may cause problems on Habitica's server.
Creating a Wiki Page[]
Once your tool is running well, a wiki page can be created for it and linked to from Extensions, Add-Ons, and Customizations. This lets Habiticans find your tool easily. If you feel uncomfortable creating your own wiki page, then you can link your creation in the Wizards of the Wiki guild. There, the scribes will be able to create a page for you.
When creating the wiki page, please use the Template:Infobox software template to ensure information is formatted and specified correctly.
Please note that your tool should follow all relevant advice in the "Rules for Third-Party Tools" section above before the wiki page is created. Habitica's staff might temporarily remove the wiki page for any tool that needs adjustments to comply with that advice. Ask in the Aspiring Comrades guild if you need help implementing the rules!
Contributor Tier Process[]
To request a Comrade contributor tier:
- Check that your tool follows all relevant guidance in the "Rules for Third-Party Tools" section above, including the "Notifying Staff about your Tool" subsection.
- If your tool is for public use, post to the Aspiring Comrades guild with links to:
- the tool
- the tool's full source code if it uses Habitica's API
- documentation for the tool, if any
- the tool's wiki page if one has already been created
Other Comrades might give feedback and help you tweak your tool. It's not essential for you to follow their advice but you might like to consider it.
At this point, you should send an email to [email protected] with the subject line "Comrade Tier Requested". This is to ensure that it is flagged for the correct person for evaluation. You must include the following:
- An affirmation that you notified the staff about your tool when you began development
- Your UUID and username
- The name of your tool
- A link to the source code
- A link to any documentation that exists
- A link to the wiki page, if one has already been created
If a staff member asks you to make changes to the tool's code or appearance, it will likely be necessary for those changes to be made before a tier will be considered, although discussion and clarification via email is always welcome.
Tiers are awarded at the discretion of the staff and take into consideration the applicability of the tool to Habitica's wider userbase and whether the tool improves the Habitica experience in a spirit consistent with the values of the community.
Once approved by staff, you will be given a tier or credit towards a tier. Keep in mind that higher tiers require more work, so partial credit is more likely to be given if you have more than one tier already.
See Also[]
- Application Programming Interface
- Extensions, Add-Ons, and Customizations
- Pro Git Book - A great guide to learning how to use Git and GitHub repositories.
- Hello World Tutorial - A quick guide to using GitHub.