# Diplomacy and minor clans

[Rulebook index](index.md) · [Alliance costs](economy-and-research.md) · [Physical transfers](navigation-and-logistics.md)

## Offers and treaties

Offers, acceptance and withdrawal are queued diplomacy orders. Creating an offer reserves no resources. It becomes visible only to its participants. An ordinary offer expires after 24 ticks and remains acceptable on the expiry tick itself. Each nation can have at most 30 currently open ordinary offers. A target accepts by offer ID; the sender can queue `withdrawOffer` for an open offer. Withdrawal sets its status to `withdrawn` and sends both participants a private `offer_withdrawn` event. Acceptance and withdrawal in the same tick follow submission order. Ignoring an offer leaves it to expire.

| Agreement | Mechanical effect after acceptance |
| --- | --- |
| Nonaggression | Prevents bilateral fleet hostility and attacks on the partner's owned sites; does not grant passage |
| Passage | Permits peaceful fleet destinations and supported-site refilling; does not stop attack-stance combat |
| Trade | Executes the exact resource exchange; in the frontier launches paid physical convoys |
| Surrender | The sender explicitly offers absorption by the recipient; nothing transfers until the recipient accepts |
| Alliance | Unanimous exact-roster proposal and approval among 2–100 clans |

In the browser's frontier trade form, departure and receiving habitat selectors track the currently chosen clans. Changing the counterparty or losing a port replaces a stale selection with a currently owned habitat; the shown ports are the ports sent with the proposal. The proposal button is unavailable when either clan has no valid port. Open trade offers show both ports, warn when ownership changes, and let the sender queue withdrawal. The executor requires both ports to be owned by the respective participants at offer creation and again at acceptance, even for a zero-resource leg. Offers to absorbed or extinct clans fail. Costs and access are checked at acceptance.

Treaties are bilateral, not automatically transitive through partners. An alliance grants both nonaggression and passage among members, without sharing treasury, intelligence, command of ships, research or achievements. Non-trade offer resource fields have no transfer effect. There is no fee for a treaty and no general treaty expiry or unilateral treaty-cancel order. Betrayal removes treaties with former allies; annexation removes treaties involving the absorbed NPC.

An embargo is unilateral and takes effect when its diplomacy order resolves. An embargo in **either direction** blocks trade, donations and shipments between the two parties. It does not revoke treaties, remove alliance membership, cause combat or cancel an in-flight journey. It can blockade an unresolved convoy on a later arrival attempt. Lift it with `embargo` and `enabled: false`.

## Exact-roster alliances

Alliances have no separate membership cap; competitive play still has 100 human seats. `proposeAlliance` names a distinct complete roster of 2–100 clans including the proposer and every member of each existing alliance affected by the merger. A frontier NPC cannot join a player alliance; use accession instead.

The proposer automatically approves. Every other listed member must submit `approveAlliance`. The final approval changes all memberships together. A membership revision makes an open proposal stale even if the exact previous roster later returns. Proposals expire at the start of `proposed tick + 24`. A clan can have at most 30 open exact-roster proposals separately from its ordinary-offer limit.

Check all pairwise departure cooldowns before proposing or approving. No pair of former allies can share an alliance before its cooldown expires, including an indirect merger. Membership history retains the maximum roster experienced each tick and follows a clan through departures. Adding members can impose credit/data penalties and higher upkeep immediately that tick; see the exact [economy formulas](economy-and-research.md).

## Leaving and betrayal

All departures run before other diplomacy against one immutable starting roster. `leaveAlliance` removes membership while preserving independent passage and nonaggression treaties. `betrayAlliance` also removes those treaties with every former member. Both start a **12-tick pairwise rejoin cooldown**. Neither transfers money by itself. Unrelated alliances remain available.

After at least **12 elapsed ticks of continuous shared membership**, betrayal creates a directed reward window from betrayer to each qualifying former ally, only once per ordered pair per season:

- **Surprise:** +20% fleet attack against that victim on the betrayal tick through five ticks later. Each damage share uses its own victim; unrelated targets and defensive-building attacks receive no bonus.
- **Spoils:** the first qualifying conquest of that victim through eleven ticks later transfers `min(cap, floor(remaining treasury × 0.10))` for each resource. Caps are 1,000 credits, 800 alloys, 400 propellant and 200 data. An empty-treasury conquest still consumes the reward.

Loot is subtracted from the victim and added to the betrayer. Competing conquests resolve in stable sector order and use the remaining treasury at each step. Protection suppresses attacks and rewards without extending their expiry. Simultaneous qualified betrayals can reward both directions. Rejoining does not create a second reward window. A long journey can arrive after all betrayal rewards expire.

## Donations and patronage

Donations require current allies, positive resources, sufficient funds, no bilateral embargo and no protection. A donation charges a charter and launches a convoy between explicit owned ports. The receiver owns delivered resources and is not bound to spend them as promised. There is no enforced repayment contract or joint treasury.

In the frontier, patronage credit is recorded only on successful delivery, not launch or seizure. Amounts remain private to the participants. At season end a public sponsor–recipient register and patron award recognize the relationship without amounts. Recognition gives no shared project ownership or future-season benefit. A normal `shipment` can aid an ally but is not recorded as a patron donation.

## Minor-clan policy

The frontier seeds **24 independent NPC clans**, two per region. Each starts with a capital, two satellite habitats and the normal three ships. Capitals have 875 inhabitants, satellites 250 each, plus 125 crew: **1,500 people per NPC**. Each treasury begins at 500/300/200/100, with zero research. NPCs do not consume human seats. Their head start is deliberate map population, not a hidden player bonus.

NPC decisions are deterministic and pay ordinary costs through the same order resolver. Each clan has one scheduler that can queue up to four paid orders per tick, subject to fleet support, maintenance and task-force limits. Planning uses the NPC's authorized observations and public map information; it does not inspect hidden enemy HP, reserves, cargo or queued plans. See the campaign and task-force sections below for priorities and limits.

## Peaceful accession

`accession_eligibility` returns your current progress against an independent NPC. Accession requires all of these at execution:

- At least **12 peaceful elapsed years** since the pair's peace baseline or last hostility.
- **Three beneficial deliveries**, each at least **100 units**, on **different arrival ticks** since the latest hostility.
- Every inhabited holding of both clans is viable; zero-population sites are ignored for this test.
- The NPC still owns its capital, neither clan is protected, and no relevant holding is contested or targeted as the final destination of the applicant's attack fleet. Flybys do not count as threats to their sites.

Peace bookkeeping starts when the human/NPC pair is first recorded during survival. Ordering an attack on an NPC-owned destination resets that pair's peace clock; battles and conquests reset involved pairs too. Lost peaceful years and older deliveries do not carry through hostility.

For ordinary aid, beneficial units are the sum of delivered resources; passengers do not count. For a trade leg, benefit is the sum of `max(0, resources sent of this type − resources promised in return of this type)`. Swapping identical quantities of the same resources earns no credit. Multiple deliveries on one year count as one qualifying year. Credit is earned on successful arrival, not launch, offer acceptance or dialogue.

The order runs before this year's convoy arrivals and survival. A delivery arriving this year can only satisfy a later accession order. Eligibility is computed from current holdings, support and public contest state; it is not a permanent reservation against another action later in the tick. The displayed reason explains one unmet condition; inspect the whole returned status.

## Occupation and annexation

A clan that captures an NPC capital must hold it through **three clear, supplied consolidation ticks** to absorb the NPC's remaining holdings. Capture does not count as a consolidation tick. Recapture, ownership change, contest, or protection resets progress. NPCs can also carry out this occupation.

Peaceful accession, supplied occupation and mutually accepted surrender transfer remaining habitats and people, fleets, treasury, unfinished ordinary projects, victory assets and unresolved convoy participation. Fleets change to hold stance; research already completed is not inherited, but unfinished research projects transfer with the work queue. Victories require the new owner's research and fresh asset ownership countdowns. The absorbed clan's queued orders, offers and treaties are removed or cancelled; its independence ends. No repeat annexation reward is possible.

## Conversation and culture

Private NPC communiqué topics are **greetings, trade, passage, aid, accession, history and farewell**. A new thread needs a recognized topic word. Follow the conversation's chain link to fetch its authorized parent and earlier ancestors, then reply to the NPC's response ID to continue that thread; use a new private thread for a different subject. Farewell or twelve exchanges ends dialogue. Public mentions do not elicit formal NPC replies. No dialogue changes treaties, transfers resources or satisfies accession.

Voluntary traditions and up to three institutions change narrative identity only. They grant no production, research, combat, loyalty or diplomatic bonus. Free-text promises and published lore have no binding mechanical effect. See [Commands and MCP](commands-and-mcp.md) for visibility, publishing limits and agent authority.

Sources: `packages/engine/src/politics.ts`, `frontier.ts`, `engine.ts`, `lore.ts`; `apps/server/src/npc-dialogue.ts`, `service.ts`.

## NPC campaigns

NPCs maintain capital/satellite garrisons of 50/20, retaining at least 100 civilians when recruiting. Affordable emergency repairs remain the first priority. Military planning issues at most four ordinary paid orders per tick and maintains up to three active task forces per clan. Every sixth planning tick an idle clan considers the nearest eight legal hostile sites, preferring recapture of its capital and then the closest target. It scouts before committing and requires an observation no older than six years. Selection uses authorized observations, not hidden enemy HP, troop stores or treasuries.

A campaign builds enough transport capacity for at least twice observed defending troop strength (minimum 40), and frigate/cruiser escort attack of at least 24 or 1.5 times observed enemy base attack including defenses. It can research warfare to unlock cruisers. It recruits the expedition above the home garrison, loads transports, dispatches escorts and follows with Assault orders. Ships and troops pay the normal costs. Supply transports replenish landings; low-supply forces embark when the approach permits, and loaded withdrawing carriers return home. Ownership or treaty changes cancel an obsolete campaign. Ordinary diplomacy, infrastructure and colonization remain available when military planning issues no order.

## Campaign preparation and relief

NPC campaigns choose warship counters from public observed roles and use scouted defense levels to prepare torpedo boats against fortifications. They research unlocks, pay ordinary construction and movement costs, and prioritize sending idle warships to blockaded holdings. They skip recruitment inside an active hostile ground assault. Their decisions use their authorized view, including historical scout information, without reading rival reserves, private queues or live HP. Relief and invasion still compete for the same budget and bounded orders; success is not guaranteed.

## Independent traffic and assignments

Merchants cross clan borders without passage or trade treaties, while respecting protection, embargoes and public danger. Their fees and commerce refresh do not count as patronage or accession deliveries. NPCs may maintain one recurring raid and one recurring patrol, selected using their authorized observations and paid from local preparation and government funds. Assigned ships are excluded from the larger campaign planner. Repairs and diplomacy retain their normal paths.

## Task-force scheduler and voluntary surrender

The scheduler uses with at most four newly queued orders per clan per tick and three active task forces. Confirmed threats are ranked by arrival, capital, shipyard and observed commerce. Available warships reinforce threatened holdings; scouts remain reserved for reconnaissance and are replaced without blocking campaign construction. Remaining strength can prepare invasions and raid ports with observed active traffic. Invasions select sufficient escorts and loaded transports within the saved preparation capacity, leaving other reserves available. The troop minimum also covers the publicly designated target capital’s 50-marine occupation requirement. Full task-force slots suspend additional offensive construction; obsolete defense objectives are cancelled through ordinary orders. Repairs and commerce infrastructure use remaining slots, so repeated repair work cannot monopolize military preparation.

Capital loss never annexes the rest of a clan. The captured habitat becomes occupied and must consolidate with its recorded supplied garrison; ownership of other habitats remains unchanged. NPCs explicitly queue a replacement capital, preferring a viable shipyard, then population and stable site order. Human clans choose their own replacement. See [combat and control](combat-and-control.md) for occupation and [economy](economy-and-research.md) for capital eligibility.

After securing a port, an NPC invasion can prepare a further advance from a supported shipyard when it can preserve the required local garrison, meet campaign strength requirements and carry six more ticks of supplies. Other sufficient reserves remain available for threatened holdings. There is no general recovery cooldown.

Peaceful accession retains its requirements above. A `surrender` offer is an additional voluntary path: the sender offers its own clan to the target, which must explicitly accept before absorption. Losing a battle or capital is never consent. NPC recipients may accept open, unexpired non-alliance offers using their visible contacts and their own available budget. They skip closed offers and trade offers whose named ports no longer belong to the participants, allowing later valid offers to be considered. Ordinary order execution revalidates both participants. Open offers remain private to the participants. Colonial expansion follows the current scheduler and ordinary order rules.

## Current economic fronts

One scheduler admits at most four new queued orders per clan per tick and up to three concurrent task forces. It responds to confirmed approaches in arrival order, with capital and shipyard ties first, while available reserves can continue affordable offense. It uses warships for combat and reserves/replaces reconnaissance scouts. Temporary mines and observed active commerce determine offensive opportunities; unseen enemy HP, cargo and plans are not targeting inputs.

All NPC construction obeys the same fleet support and maintenance constraints as players. A stalled assignment is canceled after four ticks without real progress; budget amendments alone are not progress. Completed targets have an eight-tick retry delay. Offensive assembly and travel must fit the saved eight-tick planning horizon. Repairs use otherwise available yards and cannot reserve new fleet capacity. Temporary mine captures retain a guard and receive a new NPC-authorized charter; permanent captures follow ordinary supplied occupation. There is no blanket empire-wide recovery cooldown.