30 KiB
Executable File
WikiRPG
A persistent, text-based multiplayer RPG where the wiki is the game board, and play becomes the world's history.
WikiRPG combines tabletop roleplaying, a shared online world, interlinked wiki pages, and an AI-assisted dungeon master. Players choose their own ambitions rather than follow a prescribed quest line. Their actions change the world and create a history that can be explored through the people, places, objects, and events involved.
Players decide what they want to accomplish. Rules determine what changes. AI narrates those changes. The wiki makes them discoverable—without revealing secrets.
Project status
WikiRPG is an early local prototype alongside a broader game design. The playable slice implements server-authoritative timed activities, a knowledge-filtered wiki, a small market, and persistent demo state. The sections below describe the intended game; not all are implemented. Technical architecture, rules, and economic details remain open to experimentation.
See DEVELOPMENT_PLAN.md for the gameplay-first roadmap: richer characters, cooperation, production, exploration, encounters, secrets, and player-created histories, followed by a small persistent release on Kubernetes with Dex SSO.
The experience
Imagine opening the page for a ruined river crossing. It describes the terrain, the bridge's condition, visible creatures, and characters whose presence you can perceive. A player-led reconstruction project needs timber. You can contribute materials, negotiate payment, explore upstream, or pursue an entirely different goal.
The bridge's history links to its construction, destruction, and subsequent expeditions. Those events link to their participants, whose pages connect to other adventures, possessions, and affiliations.
Meanwhile, another character might be crossing the river unnoticed. Their journey is recorded, but it does not appear in your view simply because you opened the page. If you later find tracks or learn about the journey, your understanding of the place changes.
Reading, acting, and discovering history are all parts of the same interface.
Design principles
- Player-driven goals: Players decide what is worth doing. The world provides opportunities and consequences, not a mandatory storyline.
- A persistent shared world: Locations, possessions, construction, relationships, and past actions continue to matter between sessions.
- Interlinked history: Events connect to their locations, participants, objects, and consequences.
- Knowledge matters: A character's access to information is part of play. A wiki page is not an omniscient view.
- Constrained AI authority: AI assists with narration, worldbuilding, and adjudication, but cannot freely rewrite established facts or another player's choices.
- Meaningful player authorship: Players define their characters and create culture and infrastructure through play without gaining arbitrary power by editing prose.
- Asynchronous participation: Players can contribute even when friends or trading partners are offline.
The wiki is the game board
| Page type | Contents, subject to the viewer's knowledge | Example actions |
|---|---|---|
| Character | Appearance, permitted biography, visible activity, known affiliations, discovered history | Communicate, trade, propose a joint action |
| Place | Known geography, observable occupants, resources, structures, local history | Travel, explore, gather, build, investigate |
| Object | Known properties, observed possession, discovered provenance | Examine, use, offer, transfer |
| Creature or monster | Discovered traits, sightings, habitats, encounters | Observe, evade, study, interact |
| Organization | Public or discovered membership, rules, territory, projects | Join, negotiate, contribute |
| Event | An authorized account of an action and its consequences | Investigate, follow related links |
| Project or contract | Goals, contributions, terms, progress, permitted participants | Contribute, make an offer, accept terms |
Pages provide contextual actions alongside descriptions and history. Current presence and activity are visible only when observation or another explicit disclosure rule permits it. Offline status does not automatically make a character invisible or available for unrestricted actions by others.
Wiki prose is not authoritative game state. Editing a sentence to say “I own this castle” does not establish ownership. Validated actions determine state; pages present that state and permitted authored material.
Players, creatures, and the AI dungeon master
Players fill the world's social roles: traders, explorers, builders, rulers, scholars, rivals, and collaborators. The initial concept does not rely on AI-controlled townspeople, shopkeepers, or quest-givers.
NPC creatures and monsters do exist. They provide environmental life, danger, discovery, and opportunities for encounters when other players are unavailable. Their capabilities and behavior must follow world rules rather than change arbitrarily to force a narrative outcome.
The AI serves as an environmental narrator, continuity assistant, and constrained dungeon master. It can:
- Describe what a character can perceive.
- Help interpret player intentions into supported actions.
- Propose coherent terrain, discoveries, creatures, and lore within worldbuilding constraints.
- Assist with creature behavior and encounters within validated rules.
- Narrate resolved outcomes and generate knowledge-appropriate wiki accounts.
The AI must not:
- Invent another player's consent, decisions, dialogue, or private thoughts.
- Grant resources, ownership, or abilities merely because a player asks convincingly.
- Alter established history to make a story more dramatic.
- Reveal information unavailable to the viewer.
- Treat player-written text as instructions that override game rules.
From intention to event
- Declare an intention: “I want to repair the bridge,” “I search for tracks,” or “I attempt to cross unnoticed.”
- Check prerequisites: Validate location, available resources, abilities, permissions, and relevant world state.
- Present a commitment: Explain character-knowable costs, risks, and required participation without disclosing hidden facts.
- Commit the action: The player accepts the supported action and its terms.
- Resolve through rules: Apply time, resource costs, uncertainty, observation, and consequences. Conflicting actions must resolve consistently, without duplicating possessions or spending the same resource twice.
- Record the event: Save the authoritative outcome and its disclosure rules.
- Update permitted views: Refresh affected pages and notify only viewers entitled to the information.
The AI's narrative describes the result; it is not a substitute for a validated state transition. Retried requests must not apply the same action twice.
Time, activities, and offline play
Use one continuously running server clock shared by all characters. World state does not pause when a player closes the browser. Deadlines display as both world time and the player's local time.
Start with a 20-real-hour world day: dawn rotates across real-world timezones instead of permanently assigning night to some players. One world hour lasts 50 real minutes. The initial region shares a daylight schedule: dawn from 05:00–07:00, daylight from 07:00–18:00, dusk from 18:00–20:00, and night otherwise. This is a tunable prototype rule, not a final calendar. Persist the epoch so restarts never reset the sky.
Each character can undertake one primary physical activity at a time. Travel, gathering, crafting, construction, investigation, and rest block incompatible world actions until completion or cancellation. Reading known wiki pages remains available. Remote account management and communication need their own access rules rather than an indiscriminate lock on every interaction.
Activities record start and completion times, reserved inputs, location, and cancellation rules. Completion happens server-side exactly once without a “claim reward” button. Offline time counts. Resolve overdue events in deadline order, including on restart, before accepting a new action. Day/night changes can affect observation and creature behavior once those rules are implemented, not merely the interface.
Cancellation must explain costs and progress before commitment. In the first prototype it forfeits elapsed work, refunds reserved crafting or construction materials, and leaves a canceled traveler at the origin; this is a simplification, not realistic route simulation. Future travel should track route progress and safe stopping points.
Offline is not a character condition. Dangerous activities need precommitted, bounded interruption responses, never invented AI consent. Severe consequences against offline characters require separate player-conflict policy. Avoid unlimited queues, punishing login obligations, and accelerated upkeep. Time should constrain character output without dictating when a player must log in.
One living character per player
Each player account may have one living character at a time. A living character cannot be replaced to escape an activity, debt, or inconvenient situation. After that character dies, the account may create a successor with an approved starting background.
Deceased characters remain historical entities with linked events; private information does not become public on death. A successor starts with their own knowledge and assets. Neither private memories nor wealth transfers automatically. Inheritance, estate settlement, debts, and organization succession need explicit rules before they become playable.
Character creation and successor creation must not grant repeated currency allocations. Any newcomer allocation is account-scoped and bounded; death is not a currency faucet. One character per account does not by itself prevent multiple-account abuse, which requires a separate identity and enforcement policy.
Death is permanent for the character in this proposed lifecycle. Its causes, warnings, consent rules, and protections for offline players remain undecided. The prototype tests the lifecycle boundary but does not implement lethal encounters or inheritance.
Player authorship and world consistency
Player contributions have three distinct levels:
1. Personal authorship
Players define appearance, personality, ambitions, and permitted starting background. Backgrounds cannot grant unearned wealth, exceptional powers, ownership, or authority over another character. Changes that affect mechanics require validation.
Public biographies should be deliberately published material, not automatic exposure of private character notes.
2. Creation through play
Players can write books, name discoveries, found organizations, construct buildings, make agreements, and establish traditions. These become world content through valid actions and explicit publication rules.
3. Worldbuilding proposals
Players may propose lore, locations, or other additions. Proposals remain separate from established canon until checked for contradictions, mechanical advantages, and effects on existing players. Whether approval is automated, moderated, or shared is an open design decision.
The wiki distinguishes established facts, observations, claims, and rumors. A character may claim to be the rightful ruler; publishing the claim does not make it objectively true. Player contributions should retain authorship and revision history.
Secrets and character knowledge
Recommended approach: authorized views, not cosmetic censorship
Maintain authoritative world state separately from the wiki view shown to each player. The server builds each response from information that the viewing character is allowed to access.
Hidden information must not be sent to the browser and then concealed with styling or replaced visually. That would still expose it through page source, network responses, or other interfaces.
Use three kinds of information:
- Public information: Intentionally published or otherwise accessible under defined rules.
- Character knowledge: Observations, discoveries, and accounts available to a particular character or permitted group.
- Hidden world facts: Actual state and events not yet available to that viewer.
Knowledge should record its source and when it was acquired. “I saw someone enter yesterday” is not equivalent to “they are there now.” A report can be inaccurate, incomplete, or disputed without changing the underlying truth.
What a viewer sees
- A place page lists observable or otherwise known occupants, not every character actually present.
- A hidden journey does not appear in a public activity feed.
- An unseen theft does not expose the thief's identity. A victim may discover an item missing without knowing what happened to it.
- A discovered clue may reveal part of an event without revealing its participants or full outcome.
- A character's exact location is not published by default; players can explicitly share it where the rules permit.
- Unknown locations and events do not appear as revealing links, titles, counts, search results, or “secret event” placeholders.
Visible censorship is useful only when a character already knows that a document or passage exists but cannot read its contents. Otherwise, omit unavailable information entirely.
Discovering and sharing information
Observation, investigation, messages, testimony, and publication can expand knowledge. Sharing an account gives the recipient access to that account; it does not automatically certify the account as true or expose all related hidden records.
Learning about an event can reveal an authorized account of it without granting access to every participant's private history. Authorization must be checked independently for every linked page.
Apply the same disclosure rules to page content, APIs, search, backlinks, timelines, notifications, exports, and generated summaries. Shared caches must not mix viewers' private knowledge. AI narration should receive only the context needed for the authorized account; hidden adjudication context must remain separate from player-facing generation.
This protects system-held secrets, not against players sharing information outside the game. Alternate-character knowledge transfer and other metagaming require explicit game policy.
History, truth, and corrections
Completed actions form an append-only event ledger. Events identify involved entities, their effects, and the rules governing disclosure. Current state is derived from validated events, with snapshots or indexes available for efficient retrieval.
The goal is for the entire in-world history to be browsable as knowledge permits, not for every player to receive an omniscient archive. A single authoritative event can have several partial accounts for different viewers.
Corrections to game outcomes become explicit corrective events rather than silent changes to past actions. Wiki presentation and authored descriptions can have ordinary revisions without rewriting the action ledger.
Permanent game history does not mean permanent storage of everything. Keep credentials, real-world personal data, and private out-of-game communications out of the historical ledger. Retention, moderation, and deletion requirements need separate policies. Privileged operational access should be restricted and audited.
A player-driven economy
A robust economy is a core game pillar, not an optional currency feature. The ambition is an EVE Online-like depth of player production, trade, specialization, logistics, and economic consequences, adapted to a text-based fantasy world. This does not require blockchain or real-money convertibility.
Currency should have useful purchasing power because players need goods and services that take resources, time, skill, and risk to supply. Prices should emerge from player offers and demand rather than arbitrary AI valuations.
Production, scarcity, and demand
- Production chains: Resources become intermediate materials, tools, equipment, and structures. Begin with a short chain that creates opportunities for different players to specialize.
- Geographic scarcity: Resource availability and regeneration follow explicit world rules. Regions can have different supplies; the AI cannot conjure valuable deposits or stockpiles to satisfy a request.
- Meaningful logistics: Goods have physical locations. Travel time, carrying capacity, storage, and character-knowable risks give transport and local production economic value. A remote purchase does not teleport an item to its buyer.
- Recurring demand: Consumables, construction, and proportionate maintenance or equipment wear keep producers useful. Loss and salvage rules can also affect supply where the game's conflict policy permits them. Avoid punitive upkeep that makes occasional play unviable.
- Player services: Transport, exploration, crafting, and project work can support negotiated payments and asynchronous contracts.
- Economic organizations: Groups can maintain treasuries, shared stockpiles, production projects, and controlled access to assets. Their permissions must be explicit rather than inferred from wiki descriptions.
Selling an item moves goods and money; it does not create either. Creature encounters may yield rule-defined materials or salvage, but monsters should not produce unlimited currency merely because they are defeated.
Markets and contracts
Support local buy and sell orders, partial fills, expiration, and escrow so trading does not require both parties to be online. Sell orders reserve goods at the named market; buy orders reserve funds. Buyers receive goods at that market and must arrange any onward transport.
Market listings should identify goods, quantities, prices, and pickup locations. Exposing counterparty identities is a separate disclosure decision. Price history and trade volumes should be available only for markets the character can access, under defined publication rules; private contracts must not leak into public feeds.
Simple exchanges can settle automatically. Delivery contracts need objective destinations, deadlines, and acceptance conditions. Subjective services require explicit approval and dispute rules, not an AI's unrestricted judgment.
Currency supply and economic health
Use one common currency initially. Its name and denominations remain undecided. New currency enters through a bounded, documented issuance policy; account creation must not become an unlimited source of money through alternate characters.
Because the world does not rely on NPC merchants or quest-givers, currency issuance cannot quietly assume those systems exist. A small prototype can begin with a bounded test allocation. Before scaling, define how legitimate new players gain access to currency, whether and how ongoing issuance works, and how it interacts with currency sinks.
Player payments circulate currency. Explicit system fees can remove it; payments to a player-run treasury merely redistribute it. Item consumption and destruction reduce goods, not the money supply. Track these separately.
Monitor issuance and sinks, active-account balances, prices of a representative goods basket, production and consumption, market liquidity, wealth concentration, and suspicious activity. Thin early markets need testing with real participants before adding complex monetary mechanisms. Economic tuning should be documented, not performed through secret AI price manipulation.
Recommended accounting foundation
A server-managed currency backed by a relational database and double-entry transaction ledger is the initial recommendation:
- Characters and organizations have accounts; issuance and sinks use explicit balancing accounts.
- Store amounts in integer minor units, not floating-point values.
- Every committed transaction balances. Payments, item transfers, order fills, and escrow changes settle atomically and cannot apply twice when retried.
- Ownership records track each item's quantity and location; reservations prevent the same goods or funds from backing multiple offers.
- Committed accounting entries are auditable, with corrections recorded as reversals or compensating entries rather than silent balance edits.
- Players see authorized balances and accounts of transactions. The authoritative ledger is not a public list of every character's economic activity.
- AI can explain or propose an exchange, but only validated rules can authorize transfers or issuance.
Accounting and knowledge remain separate: actual possession can change without immediately revealing the new holder to every character. Currency in a protected account is distinct from a carried purse; what can be stolen and how it is discovered must be explicitly defined.
This approach requires trust in the operator, backups, reconciliation, and restricted administrative access. It offers simpler settlement and better control over gameplay secrets than an ordinary public blockchain. Real-money purchases, withdrawals, and external asset trading are separate product and legal decisions, not prerequisites for economic depth.
Possible blockchain integration
Blockchain is an optional direction, not an assumed requirement for the first version. It may support independently verifiable currency ownership or transfers outside the game, but does not prove that an AI-generated outcome was correct or fair.
Public-chain transactions can reveal counterparties, amounts, and timing. Linking wallets to characters could undermine secret theft, hidden affiliations, or trade even when the wiki is properly filtered. Any blockchain design must reconcile that exposure with the game's knowledge model; ordinary public transactions are not secret.
Do not put private gameplay, personal data, or the entire wiki on a public chain. Before introducing real-value currency, address transaction costs, custody, theft, speculation, bots, and applicable legal obligations. The authority boundary between game ownership and external asset ownership must be explicit.
Initial playable scope
Start with one small region and a handful of players:
- Character creation with constrained backgrounds.
- Interlinked character, place, object, creature, and event pages.
- Travel, visible presence, and one hidden-travel mechanic.
- One resource and a small set of craftable items.
- A limited creature encounter system.
- One short production chain, local trading with escrow, and asynchronous offers.
- A bounded test currency supply with auditable transfers and explicit issuance rules.
- Player messages and a simple delivery contract.
- One collaborative construction project.
- Observation and investigation, including a simple theft scenario if player-conflict rules are agreed.
- Knowledge-filtered histories and search.
- AI narration grounded in validated outcomes and authorized context.
Defer a vast generated world, elaborate combat, unrestricted world editing, and blockchain deployment until this loop is enjoyable and reliable.
Prototype success criteria
- A small group creates an interesting story without being assigned a quest.
- Players can understand how their actions affected the world by following wiki links.
- Someone can make meaningful progress while other players are offline.
- A hidden journey or theft remains undisclosed until a valid observation, investigation, or disclosure reveals it.
- A partial discovery does not reveal unrelated secrets through linked pages or summaries.
- Concurrent actions cannot duplicate objects or overspend resources.
- Players can profit from production or transport because other players genuinely need the output, without mandatory quests or NPC purchasing.
- Money and item ledgers reconcile; market reservations and partial fills cannot duplicate funds or goods.
- Trading and recurring consumption remain viable at the prototype's small population size.
- AI narration does not invent mechanical rewards, player consent, or unauthorized knowledge.
Decisions still to make
- What setting and tone best support the player-driven sandbox?
- What are the starting abilities, progression rules, and limits on backgrounds?
- How should the proposed 20-hour cycle, activity durations, interruptions, and simultaneous actions be tuned?
- What are the consent, theft, PvP, injury, death, and offline-character rules?
- How are discovery, observation, concealment, and knowledge sharing adjudicated?
- Who can approve worldbuilding proposals and resolve disputed outcomes?
- How much creature behavior is rule-driven versus AI-assisted?
- What information can players intentionally publish or withdraw from future access?
- How are harassment, exploit attempts, metagaming, and appeals handled?
- How are AI costs, latency, failures, and model changes managed?
- What currency issuance, sinks, resource regeneration, and recurring demand sustain a healthy player economy?
- What market information is public, local, or private, and what assets are exposed to theft?
- Does blockchain provide enough value to justify its privacy and operational trade-offs?
North star
Build a world worth exploring and a history worth reading—where players create the stories, and discovering the truth is part of the adventure.
Running the local prototype
Requires Node.js 24. Install the package dependencies with npm install, then use npm start to serve the app and npm test for automated checks. The default address is http://127.0.0.1:8090; PORT can override it. No AI API key is needed.
The demo contains two seeded accounts, a three-location region, gathering, timber-to-plank crafting, bridge contributions, creature observation, concealed travel, local escrow-backed sell orders, and linked event pages. Timed actions take seconds for testing, while the sky follows the proposed 20-hour day. Switch demo accounts to compare knowledge views and trade. No free-text AI model is connected: narration uses deterministic templates.
SQLite stores an atomic world snapshot outside the served files; an internal balanced currency journal records demo trades. This is intentionally a small single-process prototype, not a normalized production economic database or complete event-replay architecture. Mutations require an Idempotency-Key; the last 1,000 keys per account are persisted atomically with outcomes to prevent retried requests applying twice within that window. Set WIKIRPG_DB to choose a database location. On Windows the default is beneath LOCALAPPDATA; elsewhere it is beneath the user's home directory. Restarting retains activity deadlines and resolves elapsed work. Tests use isolated temporary databases.
Security boundary: this is a loopback-only trusted-user demo, not a public multiplayer deployment. Its account switcher deliberately permits impersonating seeded accounts. Random HttpOnly/SameSite cookies, same-origin mutation checks, strict response filtering, bounded requests, parameterized persistence, and a static asset allowlist protect the local slice, but do not replace real authentication. HTTP is permitted only for this local demo; deployment requires HTTPS, authentication, account-abuse controls, and a security review. Never enter real personal data.
Not yet implemented: successor-creation UI, lethal encounters, inheritance, messages, delivery contracts, buy orders, full supply balancing, dynamic creature behavior, model-based narration, geographic daylight, and production-scale operational hardening. Successor creation is available through the domain/API layer and automated tests. Broader scope above remains a roadmap.
Dex SSO
Dex/OpenID Connect is the intended platform authentication, not a separate game password system. The prototype includes an optional Dex adapter using the maintained openid-client library, Authorization Code flow with S256 PKCE, state and nonce validation, discovered signing keys, and library validation of token signatures, audience, issuer, and expiry. It additionally requires verified email and the configured federated connector. No groups are required for game access yet; any future group policy must be checked server-side.
Set AUTH_MODE=dex, DEX_ISSUER (the platform convention is https://dex.eom.dev/), DEX_CLIENT_ID=wikirpg, DEX_CLIENT_SECRET, DEX_CONNECTOR_ID=ldap, and APP_ORIGIN (an exact HTTPS origin without a trailing slash). Register a Dex static client with that client ID, a separately managed secret, and the exact redirect URI APP_ORIGIN/auth/oidc/callback. Supply the secret through the deployment environment or Ansible Vault, never source control. No existing platform deployment files have been changed.
Preserve the issuer's exact trailing-slash convention. Accounts are linked by (issuer, subject), never automatically merged by email or display name. First login creates one living character with no currency grant. Returning login reuses that account; a name change does not replace its character. A successor does not inherit private knowledge. The account treasury currently persists across death for testing, but estate rules are not settled; this is not a finalized inheritance mechanic.
Dex mode disables the demo account-switch endpoint, and NODE_ENV=production refuses to start in demo mode. Login callbacks rotate the session; cookies are HttpOnly, Secure, and SameSite=Lax, allowing the cross-site OIDC callback. Sessions expire after eight hours or thirty idle minutes and are held in memory, so server restarts require a fresh login. Local logout removes only the game session; it does not sign out every platform application. Tokens are not stored in the browser or world database. Only openid email profile federated:id scopes are requested; group data is not needed for this slice.
Run the backend on loopback behind a trusted HTTPS reverse proxy which preserves the configured public Host header. The backend validates that Host and the exact Origin on mutations and does not trust arbitrary forwarded headers. Demo mode must not be exposed through a public proxy. Real Dex login requires client registration and operator-provided secrets; automated tests do not establish that the live platform has been configured or end-to-end login verified.