blindxfish/devplacepy
1
0
Fork 0
forked from retoor/devplacepy
Code Pull Requests Activity

ipdatepppdate

Browse Source
This commit is contained in:
retoor
2026-07-26 16:46:41 +02:00
parent 2620ecc0f1
commit ac04cf6817
30 changed files with 915 additions and 10309 deletions
Download Patch File Download Diff File Expand all files Collapse all files
devplacepy/templates/docs/code-farm.html
+343 -139
View File
@@ -14,13 +14,14 @@ play. Visiting another farm at `{{ base }}/game/farm/{username}` is public.
Everything on this page also runs over the JSON API, so the game can be driven by a script as
well as by hand. The full request and response reference is the
[Code Farm API group](/docs/game.html); this page explains the rules and the numbers behind
them, then shows a complete automated client at the end.
[Code Farm API group](/docs/game.html); this page explains the rules and the exact numbers behind
them, then documents every field a client sees and shows a complete automated client at the end.
## The core loop
1. **Plant** a crop in an empty plot. Planting costs coins.
2. The crop **builds** over real time. The build finishes at a fixed wall-clock moment.
2. The crop **builds** over real time. The build finishes at a fixed wall-clock moment
(`ready_at`); there is no server tick, the clock alone decides.
3. **Harvest** the finished build for coins and experience, which empties the plot again.
4. Spend the coins on faster CI, more plots, and perks so the next loop pays more.
@@ -32,26 +33,29 @@ progressing and wait for you, so the game is safe to check once an hour or once
Each crop has a coin cost to plant, a base build time, a coin and experience reward on harvest,
and a level at which it unlocks. Slower crops pay far more per build.
| Crop | Cost | Base build time | Coins | XP | Unlocks at level |
|------|-----:|----------------:|------:|---:|:----------------:|
| 🐚 Shell Script | 5 | 30s | 11 | 2 | 1 |
| 🐍 Python Script | 15 | 2m | 36 | 5 | 1 |
| 📜 Web App | 40 | 5m | 98 | 12 | 2 |
| 🐹 Go Service | 90 | 10m | 224 | 25 | 3 |
| 🦀 Rust Engine | 200 | 30m | 520 | 60 | 4 |
| λ Compiler | 500 | 1h | 1380 | 150 | 6 |
| ⚙️ Kernel | 1200 | 2h | 3600 | 400 | 8 |
| 🕸️ Distributed System | 5000 | 4h | 9500 | 900 | Mastery |
| 🧠 ML Pipeline | 12000 | 6h | 21000 | 1800 | Mastery |
| 🔐 Security Fortress | 30000 | 8h | 48000 | 3200 | Mastery, raid-immune |
| Crop | Key | Cost | Base build time | Coins | XP | Unlocks at |
|------|-----|-----:|----------------:|------:|---:|:----------:|
| 🐚 Shell Script | `shell` | 5 | 30s | 11 | 2 | level 1 |
| 🐍 Python Script | `python` | 15 | 2m | 36 | 5 | level 1 |
| 📜 Web App | `webapp` | 40 | 5m | 98 | 12 | level 2 |
| 🐹 Go Service | `api` | 90 | 10m | 224 | 25 | level 3 |
| 🦀 Rust Engine | `rust` | 200 | 30m | 520 | 60 | level 4 |
| λ Compiler | `haskell` | 500 | 1h | 1380 | 150 | level 6 |
| ⚙️ Kernel | `kernel` | 1200 | 2h | 3600 | 400 | level 8 |
| 🕸️ Distributed System | `distsys` | 5000 | 4h | 9500 | 900 | level 20 + Mastery |
| 🧠 ML Pipeline | `mlpipe` | 12000 | 6h | 21000 | 1800 | level 20 + Mastery |
| 🔐 Security Fortress | `secfort` | 30000 | 8h | 48000 | 3200 | level 20 + Mastery |
The three Mastery-tier crops unlock once you have earned at least one Mastery point (see
Mastery, below), on top of the usual level requirement. Security Fortress can never be raided.
The three Mastery-tier crops require **level 20** and at least **one earned Mastery point** (see
Mastery, below). The Mastery unlock is permanent - it checks points ever earned, not points held,
so spending your points never re-locks the crops. Security Fortress is **raid-immune**: it can
never be stolen.
Build time is the base time divided by the farm build speed (CI tier and the growth perk, below),
so a higher tier finishes everything proportionally faster. Coin and experience rewards shown in
the API already include your perks, refactor bonus, and the current Market Saturation factor, so
read them from the live state rather than from this table. Each crop in the state also carries a
Build time is the base time divided by the farm build speed (CI tier, the Build Cache perk, the
Bare-Metal Legacy upgrade, and the Private Registry for its three crops), so upgrades finish
everything proportionally faster. Coin and experience rewards shown in the API already include
your perks, refactor bonus, Legacy multiplier, and the current Market Saturation factor, so read
them from the live state rather than from this table. Each crop in the state also carries a
`market_state` of `normal`, `saturated`, or `boosted`.
## Plots
@@ -74,7 +78,8 @@ More plots is more builds in parallel, which is the main way to scale output.
## CI tier (build speed)
Upgrading your CI tier multiplies build speed for the whole farm. The upgrade is permanent.
Upgrading your CI tier multiplies build speed for the whole farm. The upgrade is permanent (until
a refactor resets it).
| Tier | Name | Build speed | Upgrade cost |
|:----:|------|:-----------:|-------------:|
@@ -87,151 +92,260 @@ Upgrading your CI tier multiplies build speed for the whole farm. The upgrade is
## Levels and experience
Harvesting grants experience. Experience raises your level, and higher levels unlock the more
valuable crops. The maximum level is **20**. Each level needs `50 * (level - 1)^2` total
experience, so level 2 is at 50 XP, level 5 at 800, level 10 at 4050, and level 20 at 18050.
valuable crops. The maximum level is **20**. Reaching a level needs `50 * (level - 1)^2` total
experience, so level 2 is at 50 XP, level 5 at 800, level 10 at 4050, and level 20 at 18050. The
state reports `level`, `level_into` (XP into the current level), `level_span` (XP from this level
to the next), and `level_is_max`.
## Perks
Perks are permanent upgrades bought with coins. Each level of a perk costs more than the last.
There are four:
Perks are permanent upgrades bought with coins (until a refactor resets them). The cost of level
`n+1` is `round(base * growth^n)`, so each level costs more than the last. There are four:
| Perk | Effect per level | Max level |
|------|------------------|:---------:|
| 📈 Optimizer | +5% harvest coins | 10 |
| ⚡ Build Cache | +4% build speed | 10 |
| 🏷️ Bulk Licenses | -3% planting cost | 8 |
| 🎓 Mentorship | +5% harvest experience | 10 |
| Perk | Key | Effect per level | Max level | First cost | Cost growth |
|------|-----|------------------|:---------:|-----------:|:-----------:|
| 📈 Optimizer | `yield` | +5% harvest coins | 10 | 120 | 1.6x |
| ⚡ Build Cache | `growth` | +4% build speed | 10 | 150 | 1.7x |
| 🏷️ Bulk Licenses | `discount` | -3% planting cost | 8 | 100 | 1.7x |
| 🎓 Mentorship | `xp` | +5% harvest experience | 10 | 140 | 1.6x |
The live state reports each perk's current level and the exact cost of its next level.
The live state reports each perk's current level and the exact cost of its next level - read
`cost` from the state rather than recomputing it.
## Daily bonus and streak
Once per day you can claim a coin bonus. Claiming on consecutive days builds a streak that
increases the bonus, from **20 coins** on day one up to **92 coins** at a seven-day streak.
Missing a day resets the streak. The state field `daily_available` tells you when a claim is
ready, and `daily_reward` is the amount you would receive.
Once per UTC day you can claim a coin bonus of `20 + 12 * (streak_day - 1)`, where the streak day
caps at seven: **20 coins** on day one up to **92 coins** from the seventh consecutive day on.
Missing a day resets the streak to one. The state field `daily_available` tells you when a claim
is ready, and `daily_reward` is the exact amount the next claim pays.
## Daily quests
Each day you are given three small goals, such as planting a number of crops, harvesting a number
of builds, watering neighbour builds, or earning a number of coins from harvests. Progress is
tracked automatically as you play. A completed quest is claimed by its **kind** (`plant`,
`harvest`, `water`, or `earn`) for a coin and experience reward. The state field `can_claim` on
each quest marks the ones that are ready.
Each day you are given three small goals, deterministically chosen per user and day, such as
planting a number of crops, harvesting a number of builds, watering neighbour builds, or earning a
number of coins from harvests. Progress is tracked automatically as you play. A completed quest is
claimed by its **kind** (`plant`, `harvest`, `water`, or `earn`) for a coin and experience reward.
The state field `can_claim` on each quest marks the ones that are ready; claiming an incomplete or
already-claimed quest returns an error.
## Fertilizer
Fertilizing a growing build spends coins to **halve its remaining time**. The cost scales with the
build's coin value and with how much time you skip, so a build with a long way to go costs more and
fertilizing is cheapest near the end. Each plot in the state reports its current `fertilize_cost`.
Fertilizing a growing build spends coins to **halve its remaining time**. The exact cost is
`ceil(effective_harvest_coins * skipped_seconds / full_build_seconds * 1.05)`, where
`effective_harvest_coins` already includes all your multipliers - so fully fertilizing a build
always costs at least 105% of its harvest value. Fertilizer is a pure time-skip, never a profit,
at any prestige. Each growing plot in the state reports its current `fertilize_cost`; a build
with less than two seconds remaining cannot be fertilized.
## Golden builds
Every planting has a **5% chance** to come out **golden**, decided the moment it is planted and
fixed for that build's lifetime. A golden harvest pays **5x coins** (experience is unchanged).
The plot field `is_golden` marks it - the owner always sees it, a visitor only when the build is
currently stealable (a golden build is a 5x raid target too, so watch your grace window).
## Watering a neighbour (cooperation)
Visit another member's farm and water one of their **growing** builds. Watering reduces that
build's remaining time by 8% of its total build time and rewards **you**, the visitor, with
**6 coins and 3 experience**. A single plot can be watered up to **3 times** total across all
visitors, so popular farms fill up. Each plot reports `can_water`, `watered_count`, and
`max_waters`.
build's remaining time by **8% of its full (speed-adjusted) build time** and rewards **you**, the
visitor, with **6 coins and 3 experience**. Each visitor can water a given build **once per
growth cycle**, and a single build takes at most **3 waterings** total across all visitors, so
popular farms fill up. Each plot reports `can_water` (true only for signed-in non-owners who have
not watered it yet), `watered_count`, and `max_waters`. Watering also advances your own `water`
quest.
## Raiding a ready build (competition)
If an owner leaves a build **ready** without harvesting it, another member can raid it, but only
after a protection window (60 seconds by default, longer with Branch Protection or a Defense
building) has passed since the build became ready. The raider receives a fraction of the build's
coin value (half by default, less with the owner's defenses, floored so a raid never pays nothing)
and the owner loses the build entirely - except a Security Fortress build, which can never be
raided. The owner is told their farm was raided but the raider's identity is never revealed. You
can raid a given neighbour only once per hour. Raiding a farm with **10x** your own coins grants you
a 24-hour **Underdog** boost (+25% harvest coins). Each plot reports `can_steal` and `steal_coins`
(the payout a raid would give), and `ready_at` lets you compute when the protection window ends.
If an owner leaves a build **ready** without harvesting it, another member can raid ("steal") it,
but only after a protection window has passed since the build became ready. The window is **60
seconds** base, **+30s** per level of the owner's Branch Protection Legacy upgrade, plus the
owner's Defense tier grace bonus (table below).
The raider receives a fraction of the build's realized coin value:
`max(floor, 50% - 5% x Branch Protection level)`. The floor comes from the owner's Defense tier
(10% undefended, down to 4% at Zero Trust Mesh); when the owner owns the Observability Suite the
floor is 30% instead. The owner loses the build entirely either way. A Security Fortress build
can never be raided. The owner is notified their farm was raided but the raider's identity is
never revealed.
You can raid any given neighbour only **once per hour** (per victim, so raiding several different
farms in one hour is fine). Raiding a farm holding more than **10x** your own coins grants you a
24-hour **Underdog** boost (+25% harvest coins, visible as
`underdog_boost_seconds_remaining` in your state).
Each plot on a farm you view reports:
- `can_steal` - true when everything below is satisfied and you can raid right now.
- `steal_coins` - the exact payout a raid would give.
- `steal_reason` - why a ready build is not stealable: `protected` (grace window still running),
`cooldown` (you raided this owner within the hour), or `immune` (Security Fortress). Empty when
stealable or not applicable.
- `steal_cooldown_seconds` - seconds until your per-owner cooldown ends (only set with
`steal_reason` of `cooldown`; also mirrored farm-wide as `steal_cooldown_seconds` on the farm).
- `ready_at` - add the protection window to compute when a raid becomes possible.
Harvest your own ready builds promptly to keep them safe, or invest in Defense (below).
## Market Saturation
The game tracks the last 48 hours of league-wide harvests of each crop. When a crop is being
farmed heavily, its payout drops in steps (down to 40% of normal); while that is happening, the
four starter crops (Shell Script, Python Script, Web App, Go Service) get a relief buff of up to
+15%. This rewards diversifying what you plant instead of printing one crop nonstop. Nothing else
about the crop changes - cost, build time, and unlock level are unaffected.
The game tracks the last **48 hours** of league-wide harvests of each crop and converts them into
supply measured in build time ("plot-days" at base rate), so a 30-second Shell Script and a
2-hour Kernel saturate on the same real-terms scale - quick crops are not punished for being
quick. As supply piles up, the crop's payout steps down:
| Supply (plot-days in 48h) | Payout |
|:-------------------------:|:------:|
| under 8 | 100% |
| 8 or more | 85% |
| 24 or more | 70% |
| 48 or more | 55% |
| 96 or more | 40% |
Separately, while the high-tier market (Rust Engine, Compiler, Kernel) is saturated, the four
starter crops (Shell Script, Python Script, Web App, Go Service) pay a boost of up to **+15%**
(scaling with how collapsed the high tier is) as long as they are not overfarmed themselves - a
crop is either penalized or boosted, never both. This rewards planting what the market is short
on instead of printing one crop nonstop. Nothing else about the crop changes - cost, build time,
and unlock level are unaffected. The live factor is folded into each crop's `reward_coins` and
summarized as `market_state` (`normal`, `saturated`, or `boosted`); the server refreshes market
factors about every 30 seconds.
## Infrastructure, Defense, and Cosmetics (coin sinks)
Once you are earning more coins than you can spend on plots and perks, three permanent systems
give large coins a purpose:
give large coins a purpose.
- **Infrastructure** - one-time, prestige-gated buildings bought with `POST /game/infrastructure/buy`:
**Private Registry** (Rust, Compiler, and Kernel crops grow 15% faster, prestige 3+), **Canary
Deployments** (every harvest has a 12% chance to double and a 6% chance to only refund its
planting cost, prestige 8+), and **Observability Suite** (raises the minimum coins you keep when
raided from 10% to 30%, prestige 15+).
- **Defense** - an upgradeable building (`POST /game/defense/upgrade`) that lowers your raid losses
and lengthens your protection window with every tier. Unlike a one-time purchase, it costs a
**daily coin upkeep** proportional to your balance; if you do not have enough coins to cover it,
the tier decays by one level automatically. This is the sink that scales with wealth.
- **Cosmetics** - purely cosmetic titles and plot skins bought with coins (`POST /game/cosmetics/buy`)
and equipped (`POST /game/cosmetics/equip`). Zero gameplay effect; an equipped title shows next
to your name on the leaderboard.
### Infrastructure
One-time, prestige-gated buildings bought with `POST /game/infrastructure/buy`:
| Building | Key | Effect | Cost | Requires |
|----------|-----|--------|-----:|:--------:|
| 📦 Private Registry | `registry` | Rust, Compiler, and Kernel builds finish 15% faster (watering them is 15% more effective too) | 25,000,000 | prestige 3 |
| 🐤 Canary Deployments | `canary` | Every harvest has a 12% chance to double and a 6% chance to only refund its planting cost | 75,000,000 | prestige 8 |
| 🔭 Observability Suite | `observability` | Fixes the raid payout floor at 30% of a build's value (see Raiding and Defense) | 150,000,000 | prestige 15 |
### Defense
An upgradeable building (`POST /game/defense/upgrade`) that lowers your raid losses and lengthens
your protection window per tier:
| Tier | Name | Upgrade cost | Daily upkeep (min) | Raid payout floor | Extra grace |
|:----:|------|-------------:|-------------------:|:-----------------:|:-----------:|
| 0 | Undefended | - | 0 | 10% | +0s |
| 1 | Firewall | 5,000 | 500 | 10% | +15s |
| 2 | WAF | 40,000 | 2,500 | 8% | +30s |
| 3 | SOC Monitoring | 300,000 | 15,000 | 6% | +60s |
| 4 | Zero Trust Mesh | 2,000,000 | 100,000 | 4% | +120s |
The payout floor is the minimum fraction of a build's value a raider takes from you (see Raiding
above); the Observability Suite replaces any tier floor with 30%. Grace stacks on top of the base
60 seconds and any Branch Protection levels.
Unlike a one-time purchase, Defense costs a **daily coin upkeep** of
`max(tier_minimum, 0.2% of your coin balance)` - a large balance pays real money, not a flat fee.
Upkeep is charged lazily whenever you load your own farm, for at most **2 days** at a time; if
your balance cannot cover what is due, your coins go to zero and the tier **decays by one
level**. The state reports `defense_level`, `defense_tier_name`, `defense_upkeep_daily` (today's
exact charge), and `defense_next_cost`.
### Cosmetics
Purely cosmetic titles and plot skins bought with coins (`POST /game/cosmetics/buy`) and, for
titles, equipped with `POST /game/cosmetics/equip`. Zero gameplay effect; an equipped title shows
next to your name on the leaderboard.
| Cosmetic | Key | Kind | Cost |
|----------|-----|:----:|-----:|
| 🏛️ The Architect | `title_architect` | title | 500,000 |
| ♻ Serial Refactorer | `title_refactorer` | title | 250,000 |
| ⚙ Kernel Hacker | `title_kernel_hacker` | title | 1,000,000 |
| 🌈 Neon Terminal | `skin_neon` | skin | 750,000 |
Era-exclusive cosmetics (when an Era awards one) appear in your owned list but are never sold in
the shop. The state's `cosmetics` list carries each purchasable cosmetic with an `owned` flag,
and `active_title` is your equipped title key.
## Mastery (beyond prestige)
Refactoring past **prestige 50** starts earning a second currency: one Mastery point immediately,
then one more every 10 further prestige. Mastery points never expire, and once you have earned at
least one, the three Mastery-tier crops above stay unlocked even if you later spend the point.
Spend Mastery points with `POST /game/mastery` on three permanent upgrades:
Refactoring past **prestige 50** starts earning a second currency: one Mastery point the moment
you cross 50, then one more every 10 further prestige (`total earned = 1 + (prestige - 50) / 10`,
rounded down). Points never expire, and crop unlocks check points **ever earned**
(`mastery_points_earned_total`), so spending never re-locks content. Spend points with
`POST /game/mastery` on three permanent upgrades:
| Mastery upgrade | Effect | Max level |
|------------------|--------|:---------:|
| 🔁 Continuous Delivery | Auto-replant the same crop right after harvest, if affordable | 1 |
| 📊 Farm Analytics | Unlocks lifetime stats on your farm | 1 |
| 📜 Legacy Contracts | Unlocks a weekly contract slot paying Stars and a temporary coin boost | 1 |
| Mastery upgrade | Key | Effect | Cost (points) |
|------------------|-----|--------|:-------------:|
| 🔁 Continuous Delivery | `autoreplant` | Auto-replant the same crop right after every harvest, if still affordable and unlocked | 3 |
| 📊 Farm Analytics | `analytics` | Unlocks lifetime stats: `lifetime_coins_earned` and `lifetime_harvests` | 2 |
| 📜 Legacy Contracts | `contracts` | Unlocks a weekly contract slot paying Stars and a temporary coin boost | 4 |
The state reports `mastery_points`, `mastery_points_earned_total`, and each upgrade's level and cost.
Each has a single level. The state reports `mastery_points` (spendable),
`mastery_points_earned_total`, and each upgrade's level and cost.
### Weekly contracts
With Legacy Contracts owned, one **weekly contract** appears in your `quests` list with
`scope: "weekly"` - a larger goal of the same four kinds, deterministic per user and ISO week.
Claiming it (`POST /game/quests/claim` with the contract's `quest` kind and `scope=weekly`) pays
**Stars** (`reward_stars`) plus experience, and grants a **+20% harvest-coin boost for 48
hours**.
## Refactor (prestige)
At level 10 or above you can **refactor**: the farm resets to its starting coins, level, CI tier,
perks, and plots, but you gain a permanent **+25% coin bonus** that stacks with every refactor and
multiplies with the Optimizer perk. Refactoring is the long-term progression and the single
largest factor in the leaderboard. The state reports `prestige`, `prestige_multiplier`, and
`prestige_available`.
At level 10 or above you can **refactor**: coins, XP, level, CI tier, perks, and extra plots
reset, but you gain a permanent **+25% coin bonus per refactor** that multiplies with your perks.
Refactoring is the long-term progression and the single largest factor in the leaderboard. The
state reports `prestige`, `prestige_multiplier`, `prestige_min_level`, and `prestige_available`.
Refactoring is not free: it costs a **coin fee** that grows with both your prestige count and your
current coin balance (a wealth tax), so each refactor takes longer to afford than the last. The
live state reports the exact `refactor_cost` and whether you can pay it (`refactor_affordable`).
After the fee, **10%** of your remaining coins carry over into the new run - more with the Golden
Parachute Legacy upgrade (up to 35%), previewed as `refactor_carryover_preview`.
Refactoring is not free. The fee is:
Each refactor also awards **stars**, a separate prestige currency (more at higher levels and higher
prestige). Stars are never reset and are spent on permanent **Legacy upgrades**.
```
fee = round(20000 * (1 + prestige) * (1 + 0.25 * prestige) + 0.15 * coins)
```
so it grows with both your refactor count and your current balance (a wealth tax), and each
refactor takes longer to afford than the last. The live state reports the exact `refactor_cost`
and whether you can pay it right now (`refactor_affordable`). After the fee, **10%** of your
remaining coins carry over into the new run - up to **35%** with the Golden Parachute Legacy
upgrade - previewed exactly as `refactor_carryover_preview` (and `refactor_carryover_pct`). The
new run starts with the 50 starting coins plus that carry-over.
Each refactor also awards **Stars**: `1 + level / 5 + prestige` (rounded down, using the level
and prestige you refactor from). Stars are never reset and are spent on permanent **Legacy
upgrades**. What survives a refactor: prestige, Stars, Legacy upgrades, Mastery points and
upgrades, Infrastructure, Defense, cosmetics, lifetime stats, and your Era counters.
## Community treasury and weekly grant
Every refactor fee flows into a shared **community treasury**. Once per week, an active farm that
is still building up - at least five harvests this week, fewer than 10,000 coins, and at most
prestige 5 - can claim a grant of up to 2,500 coins from it with `POST /game/grant`. The state
reports `grant_available`, `grant_amount`, `grant_reason`, and the current `treasury_balance`.
Every refactor fee flows into a shared **community treasury**. Once per ISO week, an active farm
that is still building up - at least **5 harvests this week**, fewer than **10,000 coins**, and
at most **prestige 5** - can claim a grant of up to **2,500 coins** (capped by the treasury
balance) with `POST /game/grant`. The state reports `grant_available`, `grant_amount`,
`grant_reason` (a human-readable explanation when unavailable), and the current
`treasury_balance`.
## Legacy upgrades
Stars buy Legacy upgrades, permanent boosts that persist through every future refactor. There are
six:
Stars buy Legacy upgrades, permanent boosts that persist through every future refactor. The cost
of level `n+1` is `round(base * growth^n)` Stars. There are six:
| Legacy upgrade | Effect | Max level |
|----------------|--------|:---------:|
| 🤖 CI Bot | Auto-collect ready builds when you open your farm | 1 |
| 💎 Tech Debt Payoff | +10% harvest coins per level, stacks with refactor | 10 |
| 🏎️ Bare-Metal | +5% base build speed per level | 8 |
| 🗂️ Monorepo | +1 starting plot after each refactor per level | 4 |
| 🛡️ Branch Protection | +30s steal grace and -5% steal loss per level | 5 |
| 🪂 Golden Parachute | +5% refactor coin carry-over per level | 5 |
| Legacy upgrade | Key | Effect | Max level | First cost | Cost growth |
|----------------|-----|--------|:---------:|-----------:|:-----------:|
| 🤖 CI Bot | `autoharvest` | Auto-collect ready builds whenever you load your farm | 1 | 3 | - |
| 💎 Tech Debt Payoff | `multiplier` | +10% harvest coins per level, stacks with refactor | 10 | 1 | 1.6x |
| 🏎️ Bare-Metal | `speed` | +5% base build speed per level | 8 | 1 | 1.7x |
| 🗂️ Monorepo | `plots` | +1 starting plot after each refactor per level | 4 | 3 | 2.0x |
| 🛡️ Branch Protection | `defense` | +30s steal grace and -5% steal loss per level | 5 | 2 | 1.8x |
| 🪂 Golden Parachute | `carryover` | +5% refactor coin carry-over per level | 5 | 2 | 1.8x |
The live state reports your `stars` balance and each legacy upgrade's current level and the exact
star cost of its next level.
Star cost of its next level.
## Leaderboards and scoring
The default leaderboard ranks the top farms by a composite score. Refactors dominate the formula,
then lifetime harvests, level, and everything else:
The default leaderboard ranks the top 25 farms by a composite score. Refactors dominate the
formula, then lifetime harvests, level, and everything else:
```
score = xp
@@ -244,19 +358,32 @@ score = xp
+ min(streak, 30) * 15
```
Read the top farms with `GET {{ base }}/game/leaderboard` (public, no account needed). Add
`?board=` to switch boards - `score` (default), `prestige`, `harvests` (this week only), `raids`
(average coins per successful raid over the last 30 days, minimum 3 qualifying raids), `time_to_kernel`
(fastest to harvest a Kernel after your last refactor), `fair_play` (rewards recent activity over
hoarding coins), and `era` (the current Era's board, empty when no Era is running - see below).
Read the top farms with `GET {{ base }}/game/leaderboard` (public, no account needed; results are
cached server-side for about 15 seconds). Add `?board=` to switch boards:
| Board | Ranked by |
|-------|-----------|
| `score` | The composite score above (default). |
| `prestige` | Prestige count, Stars as tiebreak. |
| `harvests` | Harvests this ISO week (`harvests_week`). |
| `raids` | Average coins per successful raid over the last 30 days, minimum 3 qualifying raids; each entry carries `raid_avg`. |
| `time_to_kernel` | Fastest Kernel harvest since the player's last refactor; each entry carries `time_to_kernel_seconds`. |
| `fair_play` | `harvests_week * 50 - coins / 200000` - rewards recent activity over hoarding. |
| `era` | The current Era's score (below); empty when no Era is running. |
Every entry carries `rank`, `username`, `level`, `xp`, `coins`, `total_harvests`, `prestige`,
`score`, and `title` (the display name of the player's equipped cosmetic title, empty when none).
## Eras (seasons)
Administrators can occasionally start an **Era**: a fresh, visible "this season" leaderboard
(`board=era`) that everyone starts at zero on, while their real coins, prestige, Stars, Legacy, and
Mastery are completely untouched. When an Era ends, the top 10 by Era score earn permanent Stars
(and sometimes an Era-exclusive cosmetic). The state reports `era_active`, `era_name`, `era_coins`,
and `era_harvests` when one is running.
(`board=era`) that everyone starts at zero on, while their real coins, prestige, Stars, Legacy,
and Mastery are completely untouched. Era score is `era_coins / 20 + era_harvests * 10 + prestige
* 2000`, so veterans keep an edge without it being insurmountable. When an Era ends, the top 10
by Era score earn permanent Stars (50, 30, 20, 15, 10, then 5 each for ranks 6-10) and sometimes
an Era-exclusive cosmetic. Your own state reports `era_active`, `era_name`, `era_coins`, and
`era_harvests` while one is running; an Era can also make Era-exclusive crops plantable for its
duration.
## Live updates
@@ -276,6 +403,7 @@ your **API key** in an `X-API-KEY` header (or `Authorization: Bearer`). Your key
| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/game` | Your farm page (HTML, or the same JSON as `/game/state` when asked). |
| `GET` | `/game/state` | Your full farm state (always JSON). |
| `GET` | `/game/leaderboard` | Top farms (public). Accepts `?board=`. |
| `GET` | `/game/farm/{username}` | Another member's farm. |
@@ -289,7 +417,7 @@ your **API key** in an `X-API-KEY` header (or `Authorization: Bearer`). Your key
| `POST` | `/game/quests/claim` | Claim a completed quest by `quest` kind, optional `scope` (`daily` or `weekly`). |
| `POST` | `/game/prestige` | Refactor at level 10 or above; costs the current `refactor_cost` in coins. |
| `POST` | `/game/grant` | Claim the weekly community grant from the treasury. |
| `POST` | `/game/legacy` | Buy a legacy upgrade (`key`) with stars. |
| `POST` | `/game/legacy` | Buy a Legacy upgrade (`key`) with Stars. |
| `POST` | `/game/mastery` | Buy a Mastery upgrade (`key`) with Mastery points. |
| `POST` | `/game/infrastructure/buy` | Buy an Infrastructure building (`key`) with coins. |
| `POST` | `/game/defense/upgrade` | Buy the next Defense tier with coins. |
@@ -299,9 +427,36 @@ your **API key** in an `X-API-KEY` header (or `Authorization: Bearer`). Your key
| `POST` | `/game/farm/{username}/steal` | Raid a neighbour's unprotected ready build in `slot`. |
POST bodies are form encoded (`application/x-www-form-urlencoded`). Form fields are `slot` (an
integer plot index), `crop`, `perk`, `quest`, `scope`, and `key` (a legacy/Mastery/Infrastructure/cosmetic
key) where the table notes them. Every POST returns the full farm under `farm`, so one call both
performs the action and gives you the new state.
integer plot index, 0-based), `crop`, `perk`, `quest`, `scope`, and `key` (a
Legacy/Mastery/Infrastructure/cosmetic key) where the table notes them. Every own-farm POST
returns `{"ok": true, "farm": {...}}` - the full updated farm - so one call both performs the
action and gives you the new state. The two neighbour actions return the **neighbour's** farm as
you see it (`{"farm": {...}}`), and a successful steal adds `"stole_coins"` with your payout.
### Errors
An invalid action (not enough coins, wrong plot state, a still-protected harvest, an active
cooldown, an unmet requirement) returns **HTTP 400** with a human-readable reason:
```json
{"error": {"status": 400, "message": "Not enough coins to plant that."}}
```
An unknown farm username is **404**. Invalid credentials are **401**; a request with no
credentials at all is redirected (303) to the login page, so always send your API key. Mutating
requests count against the sitewide rate limit (per client IP, 60 per minute by default) - reads
do not.
### Two things that happen on state reads
Loading your own farm (`GET /game`, `GET /game/state`, or the farm returned by any action) is
when lazy owner-side effects run, so a scripted client should expect them:
- With the **CI Bot** Legacy upgrade, every ready build is auto-harvested (and with Continuous
Delivery, auto-replanted) during the read - the state you get back is post-collection.
- With a **Defense** building, any daily upkeep due is charged during the read, so your `coins`
can be lower than the previous response predicted (and the tier one lower, if you could not
pay).
### Reading the state
@@ -320,10 +475,10 @@ for plot in farm["plots"]:
print(plot["slot"], plot["state"], plot.get("crop_name"), plot.get("remaining_seconds"))
```
### The farm state shape
### The plot shape
`GET /game/state` returns `{"ok": true, "farm": {...}}`. The farm carries your totals plus three
lists you act on: `plots`, `crops`, and `quests`. A plot looks like this:
`GET /game/state` returns `{"ok": true, "farm": {...}}`. The farm carries your totals plus the
lists you act on. A plot looks like this:
```json
{
@@ -331,7 +486,8 @@ lists you act on: `plots`, `crops`, and `quests`. A plot looks like this:
"state": "growing",
"crop_key": "python",
"crop_name": "Python Script",
"reward_coins": 45,
"crop_icon": "🐍",
"reward_coins": 36,
"reward_xp": 5,
"ready_at": "2026-06-23T12:34:56+00:00",
"remaining_seconds": 73,
@@ -340,13 +496,58 @@ lists you act on: `plots`, `crops`, and `quests`. A plot looks like this:
"can_water": false,
"can_steal": false,
"steal_coins": 0,
"steal_cooldown_seconds": 0,
"steal_reason": "",
"is_golden": false,
"fertilize_cost": 22
}
```
A plot's `state` is `empty`, `growing`, or `ready`. An entry in `crops` carries the live `cost`,
`reward_coins`, `grow_seconds`, `min_level`, and a `locked` flag, so a client can decide what is
both unlocked and affordable without hard-coding the table above.
A plot's `state` is `empty`, `growing`, or `ready`. `reward_coins`/`reward_xp` on a plot are the
crop's **base** rewards; the multiplied live values are on the matching entry in `crops`. An
entry in `crops` carries the live `cost`, `reward_coins`, `reward_xp`, `grow_seconds`,
`min_level`, `market_state`, and a `locked` flag, so a client can decide what is both unlocked
and affordable without hard-coding the tables above.
### The farm state reference
Every field on the `farm` object, grouped. Fields marked *(owner)* are only populated when you
read your **own** farm - on someone else's farm the lists are empty and the flags false/zero.
**Identity:** `owner_username`, `owner_uid`, `is_owner`.
**Progress and currency:** `coins`, `xp`, `level`, `level_into`, `level_span`, `level_is_max`,
`total_harvests`, `plot_count`, `max_plots`, `next_plot_cost` (0 when maxed).
**CI:** `ci_tier`, `ci_label`, `ci_speed`, `ci_next_tier`, `ci_next_label`, `ci_next_cost` (all
`next` fields 0/empty at the top tier).
**Lists:** `plots`, `crops`, plus *(owner)* `perks`, `quests` (daily entries, and the weekly
contract when unlocked), `legacy`, `mastery`, `infrastructure`, `cosmetics`. Each purchasable
entry carries `key`, `name`, `icon`, `description`, its current `level`/`owned` state, the exact
next `cost`, and a `maxed` flag where applicable.
**Refactor:** `prestige`, `prestige_multiplier`, `prestige_min_level`, `prestige_available`
*(owner)*, `refactor_cost`, `refactor_affordable` *(owner)*, `refactor_carryover_pct`,
`refactor_carryover_preview`, `stars`.
**Grant and treasury** *(owner)*: `grant_available`, `grant_amount`, `grant_reason`,
`treasury_balance`.
**Daily:** `streak`, `daily_available` *(owner)*, `daily_reward`.
**Raiding:** `steal_cooldown_seconds` (your remaining cooldown against this farm's owner; 0 on
your own farm).
**Mastery and lifetime stats:** `mastery_points`, `mastery_points_earned_total`,
`mastery_analytics_unlocked`, `lifetime_coins_earned`, `lifetime_harvests`, `harvests_week`.
**Defense:** `defense_level`, `defense_tier_name`, `defense_upkeep_daily`, `defense_next_cost`
(0 at the top tier).
**Cosmetics and boosts:** `active_title`, `underdog_boost_seconds_remaining`.
**Era:** `era_active`, `era_name`, `era_coins`, `era_harvests`.
### A complete automated farmer
@@ -395,9 +596,11 @@ def best_affordable_crop(farm):
def claim_free_rewards(farm):
if farm.get("daily_available"):
call("POST", "/game/daily")
if farm.get("grant_available"):
call("POST", "/game/grant")
for quest in farm.get("quests", []):
if quest.get("can_claim"):
call("POST", "/game/quests/claim", {"quest": quest["kind"]})
call("POST", "/game/quests/claim", {"quest": quest["kind"], "scope": quest["scope"]})
def harvest_and_replant(farm):
@@ -438,9 +641,10 @@ if __name__ == "__main__":
From here the natural extensions are easy: spend surplus coins with `POST /game/buy-plot` and
`POST /game/upgrade` when you can afford them, raise perks with `POST /game/perk`, water
neighbours by walking `GET /game/farm/{username}` and posting to its `/water` path for plots where
`can_water` is true, and refactor with `POST /game/prestige` once `prestige_available` is set. Be
polite to the rate limiter: mutating calls are limited per account, so a poll interval of a minute
or more with one action per finished build stays well within limits.
`can_water` is true, raid where `can_steal` is true, and refactor with `POST /game/prestige` once
`refactor_affordable` is set. Be polite to the rate limiter: mutating calls are limited per
client, so a poll interval of a minute or more with one action per finished build stays well
within limits.
## Ask Devii