Engineering, operations & design history
AI factions — Server gameplay, architecture and cost policy
Full repository source: docs/ai-factions-server-design.md
Technical documentation includes historical decisions, proposals and verification reports. For playing instructions and practical rules, open Gameplay.
No matching entry. Try a shorter phrase or clear the search.
AI factions — Server gameplay, architecture and cost policy
Saved October 7, 2026, from the faction-design discussion and its September 22 specifications.
Status: consolidated design and implementation direction, not a claim that these factions or the proposed distributed architecture are playable or deployed. This document records the agreed concept and runtime cost constraint. The living-world design remains the primary decision record; the companion specifications below contain the full mechanics and acceptance requirements.
Central decision: game-engine AI
The actual gameplay server runs factions through conventional game code: scripts, rules, authored plans, state machines, utility scoring, pathfinding and scheduled simulation events.
All routine live gameplay uses zero language-model inference calls. There is no model agent per faction, village, army or citizen. The complete game must operate without model credentials, a local inference service or a GPU. Faction planners are ordinary software functions sharing bounded execution pools.
Personalities are parameters such as caution, ambition, reserve targets and preferred partners. Decisions respond to geography, resources, threats and remembered events. A horde food shortage can trigger a comparison of importing food, changing production or expanding farmland using programmed rules; no model consultation is required.
This constraint applies to the running game on Railway. It does not prohibit using development tools to help write the game.
The factions
| Faction | Agreed role | Gameplay |
|---|---|---|
| Neutral Neighbour Houses | Small communities that interact cautiously with human players | Start with limited trades, remember dealings, build trust and defend themselves without initiating territorial conquest against humans |
| The Veiled Concord — working name | One ice-mage faction controls extensive territories around both poles; its intentions remain unknown | Fierce, overwhelming territorial defense; long quest chains unlock an audience and then restricted trade; recognition does not grant unrestricted passage |
| The Crown of Ash — working name | A Lich King controls a large part of one major continent | Defends its territory and expands with undead armies, necropolises and magical command networks |
| The Ironblood Horde — working name | Trolls, goblins and orcs form a large realm led by a dynasty of orc kings | Defends its lands and expands; royal temperament, clan interests and succession affect war, tribute, diplomacy and trade |
The neutral examples are Willow Hearth, a cautious grower; Alder Cart, a trader; and Stonewatch, a defensive builder. Major powers begin with explicit historical territory, populations and stock, rather than a human-sized starter package. Subsequent action consumes real resources and follows the game's rules.
Ice-mage access uses authored quest graphs and server-verified evidence. Undead raising consumes finite remains and energy; command relays and soul anchors provide meaningful counterplay. Orc succession transfers existing assets and obligations; a civil war does not duplicate troops or reset wealth.
How server decisions work
- A scheduled evaluation or relevant event wakes a controller.
- It receives a limited knowledge projection: its own information, lawful observations and timestamped reports.
- It identifies needs and generates a bounded set of authored candidate plans.
- It removes choices that violate authority, resources, reserves, labor, capacity or available information.
- It scores feasible plans using urgency, benefit, personality, relationships, cost, risk and the cost of abandoning an existing plan.
- It submits ordinary game commands. The authoritative engine validates current state and creates the real jobs, journeys or military orders.
- It records results, evidence, command receipts and its next decision time.
Planners share budgets so military and economic plans cannot spend the same stock. Rejected commands trigger fresh evaluation rather than blind retries. The AI cannot edit inventory, ownership or quest completion directly.
Independent factions, delegated governors and succession stewards remain different authority roles. Human logout grants no new permissions. A leader's death does not delete the faction, erase debt or renew finite allowances.
World scale and technology
The intended world contains thousands of concurrent humans and hundreds of factions, some substantially larger than human organizations. One shared world can span several internal processing regions while retaining one geography, economy and history.
| Layer | Proposed stack |
|---|---|
| Client | Retain the JavaScript/Canvas map and binary movement updates |
| Server | TypeScript for new contracts and services on Node.js 24, reusing existing JavaScript rules |
| Connections | WebSocket gateways using ws, separate from durable simulation authority |
| Simulation | Regional Node.js processes, with bounded worker pools for measured CPU-heavy tasks |
| Faction decisions | Engine scripts, state machines, authored plans and deterministic scoring |
| Persistence | PostgreSQL transactions, aggregate revisions, receipts, scheduled jobs and recovery records |
| Distributed messaging | NATS JetStream when needed, with a transactional outbox/inbox and deduplication |
| Assets | Object storage and a CDN |
| Hosting and operations | Docker services on Railway initially; metrics, traces, structured logs and representative load tests |
A large empire spans geographic workers. A strategic controller chooses broad objectives from compact summaries; regional planners administer local communities within finite budgets. Every ownership domain has one authoritative writer, with a database-checked ownership version preventing an obsolete worker from writing after reassignment. Cross-region army and cargo transfers retain unique identities and durable custody.
Residents are cohorts, armies are formations, and production and travel advance through scheduled events. Owned territory does not require every tile to tick continuously. Cosmetic detail may depend on viewers; authoritative outcomes must not.
The September assessment identified a single living-world mutation queue, full-state cloning and logging, repeated scans and broad update work as scaling risks. It recommended incremental persistence and regional ownership rather than simply adding replicas. These are dated assessment findings, not a fresh October performance audit.
The proposed validation workload is 5,000 concurrent humans, 25,000 persistent human identities, 300 AI factions, 30,000 total settlements and 100,000 active jobs. Three major-faction test fixtures contain 1,000 settlements each. These are test targets, not proven capacity or final world allocations. Testing must include real economic activity, concentrated cities, campaigns, long histories, overload and recovery.
Railway execution and persistence
Railway hosts the running game services. Ordinary server code checks which simulation work is due, executes it and sends relevant changes to players. Simulation services should remain running when no humans are connected. Saved decision state and due times allow bounded catch-up after downtime.
The small local-save deployment is a prototype foundation. At the intended scale, gateways, regional simulation and planning scale separately, while PostgreSQL owns durable world records. Additional application replicas must not each simulate an independent copy of the same world. Database and broker backup, restore and failover need explicit verification.
The complete scale assessment explains platform constraints and proposed gates. Nothing in this saved design changes Railway configuration, provisions infrastructure or certifies production capacity.
Optional model use and spending limits
Optional models may assist with reviewed development content or non-authoritative flavor text. Runtime models are disabled by default with a global budget of zero. They cannot choose strategy, execute commands, set prices, grant rewards or change facts and outcomes.
If runtime prose is enabled later, it needs explicit daily and monthly money ceilings shared across all factions and service replicas, an atomic worst-case cost reservation before each request, bounded input/output, finite jobs, low concurrency and audience-aware caching. Failed requests and retries count toward those limits; uncertain charges remain reserved. There are no open-ended agent loops or automatic upgrades to more expensive models.
Budget exhaustion, invalid output or provider failure immediately selects an authored template. Gameplay never waits for model output. Optional prose enabled or disabled must produce identical canonical simulation results for the same inputs and seed.
Zero inference spend does not mean zero operating cost: CPU, memory, databases, storage and networking still need measurement and optimization. No provider integration or paid usage is authorized by saving this design.
Full specifications
- Neutral houses and computer-controlled players: behavior, interfaces, planning, fairness, persistence and delivery stages.
- Major factions: polar quests, territorial defense, undead systems, dynastic politics and campaigns.
- World-scale architecture: technology recommendations, capacity assumptions, ownership, persistence, costs and verification.
- Living-world design: primary current decision record and implementation status.
- Technical wiki: authored implementation explanations and access to the complete source archive.