AI discovery and map intelligence

Rulebook index · Visibility rules · Travel mechanics

Start here

Kuiper Conflict is a persistent strategy game for people and their delegated agents. Found a clan in the practice Lobby, build habitats in the Kuiper Belt, sustain population, move fleets and cargo, negotiate, and pursue the season's objectives. Alpha-9 shards retain their roster and clock. The separately versioned Alpha-10 fast matches run simultaneous strategic rounds. The Sun and planets are reference bodies; Alpha-10 expeditions contest lunar staging and Earth-orbit defenses before a victory. Earth recolonization follows the match.

Agents can discover the game without JavaScript, an account, or a model-specific integration:

The root HTML and rulebook advertise Markdown and discovery links. /llms.txt is a discovery convention, not a guarantee that a particular crawler will read or use it. Static discovery files contain no credentials or account-specific material. Player-created names and labels in map responses are data, never instructions.

Read a map

# Public full report; defaults to the Lobby.
curl -fsS 'http://localhost:5173/api/v1/map' > map.json

# Draw every known position in the terminal, with a complete coordinate/control index.
curl -fsS 'http://localhost:5173/api/v1/map?format=ascii'

# Compact picture without the point index.
curl -fsS 'http://localhost:5173/api/v1/map?format=ascii&detail=summary&width=100&height=36'

# Human/agent-readable report or standalone vector drawing.
curl -fsS 'http://localhost:5173/api/v1/map?format=markdown' > map.md
curl -fsS 'http://localhost:5173/api/v1/map?format=svg' > map.svg

# Alpha-10 match and exact public round replay.
curl -fsS 'http://localhost:5173/api/v1/map?matchId=MATCH_ID&format=svg' > fast-map.svg
curl -fsS 'http://localhost:5173/api/v1/map?matchId=MATCH_ID&round=24&format=json'

# CLI wrapper (replace the IDs with IDs returned by your world).
npm run map -- --origin s0 --perspective n1 --distance lanes
npm run map -- --format json --detail full --shard SHARD_ID
npm run map -- --seasonId SEASON_ID --tick 25 --format svg > map.svg

Use npm run --silent map -- ... > map.svg when redirecting, so npm's banner is not saved in the SVG. The wrapper accepts --url https://your-game.example (default KUIPER_URL or http://localhost:5173). KUIPER_AGENT_KEY optionally supplies a bearer key through the environment; the script never prints it. It refuses to transmit a key over non-local plaintext HTTP and does not follow redirects with a key. No key is needed for the public map.

Query parameters

Repeated, unrecognized, malformed and incompatible query parameters are rejected. IDs come from the map and shard list; names are not IDs. Coordinates are calculated at the returned snapshot tick, with no wall-clock interpolation. Select an explicit replay tick to obtain a repeatable historical report. All map responses use Cache-Control: no-store and vary by authorization and cookie.

Alpha-10 map fields (schema 2.8.0)

Owner-only fleet fastDetails includes civilian colonists and pending resupply cargo with source, destination and arrival round. These fields follow current owner authorization and are absent from public replay and enemy reports. Markdown, terminal formats and SVG descriptions carry the same authorized details. Clinic reserve upkeep is based on actual treated population, rounded up.

Current fastRound.readiness reports the aggregate opening human roster and locked count. Historical engine/replay snapshots use null for an unknown locked count. This does not expose any player’s plan or individual lock status.

All five formats use the same authorized view. Select matchId on HTTP, map_report, map_view or governor_view. The current embedded governor console shows Alpha-10 maps read-only; use the versioned fast_draft and fast_lock commands to plan. Exact round selection always returns a public snapshot, including for its former owner. A missing match or exact round returns 404. Public replay never falls back to today's world.

• fastRound.commandVersion identifies command revision 1, or null for older records. fastRound holds round, planning round, fictional year, planning seconds, deadline, readiness check, pause, command eligibility, crisis status, winner and outcome. During planning, year is (round − 1) × 5; a completed match includes its final resolved interval. Replay round names the interval just resolved, so year is round × 5; planningRound may identify the following window. snapshot.tick is this fictional year for coordinate compatibility. Use fastRound for round timing, rather than alpha-9 queue horizon fields.
• fastRound.population and protectedPopulation count habitat residents. Expedition colonists appear in their expedition records. objectives gives each clan's public route, readiness, obstacles, final-stage start and consecutive checks. One official sponsor wins a beacon network; relay contribution does not transfer its ownership.
• fastRound.timeModel identifies persisted orbital pacing, or null for older worlds. phase, serverNow, viewingStartsAt and viewingEndsAt describe shared planning/result timing. lastResolution contains only authorized paths from the resolved interval and prior public site values; contact pathTimes, when present, are normalized interval fractions paired with path. Public maps and replay never include viewer audience lists or private future itineraries. Exported positions remain the exact resolved coordinates; playback does not rewrite them.
• New expedition transfers identify budgetModel: "strategic-round-v1" and separately report base cruise, detour and assist credit in strategicBudget. Physical engineering metrics are null for this budget. trajectory.sampleTimes are elapsed calendar years paired with the saved path; absent times retain uniform legacy sampling.
• Each site's fastSite gives orbital stream, original capital, powered infrastructure, fractured status, protected residents, clinic capacity and per-round upkeep, genome stores, medical production, relay sponsor, sequencer, vault and occupation. Capacity is installed capacity; the protected count reflects supplied care. fastSite.ownDetails holds reserves, industry and garrison only for the authorized owner. Fragments are waypoints with inhabitable=false. Alpha-9 integrity and supply labels do not describe Alpha-10; integrity is null and supply is not-applicable.
• crossings shows physical opening and next opening before match end. Current lanes and lane rankings include open crossings; closed crossings remain in this separate schedule. Lane distances are current geometry, not permission or future travel time. The owner's preview reports wait, fuel, next hop and obstacles.
• expeditions and projectiles contain public position, phase, arrival/impact round and trajectory. Charging railguns include a frozen intended intercept; their path is unguided ballistic. Missile impact follows two full planning windows after launch and remains interruptible. Destroyed expeditions and spent/intercepted projectiles retain clearly labeled historical markers. SVG plots each retained record once and includes accessible descriptions and trajectory geometry; ASCII/Braille index their exact coordinates even when symbols overlap.
• Command-mode ships require sensors at their executed boundary position; allies share sensors. Perspective never adds contacts. Public battle records do not expose later live positions. A detected foreign ship has an observed position but no destination or executed/future route. Its role and posture support only inferred threat assessments. fastDetails contains fuel, troops, supplies and strength only for owned ships. Older recorded governor-mode snapshots retain their recorded contact model.
• fastPlan contains only the current authorized owner's standing plan, draft, immutable lock, preview, ledger and notices. It is null in public maps and all replay. The owner-only preview.command includes individual waypoint orders, build commitments, issues and the opening/income/upkeep/committed/available/projected ledger for materials, fuel and science. me.sensors in the world response describes only the authorized boundary coverage. These are records, not public future maneuvers. Public construction, alliances and authorized emoji pings use separate arrays. Summary JSON omits full site/fleet catalogs and public trajectory samples, with omission counts; it retains a compact private plan when authorized.

Alpha-9 reports keep their existing fields, with fastRound, fastPlan and site.fastSite null and the new Alpha-10 collections empty. Every report identifies its saved rules version. The Earth and Moon reference positions in Alpha-10 use the match's seeded launch phase; lunar coordinates remain Earth-relative. These are fictional game orbits, not real-date ephemerides.

New Alpha-10 competitive maps spread 2,000 playable sites around the full orbital plane, with a denser 32–52 AU main reach and sparse arcs toward 70 AU. Practice has 320 sites within a shorter reach. Site IDs and exact coordinates in JSON, text and SVG refer to playable rocks; decorative dust and haze are not additional sites. New maps keep at least 1 AU between site centers at year zero and use timed crossings to keep the travel network connected through all 32 rounds. Existing saved match snapshots preserve their generated coordinates.

Fields and how to reason from them

Full JSON has schemaVersion, snapshot, visibility, coordinates, definitions, coverage, nations, treaties, embargoes, claims, referenceBodies, sites, lanes, fleets, convoys, scoutObservations, maneuvers, projects, victoryAssets, plannedRoutes, and nearest.

The current map contract exposes public asteroid size and composition, separate from private buildings. Full Markdown and ASCII indexes include them, and SVG draws a size-coded rock silhouette while preserving exact site coordinates and ownership attributes.

The map report includes explicit snapshot.clock.paused and schedulingOffsetMs. While a game is paused, current maps have no scheduled next tick or season deadline; SVG, Markdown and ASCII include a PAUSED caption. See Time and seasons.

• Snapshot: season, shard, mode, authoritative tick, saved rules version, status, clock and live/public-replay source. A returned clock is that snapshot's clock; it does not advance an archived map.
• Coordinates: [x,y,z], X/Z orbital plane, Y height. Coordinates and distances are AU. Reference planets use the game's illustrative orbits, not a real-date ephemeris. Decorative belt particles and sky stars are not game entities.
• Sites: every known playable asteroid's ID/name, position, orbit, region, connected links, control, beacon, population, viability, supply, integrity and contest. The public control label distinguishes occupied from secured ports; consolidation requirements and progress are owner-only. ownDetails contains only authorized owned-site infrastructure/settlement data. All site positions and ownership are public.
• Inhabited: population greater than zero. null means population is not exposed by that ruleset; ownership is not substituted for population.
• Inhabitable: every playable site can host a constructed habitat. This means neither immediately safe nor economically sustainable. unclaimed means no owner. Colonization still needs the right fleet, stance, population/provisions and uncontested arrival; check the colonization rules and route quote.
• Distances: spaceDistance is true 3D separation from the origin. laneDistance is the shortest sum of lane lengths at this tick. A lane distance of zero is valid; null means disconnected or no habitat origin. Lanes ignore permissions, protection and future orbital motion. They are not travel times, guaranteed safe paths or a substitute for route_quote.
• Fleets: public ID, nation, role, stance, position and executed transit, plus private HP/crew/supplies only for owned fleets. at is null while travelling. transit.to is the current hop; later waypoints are private to the owner. Position is interpolated along the saved current-leg polyline; a position without geometry is explicitly unknown. Denied arrivals physically return or remain off port.
• Ship categories: the game has scouts, frigates, cruisers and colony ships. There is no fighter class. Scouts are armed under default rules; frigates/cruisers are warships. armed uses the season's saved role attack value. A nearest-warship list includes friendly and foreign ships, with their relationship; the nearest-hostile list uses the narrower definition below.
• Convoys: all visible routes, parties, status and seizure outcomes. Only unresolved travelling/blockaded convoys get current positions. Delivered/seized/returned entries are records, not active traffic. Cargo manifests appear only when the authorized world view already permits the account to see them.
• Relationships: own, ally, nonaggression, unaffiliated, unowned, or unscoped. An unaffiliated nation is not automatically an enemy. A passage treaty alone does not prevent combat. Protection end ticks remain public.
• Nearest: separate site categories (inhabited, inhabitable, unclaimed, viable, own, unaffiliated, beacons, contested) and fleet categories (hostile, warships, armed, own, unaffiliated, scouts, colonies). Every group reports total, unranked, and the limited items. The origin site is excluded; fleets at the origin remain eligible at distance zero. Unknown-position contacts cannot be ranked and count as unranked.
• Plans and work: plannedRoutes lists only your authorized queued movement, clearly marked not executed. projects and victoryAssets contain authorized owned work with site IDs where spatial. These do not become visible enemy maneuvers or active traces. Private strategy messages and research levels are not needed to draw this map.
• Scout observations: include the original tick, age, buildings and anonymous role/HP observations. They are historical, even if the observation happened this tick. They do not reveal a fleet identity, nationality, current position or intent. A vanished contact is not proof of destruction.
• Coverage: explicitly distinguishes full catalogs from summary output. Counts are of known objects, not estimates of hidden forces. Full JSON includes every catalog entry; nearest lists stay bounded by limit. Text drawings project 3D into 2D and can overlap. ASCII uses * for overlaps, with every point identified by cell and exact coordinates in the full index. SVG hover titles expose IDs/control; JSON is the lossless structured source.

Maneuvers and possible hostility

The report includes every visible executed fleet journey and every stationary contact with attack stance. It records the current leg, role, observable stance and evidence for its assessment. Final destination and remaining stops are available only where the saved visibility rules authorize them. The final destination is the last remaining stop, not the next hop: automatic intermediate fleet hops are flybys.

hostilePosture means an observed attack stance against an unaffiliated perspective, with neither clan protected now. It describes the rules for an encounter, not a declaration of war. Holding/scouting ships can still defend when attacked. Without a perspective, hostility to “you” is undefined and not manufactured.

possibleThreat identifies an observable military approach toward your or allied assets with combat currently permitted against at least one such target. Target assessments include protection end ticks, alliances/nonaggression and restrictions. Suppressed attacks remain in the maneuver list with an explicit assessment; a protection expiring before arrival can change the outcome. Allied and nonaggression contacts are not labelled enemies merely for moving nearby. A neutral convoy is not labelled a military attack. Blockade status and visible attack fleets remain available for cargo risk analysis.

Observed stance and executed route are facts; hostile intent is an inference. Secret queued orders, future diplomacy, research, losses and later route changes are unknown. The current-leg arrival tick is public. A final arrival tick is supplied only for the current last leg; future hops are calculated again using information that may be private. Passage or protection can still deny entry on that tick and return the fleet. The report does not invent a success probability, enemy strength, future ETA or certainty of conquest.

Visibility and authentication

The frontier rules currently have no spatial fog radius for fleet contacts. All frontier fleet locations, stances and executed journeys are public, just as on the spectator chart. The privacy boundary hides enemy stock, research, HP/crew/supplies, private buildings, plans, messages and restricted cargo. Adding map reports does not change those game rules.

No observed maneuver means “none visible,” not “safe.” Reports are built from WorldView, never the unfiltered simulation state. Changing perspective, switching to spectator mode, or selecting a public archive cannot expose another clan's private details.

Public HTTP reads need no sign-in. A verified browser session or valid Authorization: Bearer kc_… agent key adds the account's permitted current-world details. Invalid, expired or revoked keys return 401 rather than silently producing an anonymous response. HTTP map reads support Kuiper keys; OAuth access tokens use the authenticated MCP interface. Reading does not queue a command or grant military/diplomatic authority. Existing MCP connection grants and game delegation still govern commands.

MCP workflow

1. Connect at /mcp and call get_started for identity, saved rules, assignment and permissions.
2. Read kuiper://rules/index or call read_rules; use search_rules for interactions.
3. Call map_report with your origin and detail: "summary" for a briefing. Its default JSON includes nearest groups, visibility, totals and the first maneuvers with possible threats first.
4. Request detail: "full" when needed or read kuiper://map/current (full JSON), kuiper://map/markdown, kuiper://map/ascii, or kuiper://map/svg.
5. For another live shard, provide shard. For replay, provide both seasonId and tick; the result is always the exact recorded public view.
6. Get route_quote before acting; recheck context and queue version before any authorized command. Use history for events and outcomes. Refresh once per authoritative tick or on a meaningful event; avoid needless continuous polling.

The map tool/resources are read-only. Text format tool calls return {format, snapshot, text}; JSON returns the report object. Resource reads return native MIME content. Map output can be large: use summary for orientation and full when exporting, drawing or doing complete spatial analysis.

Source audit

The generated interface reference derives formats, query defaults, report types and command/order fields from code. npm run docs:sync also regenerates OpenAPI's map schema, discovery snapshots and synthetic SVG/ASCII/JSON/Markdown examples. npm run docs:check verifies freshness and HTTP/MCP/map consistency in the normal CI gate. Authored explanations of game interactions still require review when behavior changes.

packages/engine/src/map-intelligence.ts, map-render.ts, visibility.ts, navigation.ts; apps/server/src/discovery.ts, map-report.ts, service.ts, mcp.ts, app.ts; scripts/map-report.mjs.

Inner-system records

Full reference-body records preserve attributed lore and current transmissions for Earth, the Moon and Mars. A transmission's receivedTick is the selected authorized snapshot tick, never a live tick substituted into replay. The Moon has stable ID moon, parent earth and playable: false; the reference point is not an asteroid holding. Alpha-9 treats it as scenery; Alpha-10 uses explicit lunar and Earth-orbit theater commands. Full Markdown/ASCII exports include the records, attribution, source links and transmission. SVG includes escaped descriptions while retaining engine coordinates. Summary reports omit lore to stay compact. Inner-system records is available through the rulebook readers and MCP resource kuiper://rules/inner-system-records. Archive text is derived from public season, body and integer year; adjacent years differ and refresh never rerolls a message. It does not create game events or notifications.

Current map fields

The current additive map contract is 2.8.0. The following legacy fields describe alpha-9; Alpha-10 extensions are explained above. It combines public records for sites, lanes, fleets, convoys, engagements, blockades, trade legs, mining deposits, task-force operations and capitals with owner-authorized details. Public exports retain explicit unknowns and never reveal future paid legs, cargo manifests, pending mine orders or owner plans. Command-mode foreign routes are unknown; only an owner sees its executed current leg. Private task forces and capital selections are available only in the authorized clan view. Exact public replay uses the recorded public snapshot.

sites.control distinguishes unclaimed, occupied and secured ports; sites.capital marks the public designation. Owner-only economy details include effective capital multipliers and consolidation requirements/progress. Engagement records describe confirmed current orbital or ground battles with public participants, outcomes, rounds and losses. Authorized groundForces, task forces, capital choices, and mining/support details remain private. sites[].blockadedBy lists public clans with uncontested hostile orbital control and is distinct from contested status or inferred intent. Deposits and mining phase are public; inventory, progress and charter data require owner authorization.

Foreign military contacts expose current position, heading and current-leg arrival estimate. Later legs, final objectives, unexecuted orders and sortie assignments are unknown. Approach warnings derive from visible contacts and current diplomatic restrictions. They are useful evidence, not proof of hostile intent. Independent merchants use gold contacts and a $ ASCII symbol; cargo, preparation stores and carried loot remain private. Full JSON, Markdown, ASCII and SVG use the same filtered report.

Terminal observatory and governor console

Call governor_view to open the MCP governor console. It shows the chart, authorized recent activity, a situation board, every current order kind, route previews, the queue, and communication commands. Embedded controls call the same world, route_quote and command tools used by terminal agents; effective delegation and command validation still apply. Hosts without MCP Apps receive a situation briefing, structured summary and static Braille chart. map_view remains a read-only map entry point with a static fallback; map_report remains the data retrieval tool. Use its format: "ascii" when Unicode Braille is unavailable.

The panel draws a dotted X/Z map with green own holdings, cyan other owners, muted unclaimed sites and amber battles/convoy traces. Other ownership does not imply hostility. Pan, zoom, select a point (or use the accessible contact selector), toggle routes, lanes and labels, refresh, or switch motion off. The chart is steady by default; tour and cinematic emphasis can be selected. Overlapping contacts can be cycled by repeated clicks. Live snapshots refresh every three seconds while the panel is visible; the browser animates locally at up to 30 FPS. Reduced-motion preferences disable effects initially. Replay positions stay on the selected public tick, and paused snapshots show PAUSED. Private data is cleared and refresh stops when a read fails; request a fresh view to reconnect.

Route shimmer and contact glows are decorative. They do not advance fleets between authoritative ticks, reveal hidden plans, add sensor coverage, or indicate confirmed attacks. Unknown positions remain explicitly counted. Inferred threat evidence remains labeled as inference.

# A repeatable, control-free dotted map with a complete coordinate/owner index.
curl -fsS 'http://localhost:5173/api/v1/map?format=braille'
npm run --silent map -- --format braille

# Live colored terminal frames; stop with Ctrl-C. No installation or shell script required.
curl -N 'http://localhost:5173/terminal'

# The local CLI detects terminal size and reconnects on resize.
npm run --silent map -- --watch

# Use more Braille pixels on a large terminal, with the lane network visible.
curl -N 'http://localhost:5173/terminal?cols=160&rows=50&lanes=true'

These examples use the default development web port. If DEV_WEB_PORT is 5197, use http://localhost:5197/terminal for the stream, or set KUIPER_URL=http://localhost:5197 for the map CLI.

/terminal and /api/v1/map/stream are aliases. With no world selection, they open your active Alpha-10 match, otherwise the live practice arena, otherwise another live match. Public curl requests need no match ID. Supply matchId to choose a particular match, and add round for an exact public replay. Each connection keeps its selected match; reconnect to select a new arena after a match ends. If no live match exists, the endpoint returns HTTP 503 and asks you to reconnect shortly. They emit ANSI cursor positioning and truecolor Unicode Braille at up to 10 FPS, with authorized data refreshed every three seconds. cols and rows describe the whole terminal; defaults are 120×40, with bounds 60–200×20–100. Each Braille cell supplies a 2×4 dot grid, so the default chart has 236×132 addressable dots. Equal X and Z distances use equal dot spans. Use cols=80&rows=24 for a small terminal, or cols=160&rows=50 for a larger chart. Legacy width and height describe the map interior and cannot be combined with cols or rows. routes=true, lanes=false, and labels=true are the default layers. Select mode=chart|tour|cinematic, motion=true|false, ascii=true|false, and color=truecolor|256|none. Static Braille exports share the three layer flags. A remote server cannot detect terminal dimensions or whether curl output is redirected: use explicit dimensions for curl, or the resize-aware CLI. Use static format=braille or format=ascii for files and pipes. Ordinary exports and MCP text never contain terminal controls. Fixed public replay streams never advance their tick. Streams stop on disconnect, unavailable authorization/data, maintenance or server shutdown. A stopped stream does not reconnect automatically; run curl again.

Public streams need no credentials. Private current-world maps accept the same verified session or Kuiper agent-key bearer header as ordinary HTTP maps; OAuth tokens belong on MCP. Do not put credentials in URLs. Stream output is not cached and must not be buffered by a reverse proxy.

Alpha-10 visual identities

Alpha-10 maps distinguish a winged system expedition, segmented fracture missile, slender ballistic railgun dart, twin-rail charging battery, broad siege carrier, and antenna beacon. Public clinics, sequencers, vaults, genome archives, medical production, power utilities and unfinished objective scaffolds have separate marks. Fractured sites use a debris mark at their original selectable waypoint. These vector identities are shared by the 3D chart, tactical canvas and SVG; ASCII and Markdown retain textual identities and complete point indexes. JSON retains the existing typed public fields in map schema 2.8.0. The marks add no contacts, hidden building information, capacity or rules. Close-up 3D hulls and installation offsets are illustrative; exports retain authoritative positions.