Official User Guide

Feed The Troll

A gamification app for Jira Cloud. Your real Jira work earns XP, evolves a personal troll, and shapes a shared team village. Every number on this page reflects the exact values used by the app.

Getting Started

Feed The Troll is a Jira Cloud app installed from the Atlassian Marketplace by your Jira System Administrator. It surfaces in five places inside Jira:

Issue Context Panel - the right-hand context panel visible on every issue; your main hub for troll management, appearance, quests, and privacy settings
My Troll Status - an optional dashboard gadget you can add to any Jira Dashboard
Team Village in the project sidebar - opens the Team Village that project belongs to, or a small village of its own while the project is in none
Team Village - a global page where your team's trolls meet across the projects you share. The free plan includes one Team Village with up to two projects.
Feed The Troll Administration - the global admin page for Jira System Administrators

First-Time Setup

Ask your Jira System Admin to install Feed The Troll from the Atlassian Marketplace. Right after installing, the admin clicks Get started and creates your Team Village (see Global Admin).
Open any Jira issue in one of your team's projects. The My Troll panel appears on the right. If your team has a Team Village, it says Meet your troll: click Start my troll. The name and look are ready, and any old project trolls' progress comes along. In a project without a Team Village, click Hatch to create a troll for that project.
Before you start, you can change the name and pick a Lineage (one of 15 types). The lineage shapes your XP bonuses and stays with the troll; the name can be changed later in the Gear tab.
Do your normal Jira work. XP is awarded automatically in the background - no manual tracking required.
Click Open Team Village right after you start, or any time under Visit a Village on your troll card, to see your team's trolls together in this project's village. Every project's sidebar has the same Team Village entry. From the Apps menu, Team Village opens the village you were most recently active in; the switcher at the top takes you to the others.

Secure by design: Feed The Troll runs entirely on Atlassian's infrastructure. No data leaves Atlassian's cloud and no third-party servers are involved. Your troll data is stored with platform-enforced isolation.

Earning XP

Feed The Troll awards XP automatically for 8 activities - six Jira events plus sending and receiving Toasts. The formula is:

Total XP = floor( baseXP × qualityMultiplier × (1 + typeBonus) )

Base XP & Anti-Gaming Limits

All values below are the exact numbers used by the app.

Event	Base XP	Daily Cap	Cooldown
Log time on an issue	15 XP	4 / day	60 min
Transition an issue status	10 XP	8 / day	30 min
Flag an issue as blocked	20 XP	3 / day	2 hr
Comment on an issue	8 XP	6 / day	15 min
Win the raid when a sprint closes (team event)	55–75 XP	1 / sprint	None
Receive a Toast from a teammate	10 XP	5 / day	5 min
Send a Toast to a teammate	5 XP	3 / day	5 min
Update a time log	5 XP	4 / day, once per issue	30 min

Silent caps: When a daily cap is reached, no XP is awarded and no error is shown. The troll simply stops eating until the next day (resets at midnight UTC). No punishment.

Quality Multipliers

Certain good habits award bonus multipliers on top of the base XP.

Event	Condition	Multiplier
Time logged	Logged on the same day you did the work	1.5× → 22 XP
Status transition	Moved to a status in Jira's In Progress category	1.3× → 13 XP
Status transition	Moved to a status in Jira's Done category, whatever it is called	2.0× → 20 XP
Status transition	Moved to Done on an issue created 30+ days earlier (Dusty Ticket)	2.5× → 25 XP
Blocker flag	Flag an issue that already has a comment, such as one explaining the blocker	2.0× → 40 XP
Comment	Comment on an issue assigned to someone else	1.5× → 12 XP

Evolution & Levels

Every troll has a level driven by cumulative XP. The XP threshold to reach level L is:

XP required = floor( 50 × L^1.5 )

Hatchling

1–4

0–558 XP

Youngster

5–9

559–1580 XP

Adult

10–19

1581–4471 XP

Elder

20–49

4472–17676 XP

Legendary

50+

17677+ XP

Milestone levels from the formula: Level 5 = 559 XP • Level 10 = 1,581 XP • Level 20 = 4,472 XP • Level 50 = 17,677 XP. At each stage boundary your troll's sprite and evolution name change, unique per Lineage.

The 15 Lineages

Choose your Lineage when your troll hatches. It sets your XP bonus per event type and stays with the troll. The bonus multiplies on top of the quality multiplier: base × quality × (1 + bonus). The raid and team quest bonus applies to the XP every troll gets from a won raid and from a finished team quest.

All 15 lineages are available to every team member - role labels are suggestions only, not restrictions.

All Lineages

Time logged+10%
Status changed+10%
Comment created+10%

Time logged+30%
Time log updated+20%

Status changed+25%
Raid and team quest XP+20%

Comment created+30%
Toasts received+20%

Worklog, Status, Comment+5% each

Status changed+25%
Time logged+15%
Comment created+10%

Comment created+30%
Blocker flagged+25%
Status changed+15%

Raid and team quest XP+40%
Status changed+20%
Comment created+15%

Raid and team quest XP+50%
Blocker flagged+30%
Toasts received+20%

Comment created+25%
Status changed+20%
Time logged+15%

Status changed+30%
Blocker flagged+25%
Time logged+15%

Comment created+30%
Status changed+25%
Toasts received+20%

Comment created+30%
Time logged+20%
Status changed+10%

Status changed+25%
Raid and team quest XP+20%
Time logged+10%

Raid and team quest XP+40%
Status changed+20%
Comment created+15%

Troll States & Streaks

Your troll's state (visible in the Issue Context Panel sprite and animation) is determined by your recent activity. States are strictly upward - the only downward transition is to sleeping, which is peaceful and non-punitive.

State	Condition	Transition to next
Sleeping	3+ days since last Jira activity	Any activity → Awake
Awake	Active in the last 3 days, streak < 3 days	Streak ≥ 3 days → Thriving
Thriving	Active, streak ≥ 3 days	Level up → Celebrating
Celebrating	The rest of the day of a level-up; the confetti plays once	Thriving or Awake the next day

Streak Logic

Streaks track consecutive days with any Jira activity. The key rule: streaks pause, they never reset.

Active yesterday → streak +1
Active today already → no change
Missed 1+ days (holiday, weekend) → streak stays the same (paused)
First ever activity → streak = 1

No punishment: There is no "sick", "sad", or "dying" state. Missing a week of work simply pauses your streak. When you return, your troll wakes up and picks up exactly where it left off.

Quests

Feed The Troll has two kinds of quests: Personal Quests you activate yourself, and Team Quests generated each sprint. You can have up to 3 personal quests active at once. Completing a quest awards bonus XP and may unlock a collection item. Manage your personal quests from the Issue Context Panel.

Worklog Warrior

Log time on 5 different days

75 XP reward Unlocks: Hard Hat, Timekeeper title Min Level 1

Blocked Guardian

Flag 3 blockers to protect the village

60 XP reward Unlocks: Shield Tool, Guardian title Min Level 1

Comment Helper

Comment on 10 issues to help your team

80 XP reward Unlocks: Speech Bubble Hat, Scribe title Min Level 2

Status Keeper

Update 20 issue statuses

100 XP reward Unlocks: Clipboard Tool Min Level 3

Estimation Sage

Complete 5 issues within ±20% of estimate

125 XP reward Unlocks: Wizard Hat Min Level 5

Streak bonus: A streak of 7 days or more raises the XP a completed quest pays: +10% for each full week of streak, capped at +50%. Everyday XP from Jira events is not multiplied by your streak.

Each quest counts what it says. Worklog Warrior counts days, so two worklogs on one day count once. Blocked Guardian and Comment Helper count different issues. Status Keeper counts status changes, and Estimation Sage counts an issue once it reaches a Done status with its time spent within 20% of its original estimate. A quest only counts actions that earned XP, so cooldowns and daily caps apply to it too.

Team Quests

Team Quests are generated automatically at the start of each sprint. The whole team contributes progress together. A sprint start adds one team quest to each of the sprint's projects that has trolls, and an unfinished quest ends when its sprint closes. The quests on offer today are both about aging work, so a project gets Spring Cleaning first and Deep Clean while Spring Cleaning is still running.

Six team quests are defined, but only the two the app can measure are offered today: Spring Cleaning (finish 3 or more issues that were created at least 7 days ago) and Deep Clean (finish 5 or more), with higher targets on bigger teams. Flow Masters, Sprint Warriors, Sprint Champions and All Hands on Deck wait until the app can measure them. A finished quest pays every member XP (Spring Cleaning 30, Deep Clean 50, plus up to 10 more on a larger team), with each troll's lineage sprint bonus on top, and grows one village building by a level: the Wall for Spring Cleaning, the Keep for Deep Clean. It pays once, and only once.

Collection

The catalog holds 52 items in four categories: hats, tools, colours and titles. Five of them, two seasonal and three secret, have no way in at the moment and stay hidden, so 47 can be earned. Items are equipped from the Issue Context Panel and appear on your troll's sprite.

Hats (17 items)

Hard HatQuest: Worklog Warrior
Speech Bubble HatQuest: Comment Helper
Wizard HatQuest: Estimation Sage
Viking HelmetLevel 5
Top HatLevel 10
Royal CrownLevel 15
Graduation CapLevel 20
Cowboy Hat14-day streak
+ 7 more…Various sources

Tools (15 items)

ShieldQuest: Blocked Guardian
ClipboardQuest: Status Keeper
+ 13 more…Levels, streaks & drops

Colors (8 items)

GreenDefault
Blue, Purple, BrownLevels 5, 10, 15
White, Red, Gold, BlackLevels 20, 25, 35, 45

Titles (12 items)

TimekeeperQuest: Worklog Warrior
GuardianQuest: Blocked Guardian
ScribeQuest: Comment Helper
Streak Master7-day streak
Team Player10 Toasts received
+ 7 more…Levels, streaks, one secret

Unlock Sources

LevelAutomatic at threshold
QuestComplete specific quest
StreakMaintain streak N days
ToastsReceive N Toasts from teammates
Tavern Loot DropRandom drop while working

Tavern Loot Drops

While logging work, leaving comments, or moving issues, there is a small chance a Tavern Loot Drop chest appears above your troll. Opening it rewards either bonus XP or a random item from the loot table.

Tier	Chance	Reward
XP Bonus	65 %	+25 XP
Common item	20 %	Level 3-10 hat or tool you don't already own
Uncommon item	10 %	Level 12-20 hat or tool you don't already own
Exclusive item	5 %	Loot-drop-only item (Witch Hat, Jester's Cap, Glowing Orb)

A drop can trigger at most once per day per project. If you already own all items in a tier, that tier falls back to XP instead.

Hidden items

Items obtainable only via Loot Drops are not shown in the Collection grid until you own them, and the category counter leaves them out of its total too. Seasonal and secret items, which nothing grants at the moment, are hidden the same way. With both loot-drop hats undiscovered, the Hats tab counts out of 12 rather than 17, so the grid never dangles an item you cannot get by playing.

The Village

Your team's trolls meet in the Team Village, open from Your Project > Team Village or from the Apps menu. The village has eight building types, each with levels 0–5.

Buildings

Building	Max Level	Notes
Hut	5	The first structure. It is also what grows when a won raid goes unclaimed in an empty village.
Wall	5	Team quest reward: Spring Cleaning
Keep	5	Team quest reward: Deep Clean
Library	5	Raid rewards for now; its team quest, Flow Masters, is not offered yet
Smithy	5	Raid rewards for now; its team quest, Sprint Warriors, is not offered yet
Tower	5	Raid rewards for now; its team quest, Sprint Champions, is not offered yet
Tavern	5	Raid rewards for now; its team quest, All Hands on Deck, is not offered yet
Garden	5	No team quest pays it, so it grows only through raid rewards

Any of the eight can also be chosen as the reward for a won raid. Villages created before these names settled may still store a building as watchtower; the app reads it as the Tower.

Defense Score (0–100)

Calculated from team behavior. Starts at 50.

Work in progress unmoved for 7+ days −3 each Max penalty: −30

No aging issues +10 All issues are fresh

WIP overload −2 per excess Threshold: 2 per active troll (min 4). Max penalty: −20

WIP under control +5 Within WIP limit

Blocker flagged (weekly) +2 each Flagging is GOOD - communication. Max: +15

Team activity ≥70% +10 Share of trolls that earned XP in the last 7 days

Team activity <30% −10 Fewer than 30% earned XP in the last 7 days

Prosperity Score (0–100)

Weekly team XP +1 per 100 XP Max: +20. Zero XP = −10

Avg team streak +1 per day Max: +10

Active troll count +2 per troll Max: +10

Sprint Raids

When a sprint is closed via Board > Complete Sprint, a Raid is triggered automatically. The outcome depends entirely on the village's Defense Score at the moment of sprint close.

D ≥ 60

Victory

One building to claim, and 55–75 bonus XP per troll (scales with defense score).

40–59

Stalemate

Village holds. No bonus XP, no building change.

D < 40

Damage

Highest-level building loses 1 level (cosmetic). Trolls are never harmed.

Victory XP: Every team member earns between 55 and 75 bonus XP, scaling with the defense score. A defense of 60 awards +55 XP per troll; a perfect 100 awards +75 XP.

Claiming the building a raid won

A won raid pays exactly one building. Anyone on the team can pick which one from the Team Village, and the first pick is the one that counts; a building already at level 5 cannot be chosen. If nobody has picked by the time the project's next sprint starts, the app grows the lowest building that can still grow, so a won raid is never lost to indecision.

All raids are logged and viewable from the Village page's history tab. The team can review per-sprint defense scores to identify trends.

Team Villages

A Team Village combines several Jira projects into one shared village so a team that works across projects sees a single roster instead of a separate village per project. A Jira System Administrator creates one in a single step from Get started, and manages villages on the Feed The Troll Administration page. The free plan includes one Team Village with up to two projects. Paid plans and trials can have up to 10 Team Villages, each holding up to 25 projects.

What a Team Village shows

One combined view of the included projects: aggregate defense and prosperity, buildings, raids, and recent activity.
A privacy-safe roster - each teammate appears once, honouring their personal privacy settings.
An optional team leaderboard (off by default) that uses only public level and XP.
Included project names are hidden by default; an admin can choose to show them.

Two progression modes

New Team Villages start with Traveling Trolls. An admin can switch a village to Classic Project Trolls in its settings:

One Traveling Troll Per Teammate - each teammate has a single troll that earns XP in any included project. This is the default.
Classic Project Trolls - each project keeps separate trolls. The Team Village only shows a shared view; your per-project trolls are unchanged.

Traveling Trolls: in this mode one profile per teammate travels across the included projects. Your level, XP, streak, and appearance follow that profile, and XP from every source - Jira events, personal quests, collection loot, Toasts, team-quest rewards, and raid rewards - feeds it no matter which included project the work happened in. Each project's own Village still shows its local work context, health, buildings, and raids.

Switching a Team Village back to Classic, removing one of its projects, or deleting it first requires the admin to archive its active Traveling Trolls. Archiving retires the active profiles but never deletes their history.

Starting your troll

Open any issue in one of the village's projects. My Troll says Meet your troll; click Start my troll. If you had project trolls, their progress comes along and they stay saved, and the panel tells you what happened, for example "We combined your progress from 3 projects." Then click Open Team Village to meet your team. Prefer to keep a single project troll for now? Choose Not now, keep my project troll; a small banner keeps the invitation one click away.

Sending a Toast

You can send a teammate a Toast two ways: from the Toast tab on your My Troll issue panel, or by clicking a teammate in the Team Village and choosing Send a Toast. Add a short optional message if you like. It gives them a small XP boost and a warm notification, and sending one grows your own troll too. A teammate who turns off Allow Toasts in the Gear tab will not show the option. When Harmony Mode is on, or a project's settings turn Toasts off, the Toast tab and Send a Toast disappear and no Toast is paid. The daily limits, 5 received and 3 sent, count across the whole Team Village, not per project.

Troll Sprint

Click the Troll Sprint sign in the top corner of the Team Village. Your troll runs on its own along a track of about 20 seconds; press Space, click or tap to jump over bugs and card stacks, and hold to jump higher. Bridges over tar are faster, if you land on them. Everyone on the site gets the same track on the same UTC day, dressed for the village's season, and each day has a Sprint Goal time. Your troll runs in the hat and tool it wears. R restarts, Esc closes.

Your best run today comes back as a ghost to race. On its own, the game sends no time or result anywhere, only a count that it was opened and that a run finished, and your best lasts until you reload the page.

To race teammates, choose Turn on under the track. The game first tells you what is shared: your troll’s name, your best time today and its ghost, seen by teammates who can see your troll. Then pick a teammate under Race, and meeting the Sprint Goal earns +10 XP once a day. After a race you can send that teammate a Toast in one click, win or lose. While you share, the sign shows how many teammates ran today. A run is kept for its own day and the next one, then deleted, or at once with Stop sharing. Racing is not offered under Harmony Mode or Ethics Mode, and an admin can turn Troll Sprint off in the site settings.

App Behaviour

Feed The Troll ships with sensible gameplay defaults for every project. The table below describes the current defaults, not a separate Project Settings page. Jira System Administrators manage site-wide access, privacy overrides, and Team Villages from Feed The Troll Administration.

Feature	Default	What it controls
Leaderboard	OFF	Optional ranking by level in a Team Village, off when the village is created
Toasts	ON	Lets teammates send each other Toasts
Team Quests	ON	Sprint-scoped shared quests generated each sprint
Sprint Raids	ON	Defense events triggered at sprint close
Ethics Mode	OFF	Cooperative-only mode; Harmony Mode turns it on for every project - see below
Max active personal quests	3	How many personal quests a user can have active simultaneously

Ethics Mode

Ethics Mode is the cooperative-only behaviour used by Global Harmony Mode. When a Jira System Administrator enables Global Harmony Mode, the app disables competitive elements across every enabled project:

Leaderboard hidden - no individual XP or level rankings are shown, regardless of each user's own privacy settings
Toasts disabled - sending and receiving Toasts are turned off entirely, and the Toast tab and Send a Toast disappear
Activity feed hidden - the Team Village activity feed is turned off

Team Quests and Sprint Raids remain fully active because they are collaborative rather than competitive.

Instance-wide: To activate Ethics Mode across all projects simultaneously, a Jira System Administrator can enable Global Harmony Mode in the Global Admin page (see below). Individual project overrides are not possible while Global Harmony Mode is on.

Privacy Controls

Every user controls their own visibility from the Gear tab of the My Troll issue panel. A save applies to all of your trolls at once, not just the project you happen to have open. Defaults are designed to be social-friendly while protecting detailed stats. Your troll data is stored with per-user isolation - even System Admins cannot see another user's private troll data.

Privacy Toggle	Default	What it controls
`Show in Village`	ON	Your troll appears in the team village scene
`Show Level`	ON	Your level is visible on the leaderboard
`Show Streak`	OFF	Your streak day count is visible to teammates
`Show XP`	OFF	Your total XP is visible to teammates
`Allow Toasts`	ON	Others can send you a Toast (+10 XP each, up to 5 per day)

Privacy-Safe Activation Metrics

Feed The Troll records twelve one-time, installation-level activation milestones using Atlassian Forge custom counters. These counters help us understand whether an installation reached setup, created its Team Village, created a troll or a Traveling Troll, earned its first positive XP, activated a quest, opened a village, and saw a teammate there, and whether someone chose "Not now". Three more counters, kept only in Forge custom metrics with no stored record, count plan changes (a site moving to or from the free plan) and when a free-plan limit is reached, and four count Troll Sprint use: the game opened, opened from My Troll, a run finished, and racing turned on. None of them carries a person, a time or a result.

The counters do not include Jira issue content, issue keys, project names, user or account IDs, troll names, comments, worklogs, or configuration values. No third-party analytics service receives this data. A Jira administrator can disable custom metrics access through Atlassian Administration without affecting product functionality. See the Privacy and Security Policy for full details.

Global Admin

A Jira System Administrator accesses the Feed The Troll Administration page at Jira Settings > Apps > Feed The Troll. Only users in the Jira System Administrators group can reach it.

First-Time Setup

Right after installing, open Manage Apps and click Get started next to Feed The Troll. On a site that has never been set up, the Feed The Troll Administration page opens the same screen. It asks two things: a name for your Team Village and the projects your team works in. Click Create Team Village. One save turns the app on for those projects and creates the village with Traveling Trolls, with personal stats private and the leaderboard off.

The ready screen then offers Open Team Village, a quick way to try it, and Copy a message for your team. Feed The Troll sends no emails or notifications. Everything else lives on the admin page and can be changed at any time: each Team Village has a row with Edit, and the site settings Where trolls appear, Harmony Mode and Who sees trolls each have Change. Nothing changes until you press Save. The page follows Jira's light or dark theme.

Harmony Mode

Harmony Mode makes Feed The Troll calmer for the whole site:

It turns off leaderboards and the activity feed in every Team Village, and Toasts everywhere: the Toast tab in My Troll and Send a Toast in the village disappear.
Trolls, quests and raids stay on.
Project admins cannot turn it off.

Where Trolls Appear

All Jira projects: every current and future project (paid plans and trials).
Selected projects: only the projects you pick, good for pilots. On a paid plan, saving a Team Village turns trolls on in its projects and says which ones.
Off in every project: trolls hide everywhere. No data is deleted, and turning it back on restores everything.

Free plan: one Team Village with up to 2 projects. The projects you pick under Where trolls appear are the plan's projects, and they can belong to one Team Village. All Jira projects needs a paid plan or a trial. Privacy controls, Harmony and Restrict trolls to your team work on every plan.

Who Sees Trolls

By default the troll shows to everyone who can view an issue, which can include external or portal customers. Under Who sees trolls, choose Only your team to show the troll only to people who have Jira's View Development Tools permission - so customers do not see it. This covers every place the troll appears: the My Troll issue panel and the Team Village, including its entry in each project's sidebar.

To take effect, grant View Development Tools to your team's role in the project's Permission Scheme and remove Any logged in user. That also keeps commit and build information away from customers. This option is off by default, so existing setups are unchanged until you switch it on.

Data & Licensing

All data is stored securely within Atlassian's infrastructure. Individual user data is never visible at the admin level.

Marketplace licensing: Feed The Troll is a single-edition Paid via Atlassian (PvA) app. Without an active subscription the site is on the free plan: one Team Village with up to 2 projects, with the full game in those projects. An active Atlassian subscription or trial includes every project and up to 10 Team Villages - enforced automatically, no manual configuration required.

When a trial or a subscription ends, nothing is deleted and every Team Village stays. The free plan covers the two busiest projects of the busiest Team Village, measured by activity over the last 30 days. Work there keeps earning XP; the other projects pause until an admin upgrades or picks different projects under Where trolls appear. Troll progress in paused projects is kept, and upgrading brings every project back at once.