Template:Third Party Tool Rules

This content has been written by staff and we want to keep a close watch on how it's edited so it's being placed in a template which will then be placed in a larger page. Staff can then ignore changes to the page but watch this template.

Habitica Third-Party Developer Guidelines
First of all, welcome to the Habitica family! As an open source project, we fully welcome 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.

Where to start
To begin, we recommend reading the Guidance for Comrades Habitica wiki page dedicated to helpful instructions for our third-party developers who we refer to as "Comrades". It has a lot of initial information that can help you on your way. You can also join the Habitica Guild Aspiring Comrades to share your work, get feedback, and discuss ideas with fellow contributors.

Here are links to our various Github repositories for each platform. You can check out our code here and pull any assets you may need from them.

[https://github.com/HabitRPG/habitica Habitica Github Habitica Android Github Habitica iOS Github

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 searches may think it's a typo. Try names like "Habitica Chat Extension" or "Skin for Habitica". It's recommended that you choose a name different from the existing [[Extensions XXX

Iconography and Colors
{XXX add image} If your app, extension, or contribution needs an icon, avoid using the Habitica logo or the {XXX official?} color purple. 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.

{XXX Can other colours be used too?} You can use any color (except for purple) from our official color palette, found in the image to the right, to create your own app icon if you'd like to bring some Habitica flair to it. When making your own icon, make sure it's easily differentiated at a glance from the official app icons.

{XXX add thumbnail of muckups and link} We've provided a set of iOS, Android, and generic icon mockups that use our palette and various icons from Habitica's UI that anyone is free to use. Go monochrome or mix and match to create a palette unique to you! Have fun.

Server Calls
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

 * 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 would 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 user may be able to manually initiate through acting. This is to prevent any compounding problems of too many users letting the automatic calls run.
 * If your third-party app requires you to make calls more often or if you expect many users to use your tool please contact us in advance via our admin email.
 * Include an X-Client Header as described below.

X-Client Header
We require all third-party apps or extensions to include an "X-Client" HTTP header with your API requests. The content of the header should be the name of the extension and creator Habitica Username in the format "username-appname". {For example, XXX ...}

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 extension so that it runs without problems.