Premium

Premium membership lets you build more at once in every village, keep a research queue instead of one research at a time, save layouts as templates you can stamp onto any village, castle or garrison, set up auto-scouting the way you want it, have villages share and sell their surplus on their own, keep their soldiers topped up, and clear nearby camps on their own. Right now premium can only be granted by an admin. There is no way to buy it in game, with Crowns or otherwise.

The basics

Perk	Without premium	With premium
Buildings under construction at once, per village	2	4
Buildings waiting for builders, per village	3	8
Researches in hand (one running, the rest queued)	1	3
Layout templates	not available	10 per kind (village, castle, garrison)
Auto-scouting	stashes and herds, 15 cells, every 4 game hours, 1 scout per village	choose targets, 25 cells, every 2 game hours, up to 5 scouts per village (see Automation)
Auto-transport	not available	caravans keep each good between levels across your villages (see Automation)
Auto-hiring	not available	keep each village's soldiers topped up to set numbers within gold and peasant reserves (see Automation)
Auto-fighting	not available	march on nearby tier I camps your villages outmatch, on a fresh scout report (see Automation)
Auto-selling	not available	sell what villages hold above set levels at the best market in reach (see Automation)

• Premium is active while its end time is in the future. When it runs out, the extra slots and template use stop on their own.
• Nothing you already started is cancelled when premium ends. Templates you saved are kept.
• Research slot cards add to whatever slots you have, premium or not (see cards-and-crowns.md).

How premium is granted

An admin grants premium by lord name and a number of days.

• A positive number of days extends premium. If you already have premium, the days are added to your current end time. If not, they count from now.
• Zero or a negative number revokes premium immediately.
• One premium day is 86,400,000 ms (24 real hours) regardless of world speed. Unlike most timers in the game, premium length is not divided by world speed.

When premium is granted or revoked through the admin panel, every village of that lord is refreshed at once, so buildings waiting in the queue start straight away if the new slot count allows. When premium simply runs out, the server notices on its next tick and does the same refresh.

Construction slots

Each village can have a limited number of buildings under construction at the same time. Further buildings you place wait in the queue and start as slots free up.

slots = premium ? max(premiumBuildSlots, buildSlots) : buildSlots
      = premium ? max(4, 2) : 2

The limit is per village, so a lord with three villages and premium can have up to 12 buildings going up at once.

When premium ends, buildings already under construction keep going and finish normally. Only new starts are held to 2. If four are under construction when premium lapses, the next queued building starts only after three of them have finished.

Premium also lets more buildings wait behind the builders:

waiting = premium ? max(premiumBuildQueue, buildQueue) : buildQueue
        = premium ? max(8, 3) : 3

When premium ends, buildings already waiting stay in the queue and start in turn. You cannot add more until fewer than 3 are waiting. See village.md for queue order and finish estimates.

Castle construction has its own slot count (2 per castle) and premium does not change it. See castles.md.

Research queue

Only one research runs at a time. Research slots are how many you can have in hand: the one running plus those queued behind it.

research slots = (premium ? max(premiumResearchSlots, researchSlots) : researchSlots)
               + extra slots from cards
               = (premium ? 3 : 1) + cards

With premium you can queue two researches behind the active one. A queued research may depend on one ahead of it in the queue. Research points are paid when you queue, and cancelling refunds the points in full, along with any queued research that needed the cancelled one.

Queued research runs back to back, each starting when the last one ended, even while you are offline. Worked example: you queue Forestry and then Carpentry and log off for longer than both take. When the server next settles your research, both are done, and Carpentry's start time is the moment Forestry finished, not the moment you came back.

Card slot bonuses stack on top: Extra Scribes (+1) and College of Scribes (+2) together with premium give 3 + 1 + 2 = 6. See research.md.

Layout templates

A template is a named, saved layout you can apply to any of your villages later. There are three kinds:

Kind	What it saves	Anchor
Village	Every building that is not a fixed building, by type and position	The village hall
Castle	Every castle piece that is not fixed, by type, position and rotation	The castle keep
Garrison	Where soldiers stand, by unit type, position and count	The castle keep

Positions are stored as offsets from the anchor, so a template saved in one village lines up around the hall (or keep) of another village wherever that hall stands.

Saving

• Needs active premium.
• Names are trimmed to 32 characters. Control characters and the < and > characters are removed. An empty name is refused.
• Saving with a name you already used for that kind (ignoring upper and lower case) overwrites the old template instead of making a new one. Overwriting does not count against the cap.
• Up to 10 templates per kind. A full kind refuses new names until you delete one.
• A template holds at most 400 items. Anything beyond the first 400 is dropped when saving.
• Saving an empty layout is refused ("Nothing to save yet").

Applying

Needs active premium. What happens depends on the kind.

Village and castle templates go through each saved item in order and place it as if you had placed it by hand: normal cost, rank and research requirements, and placement rules all apply. Placed buildings join the normal construction queue, so with premium four start at once and the rest wait. Items already standing at exactly that spot are skipped silently. Items that cannot be placed are skipped and reported with the reason, for example not enough wood or the spot being blocked. You get back how many were placed and the list of skipped items.

Worked example from the tests: a village template holds three hovels. You apply it with wood for only two. Two hovels are queued and one is reported as skipped for lack of resources. After gathering more wood you apply the same template again: the two standing hovels are passed over and only the missing one is placed.

Garrison templates replace the castle's current garrison. Each saved spot is filled with up to the saved number of soldiers of that type, limited by the troops at home in the village and by how many the spot holds. Spots that come up short are reported as skipped. The "placed" count for a garrison is the number of soldiers placed, not the number of spots.

When premium ends

Saving and applying are refused with "Templates are a premium perk." Your templates stay stored, and you can still delete them. If premium returns, they are usable again.

Interactions

• automation.md: auto-scouting settings, auto-transport, auto-selling, auto-hiring and auto-fighting, which need premium.
• village.md: construction queue and building placement rules that templates go through.
• research.md: the research tree and how the queue settles.
• cards-and-crowns.md: research slot cards, build speed cards and finish-queue cards that combine with premium slots.
• castles.md: castle pieces, the castle's own build slots, and garrisons.
• military.md: troops at home, which garrison templates draw on.
• ranks-and-renown.md: rank requirements that can make template items skip.
• getting-started.md, profile.md.

For maintainers

Source files:

• server/src/features/premium/index.ts: setPremiumDays, refreshPremium, the constructionSlots and buildQueue modifiers, lapse detection in tick, template message handling.
• server/src/features/premium/templates.ts: template storage, name and item cleaning, cap, village capture and apply.
• server/src/features/premium/premium.test.ts: behaviour tests.
• server/src/features/registry.ts: isPremium (premium.until > now).
• server/src/features/castle/index.ts and castle/logic.ts: castle and garrison template kinds (layoutItems, applyLayout, garrisonItems, fitGarrison), castle constructionSlots.
• server/src/features/research/index.ts: researchSlotsOf.
• server/src/features/admin/index.ts: adminGrantPremium.
• server/src/village/sim.ts: combineModifiers (highest constructionSlots and buildQueue win), startQueued and the queue_full check in placeBuilding.
• packages/protocol/src/features/premium.ts: template types and messages.
• server/src/tuning.ts: premium block.

Key constants:

Constant	Value	Live-tunable	Where
premium.buildSlots	2	yes, 1 to 50	tuning.ts
premium.premiumBuildSlots	4	yes, 1 to 50	tuning.ts
premium.buildQueue	3	yes, 0 to 100	tuning.ts
premium.premiumBuildQueue	8	yes, 0 to 100	tuning.ts
premium.researchSlots	1	yes, 1 to 20	tuning.ts
premium.premiumResearchSlots	3	yes, 1 to 20	tuning.ts
premium.templateCap	10 per kind	yes, 0 to 100	tuning.ts
MAX_ITEMS	400 per template	no	templates.ts
Template name length	32 characters	no	templates.ts
Castle construction slots	2	no	castle/content.ts
Premium day	86,400,000 ms, not scaled by world speed	no	premium/index.ts