Habitica: How it Works; How Beeminder's Integration Works

Akrasia
1

This post is a work-in-progress. I’m writing enough for now to explain a support issue that occurred recently but I’ll add more later.

Habitica (formerly HabitRPG) is a habit-building and productivity website/app with motivational features based on role-playing games (earn Gold and Experience by doing tasks; lose Health by avoiding tasks or doing bad habits). Beeminder’s Habitica integration gives further encouragement to keep working on your Habitica tasks. This post describes the main features of Habitica, focusing especially on details relevant to the integration.

Habitica has four types of tasks :

  • To-Dos: Once-off tasks. When you complete a To-Do it disappears from your active task list for good (although you can find it elsewhere and manually mark it incomplete if needed). You earn Gold and Experience when you complete a To-Do.
  • Dailies: Recurring tasks. When you complete each Daily, it’s gone for the day but the next morning Habitica will automatically reset it so you use can it again. You earn Gold and Experience when you complete a Daily. If you leave a Daily incomplete, you lose Health the next morning.
  • Habits: Good or bad “tasks” intended to be done on an irregular schedule or multiple times a day (drink water / drink alcohol; bite fingernails; go for a walk). Habits have plus and minus buttons (good versus bad actions) and when you click one of those buttons, the Habit remains visible so that you can click it again as often as needed. You earn Gold and Experience when you do a good Habit; you lose Health when you do a bad one.
  • Rewards: Items or actions that you pay Gold to use/do (“eat a chocolate”, “have a bubble bath”). They’re not necessarily tasks in the usual sense but in Habitica’s database and code they are handled just like the other three task types.

Beeminder’s Habitica integration tracks To-Dos and Dailies using Habitica’s API, which provides data about the user’s tasks (all four types) and how they have been used in recent days. Tracking To-Dos and Dailies is pretty simple because all the Beeminder goal needs to do is fetch your task list every so often to find out which of those task have been marked complete. In Habitica’s database, those two task types have a completed attribute that’s either true or false and the API provides that data, so assessing completion is easy.

Habits can’t be tracked in the same way because they don’t have a completed attribute. The API does return data about Habits but it’s more verbose and doesn’t give a simple yes/no answer about whether/when a Habit has been used.
To get more technical, here is an example of the relevant fields for one Habit that was used on two days in November:

{
    "up": true,  // this means that the Habit has a plus button for recording good actions (`false` would mean the plus button was disabled)
    "down": true,  // this means that the Habit has a minus button for recording bad actions (`false` would mean the minus button was disabled)
    "history": [ // this array has one entry for each day on which the Habit was used (the entry is updated whenever the Habit's buttons are clicked)
        {
            "date": 1541175105725,  // 2018-11-02 16:11:45 UTC // the most recent time on the given day that the Habit was used
            "scoredUp": 1,  // the plus button was clicked once on 2018-11-02
            "scoredDown": 0  // the minus button was not clicked at all on 2018-11-02
        },
        {
            "date": 1541416652636,  // 2018-11-05 11:17:32 UTC
            "scoredUp": 2,  // the plus button was clicked twice on 2018-11-05
            "scoredDown": 1  // the minus button was clicked once on 2018-11-05
        }
    ],
}

So a hypothetical Beeminder goal could use that history array to record how Habits were used. Since the dates and scoredUp/scoredDown numbers change throughout the day, the goal would have to keep updating its datapoint(s) for each Habit to keep in sync with the data from Habitica’s API.

2 Likes