FANDOM


Coding 3 by phoneix faerie-d7idtti
Comrades are Habitica contributors who create third-party tools. This includes but is not limited to: web-based tools, apps, browser extensions, and CSS templates.

Becoming a ComradeEdit

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.

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:

Asking for AssistanceEdit

For questions about using Habitica's API and writing code with it, first see Application Programming Interface which has a lot of useful tips then 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 Program 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.

NamingEdit

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 ColorsEdit

Color palette official

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!

Icon mockups for Comrades

API Server CallsEdit

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 CallsEdit

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 admin@habitica.com.
  • 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 HeaderEdit

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 jQuery Ajax 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.
$.ajax({
  url: 'https://habitica.com/api/v3/user',
  type: 'GET',
  dataType: 'json',
  cache: false,
  beforeSend: function(xhr){
    xhr.setRequestHeader('x-client', '12345678-90ab-416b-cdef-1234567890ab-MyHabiticaApp');
    xhr.setRequestHeader('x-api-user', playerUserID);
    xhr.setRequestHeader('x-api-key',  playerAPItoken);
  },
  success: yourFunctionToProcessTheData,
  error: yourFunctionToReportAnError,
});

Notifying Staff about your ToolEdit

When you're all done and ready for your tool to go live, please fill out the Habitica 3rd Party Application Submission form with the relevant information about your app, extension, or tool. 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.

Creating a Wiki PageEdit

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 ProcessEdit

To gain a Comrade contributor tier:

  • Check that your tool follows all relevant advice in the "Rules for Third-Party Tools" section above, including the "Notifying Staff about your Tool" subsection.
  • 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. If staff or moderators ask you to make changes to the tool's code or appearance, it will probably be necessary for those changes to be made before a tier can be awarded although you are welcome to discuss their requests if you wish.

Once approved by an admin, you will be given a tier or credit towards your next tier if you already have tiers. Keep in mind that higher tiers require more work.

If you have posted about your tool to the Aspiring Comrades guild and have not had any response from staff or mods after two weeks have passed, please post a reminder there.

See AlsoEdit

Community content is available under CC-BY-SA unless otherwise noted.