System Requirements Document for bedwars

1. Introduction

bedwars is a browser-playable, 3D multiplayer Bedwars game inspired by Minecraft Bedwars. Players enter a live voxel arena, fight alongside teammates against real human opponents, defend their team's bed, gather resources, buy items and upgrades, and try to be the last team standing. The product intent is to deliver the core Bedwars gameplay loop — team islands, resource generators, an item shop, bed destruction, and last-team-standing victory — as a real-time 3D experience in the browser, with matches populated by real players rather than bots.

The audience is competitive and social players (roughly ages 10–25) who expect a Minecraft-adjacent block world but a more premium, cinematic presentation than a typical fan server. They arrive to play with other real people: to join a lobby, ready up with teammates, and step into a live arena where the outcome depends on human opponents and allies.

This document is the System Requirements Document for the product; it specifies the game's features, workflows, personas, pages, and delivery boundaries.

Success Criteria

• A new player can move from first visit to an active multiplayer match without leaving the browser.
• Every match is populated by real players; no bots fill teams.
• A match reliably ends with one team remaining, and the winning team is shown to all participants.
• The 3D arena, resource gathering, item/upgrade purchasing, and bed destruction are all playable in real time in the browser.

2. System Overview

bedwars is delivered as a browser application with a custom first-party UI and application-owned player identity. The current delivery comprises:

• A public entry surface that presents the 3D voxel Bedwars arena and the live multiplayer nature of the game, and routes visitors to begin.
• Self-service enrollment and returning verification so each player has a durable identity that binds their lobby membership and match participation.
• A lobby system where authenticated players browse, create, and join multiplayer lobbies with other real players.
• A focused lobby workspace where the host readies participants and starts the match.
• The 3D match arena where players move, place and break blocks, fight, gather resources, buy items and upgrades, and destroy opposing teams' beds.
• A match results surface that shows the winning team and final outcome when the match ends.

Actors. The active human personas are the Bedwars Player and the Match Host / Lobby Creator. The game server and real-time match simulation are system actors that execute accepted gameplay; they are not personas.

Ownership. All accepted human-facing behavior is owned by first-party custom pages. Real-time match simulation, resource generation, and match-end determination are system processes that support the human interaction on the Match page.

Narrow exclusions. Matches are multiplayer with real players, not bots. The product is a 3D browser game; it is not a native desktop or mobile application.

Removed from scope

• Bots (also: AI opponents, computer-controlled players)

2a. Product Interpretation and Delivery Boundary

bedwars is a first-party browser game. The application owns player identity: a visitor can enroll through self-service sign-up or verify an existing identity at login, and that identity carries their lobby membership and match participation across sessions. The Landing page is anonymously reachable and explains the game and how to begin; the Lobbies, Lobby Details, Match, and Match Results pages require a verified player identity.

The current horizon covers the complete playable loop: entry, enrollment/verification, lobby browsing and creation, lobby readiness and match start, the live 3D match, and match results. Real-time match simulation and resource generation run as system processes behind the Match page; they are not separate human-facing destinations. No future-horizon features are currently accepted.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Presents the 3D voxel Bedwars arena as the hero subject, the game's premise (defend your bed, break theirs), and the live multiplayer nature of matches. A live-status strip shows real player count and active lobby count. HUD micro-labels (team tags, resource counters) float at the arena's corners.
• Primary actions: "Enter the arena" (solid cyan CTA) routes toward enrollment or verification and then into the game. "Join a lobby" (glass-bordered CTA) routes toward enrollment or verification and then to Lobbies.
• Supporting actions: Navigate to Login for returning players; navigate to Sign Up for new players.
• Domain entities: Live player count, active lobby count, arena scene.
• Component responsibilities: WebGL arena hero with slow orbit; top live-status rail (player count, region, ping) in JetBrains Mono with pulsing cyan live dot; oversized flush-left three-line headline; live-status strip; CTA cluster; HUD micro-label overlays.
• States: Loading — arena scene initializes with a composed still frame and status rail placeholders. Empty — if live counts are unavailable, the status strip shows a neutral unavailable state without blocking CTAs. Success — arena orbits, counts display, CTAs are active. Error — if the arena scene fails to initialize, a static composed fallback frame is shown and CTAs remain usable. Recovery — reduced-motion freezes the orbit to a composed still frame while keeping the HUD readable.

Login

• Information/state: Anonymous identity-access surface for returning players. Collects returning-player credentials and verifies identity.
• Primary actions: Submit credentials to verify identity and continue to Lobbies.
• Supporting actions: Navigate to Sign Up for players without an identity; return to Landing.
• Domain entities: Player identity, credentials.
• Component responsibilities: Credential form; submit control; error messaging; link to Sign Up.
• States: Loading — submit disabled with progress indication during verification. Empty — form fields empty on arrival. Success — verified identity routes to Lobbies. Error — invalid credentials show an inline error and preserve entered values. Recovery — player can retry or navigate to Sign Up.

Lobbies

• Information/state: Authenticated lobby browser. Lists available multiplayer lobbies with their participant counts and readiness, and shows the player's own lobby membership if any.
• Primary actions: Create a new lobby (becoming its host); join an existing lobby; open a lobby's details.
• Supporting actions: Refresh the lobby list; leave the current lobby.
• Domain entities: Lobby, lobby host, participant roster, participant count, readiness.
• Component responsibilities: Lobby list with per-lobby participant counts and readiness indicators; create-lobby control; join control; navigation to Lobby Details.
• States: Loading — lobby list shows skeleton rows while fetching. Empty — no open lobbies shows an empty state with a prominent create-lobby action. Success — lobbies list with live counts. Error — fetch failure shows a retry control. Recovery — retry re-fetches; a player already in a lobby is routed to its details.

Sign Up

• Information/state: Anonymous self-service enrollment surface for new players. Collects the information needed to establish a durable player identity.
• Primary actions: Submit enrollment to create a player identity and continue to Lobbies.
• Supporting actions: Navigate to Login for existing players; return to Landing.
• Domain entities: Player identity, display name, credentials.
• Component responsibilities: Enrollment form; submit control; validation messaging; link to Login.
• States: Loading — submit disabled with progress indication during creation. Empty — form fields empty on arrival. Success — created identity routes to Lobbies. Error — validation or conflict errors show inline and preserve entered values. Recovery — player can correct and resubmit or navigate to Login.

Lobby Details

• Information/state: Authenticated focused lobby workspace. Shows the lobby's participant roster with readiness state, team assignment, and host identity.
• Primary actions: Participant toggles their own ready state; host starts the match once participants are ready.
• Supporting actions: Leave the lobby; host may remove a participant.
• Domain entities: Lobby, participant, readiness, team assignment, host.
• Component responsibilities: Roster with readiness rings; ready toggle; host start control (enabled only when readiness conditions are met); leave control.
• States: Loading — roster loads with readiness placeholders. Empty — a lobby with only the host shows a waiting state prompting invitation of other players. Success — roster updates live as participants ready up; host start becomes available. Error — start failure shows an inline error and keeps the lobby intact. Recovery — participants can re-ready; host can retry start.

Match

• Information/state: Authenticated 3D arena. Renders the voxel arena with team islands, resource generators, beds, and opposing teams. HUD shows team identity (cyan-teal for your team, magenta for enemy), resource counters, and bed status.
• Primary actions: Move, place and break blocks, fight opponents, gather resources, buy items and upgrades, and destroy opposing teams' beds.
• Supporting actions: Open the item shop; view team and bed status.
• Domain entities: Arena, team, bed, resource generator, resource, item, upgrade, player combat state.
• Component responsibilities: WebGL arena renderer; movement and block controls; combat controls; resource HUD; item shop panel; bed status indicators; team scoreboard.
• States: Loading — arena initializes with a composed still frame and HUD placeholders. Empty — not applicable; a match always has participants. Success — live arena with real-time updates. Error — connection loss shows a reconnection state and preserves match state where possible. Recovery — reconnection restores the player to the match; if the match has ended, the player is routed to Match Results.

Match Results

• Information/state: Authenticated final outcome surface. Shows the winning team and final match outcome when the match ends.
• Primary actions: Return to Lobbies to play again.
• Supporting actions: Review final team standings.
• Domain entities: Match, winning team, final standings.
• Component responsibilities: Winning-team display; final standings; return-to-lobbies control.
• States: Loading — results load with a composed placeholder. Empty — not applicable; results always follow a completed match. Success — winning team and standings displayed. Error — results fetch failure shows a retry control. Recovery — retry re-fetches; player can return to Lobbies.

3. Functional Requirements

FR-1 — 3D browser game (explicit) As a Bedwars Player, I should play a 3D Bedwars game inspired by Minecraft Bedwars in my browser, so that I can experience the block-world arena without installing anything.

• Trigger/input: Player opens the game in a browser.
• Observable result: A 3D voxel arena renders and is playable in the browser.
• Access state: Landing is anonymous; Match requires login.
• Failure/recovery: If the 3D scene fails to initialize, a composed fallback is shown and the player can retry.
• Continuation: Player proceeds to enroll or verify and enter a lobby.

FR-2 — Multiplayer with real players (explicit) As a Bedwars Player, I should play matches populated by real players rather than bots, so that competition and teamwork are genuine.

• Trigger/input: Player joins a lobby with other real players and the host starts the match.
• Observable result: The match contains only real human participants.
• Access state: Login required for Lobbies, Lobby Details, Match, and Match Results.
• Failure/recovery: If a lobby lacks enough real players, the host cannot start until readiness conditions are met.
• Continuation: Match proceeds with the real participants present.

FR-3 — Team competition and bed destruction (explicit) As a Bedwars Player, I should compete in teams to destroy opposing teams' beds and eliminate opponents, so that my team can be the last one standing.

• Trigger/input: Player attacks an opposing team's bed or eliminates opponents during a match.
• Observable result: A destroyed bed removes that team's respawn protection; eliminated opponents are removed from play.
• Access state: Login required; player is in an active match.
• Failure/recovery: If the player's own bed is destroyed, the player loses respawn protection and can be eliminated.
• Continuation: Play continues until one team remains.

FR-4 — Resource gathering and spending (explicit) As a Bedwars Player, I should gather resources and spend them on items and upgrades during a match, so that I can strengthen my team's position.

• Trigger/input: Player collects resources from generators and opens the item shop to purchase items or upgrades.
• Observable result: Resource counters decrease and the purchased item or upgrade takes effect.
• Access state: Login required; player is in an active match.
• Failure/recovery: Insufficient resources prevent purchase and show an inline message.
• Continuation: Player returns to the arena with the purchase applied.

FR-5 — Match end and winning team (explicit) As a Bedwars Player, I should see the match end when one team remains and be shown the winning team, so that the outcome is clear.

• Trigger/input: The last opposing team is eliminated.
• Observable result: The match ends and the winning team is displayed on Match Results.
• Access state: Login required.
• Failure/recovery: If results fail to load, a retry control is shown.
• Continuation: Player returns to Lobbies to play again.

FR-6 — Self-service enrollment (required_inference) As a new player, I should enroll through self-service sign-up, so that I can establish a durable identity and join lobbies.

• Trigger/input: New player submits the Sign Up form.
• Observable result: A player identity is created and the player is routed to Lobbies.
• Access state: Sign Up is anonymous.
• Failure/recovery: Validation or conflict errors show inline and preserve entered values.
• Continuation: Player browses or creates a lobby.

FR-7 — Returning verification (required_inference) As a returning player, I should verify my identity at login, so that I can rejoin my lobbies and matches.

• Trigger/input: Returning player submits credentials on Login.
• Observable result: Identity is verified and the player is routed to Lobbies.
• Access state: Login is anonymous.
• Failure/recovery: Invalid credentials show an inline error and preserve entered values.
• Continuation: Player resumes lobby or match participation.

FR-8 — Authenticated lobby membership (required_inference) As a Bedwars Player, I should be a member of an authenticated lobby before joining or starting a match, so that matches are formed from real, identified players.

• Trigger/input: Authenticated player creates or joins a lobby.
• Observable result: The player appears in the lobby roster and can ready up.
• Access state: Login required.
• Failure/recovery: If the player is already in a lobby, they are routed to its details.
• Continuation: Host starts the match once readiness conditions are met.

FR-9 — Lobby creation and hosting (required_inference) As a Match Host / Lobby Creator, I should create a lobby and start the match once participants are ready, so that real players can play together.

• Trigger/input: Host creates a lobby and, once participants are ready, starts the match.
• Observable result: The match launches with the intended players.
• Access state: Login required.
• Failure/recovery: Start is unavailable until readiness conditions are met; start failure keeps the lobby intact.
• Continuation: Participants enter the Match page.

4. User Personas

Bedwars Player

• Product context: A player who joins a 3D Bedwars match with other real players, defends their bed, gathers resources, buys upgrades, and tries to eliminate opposing teams.
• Primary goal: Win the match, or see their team's result when eliminated.
• Distinct responsibilities: Moves, places and breaks blocks, fights opponents, gathers resources, spends them on items and upgrades, and attacks opposing beds. Reads team identity (cyan-teal vs magenta) and resource counters from the HUD.
• Inputs/decisions: When to gather versus fight, which items and upgrades to buy, when to attack an opposing bed, and when to defend their own.
• Interactions: Plays alongside teammates and against real opponents; depends on the host to start the match.
• Observable success: The match ends with their team remaining, or their team's final result is shown on Match Results.

Match Host / Lobby Creator

• Product context: A player who creates or joins a multiplayer lobby so real players can play together, and starts the match once participants are ready.
• Primary goal: Launch a match with the intended real players.
• Distinct responsibilities: Creates the lobby, monitors participant readiness, and starts the match when readiness conditions are met.
• Inputs/decisions: When enough participants are ready to start; whether to remove a participant.
• Interactions: Coordinates with participants in Lobby Details; hands off to the Match page on start.
• Observable success: The match launches with the intended players.

5. Core User Flows

Flow A — New player enrolls and enters a lobby

1. Visitor opens the Landing page anonymously and sees the 3D voxel arena hero, the live-status strip, and the two CTAs.
2. Visitor selects "Enter the arena" or "Join a lobby" and is routed to Sign Up.
3. Visitor submits the Sign Up form; a player identity is created.
4. Player is routed to Lobbies and sees available lobbies with participant counts.
5. Player creates a new lobby (becoming its host) or joins an existing lobby.
6. Player lands in Lobby Details and appears in the roster.
7. Failure/recovery: If enrollment validation fails, inline errors preserve entered values and the player can correct and resubmit.

Flow B — Returning player verifies and resumes

1. Returning player opens Login from Landing.
2. Player submits credentials; identity is verified.
3. Player is routed to Lobbies; if already in a lobby, they are routed to its details.
4. Failure/recovery: Invalid credentials show an inline error and preserve entered values; the player can retry or navigate to Sign Up.

Flow C — Host readies participants and starts the match

1. Host is in Lobby Details with the participant roster and readiness rings.
2. Participants toggle their own ready state; the roster updates live.
3. Once readiness conditions are met, the host's start control becomes available.
4. Host starts the match; participants enter the Match page.
5. Failure/recovery: If start fails, an inline error is shown and the lobby remains intact; the host can retry.

Flow D — Player competes in the match

1. Player enters the Match page and sees the 3D arena with team islands, resource generators, and beds.
2. Player moves, places and breaks blocks, and fights opponents.
3. Player gathers resources from generators; resource counters update.
4. Player opens the item shop and spends resources on items and upgrades; purchases take effect.
5. Player attacks an opposing team's bed; a destroyed bed removes that team's respawn protection.
6. Failure/recovery: If the player's own bed is destroyed, they lose respawn protection and can be eliminated; if the connection drops, a reconnection state preserves match state where possible.

Flow E — Match ends and results are shown

1. The last opposing team is eliminated; the match ends.
2. All participants are routed to Match Results.
3. Match Results shows the winning team and final standings.
4. Player returns to Lobbies to play again.
5. Failure/recovery: If results fail to load, a retry control is shown; the player can still return to Lobbies.

6. Visuals Colors and Theme

Muse: Gleb Kuznetsov. Headline: "DEFEND THE BED. BREAK THEIRS."

Mode: Dark.

Colour tokens (exact hex by role):

• Background: #08090F (dominant ground, ~70% of screen)
• Surface: #11131C (floating glass panels at 60–80% opacity)
• Text: #ECEFF6 (body copy)
• Primary: #22E0C8 (electric cyan-teal; CTAs, live indicators, focus rings, HUD strokes, ~10%)
• Accent: #FF3D7F (hot magenta; rivalry/opposing-team moments, bed-destroy alerts, enemy team colour, ~8%)
• Muted: #6C7385 (secondary labels)
• Resource/upgrade gold: #F5C451
• Panel borders: #22E0C8 at 15% opacity, 1px luminous edges

Team identity: cyan-teal (#22E0C8) for your team vs magenta (#FF3D7F) for the enemy, plus warm gold (#F5C451) for resources/upgrades.

Typography:

• Headings: Space Grotesk, wide geometric display, weight 500–700, headline tracking -0.02em, leading 0.95.
• Body: Space Grotesk, line-height 1.5.
• Numbers/stats: JetBrains Mono at 14/12px.
• Micro-labels: uppercase 11–12px with 0.18em tracking (e.g., 'LIVE ARENA', 'TEAM CYAN', '3/4 READY').
• Type scale: 1.333 modular with display tier 56/72/96/128px (clamp 56→128), UI 40/28/20/16px, micro-labels 13/12/11px.

Shape language: Thin luminous strokes (1px, 15–30% cyan), floating glass panels with 12–16px radii and a 1px light top edge, radial and circular HUD gauges (team readiness rings, resource dials), soft glow bloom around arena edges, and hard-edged rectangular data strips contrasting with rounded panels. No soft blobby cards; no drop shadows for depth — depth comes from blur, glow, and layered opacity.

Layout: Full-bleed 3D arena scene as hero backdrop with a floating HUD frame: top status rail (live player count, server region, ping), left-aligned oversized headline panel, bottom-left team roster strip, bottom-right CTA cluster. Below the hero, a strict 12-column grid with 96px vertical rhythm; each section reads like a HUD panel docked to the grid. Lobby and match pages reuse the same HUD frame.

Imagery: The 3D block arena itself — a Minecraft-scale voxel island rendered in Three.js with emissive team wool, glowing beds, floating resource islands, and a starfield void. Macro product-style renders of blocks (bed, wool, iron, diamond, obsidian) as isolated floating objects with volumetric rim light. No flat clip art, no stock people, no gradient blobs.

Avoid: White or near-white grounds; blue-indigo (#0057FF/#2563EB/#4F46E5) as primary accent; centred headline + subtext + button SaaS hero; gradient-blob backgrounds or identical hover-lift card grids; Inter, Roboto, Arial, Poppins, or system-ui for headings or body; flat clip art or stock photography of people; bouncy or playful spring easing; presenting or linking to the planning/SRD document anywhere in the UI.

7. Signature Design Concept

The public entry is a full-viewport dark void (#08090F) with a hand-built voxel Bedwars arena floating in it, slowly orbiting under a volumetric spotlight. The arena is the dominant element, occupying the right two-thirds and bleeding off the right and bottom edges. On the left, an oversized Space Grotesk headline "DEFEND THE BED. BREAK THEIRS." is set at clamp(56px, 8vw, 128px), flush-left, stacked in three lines over the void with a thin cyan rule above it. Beneath the headline, a compact live-status strip ("1,284 PLAYERS IN 96 LOBBIES") with a pulsing cyan dot, and two CTAs: a solid cyan "Enter the arena" and a glass-bordered "Join a lobby". HUD micro-labels in 11px uppercase cyan float at the arena's corners (team tags, resource counters) as if the scene is being observed through a game client. No centred layout, no subtext paragraph, no blue button.

8. Interaction Model & Motion Direction

Interaction Model: Parallax Motion Tempo: cinematic Hero Dimensionality: webgl

Landing Hero Motion Brief

• Focal subject: The hand-built voxel Bedwars arena floating in a dark void, rendered in real-time WebGL/R3F with emissive team wool, glowing beds, floating resource islands, and a starfield void.
• Input→transformation→outcome thesis: As the visitor moves the pointer and scrolls, the arena camera drifts and the HUD panels parallax at 0.15–0.3 depth; light sweeps across panel edges on hover; the composed first frame presents the arena orbiting under a volumetric spotlight with the headline and CTAs in place — the visitor feels they are stepping into a live match.
• Motion vocabulary: Continuous slow orbit of the arena camera; parallax on HUD panels at 0.15–0.3 depth; light sweeps across panel edges on hover; scroll-scrubbed camera drift as the user descends; pulsing cyan live dot; counting player numbers; sweeping readiness rings on lobby and match pages.
• Composed first frame: Dark void with the arena occupying the right two-thirds, bleeding off the right and bottom edges; flush-left three-line headline over the void with a thin cyan rule above; live-status strip with pulsing cyan dot; solid cyan "Enter the arena" and glass-bordered "Join a lobby" CTAs; HUD micro-labels pinned to the arena's corners.
• Reduced-motion state: The orbit freezes to a composed still frame and sweeps are disabled while the HUD remains readable; scrollable content wraps or scrolls so every item can be brought fully into view.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

A single crafted real-time voxel Bedwars arena floating in a dark void: team islands with emissive cyan-teal and magenta wool, glowing beds, floating resource islands, and a starfield void, lit by a volumetric spotlight and slowly orbiting. The scene shows the product's defining state — a live multiplayer arena — and is the hero subject of the Landing page.

9. Non-Functional Requirements

• 3D rendering (explicit): The game must be 3D, rendered in the browser via WebGL/Three.js.
• Browser playability (explicit): The game must be playable in the browser without installation.
• Real-player multiplayer (explicit): Matches must be multiplayer with real players, not bots.
• Durable state (required_inference): Player identity, lobby membership, and match participation must persist across sessions.
• Real-time state (required_inference): Lobby rosters, readiness, and match state must update in real time for all participants.
• Reduced motion (required_inference): All motion must respect prefers-reduced-motion by freezing the orbit to a composed still frame and disabling sweeps while keeping the HUD readable.
• Readable text and controls (required_inference): Headlines, wordmarks, labels, numbers, cards' text, and controls must stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no other element covering them.

10. Tech Stack

• Frontend: React with Three.js / React Three Fiber for the 3D arena and HUD.
• Backend: Python/FastAPI for identity, lobby, and match orchestration.
• Real-time state: Redis for durable and real-time lobby and match state.
• Storage: Persistent storage for player identity and match records.
• Deployment: Docker/docker-compose for the application services.

11. Assumptions and Constraints

• Assumption: Players have a modern browser with WebGL support.
• Assumption: Matches are formed from authenticated lobbies; no match starts without a host and ready participants.
• Constraint: The game must be 3D (explicit).
• Constraint: Matches must be multiplayer with real players, not bots (explicit).
• Constraint: The game must be playable in the browser (explicit).
• Constraint: The generic indigo/blue-on-white SaaS template is forbidden for this project.

12. Glossary

• Bedwars: A team-based competitive game mode where teams defend their bed, gather resources, buy items and upgrades, and try to destroy opposing teams' beds to eliminate them.
• Bed: A team's respawn anchor; destroying it removes that team's respawn protection.
• Lobby: A pre-match gathering space where real players assemble and ready up before a match starts.
• Host: The player who creates a lobby and starts the match once participants are ready.
• Resource generator: An in-arena source that produces resources players collect and spend.
• Item shop: The in-match interface where players spend resources on items and upgrades.
• HUD: The heads-up display overlay showing team identity, resource counters, bed status, and live status.
• Voxel: A block-based 3D unit composing the arena, inspired by Minecraft.