Colony & Settlement System

Last Updated: 2026-09-13 (runtime loaded; holding setup and GM cancel paths verified; player transaction smoke pending)

Current accounting and session workflow

Use Create Colony in the Actor Directory: the implementation creates a party Actor with the colony sheet, not an arbitrary NPC/loot actor. The existing structure, staff, vendor and shared-treasury system also represents a small remote business holding; marking the gift-shop holding player-owned does not confer ownership of Blorpulon Six.

Open Campaign Controls, then Session Restock and Income in the Actor Directory. Its Session Maintenance menu restocks all configured managed vendors in the world and scene-token inventories, including Rishae, once per explicit session ID. Linked instances are deduplicated. Repeat the same ID to retry unchanged failures, not to reroll completed shops. Review Interrupted Stock records a GM-inspected shelf as accepted without rerolling, or permits retry only when the inventory exactly matches the saved pre-refresh fingerprint. A review note is required. Merchants without a managed profile are listed as incomplete coverage; their inventory is preserved. Hero Point awards remain a separate repeatable action. Stock does not unlock network access, advance story stages or grant wishlist items that have not been implemented.

Campaign Controls also exposes existing linked-hull facility access and Rishae's shop availability. These persistent switches require an explicit choice and confirmation; restock does not reset them. Hull access reconciles managed grants while preserving internalized signature training from installed, operational facilities on linked hulls. Shop OFF blocks player browsing, trades and deliveries while preserving its inventory and allowing GM inspection and managed restock. Only the active GM executes changes.

Income uses in-world time, not session count. The global calculator now asks for an inclusive start day and exclusive end day (for example, 10 to 13 pays three days). The first approved period establishes the boundary. Later periods must be contiguous; already-paid periods are skipped and partial overlaps/gaps reject before payment. The active GM commits income and each colony's paid-through boundary in one existing shared-treasury setting update. Old date-only history requires reconciliation, not a blind second payout. Rates must represent the chosen period; this is not a historical payroll reconstruction or an automatic use of Foundry's world-time clock.

Individual recorded staff salaries are used, including explicit zero; the structure's default salary applies only when a staff entry has no salary. Missing required staff means no gross revenue. Net income is floored at zero under the existing no-auto-debt policy. Runtime amounts are credits (10 credits = 1 gp). Legacy denominations retain their exact copper value; mixed legacy and credit balances require reconciliation. Blorpulon Six income is approved at 10 credits/day net (20 gross less 10 operating costs), starting at the next session opening with no backpay. At that actual opening, use Review Colony Income > Record Holding Opening and enter its in-world day on the same timeline used for other colonies. This records no payment. Until the opening is recorded, the holding cannot pay; earlier days are excluded from its first period. Repeating the same opening is harmless; moving it or conflicting paid history requires reconciliation. This start policy does not reset with later sessions.

September 13 local transfer repair, unreleased: character deposits and withdrawals now use exact existing coin stacks with explicit active-GM review. Requests do not automatically authorize spending. A durable pending record precedes the character write; the treasury balance and completion receipt then commit together. Uncertain writes block transfers, income and opening-day accounting until reviewed. The old synthetic-currency writer remains removed. Signed-in verification and release remain.

The same Review Colony Income dialog is available from Session Maintenance and the colony sheet. Opening either entry point does not itself distribute income.

Complete documentation for the colony (settlement tracker) system in pf2e-starships.

Overview

The Colony system provides a settlement tracker for managing locations your party visits, owns, or operates. It tracks:

• Leadership - NPCs assigned to administrative roles
• Vendors - Merchants and service providers
• Structures - Buildings with income generation
• Points of Interest - Notable locations linked to journals
• Treasury - Shared party funds (player-owned colonies)

Creating a Colony

1. Use Create Colony in the Actor Directory (GM only)
2. The module creates a party Actor with the Colony Actor Sheet
3. Configure the colony type and ownership

Colony Types

Colony type is a descriptive label only - it doesn't affect mechanics.

Ownership Types

Administration Tab

Leaders

Assign NPCs to leadership roles within your colony.

Adding a Leader:

1. Click the + button in the Leaders section (GM only)
2. Select an NPC actor from the world
3. Assign a role name (Administrator, Commander, Warden, etc.)

Leader Features:

• Click the external link icon to open the NPC's character sheet
• Role names are freeform text - use whatever fits your setting
• Leaders are tracked for narrative purposes, not mechanical bonuses

Vendors

Track merchants and service providers in your colony.

Adding a Vendor:

1. Click the + button in the Vendors section (GM only)
2. Select an NPC actor (typically one with a merchant sheet)
3. Optionally specify their location within the colony

Vendor Features:

• Click the store icon to open the vendor's sheet for shopping
• Location field helps players find specific shops
• Integrates with PF2E's merchant actor functionality

Shared Treasury (Player-Owned Only)

Player-owned colonies display the existing global shared treasury to users with sheet access. Colony ownership flags do not replace Foundry document permissions.

Character deposits and withdrawals (local replacement): select an owned world character and a positive credit amount, with at most one decimal place (one copper). Players request review; the active GM confirms the real player request, exact character, direction, amount and colony. Plain module-socket identity is not trusted as spending authority. Existing pp/gp/credstick/sp/cp stacks are used; zero stacks survive and UPB/BP are excluded. Reject unavailable exact change before any mutation. Do not edit synthetic system.currency or use SF2E currency helpers to bypass this path.

The GM keeps this character out of other trades until completion. Income, opening-day bookkeeping and transfers share one active-client accounting lock; this is not a cross-client currency lock for other modules. Durable transfer receipts reject duplicate tokens. A pending transfer blocks further accounting rather than being silently retried. In Review Interrupted Transfer, first verify all previous writes have settled and other character trading is paused. Exact original coins allow cancellation; exact target coins allow completion of the treasury side only. Neither recovery repeats a coin write. Any other coin state requires manual investigation without automatic overwriting/refunds. Two document writes are not a crash-atomic transaction. Keep release and signed-in failure/recovery smoke separate from local fixture success.

Colony income deposits remain available through the explicit-period calculator.

Transaction History:

• Recent transactions show amount, character name, and date
• Deposits show as positive (+), withdrawals as negative (-)
• Treasury balance is shared across ALL player-owned colonies

Structures Tab

Structures

Buildings and facilities in your colony. Add structures by dragging equipment items onto the colony sheet.

Adding a Structure:

1. Drag an equipment item onto the Structures tab
2. The item is added to the colony with default settings
3. Configure ownership, income, and staff as needed

Structure Properties:

Managing Staff:

1. Click the users icon on a structure
2. Add staff members (NPCs or named hirelings)
3. Staff count affects whether the structure operates at full capacity

Income Calculator (GM Only)

The Income Calculator automates revenue distribution from all structures.

How It Works:

1. As the active GM, click "Calculate & Deposit Income" on a colony sheet or "Review Colony Income" in Session Maintenance.
2. Enter recorded start and end days. Start is inclusive, end is exclusive; 10 to 13 covers three days. Use the rates and staffing applicable to that period.
3. Each enabled structure earns max(0, gross revenue - sum of staff wages) per day. Gross revenue is zero when required staff are missing. Explicit zero wages remain zero.
4. Net income from all eligible player-owned colonies is deposited into the shared treasury together with their accrual boundaries in one write.
5. Repeating an already-paid period makes no deposit. Partial overlaps, gaps, periods before the established start, and unreconciled legacy history require review.

Example Calculation:

Tavern:
  Income: 50 credits/day
  Staff Required: 2
  Recorded Staff Salaries: 10 credits/day and 5 credits/day

  Net Income = 50 - (10 + 5) = 35 credits/day

Points of Interest

Notable locations within or near your colony, linked to journal entries.

Adding a Point of Interest:

1. Click the + button in the POI section (GM only)
2. Enter a name for the location
3. Optionally link to a journal entry for detailed information

Using POIs:

• Click the book icon to open the linked journal
• Use for quest locations, dungeons, landmarks, etc.
• Helps organize narrative information about the colony

Linked Scene

Connect your colony to a Foundry scene for easy navigation.

Setting Up:

1. In the colony header, select a scene from the dropdown (GM only)
2. The colony is now associated with that scene

Benefits:

• Quick access to the colony's map
• Visual reference for players
• Organize scenes by settlement

Workflow Examples

Setting Up a New Settlement

1. Create the Colony Actor
   • Use Create Colony in the Actor Directory
   • Set type (Settlement, Station, etc.)
   • Set ownership (Player if party-owned)
2. Add Leadership
   • Assign governor/administrator
   • Add security chief, dock master, etc.
3. Register Vendors
   • Add the local blacksmith, general store, etc.
   • Set locations for each vendor
4. Add Structures
   • Drag in buildings the party owns
   • Configure income for revenue-generating properties
5. Link Resources
   • Create journal entries for notable locations
   • Add as Points of Interest
   • Link to the settlement's scene

Managing a Trade Post

1. Structures for Income
   • Add warehouse (storage income)
   • Add marketplace stall (merchant income)
   • Set appropriate staff and salaries
2. Vendors
   • Add trading company agent
   • Add supply merchant
3. Regular Income
   • Active GM records a contiguous in-world accrual period in the Income Calculator
   • Income deposited into the shared treasury with per-colony breakdown

Running a Starbase

1. Colony Type: Station
2. Leaders: Station Commander, Chief Engineer, Security Chief
3. Vendors: Quartermaster, Tech Supplier, Medical Officer
4. Structures: Docking Bay (income from fees), Cantina (entertainment income)
5. POIs: Reactor Core, Observation Deck, Cargo Hold Alpha

Tips for GMs

When to Use Colonies

• Hub Locations - Places the party returns to frequently
• Party Property - Bases, ships-as-settlements, claimed territories
• Quest Hubs - Towns with multiple NPCs and services
• Trade Centers - Locations for commerce and downtime

Income Balancing

The income system is meant for downtime wealth, not primary income:

Adjust based on party level and campaign wealth.

Integrating with Adventures

• Use POIs to track dungeon entrances, quest givers, plot locations
• Leaders can be contacts, quest givers, or information sources
• Vendors provide equipment and services between adventures
• Treasury serves as party bank for shared expenses across all player-owned colonies

Structure Item Flags (Developer Reference)

When equipment items are added as structures, they gain special data:

flags["pf2e-starships"].structure = {
  isStructure: true,
  owner: "characterId" | null,
  publicAccess: true | false,
  lots: 1,
  income: {
    enabled: true | false,
    perDay: { credits: 0 },
    staffRequired: 0,
    staffSalary: { credits: 0 }
  },
  staff: []
}

Related Documentation

• Quick Reference: Colony Management Quick Reference
• Compiled Rules: GM Rules (Book Two, Part VI)
• Structure Catalog: Item Catalog (Section 1)
• Source Code: src/actor/ColonyActorSheet.ts

End of Colony & Settlement System Documentation