portlight 2.1.0

English | 日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

Portlight is a trade-first maritime strategy game for the terminal. You run a captain, a hold, and a reputation across twenty ports. Prices move when you sell. Contracts want provenance. Brokers and warehouses change what a voyage is worth. Four victory paths score the career you actually built — not the one you picked on day one.

Play in the TUI (portlight tui) or the CLI. Same save. Same world.

Install

pip install "portlight[tui]"

Python 3.11+. The tui extra pulls Textual. CLI-only: pip install portlight.

No Python? The npm launcher fetches the GitHub Release binary:

npx @mcptoolshop/portlight

Print-and-play PDF kit: pip install "portlight[printandplay]".

Play

portlight tui

If there is no save, the TUI lists slots and New. Pick a captain type. Then:

CLI is the same game with typed commands:

portlight new "Captain Hawk" --type merchant
portlight market
portlight buy grain 10
portlight sail al_manar
portlight advance
portlight sell grain 10
portlight tui

portlight --json status dumps a stable dict (captain, port, cargo, market, routes, board) with no ANSI. portlight saves lists slots.

Guided first session: docs/START_HERE.md. Handbook: https://mcp-tool-shop-org.github.io/portlight/handbook/.

Why Portlight

Most trading games flatten trade into a number that goes up. Portlight treats trade as a commercial discipline:

• Prices react to your trades. Dump grain and the local price crashes.
• Ports have economic identities. Porto Novo grows grain. Silk Haven exports silk. That is structure, not noise.
• Voyages carry risk. Storms, pirates, inspections, seasons. Provisions, hull, and crew are real costs.
• Contracts require proof. Right goods, right port, tracked provenance, real deadlines.
• Infrastructure changes timing. Warehouses stage cargo. Brokers improve the board. Licenses open premium access. All five live regions have broker offices and a regional charter.
• Reputation is four axes. Commercial trust, customs heat, regional standing, underworld. They open and close doors independently.
• The game reads what you built. Milestones and four victory paths score evidence, not a menu choice.

The world

Five regions. Twenty ports. Forty-three routes.

Eighteen goods (including pelts and contraband). One hundred thirty-four named NPCs. Four pirate factions with eight live named captains. Seasonal weather. Festivals, superstitions, crew morale.

Nine captains

portlight new "Name" without --type opens the roster. Bounty Hunter is not a flavour label: portlight bounty accept <id> then portlight bounty hunt <id> forces the named captain. Ghost ids are gone; the board only lists live PIRATE_CAPTAINS.

Systems

Economy — Scarcity pricing, flood penalties, market shocks, regional import/export identity.

Voyages — Multi-day travel. Weather, pirates, inspections. Named pirate duels prefer an active bounty when one matches the waters.

Contracts — Seven families, twenty-four templates. Trust and standing gates. Provenance-validated delivery.

Reputation — Regional standing, commercial trust, customs heat, underworld connections.

Combat — Personal stance triangle (thrust / slash / parry), melee and ranged, fighting styles (TUI Y fires the style special). Naval: broadside, close, evade, rake, flee. Prize capture with a real fleet hull.

Infrastructure — Three warehouse tiers. Broker offices: Local + Established in all five regions. Seven licenses (five regional charters including North Atlantic and South Seas, plus two global). Real upkeep.

Finance — Hull, cargo, and contract-guarantee insurance. Three credit tiers with interest and default.

Fleet — Multiple hulls, dock/board at the same port, cargo transfer, eighteen upgrades.

Career — Twenty-seven milestones, seven profile tags, four victory paths. Dashboard shows the ledger; day-advance toasts newly completed beats.

Victory paths

• Lawful Trade House — High trust, premium contracts, clean reputation, infrastructure breadth.
• Shadow Network — Luxury margins under heat, survived seizures, still ahead.
• Oceanic Reach — East Indies standing, distant infrastructure, long-haul mastery.
• Commercial Empire — Multi-region warehouses, brokers, licenses, financial leverage.

Print-and-play

pip install "portlight[printandplay]"
portlight print-and-play

Kit-sized PDF (portrait after the landscape board, silver track 0–100). Rulebook: docs/PRINT_AND_PLAY_RULES.md.

Command groups

Run portlight guide in-game, or docs/COMMANDS.md.

Quality

• 1,853 tests
• 14 cross-system invariants under 9 compound stress scenarios
• Balance harness: 7 policy bots, 7 scenario packs
• Save format v12 with a full migration chain
• Ruff-clean. Python 3.11 / 3.12 / 3.13

Security

Local-only game. No network during play. Saves to saves/ and reports to artifacts/ as JSON. No secrets, no telemetry, no elevated permissions. See SECURITY.md.

Development

pip install -e ".[dev]"
pytest
ruff check src/ tests/

verify.sh runs tests, ruff, a wheel build, and a smoke-import of the built artifact.

License

MIT

Built by MCP Tool Shop