Dev blog: Charters and their structures

The problem

Haven is the only home, and Layer 6 has none.

Haven is a safe station at 8, 8 on every layer but Layer 6. It builds Patrol through Destroyer and nothing bigger.

Cruiser and Carrier hulls are built at a charter shipyard, and class 4 and 5 jobs need a charter Shard sum. On Layer 6 there is no Haven to dock at, so a charter berth is the only dock there.

We wanted a group that holds ground without trapping anyone. A pilot's Shard stays theirs, and they can walk out with it.

Layer 1 around the Haven station. The station sits in the middle of the map. Two incursions are marked on the hexes, rock clusters mark belts, and the fleet column on the left lists six berthed Carriers. A button at the lower right offers travel up to Layer 2. — Haven on Layer 1, from a store screenshot taken with a dev account, so the Marks and the six Carriers are not what a new pilot has. Charters never build on Haven or on the six sectors around it.

What we wanted instead

Three rules we kept.

The design document pitches a charter that can hold a yard without trapping anyone who levelled it. Three rules came out of that.

Your Shard is yours

Leave a charter and your Resonance Shard comes with you. Get removed and it stays yours. Nobody can zero another pilot's Shard.

The charter holds the ground

Nobody owns a structure but the charter, and only its lead or a quartermaster can build one. When a charter ends, its modules come down and the bills wait at Haven.

Every module shoots

Every module carries a gun. It fires at hostile charters and at anyone who attacks, and it needs no member at the controls.

What we built: the people

Five roles and one Shard sum.

A charter is a list of pilots with a role each. Its Shard sum adds up their levels, and the sum opens services. There is no limit on members, and founding costs nothing.

5roles: Lead, Quartermaster, Warden, Member and Recruit

50 and 200charter Shard sums that open the Cruiser and Carrier lines

1 percentof a member's level leaves the sum for each full day they are away

14 daysa lead can stay away before the seat passes on

LeadOne seat. Sets roles and does everything a quartermaster does. Naming another pilot lead hands the seat over, and the old lead becomes a Member.

QuartermasterBuilds, repairs, packs up and upgrades structures. Withdraws from storehouses. Sets charter standings. Invites, and removes anyone ranked below.

Warden, Member, RecruitA Warden may invite. A Member and a Recruit may not. All three can deposit in a storehouse, dock at a berth and jump between the Post and outposts. New joiners start as Recruits.

What the sum opens

A sum of 50Cruiser hulls at a charter shipyard and class 4 jobs. Refining yields 5 percent more and research runs 10 percent faster.

A sum of 200Carrier hulls and class 5 jobs. Refining yields 10 percent more and research runs 20 percent faster.

A charter of one counts, so a solo pilot at Shard 50 clears the first line. The refining figures are marked stand-ins in the balance file. The industry side of these unlocks belongs to another post.

Staying and leaving

The sum is live, and the seat does not stick.

Each full day away takes 1 percent of a member's level out of the sum, and after 100 days they count for nothing. One login restores them. Their own Shard never drops.
If the lead stays away for 14 days, the seat passes to the quartermaster who counts most, or to the member who counts most when there is no quartermaster. A tie goes to the longer membership.
A pilot who is removed cannot rejoin for a day. A pilot who leaves keeps their Shard.

Boards and chat

Where a charter shows up.

Journal > Leaders has a Charters board: the top ten charters by Shard sum.
Coming in 0.5.3, two more boards rank charters by Titans felled and by Dreadnoughts built.
Charter chat is a channel of its own in the chat dock, open to members only.
Join or found a charter is one of the eight first-week tasks, and Help > Tutorials has an unpaid Charter and trade topic that uses a practice pilot.

What we built: the ground

Six modules, and the Post comes first.

A charter builds on Layer 4, Layer 5 and Layer 6. The lead or a quartermaster flies the active ship to a sector, picks a module in Charter > Structures and presses Build here. The bill leaves their stash and the clock starts.

PostRequired before any other module. Pings the charter when hit. Every shipyard pauses while it is offline. Hull 20,000, gun 140.1 · 8 h

ShipyardBuilds Cruiser and Carrier hulls, one at a time per yard, while the Post is online and the sum is 50 or 200. Hull 8,000, gun 50.2 · 4 h

GarrisonThe strongest gun, 200 a shot. It covers its own sector and every sector one step out. Hull 11,000.3 · 4 h

StorehouseCharter stock. Any member stores materials and modules. The lead and quartermasters take them out. Hull 8,000, gun 50.3 · 2 h

BerthDock in place to refill, refit and repair without the trip to Haven. No market, broker or industry. Hull 6,000, gun 50.3 · 2 h

OutpostSees its own sector and up to five sectors out. A jump point with the Post and the other outposts. Hull 4,000, gun 50.6 · 1 h

Each tag is the cap per charter and the build time. A full set is 18 modules. Hull is the design table times 200, and a gun is the design table times 2, one shot every 2 seconds.

14 hof Layer 4 combat income is the balance note's target for a Post, not a measured figure

18,200 Platefor a full set of 18, with 12,560 Cell, 10,640 Cable and 2,600 Trace

2 sbetween shots from any one module

7 daysa disbanded charter's bills wait at Haven

A Post costs 3,000 Plate, 2,000 Cell, 2,000 Cable and 1,000 Trace. Every bill is a stand-in in the balance file, chosen by us when the owner asked, and testers will tune them.

Where a module may stand

Not just anywhere.

Layer 4, Layer 5 or Layer 6. Coming in 0.5.3: any of the six Rifts, on the same rules and with the same bills.
Not on Haven or the six sectors around it, not on a wormhole end, and not in an incursion sector.
One charter to a sector, and one module of each kind. The home sector can hold one of each, Post included.
Separate structure sectors sit at least two sectors apart. A charter's own Garrison and Outpost may touch.

What happens to it

A module stays put until someone moves it.

A layer storm reshapes the map around a structure and leaves its sector open and joined to the rest. Storms have their own post.
Hull does not heal on its own. A damaged module stays damaged until someone pays to repair it.
Pack up an online module with a ship in its sector and the whole bill and any stock go to your stash. The Post packs last.
If a charter ends, every module comes down. Bill and stock wait seven days at the Haven of the layer it stood on, for the last lead. Layer 6 has no Haven, so those wait at Layer 5.

Guns, garrisons and going offline

Who it shootsPilots of a charter that the lead or a quartermaster set to Hostile or KOS, pilots they marked the same way, anyone who fired on a module or a member in range in the last 120 seconds, and NPCs locking a member. A neutral passing through is left alone, and so is a ship in its arrival flag.

How it goes downAt 0 hull a module goes offline. A Post offline pauses every shipyard. A berth stops docking. An outpost loses its vision and leaves the jump network. A Garrison stops shooting. A Storehouse keeps its stock and locks withdrawals. A module still being built cannot be shot.

How it comes backThe lead or a quartermaster repairs from the Sector card with a ship there. The cost is a quarter of the bill scaled by the damage, plus 50 Marks for each missing design point. A Post from zero, which has 100 design points, costs 5,000 Marks, 750 Plate, 500 Cell, 500 Cable and 250 Trace.

Outposts and jumps

A jump is one click and a five minute wait.

With a ship at the Post or an online outpost, the Sector card shows a Jump button for every other point. Every ship of yours in that sector goes. A ship that is firing, locked on a target, or held by an enemy lock or clamp cannot jump, and one such ship holds back the whole jump.

The ships land with a 60 second flag: they cannot fire and nobody can lock them. Then each ship waits 5 minutes before it can jump again. A vision upgrade takes an hour and costs 40 Plate, 20 Cell and 20 Cable times the level reached.

The numbers

60 sno-fire arrival flag after a jump

5 minbefore that ship jumps again

1 to 5vision levels, one hour each

7 to 91sectors an outpost can see at most, from level 1 to level 5

Storehouses

A storehouse works with a ship in its sector. Any member puts materials and modules in. The lead and quartermasters take them out. If it goes offline the stock stays and the doors lock until it is repaired. Blueprints do not go in: they stay with pilots.

Coming in 0.5.3: building in any Rift

A charter will be able to build in any of the six Rifts. A Rift has no Haven, so a module that comes down there waits at the Haven of the layer the Rift matches. Layer 6 has no Haven either, so Rift 6 modules wait at Layer 5. The six Rifts have their own post.

As a pilot lives it

Found it, fill it, hold it.

The server owns every step: the roles, the placement, the bills and the guns. The client sends an order and draws the answer.

FoundPress Charter, type a name of one or two plain words, press Found charter. No leading The, no apostrophe, and not taken. You are the lead.
InviteA Lead, Quartermaster or Warden types a pilot's name. The pilot accepts under Invites and starts as a Recruit. The lead sets roles from a dropdown on the Members tab.
ClaimThe lead or a quartermaster flies the active ship to a legal sector on Layer 4, 5 or 6 and builds the Post. Eight hours on the wall clock.
Fill inShipyards, garrisons, storehouses, berths and outposts, each with a ship on the spot and each two or more sectors from the next structure sector.
HoldWhen a module is hit, every member gets a log line and an Alert, once a minute per module at most. Repair, Jump, Vision and Pack up are buttons on the Sector card.

LogCharter North Cut founded. You are its lead.

LogJoined North Cut as a recruit. Your Shard adds to its sum.

LogPILOT started a Post on Layer 4 5, 5. Ready in 8 h.

LogPost on Layer 4 5, 5 is online.

LogStructure sectors sit at least two sectors apart.

LogYour Garrison on Layer 4 5, 5 is under attack by PILOT. Hull 62%.

LogYour Garrison on Layer 4 5, 5 is offline. Repair it with Marks and materials.

LogJumped 3 ships to the Outpost on Layer 4 8, 5. They cannot fire or be locked for 60 s.

The wording is copied from social.py and structures.py. The server fills in the names, the layer, the cell and the hull, and we wrote PILOT where it puts a pilot's name. North Cut is the sample name the design document uses.

In the sector

Everything a module can do is a button on the card.

With a ship in the sector, the Sector card lists each module there with its state and hull. Your own modules offer Repair, Jump, Vision and Pack up. A stranger's offers Attack. The log at the lower left shows the same kinds of lines as the box above.

The Journal's Contracts tab is open in the middle of the screen. At the lower right the Sector card lists a Post and a Storehouse of one charter, both online at 100 percent hull, each with a Pack up button, and a Jump button to an Outpost. At the lower left the log shows lines about an Outpost and a Shipyard being started and a Post coming online. — An early alpha capture on a private test server with a dev account. The Contracts tab happens to be open and is not the subject. Look at the two lower corners. Layer 4 is still named Claim here.

Under the hood

Two mixins, one tick, one saved list.

Charters live in server/social.py, 291 lines. Structures live in server/structures.py. About 670 of its 1,172 lines are the structures, and the rest is the 0.5.3 hangar, which has its own post. Both are mixins on the World class, and both save in the shared world record.

Charterssocial.py holds chat channels, the charter record, invites, roles, contribution decay, succession and the charter view the client reads.

Structuresstructures.py holds the module tables, placement, build, repair, pack up, vision, jumps, storehouse stock, the guns and the disband.

Around themstandings.py keeps the Hostile and KOS book the guns read. rules.py keeps the name rule and the layer names. layout.py keeps structure sectors open through storms.

One module, from bill to repair

BuildThe lead or a quartermaster sends the build order. The server checks role, ship and placement, then takes the bill._structure_build, _placement_problem
Come onlineEvery tick compares the clock to the finish time. At zero the module is online and the charter is told._tick_structures
Spot a hostileEvery two seconds an online module looks for a pilot who is not a member and is hostile to the charter._structure_fire, _structure_hostile_to
FireIt hits the first match in reach with the shared damage code. A garrison reaches one sector out._hurt_ship, _hurt_npc
Take a hitA pilot who locks a module becomes a target of that charter's modules in reach for 120 seconds, and the shots land on the module's hull._attack_structure, _tick_structure_guns_for, _hurt_structure
Down and upAt 0 hull the module goes offline and the charter is told. A paid repair brings it back._hurt_structure, _structure_repair

The main functions

_placement_problemstructures.py

Every placement rule in one function that returns the refusal text, or an empty string. Build and the tests both call it.

_shard_sumsocial.py

Adds each member's level less 1 percent a day away. It is worked out on every read, so there is no stored sum to drift.

_charter_maintainsocial.py

Passes the lead seat on after 14 days away. It runs when a charter view is built, so it takes effect when a member next loads a snapshot.

_structure_firestructures.py

One shot per module per cycle: the first hostile pilot in reach, else an NPC locking a member.

_structure_jumpstructures.py

Moves every ship of the pilot in the source sector, sets the 60 second flag and the 5 minute cooldown.

_disband_modulestructures.py

Removes a module whose charter is gone and files a seven day claim for its bill and stock at a Haven.

_paint_structuresmain.gd

Draws the lettered diamonds, the vision ring and the relation colours. It decides nothing.

Choices we are happy with

One table per factThe caps, hours, hulls, guns and bills are plain dictionaries at the top of structures.py, each with a row in the balance file. The structures view sends them to the client, so the Charter screen shows the server's numbers.

A sum that cannot driftThe Shard sum is worked out from the members every time. Leaving, removal and staying away change it with no bookkeeping.

AnchorsStructure sectors go to the layout generator as anchors, so a storm cannot bury a charter. The same hook keeps incursion sectors open.

One damage pathStructure guns call the same hurt functions that ship and NPC fire call, with the charter and module name as the source. A garrison shot is an ordinary hit.

The client side

The server owns it all. The client draws and asks.

client/features/charter_panel.gd builds the Overview, Members, Structures and Standings tabs, and the Hangar tab that is coming in 0.5.3. It reads the build tables from the server.
client/features/sector_card.gd offers Attack, Repair, Jump, Vision and Pack up. Each button sends an order and nothing else.
client/main.gd paints one lettered diamond per module: P, Y, G, S, B and O. Colour is the relation, grey is offline, an outline is still building, and your own online outposts draw a vision ring.

What the code looks like in numbers

291lines in social.py

1,172lines in structures.py, hangar included

853lines in charter_panel.gd

7 and 7server orders for charters and for structures and stock

What the tests prove

What is pinned, and what is not.

The tests live in server/test_alpha.py, in the CharterTest and StructuresTest classes, with the standings tests and two Rift tests beside them. The eleven tests in those two classes passed when we ran them for this post. The pre-commit hook runs the whole suite on every commit.

Pinned

test_found_invite_join_roles_kick_and_sum: founding, a taken name, invites, a Recruit start, the sum, who can invite, who can remove whom, and the one day block after a removal.
test_contribution_decays_and_a_leaving_lead_hands_on: a level 50 member ten days away counts 45, and a lead gone 15 days hands the seat on.
test_post_first_placement_rules_and_build_time: Post first, the 8 hour clock, the cap, two sectors apart, Layer 4 to 6 only and the role gate.
test_no_structure_on_a_wormhole_sector: the 0.5.2 fix.
test_guns_shoot_hostiles_go_offline_and_repair: a neutral is left alone, a Hostile pilot is shot, 0 hull goes offline, and a Post repair costs 5,000 Marks.
test_attacking_a_structure_marks_the_attacker and the berth, storehouse, shipyard and disband tests beside it.
test_tutorial_blocks_bounties_and_structures: no structure orders in the tutorial.

Not pinned, or thin

No test reads a Garrison's one sector reach, pack up, an outpost's vision radius or its upgrade, or a shot at an NPC that locks a member.
No test checks the alarm line or its 60 second gap. Every module sends it, not only the Post as the help text says.
The playtest check builds one Post on Layer 4 and stops. No check builds a full set of 18.
As the code reads today, outpost vision is counted over the 20 by 20 box the layers use. A Rift is 28 wide, so an outpost far out in a Rift would see less than its level says, and near the edge it would see nothing. No test covers it. We found it while writing this post.
Pack up sends all the stock to the pilot who packs, not back to whoever deposited it. Nothing in the balance files tunes the full refund of the bill.
The Charters board does not show your own rank when your charter is outside the top ten. The pilot boards do.

What we learned and what is next

The numbers are guesses we named.

A retired list hid a bugUntil 0.5.2, placement read a function that an earlier design retired and that always returned nothing, so no structure ever refused a wormhole sector. Placement now reads every wormhole end on the layer, and a test pins it.

Review caught the edgesThe review of the first build led to fixes, among them: a module still being built cannot be shot, pack up needs the module online, a yard takes one hull, and a held ship cannot jump.

Stand-ins stay labelledWe chose the bills and the scales when the owner asked us to. The bills are marked stand-ins in the balance file. The module comments call the hull and gun scales, the gun cycle and the repair cost stand-ins too, though the file does not flag them.

Where we would push next

Coming in 0.5.3: charters may build in any of the six Rifts.
Check outpost vision in a Rift and give it a test. It is not in a build yet.

The public roadmap lists a clearer map, with bigger structure markers at low zoom, a legend and outpost vision, and balance passes on structure prices. Neither has a version.
The design document asks for permission checkboxes and a daily withdrawal cap. The build has five fixed roles and no cap. No build has either.

Coming in 0.5.3, the Charter screen gets a Hangar tab. A charter keeps a Dreadnought there, behind a higher Shard sum than the Carrier yard asks for. The Dreadnought has its own post, so we leave the rest to it.

Join the open alpha

Found a charter and see what holds.

Keel is free to play on PC, and the open alpha is where charters live. Find us in the Keel Discord, tell us what a charter did to your evening, and file a report from inside the game when something looks wrong.

Players whose reports become fixes are credited in game. Start by founding a charter of one from the Charter button and reading the Structures tab for the bills.