Eden Realms — Game Design Document

Document version: 0.1
Project stage: Pre-production / concept definition
Working game name: Eden Realms
Last updated: 2026-07-31
Document status: Living design document; no implementation has begun

1. Document purpose

This Game Design Document (GDD) is the current design source of truth for Eden Realms. It communicates what the game is, what experience it should create, how its major systems relate, and what the first playable version must prove.

This is not intended to freeze every balance value before testing. High-level decisions are recorded as confirmed direction, while untested mechanics and numerical values remain proposals or open questions. As prototypes are tested, this document should be updated alongside MILESTONES.md, CHANGELOG.md, README.md, and supporting feature specifications.

1.1 Decision labels

• Confirmed: Agreed foundation of the game.
• Proposed: Current design direction that must be tested.
• Future: Intentionally outside the first playable version.
• Open question: Requires a later design decision.

1.2 Design-document strategy

The main GDD explains the whole game at a useful level. Complicated systems such as hero generation, raid resolution, map editing, social permissions, and economy balance should eventually receive focused feature documents rather than making this file impossible to maintain.

The document structure follows the living, purpose-driven approach described in Game Dev Beginner's How to write a game design document: communicate the high-level concept and pillars first, expand mechanics as they become testable, and use focused supporting documents for systems that outgrow the main GDD.

2. High concept

2.1 One-sentence pitch

Eden Realms is a persistent, cooperative, text-first fantasy settlement RPG where players establish frontier keeps, manage settlers and resources, attract randomized heroes, and send parties into a whimsical hex-based world shaped by dice, idle timers, shared stories, and a human Server Master.

2.2 Player-facing fantasy

The player is the steward of a growing keep, not a single adventuring hero. They build a home in an untamed realm, sustain its people, recruit remarkable heroes, prepare expeditions, discover forgotten stories, and cooperate with neighboring players when the realm is threatened.

The desired feeling is:

“I helped turn a dangerous frontier into a place with a history, and I can still visit the record of what we built together.”

2.3 Genre

• Persistent browser-based role-playing game
• Cozy settlement and resource management
• Cooperative idle game
• Text-first adventure and campaign game
• Dice-driven tabletop-inspired RPG
• Lightweight asynchronous multiplayer

2.4 Initial platform

• Web browser on desktop and mobile
• Responsive HTML interface
• Keyboard, mouse, and touch input
• No native mobile application in the initial release
• Server APIs designed so a native client could be added later

2.5 Initial player structure

• Minimum target test group: four separate player accounts
• One Server Master may create and operate a Realm
• Players may belong to multiple Realms through one persistent account
• Parties contain up to five heroes
• The game is primarily asynchronous, with optional shared events and social interaction

3. Design pillars

Every major feature should support at least one pillar and must not undermine the others.

3.1 Cozy survival, not constant punishment

Food, weather, supplies, injuries, and danger create meaningful pressure, but ordinary play should feel restorative and inviting. Low-risk activities should produce setbacks, stories, or inefficiency more often than irreversible loss. Lethal danger must be clearly communicated before a player commits to it.

3.2 The settlement is the player's long-term build

Buildings, professions, terrain, culture, relics, and settlement history determine what the keep can produce and which heroes it attracts. Progress is expressed through a living place rather than only through increasing character numbers.

3.3 Idle decisions should remain meaningful

Timers create anticipation and allow progress without constant attention. Before starting an activity, players choose who goes, what supplies are committed, how much risk is acceptable, and what opportunity they give up. A timer should not replace decision-making.

3.4 Shared worlds should leave permanent stories

Realm discoveries, campaigns, raids, fallen heroes, settlements, and player journals become a readable historical record. Archiving a Realm makes it read-only rather than erasing it.

3.5 A human Server Master shapes the world

The Server Master creates maps, locations, starting conditions, events, threats, and campaigns. The application supplies consistent rules, permissions, logs, and automated resolution without replacing the Server Master's creativity.

3.6 Surprise with understandable rules

Random heroes, dice rolls, loot, and mission outcomes create discovery, but important results must be explainable. Players should understand which stats, buildings, supplies, traits, risks, and rolls affected an outcome.

3.7 Social by design, limited by intention

Eden Realms should support roleplay, cooperation, planning, and remembrance without attempting to become a general-purpose social network or a full Discord replacement.

4. Inspirations and interpretation

These references describe desired qualities, not content to copy.

Eden Realms will use an original setting, ruleset, terminology, characters, lore, art, and written content. It is inspired by classic tabletop fantasy but is not intended to reproduce D&D 5e rules or protected content.

5. Product identity and vocabulary

5.1 Eden Realms

The overall game and web platform.

5.2 Eden Realm

An individual persistent world created and managed by a Server Master. A Realm contains its own members, map, keeps, ruleset, events, resources, history, and archive state.

5.3 Chronicle

The player-facing cross-Realm lobby, identity, profile, history, journals, Realm directory, and archive navigator. Chronicle follows the account rather than belonging to one Realm.

5.4 Server Master

The Realm creator and world facilitator, comparable to a tabletop Dungeon Master. A Server Master controls their own Realm content and events but cannot bypass platform security or access another owner's Realm.

5.5 Keep

A player's home settlement and management center within a Realm.

5.6 Settlers

The people who operate farms, fisheries, mines, workshops, housing, transport, healing, and other settlement functions. “Settlers” is the preferred working term; alternate in-world cultural names may be introduced later.

5.7 Heroes

Named, randomized adventurers attracted by the keep. Heroes form parties, undertake missions, explore dungeons, acquire equipment, defend the Realm, become injured, retire, disappear, or die.

6. Experience overview

6.1 Primary gameplay loop

1. Review the keep, available workers, heroes, supplies, and current Realm events.
2. Choose settlement work, construction, recruitment priorities, or expeditions.
3. Commit settlers, heroes, rations, equipment, and time.
4. Allow server-tracked timers and events to progress.
5. Return to resolve or review outcomes.
6. Collect resources, discoveries, equipment, injuries, losses, and story entries.
7. Improve the keep and prepare for more demanding opportunities.
8. Coordinate with other players for dungeons, Realm decisions, or raids.
9. Preserve meaningful outcomes in the Realm record and player Chronicle.

6.2 Nested loops

Daily cozy loop

• Fish, farm, forage, gather, craft, repair, cook, rest, and socialize.
• Maintain rations, housing, morale, and production.
• Check completed assignments and new arrivals.

Settlement loop

• Claim permitted hexes.
• Construct and improve buildings.
• Assign settlers to professions.
• Balance production, storage, upkeep, and hero capacity.
• Develop a recognizable settlement specialty.

Hero loop

• Attract procedurally generated heroes.
• Decide whether to recruit them.
• Equip, recover, and organize them.
• Form parties of up to five.
• Build histories and relationships through missions.

Expedition loop

• Select a known location or investigate an uncertain lead.
• Evaluate travel time, requirements, risk, and possible rewards.
• Commit a party, equipment, and rations.
• Resolve dice-driven events and return with consequences.

Realm loop

• Discover regions and key locations.
• Participate in Server Master events.
• Cooperate on large construction, defense, dungeons, and raids.
• Shape the culture and recorded history of the Realm.

Chronicle loop

• Review active and archived Realms.
• Follow personal, hero, keep, and campaign histories.
• Write or read permitted journals and roleplay records.
• Revisit past worlds without searching through disconnected files or chat logs.

7. Roles and authority

7.1 Player

A player owns one platform account and Chronicle. Within each Realm, the player may own a keep, manage assigned settlers and heroes, take part in social spaces, and contribute to Realm events.

7.2 Server Master

The Server Master can:

• Create and configure a Realm.
• Create the initial hex map and key locations.
• Define starting regions and player allocations.
• Set starting resources, rations, settlers, professions, and constraints.
• Create story events, missions, dungeons, discoveries, and threats.
• Start Realm raids and define their narrative context.
• Pause or archive the Realm.
• Review an audit log of important Realm actions.

The Server Master cannot:

• Access private account information unrelated to their Realm.
• Manage another Server Master's Realm.
• silently alter results without leaving an appropriate audit record.
• Bypass platform authentication or authorization.

7.3 Platform administrator

The platform administrator maintains the Eden Realms installation, accounts, security, backups, and system health. This is distinct from creative authority inside a Realm.

8. Chronicle design

8.1 Purpose

Chronicle is a deliberately limited social and historical client. It gives players a persistent identity and a dependable place to find current activity, previous campaigns, and archived Realms.

8.2 Initial Chronicle features

• Player profile and display identity
• Active Realm list
• Pending Realm invitations
• Archived Realm list
• Recent account and Realm activity summaries
• Links to characters, keeps, heroes, campaigns, and Realm histories as they become available
• Privacy settings
• Empty states for new players

8.3 Future Chronicle features

• Player and campaign journals
• In-character and out-of-character posting spaces
• Direct messages
• Lightweight live Realm chat
• Forums or discussion boards
• Friend or trusted-contact relationships
• Achievements and notable discoveries
• Search across information the player is permitted to view

8.4 Archive behavior

An archived Realm is read-only and remains discoverable through Chronicle. Its archive may include:

• Realm name, Server Master, lifespan, and status
• Participating players and heroes, subject to privacy settings
• Final map and settlement states
• Major discoveries and campaign milestones
• Raid records
• Fallen or retired heroes
• Player and campaign journals
• A final Realm summary
• Link to a successor Realm, when one exists

Archived records should be stable. Corrections or moderation actions require an audit trail rather than untracked rewriting.

9. Hosted Realm design

9.1 Realm lifecycle

• Draft: Server Master is configuring the Realm.
• Open: Invitations or future applications may be accepted.
• Active: Normal play is available.
• Paused: Read access remains, but most game-changing actions stop.
• Archived: The Realm becomes permanently read-only for ordinary users.

9.2 Initial Realm setup flow

1. Server Master creates the Realm identity and description.
2. Server Master selects the current ruleset version.
3. Server Master creates a connected hex map.
4. Terrain, buildability, special features, and key locations are assigned.
5. Starting regions or hexes are reserved for players.
6. Starting resources, rations, settlers, professions, and conditions are configured.
7. Players are invited through Chronicle.
8. The Server Master reviews a setup-validation checklist.
9. The Realm becomes Active.

9.3 Realm isolation

Every Realm-owned object must have an authoritative Realm relationship. Membership in one Realm never grants access to another. The browser may request a Realm, but the server determines whether the current account may see or modify it.

9.4 Initial hosting model

During early development, a Realm is a logical world inside one Eden Realms PHP application and SQLite database. It is not a separate container or machine. This keeps the prototype understandable while preserving boundaries that can support more advanced hosting later.

10. World and hex map

10.1 Map concept

The Realm map consists of connected hexagonal tiles laid down by the Server Master. Pixel-art assets represent terrain, structures, discoveries, and state overlays.

10.2 Coordinate model

The authoritative map should use axial hex coordinates rather than screen positions. This supports reliable adjacency, travel range, roads, building bonuses, fog of discovery, and future pathfinding independent of the renderer.

10.3 Hex properties

Each hex may include:

• Realm ID
• Axial coordinate
• Terrain type
• Discovery state
• Buildable or blocked state
• Ownership or claim
• Region membership
• Named location
• Resource feature
• Hazard or story tag
• Primary structure
• Road, river, or other connection data later

10.4 Example terrain

• Grassland
• Forest
• Hills
• Mountain
• River or lakeshore
• Coast
• Swamp
• Ruins
• Corrupted or haunted land

The final terrain list is open and should be driven by available pixel-art scope and prototype needs.

10.5 Buildable areas

The Server Master explicitly decides which map hexes can support player structures. A buildable hex normally holds one primary structure, although upgrades and minor attachments may be added later.

10.6 Adjacency and placement

Placement creates meaningful settlement planning. Proposed examples:

• A forge near an ore source improves smithing or melee equipment production.
• A ranger lodge beside forests improves scouting, hunting, and ranger attraction.
• A fishery beside water produces rations and supports water-related events.
• A stable connected to routes reduces some travel times.
• An observatory near ruins improves magical discovery while increasing unusual risks.

These are proposed relationships, not final balance rules.

10.7 Initial map scope

The first playable Realm should use approximately 20–50 connected hexes, four starting player regions, several terrain types, and a small number of notable locations.

11. Keeps and settlement management

11.1 Keep purpose

The keep is the player's primary management space. It stores resources, houses settlers and heroes, supports assignments, and expresses the player's long-term strategy.

11.2 Initial keep state

A new keep may receive:

• One assigned starting hex or region
• Starting housing
• A fixed settler population
• Initial rations
• Basic construction resources
• Limited storage
• A small number of build opportunities

Exact values remain open until the prototype ruleset is defined.

11.3 Building design principle

Buildings provide production and utility while shaping the hero-attraction pool. They influence recruitment rather than guaranteeing a class on demand.

11.4 Proposed building families

Not every building or class will be included in the first playable version.

11.5 Settlement specialization

Players may develop balanced settlements or recognizable specialties such as:

• Forge town
• Hunting outpost
• Arcane enclave
• Trade and travel hub
• Agricultural homestead
• Experimental workshop settlement

To prevent one dominant build, future balancing may use land limits, worker requirements, upkeep, diminishing attraction bonuses, terrain constraints, and cross-building synergies.

11.6 Settlement Legacy

Future: The keep's buildings, culture, relics, guilds, retired heroes, mentors, major victories, and historical choices influence future recruitment. This replaces a literal hero-breeding system with a world-appropriate legacy system.

12. Resources, rations, and economy

12.1 Resource purpose

Resources support survival, building, recruitment, missions, upkeep, crafting, and Realm contributions. Scarcity should create choices without turning ordinary cozy activities into constant crisis management.

12.2 Proposed prototype resources

• Rations
• Wood
• Stone
• Ore
• Coin or another general exchange resource

Additional resources such as herbs, fish, hides, magical components, relic fragments, and crafted goods should wait until the basic economy is testable.

12.3 Resource rules

• All gains and costs are resolved by the server.
• Resource totals cannot become negative unless a future debt mechanic explicitly allows it.
• Important changes create resource transaction records.
• Storage capacity may limit accumulation.
• Missions and hero upkeep may consume rations.
• Construction consumes materials and time.
• Realm raids may accept voluntary resource contributions.

12.4 Economic design risks

• Timers that feel like chores rather than anticipation
• Unbounded accumulation removing meaningful choices
• Mandatory upkeep punishing players for being offline
• One resource becoming the only meaningful resource
• High-risk content being required for basic survival
• Multi-account abuse or duplicated rewards

The prototype must favor readable, forgiving numbers over an elaborate economy.

13. Settlers and professions

13.1 Settler role

Settlers sustain the keep. They perform dependable production and support work while heroes handle dangerous or unusual adventures.

13.2 Proposed starter professions

• Farmer
• Fisher
• Woodcutter
• Miner
• Builder

13.3 Settler properties

A settler may have:

• Name
• Profession
• Relevant work statistics
• Traits
• Current assignment
• Availability state
• Morale or wellbeing later
• Personal history later

13.4 Assignment flow

1. Player chooses an available settler.
2. Player selects a permitted assignment.
3. The server validates ownership, prerequisites, capacity, and current state.
4. The server records start and completion timestamps.
5. The client displays time remaining.
6. The server determines when the assignment has completed.
7. The result is generated once and recorded.
8. The keep receives resources, an event, or another defined outcome.

The browser countdown is informational. Changing local time or JavaScript must not change the authoritative result.

14. Heroes

14.1 Hero identity

Heroes are individual characters rather than interchangeable units. A player should remember who explored a ruin, survived a disastrous mission, defended the Realm, founded a guild, retired, or died.

14.2 Proposed hero data

• Name
• Ancestry or race
• Class
• Core statistics
• Traits
• Upkeep or ration requirement
• Equipment
• Injury and recovery state
• Current assignment
• Recruitment source and attraction explanation
• Mission and party history
• Realm and Chronicle milestones
• Status: available, assigned, traveling, injured, resting, missing, retired, or dead

14.3 Initial classes

The initial class pool is expected to draw from classic fantasy roles. Candidate prototype classes:

• Fighter
• Ranger
• Rogue
• Mage
• Warlock
• Bard
• Barbarian
• Druid
• Cleric
• Paladin

Additional classes, artificer-like specialists, and culturally specific classes are future content.

14.4 Races and cultures

The setting will contain classic fantasy peoples, initially centered on human and orc cultures, with room for dragons, dragon-related peoples, undead, fae, and other original groups.

Human and orc conflict may be part of the world's history or active tension, but no playable people should be reduced to biologically predetermined good or evil. Cultures, factions, personal choices, and historical circumstances should create conflict and alliance.

14.5 Attraction system

Hero arrivals use a weighted server-side selection system influenced by:

• Keep buildings
• Available housing
• Settlement reputation
• Terrain and region
• Realm events
• Existing roster
• Settlement Legacy later
• Ruleset-defined base weights

Buildings modify probability rather than directly manufacturing a class. The player should receive a plain-language explanation of major attraction factors.

14.6 Proposed hero stat generation

1. Select an eligible class using weighted attraction values.
2. Generate class-weighted base statistics.
3. Apply ancestry or cultural modifiers where the ruleset uses them.
4. Apply trait modifiers.
5. Apply permitted settlement or event modifiers.
6. Clamp results to ruleset minimums and maximums.
7. Calculate derived values.
8. Save the result with its algorithm and ruleset version.
9. Heroes get 4 spell slots, consumables or items that fit in inventory, 
10. heroes train to learn new spells at the location of their class. 

Potential core stats:

• Strength
• Agility
• Intellect
• Will
• Vitality
• Luck

The final stat list, ranges, dice, and modifier formulas are open design questions that require a focused ruleset document before implementation.

14.7 Traits

Traits provide mechanical variation and story identity. Examples include brave, cautious, curious, loyal, nocturnal, gluttonous, stubborn, or superstitious. Traits should create tradeoffs and narrative hooks rather than simply sorting heroes into good and bad quality tiers.

14.8 Hero upkeep

Heroes require housing and may consume rations or other support. Upkeep must create roster decisions without punishing casual players for not logging in. Proposed safeguards include grace periods, paused consumption during Realm pauses, and nonlethal consequences for ordinary shortages.

15. Parties, missions, quests, and dungeons

15.1 Party formation

• A party may contain one to five heroes.
• A hero cannot be assigned to multiple activities simultaneously.
• Party composition influences available modifiers and outcomes.
• Supplies and equipment are committed before departure.

15.2 Mission definition

A mission may contain:

• Realm and location
• Narrative prompt
• Prerequisites
• Party-size limits
• Recommended abilities or roles
• Ration and resource cost
• Duration
• Risk rating
• Possible event table
• Dice checks
• Success tiers
• Loot table
• Injury, missing, or death rules
• Follow-up discoveries or quests

15.3 Mission lifecycle

1. Discover or receive the mission.
2. Review known requirements, risks, duration, and potential rewards.
3. Build a party of up to five.
4. Commit supplies and equipment.
5. Confirm the mission.
6. Server locks the participants and costs.
7. The mission timer progresses using server time.
8. Server resolves the result once.
9. Player receives a readable report and consequences.
10. Relevant history appears in the Realm and Chronicle.

15.4 Result tiers

Proposed result tiers:

• Exceptional success
• Success
• Success with complication
• Failure with survival
• Severe failure

Not every mission permits death. Risk categories must state possible consequences before confirmation.

15.5 Dungeons

Future: Dungeons expand missions into multi-stage expeditions with party composition, branching decisions, supplies, rooms, encounters, loot, and retreat choices. The first playable slice only needs one simple timed mission.

16. Dice and automated resolution

16.1 Design purpose

Dice make uncertainty visible and give Eden Realms its tabletop character. The server rolls authoritatively while the client presents understandable results.

16.2 Roll record

Important rolls should record:

• Dice expression
• Raw roll
• Hero, party, item, building, and event modifiers
• Final result
• Target difficulty
• Outcome tier
• Ruleset version
• Timestamp

16.3 Fairness and transparency

• The browser never supplies the successful result.
• A mission is resolved once.
• Major modifiers are displayed to the player.
• Hidden information may exist for narrative reasons, but the system must remain auditable.
• Server Master interventions that change a recorded result require an explicit, logged mechanism if they are allowed at all.

17. Injury, disappearance, retirement, and death

17.1 Consequence ladder

Danger can produce:

• Lost time
• Reduced rewards
• Damaged or lost equipment
• Temporary injury
• Extended recovery
• Delayed return
• Missing status and a rescue opportunity
• Retirement
• Permanent death

17.2 Cozy-tone safeguards

• Routine settlement work should not unexpectedly kill characters.
• Low-risk missions should emphasize complications over death.
• Permanent loss belongs to clearly marked dangerous content.
• Players must see the risk before confirming an activity.
• Recovery, memorial, inheritance, or rescue systems can turn loss into story rather than pure deletion.

17.3 Proof of demise

When a hero dies or disappears, the result may include proof such as a recovered item, witness report, expedition journal, memorial token, or confirmed remains. The exact form depends on the mission outcome. Death becomes part of the Realm and Chronicle record.

18. Raids and Realm threats

18.1 Raid purpose

Raids are cooperative endgame events in which players contribute heroes and resources to defend their keeps or the wider Realm. They provide a shared reason to specialize settlements, retain multiple heroes, plan together, and preserve major historical events.

18.2 Raid lifecycle

1. Server Master announces a threat and narrative stakes.
2. The server presents the preparation window, requirements, deadline, and known danger.
3. Players commit eligible heroes, parties, equipment, or resources.
4. Contributions remain visible according to Realm rules.
5. The contribution window closes at the server deadline.
6. Automated resolution processes forces, waves, modifiers, rolls, and Realm conditions.
7. Players receive individual and shared results.
8. Keeps receive consequences and rewards.
9. The final raid record becomes part of Realm history.

18.3 Raid transparency

The report should explain:

• Participating players and heroes
• Resources contributed
• Defensive structures or Realm bonuses
• Enemy waves or stages
• Relevant rolls and modifiers
• Injuries, losses, rewards, and world consequences
• Why the Realm succeeded or failed

18.4 Initial raid scope

The first playable slice uses one preparation window, one enemy force, one automated resolution, and one final report. Multi-stage raids, live decisions, bosses, alliances, and seasons are future systems.

19. Social and roleplay systems

19.1 Social goals

• Help four or more players coordinate asynchronous play.
• Support in-character and out-of-character communication.
• Preserve campaign information better than ephemeral chat alone.
• Let players build a shared history without creating a heavy general social network.

19.2 Planned spaces

• Realm announcements
• Party planning
• In-character campaign posts
• Out-of-character discussion
• Player journals
• Campaign journals or logs
• Direct messaging
• Lightweight live Realm chat
• Forums or topic-based discussions

19.3 Social boundaries

Social features require:

• Realm-scoped permissions
• Blocking and moderation later
• Rate limits
• Content length limits
• Safe text rendering
• Privacy controls
• Retention and deletion rules
• Clear separation of public, Realm-only, party-only, and private content

Most social systems remain outside the first five foundation phases except Chronicle structure and activity history.

20. Narrative, world, and tone

20.1 Setting direction

Eden Realms takes place in a whimsical fantasy frontier where old civilizations, dangerous ruins, dragons, undead remnants, rival peoples, magical landscapes, and new settlements overlap.

The focus is early settler life in a fantastical world: making shelter, fishing unfamiliar waters, cultivating land, welcoming travelers, learning regional stories, and deciding what kind of community will grow.

20.2 Conflict direction

Humans and orcs may begin as central rival cultures, but the setting should support cooperation, internal factions, competing histories, and individual moral choice. Dragons, undead, and other supernatural forces widen the world beyond a single binary war.

20.3 Story delivery

Story may appear through:

• Server Master-authored events
• Mission reports
• Map discoveries
• Hero traits and histories
• Settler stories
• Journals and posts
• Building and settlement milestones
• Items and relics
• Realm-wide threats
• Archive summaries

20.4 Tone range

The baseline is cozy, curious, and whimsical. Danger, grief, horror, political tension, and tragedy may appear, especially in optional campaigns and high-risk expeditions, but should not erase the underlying promise of building a home.

21. User interface and player journey

21.1 Public journey

1. Visit Eden Realms.
2. Learn the high concept.
3. Register or log in.
4. Enter Chronicle.

21.2 Chronicle journey

1. Review profile and recent activity.
2. See invitations, active Realms, and archived Realms.
3. Accept an invitation or enter an active Realm.
4. Return later to review history or another Realm.

21.3 Realm journey

1. Enter the Realm overview.
2. Review keep status, assignments, heroes, Realm events, and social activity.
3. Open the map or a management panel.
4. Commit an action.
5. Receive immediate validation and a server-recorded state.
6. Return when the activity completes.

21.4 Initial screen families

• Public landing/login/register
• Chronicle home
• Profile and preferences
• Realm invitations
• Active and archived Realm lists
• Realm overview
• Server Master Realm dashboard
• Hex map
• Keep overview
• Settlers and assignments
• Buildings
• Heroes and recruitment
• Party and mission preparation
• Mission result
• Raid preparation and report
• Activity/history views

21.5 Frontend principles

• Mobile-first, responsive layout
• Simple presentation without premature scaling work
• Server-provided JSON rendered into the DOM
• Correct DOMContentLoaded initialization
• Clear loading, empty, success, and error states
• Accessible semantic HTML and controls
• Touch-friendly targets
• Keyboard usability
• No required frontend framework initially
• Untrusted text inserted safely, never as arbitrary HTML

21.6 Map rendering

The initial renderer may use DOM elements and pixel-art assets supplied by the API-backed map state. The authoritative map remains independent of screen pixels so Canvas, WebGL, or a native renderer can replace the presentation later without rewriting game rules.

22. Visual direction

22.1 Art goals

• Whimsical pixel-art fantasy
• Readable hex terrain pieces that connect cleanly
• Cozy settlement details contrasted with mysterious wilderness
• Strong visual states for unexplored, explored, buildable, claimed, dangerous, and corrupted tiles
• Distinct silhouettes and color language for structures
• Mobile readability before decorative density

22.2 Asset families

• Base hex terrain tiles
• Edge and connection variants where needed
• Rivers, roads, coastlines, and borders later
• Structure overlays
• Resource and landmark overlays
• Fog, claim, selection, danger, and event states
• Hero portraits or sprites later
• UI icons for resources, professions, classes, risk, and time

22.3 Art-production caution

The initial tile system should be defined before producing a large asset library. Tile dimensions, orientation, coordinate layout, edge rules, zoom behavior, and overlay strategy must be tested with placeholder art first.

23. Audio direction

Audio is not required for the first foundation phases. The eventual direction may include:

• Gentle settlement ambience
• Wind, rain, forest, water, forge, inn, and farm soundscapes
• Short completion and discovery cues
• Restrained music appropriate for long-running browser sessions
• Strong user control, including mute and volume settings

Audio must never be required to understand an event or result.

24. Technical foundation

24.1 Initial technology

• HTML
• CSS
• Plain JavaScript
• PHP
• SQLite
• Docker Compose

24.2 Application boundary

The browser is a client. PHP and SQLite form the authoritative Eden Realms server. The browser displays state and submits intentions; it does not decide resource gains, timer completion, dice, hero statistics, permissions, loot, or raid results.

24.3 Initial deployment shape

• One PHP web application container
• One persistent application-data volume
• SQLite stored outside the public web directory
• No Redis, queue, separate database server, microservices, or per-Realm containers initially

24.4 API principles

• JSON responses with consistent success and error shapes
• Stable machine-readable error codes
• UTC timestamps
• Server-side validation
• Explicit HTTP methods
• Authentication and authorization on every protected request
• Realm ownership verified from stored relationships
• Pagination when lists become large
• Versioned rulesets and important result algorithms

24.5 Timer model

The server stores start and completion timestamps. Early activities may resolve when an authorized request observes or claims completion, avoiding a background job system during the prototype. Background workers can be introduced only when Realm-wide scheduled events require them.

24.6 Future technical growth

Potential future changes, introduced only when justified:

• PostgreSQL
• Background job queue
• Multiple application workers
• Real-time event service
• Object storage for media
• Native mobile client
• Independently hosted or federated Realms

Correct API, Realm, migration, and authorization boundaries matter now; large-scale infrastructure does not.

25. Security and integrity baseline

Even in development, Eden Realms must include:

• Secure password hashing
• Server-side sessions
• Session ID regeneration after login or privilege change
• HTTP-only and SameSite cookies
• CSRF protection for state-changing browser requests
• Server-side authorization
• Realm isolation
• Prepared SQLite statements
• Input validation and output escaping
• Login and chat rate limiting as those features arrive
• Generic production-style error responses
• Sensitive values excluded from logs
• Audit records for important Server Master and administrator actions
• Private database, configuration, logs, and source outside the public directory
• Database backups and tested restoration before production

Known development shortcuts and missing production controls must be recorded in SECURITY.md rather than forgotten.

26. First playable vertical slice

26.1 Purpose

Prove that managing a keep, waiting for meaningful results, attracting heroes, and cooperating in a shared Realm is understandable and enjoyable.

26.2 Required content

• One Server Master-created Realm
• Four independent player accounts
• One connected 20–50 hex map
• Four starting regions or keeps
• Basic resources and rations
• A small settler population per keep
• Farming, fishing, and/or gathering assignments
• Housing plus a small selection of class-influencing structures
• Randomized heroes from a limited class pool
• Parties of up to five heroes
• One mission location and mission type
• Server-side dice resolution
• Loot, injury, and narrative outcomes
• One cooperative automated raid
• Realm activity history
• Chronicle summaries and archived Realm access

26.3 Explicit exclusions

• Full combat simulation
• Large dungeon trees
• Player trading economy
• Rich live chat
• Forums and direct messages
• Native mobile application
• Advanced legacy or inheritance system
• Large-scale public hosting
• Monetization

26.4 Success criteria

The vertical slice succeeds when:

• Four players can understand what to do without developer intervention.
• Settlement choices visibly influence hero recruitment or preparation.
• Timed actions feel worth returning for.
• Players can explain why a mission or raid produced its result.
• Cooperative preparation matters.
• The Realm produces at least one memorable shared story.
• Archiving preserves a readable record of that story.

27. Foundation roadmap

Phase 1 — Foundation and frontend shell

• Establish project documentation and architecture.
• Create Docker Compose, PHP, SQLite, migrations, routing, logging, and health checks.
• Create the responsive application shell.
• Establish safe DOM and API loading behavior.
• Verify persistence, error handling, and private-file protection.

Phase 2 — Authentication and authorization

• Create accounts, roles, secure sessions, registration, login, and logout.
• Add CSRF protection, rate limiting, audit events, and reusable permission checks.
• Verify four separate accounts and direct API authorization failures.

Phase 3 — Player Chronicle

• Create the account-wide profile and authenticated lobby.
• Add Realm invitations, active Realm list, archived Realm list, privacy, and activity history.
• Verify profile ownership and field-level visibility.

Phase 4 — Hosted Realms

• Create Realm lifecycle, ownership, memberships, invitations, dashboard, isolation, and archive behavior.
• Verify at least two Realm owners, multiple Realms, four players, and one read-only archive.

Phase 5 — First playable vertical slice

• Add the hex map, keeps, resources, settlers, structures, hero attraction, parties, one mission, dice resolution, one raid, and Chronicle history.
• Verify the complete four-player loop and archive the resulting Realm.

Each phase must be completed, tested, documented, and entered in CHANGELOG.md before the next phase begins.

28. Later production stages

After the five foundation phases, development continues through:

Prototype

Validate the core loop, pacing, terminology, risk, player comprehension, and cooperative value.

Development

Expand proven systems, content tools, social features, progression, rulesets, and Server Master capabilities.

Debugging

Focus on data integrity, timer behavior, concurrency, authorization, duplicate resolution, economy exploits, migration safety, and recovery.

Polishing

Improve mobile UX, accessibility, onboarding, visual feedback, pacing, writing, pixel art, audio, and player-facing explanations.

Production

Add HTTPS, production secrets, backups, monitoring, email flows, abuse controls, moderation, disaster recovery, deployment automation, load testing, and any justified infrastructure upgrades.

29. Risks and mitigations

29.1 Scope expansion

Risk: Social networking, MMO systems, world building, idle economy, and tabletop campaigns expand simultaneously.
Mitigation: The five foundation phases and vertical-slice exclusions define strict gates.

29.2 Idle gameplay becoming passive

Risk: The game becomes a collection of countdowns with few decisions.
Mitigation: Require meaningful preparation, tradeoffs, risk selection, party composition, and readable consequences before timers begin.

29.3 Cozy tone conflicting with permanent death

Risk: Random loss discourages attachment and relaxed play.
Mitigation: Reserve permanent loss for clearly marked high-risk content and use complications, injury, delay, rescue, and retirement elsewhere.

29.4 Server Master workload

Risk: Creating maps, stories, missions, and events becomes too demanding.
Mitigation: Begin with reusable templates, validation, automation, and small maps; measure authoring time before expanding tools.

29.5 Unfair or opaque randomness

Risk: Players cannot understand recruitment or mission outcomes.
Mitigation: Record rolls and modifier explanations, version algorithms, and keep weighted systems auditable.

29.6 Resource inflation

Risk: Idle accumulation removes meaningful decisions.
Mitigation: Use limited storage, construction sinks, upkeep safeguards, progression gates, and balance telemetry without punitive offline loss.

29.7 Data leakage between Realms

Risk: Multi-Realm queries or permissions expose another world's private data.
Mitigation: Require authoritative Realm relationships, server-side membership checks, isolation tests, and audit logging from the beginning.

29.8 Archive growth

Risk: Permanent Realm history creates growing storage and privacy obligations.
Mitigation: Define retention, visibility, export, deletion, and immutable-history policies before public production.

30. Open design questions

These questions should be answered through focused design work or prototype testing:

1. What is the final original ruleset and dice expression?
2. Which hero statistics are essential in the first prototype?
3. Which races, cultures, and five starter classes launch first?
4. Are players individual rulers, households, guild stewards, or another in-world role?
5. How are new heroes offered, accepted, rejected, and replaced?
6. How often should a player meaningfully check the game?
7. Do completed tasks resolve automatically or require a claim action?
8. What happens to upkeep while a player is absent or a Realm is paused?
9. What is the safest first implementation of permanent hero death?
10. How much of a mission result is random versus authored by the Server Master?
11. Can Server Masters override automated results, and how is that disclosed?
12. How do players cooperate outside raids during the first expansion?
13. Which Chronicle information is private, Realm-visible, or public by default?
14. Can a Realm archive ever be restored, forked, or continued?
15. What exact pixel-art hex orientation, size, and layering convention will be used?
16. Which accessibility settings are required before broader testing?
17. What moderation responsibilities belong to Server Masters versus platform administrators?
18. How will original terminology distinguish Eden Realms from its inspirations?

31. Immediate next design documents

Before or during the applicable implementation phase, create focused specifications for:

1. Platform architecture and API conventions
2. Authentication, roles, and Realm authorization matrix
3. Chronicle information architecture and privacy model
4. Realm lifecycle and Server Master workflow
5. Hex map data and pixel-art asset specification
6. Prototype ruleset, hero generation, and dice formulas
7. Timer, mission, and idempotent result-resolution rules
8. Raid preparation and automated resolution
9. Archive, retention, correction, and deletion policy

32. Document history

0.1 — 2026-07-31

• Created the initial Eden Realms Game Design Document.
• Consolidated the agreed high concept, Chronicle, Hosted Realms, Server Master, keeps, settlers, buildings, hero attraction, hex map, missions, raids, archive behavior, technical foundation, security baseline, and five-phase roadmap.
• Marked unresolved rules, balance values, and future systems as open or proposed.