System Requirements Document for first-person-perspective

1. Introduction

This document specifies first-person-perspective, a browser-based experience in which the player holds and fires a gun seen from their own eyes. The product intent is narrow and deliberate: present a gun in a first-person perspective, make that view feel technical, tense and immersive, and let the player fire it while the shot data becomes the visual language of the scene.

The audience is the Player — a person who wants to experience a first-person weapon view directly in the browser, without a broader game, campaign, inventory, or multiplayer context. The experience is a single, self-contained first-person gun view: the gun is a real-time 3D subject, it sways with the pointer, it kicks on fire, and a teal particle field and corner readouts respond to each shot.

The requester asked for this System Requirements Document to describe the product itself; it is not a product feature, page, or workflow.

Success Criteria

• A player can reach the experience anonymously and enter the first-person gun view without creating an account.
• The gun is always presented from the first-person perspective — the player's own eyes — and never from a third-person or external view.
• Firing produces an immediate, observable response: a short sharp recoil kick, a particle burst from the muzzle, and updated shot, hit and accuracy readouts.
• The gun sways with pointer movement, so the view feels held rather than static.
• The experience remains usable and readable at 375px, 768px and 1280px viewports, and provides a usable static arrangement under prefers-reduced-motion.

2. System Overview

2a. Product Interpretation and Delivery Boundary

first-person-perspective is delivered as a first-party web application. The React frontend renders the experience; a shared FastAPI backend serves the application's APIs; MariaDB is available for application-owned persistent data. The first-person gun view itself is a real-time client-side 3D scene (WebGL/R3F) rendered in the browser.

Delivery and access ownership:

• Landing is the anonymous public entry. It explains the first-person gun view and lets the player begin. No account, sign-in, or identity establishment is required or provided.
• Play is the first-person gun view itself. It is reachable without identity and holds no durable per-player state that must be privately owned or resumed; a session is ephemeral and ends when the player leaves.
• Because the accepted behavior creates no durable relationship, entitlement, commitment, or value transfer bound to a specific person, no application-owned identity, account management, or permission model is introduced. Access is public and ephemeral by design.

Current versus future boundary: only the first-person gun view, its firing response, its pointer sway, and its shot readouts are current. Anything beyond that — additional weapons, targets with scoring rules, progression, multiplayer, persistence of scores — is not part of this delivery and is not implied by the pages or requirements below.

2c. Page Content and Component Coverage

Landing

• Information and state: the product name, a one-line statement that this is a first-person gun view, and a short note that the experience is played directly in the browser with no account. The page is anonymous and stateless.
• Primary action: a single Enter control that opens the Play view.
• Supporting actions: none required beyond entering; no sign-in, settings, or account controls.
• Domain entities: none persisted; the page presents product framing only.
• Component responsibilities:
  • Hero headline block, top-left over the dark void, at the direction's large display size, wrapping or scaling to fit at 375px, 768px and 1280px.
  • A real-time 3D gun subject, low right at large scale with a warm rim light, swaying gently with the pointer.
  • A teal generative particle field flowing behind the gun.
  • The Enter control, fully visible and never covered by the gun, particles, or headline.
• States:
  • Loading: the 3D scene and particle field initialize; the headline and Enter control are visible immediately so the player is never blocked.
  • Empty: not applicable — the page has fixed framing content.
  • Success: the player activates Enter and the Play view opens.
  • Error/recovery: if the 3D scene cannot initialize, the headline and Enter control remain usable and a short mono note states that the 3D preview is unavailable; the player can still enter Play.
  • Reduced motion: the gun and particle field render as a still composed frame; the headline and Enter control remain whole and readable.

Play

• Information and state: the live first-person gun view, plus corner readouts for shots fired, hits, and accuracy. Readouts hug the corners and stay clear of the centre of the screen.
• Primary action: Fire — a pointer click/tap or the designated fire key — which produces a recoil kick, a muzzle particle burst, and updated readouts.
• Supporting actions: pointer movement to sway the gun; leaving the view to return to Landing.
• Domain entities: an in-session shot record — each shot increments shots fired, may register a hit, and recomputes accuracy as hits ÷ shots. This record is ephemeral and lives only for the current session.
• Component responsibilities:
  • Full-bleed dark canvas holding the real-time 3D gun in first-person position, with a dark metal finish and warm rim light.
  • Pointer-sway controller that tilts the gun with pointer movement.
  • Fire controller that applies a short sharp recoil kick and emits a teal particle burst from the muzzle.
  • Teal particle field that spreads from the muzzle on each shot and flows slowly in the background.
  • Thin data rail at the left edge.
  • Corner readouts in mono type that count shots, hits and accuracy up as they change.
  • A visible way back to Landing.
• States:
  • Loading: the 3D scene initializes; readouts show zero values and the view is not yet interactive.
  • Empty: before the first shot, shots fired = 0, hits = 0, accuracy shown as 0% (or an em dash until a shot is fired).

• Success: each shot immediately shows recoil, a muzzle particle burst, and incremented readouts.
• Error/recovery: if the 3D scene fails to initialize, a mono message states the view is unavailable and offers a retry that re-initializes the scene, plus a return to Landing.
• Reduced motion: the gun renders still, recoil and particle spread are replaced by a static muzzle flash and an immediate readout update, so firing remains fully usable.

3. Functional Requirements

FR-1 — First-person gun view (explicit) As a Player, I should see a gun rendered from the first-person perspective — from my own eyes — so that the experience is a first-person weapon view.

• Trigger: the player enters Play.
• Observable result: a real-time 3D gun is rendered in first-person position, filling the screen, with a dark metal finish and warm rim light.
• Constraint: the view is first-person only; no third-person or external camera view is offered.
• Failure/recovery: if the 3D scene cannot initialize, a mono message states the view is unavailable with a retry and a return to Landing.
• Continuation: once rendered, the player can sway and fire.

FR-2 — Pointer sway (explicit, from creative direction) As a Player, I should see the gun sway with my pointer movement so that the view feels held and alive.

• Trigger: pointer movement over the Play view.
• Observable result: the gun tilts and drifts in response, within a restrained range that keeps the gun in frame.
• Failure/recovery: with prefers-reduced-motion, the gun holds a still composed pose.
• Continuation: sway continues alongside firing.

FR-3 — Fire with recoil (explicit, from creative direction) As a Player, I should fire the gun and feel a short sharp recoil kick so that firing reads as immediate and tense.

• Trigger: pointer click/tap or the designated fire key in Play.
• Observable result: the gun kicks sharply and briefly, then settles back to its held position.
• Failure/recovery: under reduced motion, a static muzzle flash replaces the kick; the shot still registers.
• Continuation: the player can fire again immediately.

FR-4 — Muzzle particle burst (explicit, from creative direction) As a Player, I should see a teal particle field spread from the muzzle on each shot so that the shot data becomes visible.

• Trigger: each fire action.
• Observable result: a teal particle burst emits from the muzzle and disperses into the background field.
• Failure/recovery: under reduced motion, a static muzzle flash stands in for the burst.
• Continuation: the background field continues its slow generative flow between shots.

FR-5 — Shot, hit and accuracy readouts (explicit, from creative direction) As a Player, I should see corner readouts count shots, hits and accuracy as they change so that I can read my performance at a glance.

• Trigger: each fire action.
• Observable result: shots fired increments; a hit increments hits when the shot registers a hit; accuracy recomputes as hits ÷ shots and is displayed as a percentage.
• State: readouts begin at zero before the first shot; accuracy shows 0% or an em dash until a shot is fired.
• Failure/recovery: readouts remain visible and correct even if the 3D scene fails, so the player retains feedback.
• Continuation: readouts persist for the session and reset when the player leaves and re-enters Play.

FR-6 — Enter the experience (required_inference) As a Player, I should enter the first-person gun view from the Landing page without an account so that I can start playing immediately.

• Trigger: the player activates Enter on Landing.
• Observable result: the Play view opens with the gun in first-person position and readouts at zero.
• Access: anonymous; no identity, sign-in, or account is required.
• Failure/recovery: if Play fails to initialize, the player is returned to Landing with a mono notice and can try again.
• Continuation: the player can return to Landing at any time.

FR-7 — Return to Landing (required_inference) As a Player, I should be able to leave the Play view and return to Landing so that I can end or restart the session.

• Trigger: the player activates the return control in Play.
• Observable result: the Play view closes, the session's shot record is discarded, and Landing is shown.
• Continuation: the player can enter Play again with readouts reset to zero.

4. User Personas

Player

• Product context: the Player wants a direct, immersive first-person weapon view in the browser. They arrive at Landing with no account and no prior setup, and they expect to be holding a gun within seconds.
• Primary goal: experience a convincing first-person gun — see it, sway it, fire it — and watch the shot data respond.
• Distinct accepted responsibilities:
  • Deciding to enter the experience from Landing.
  • Moving the pointer to sway the gun.
  • Firing the gun, repeatedly, and reading the resulting recoil, muzzle burst, and readouts.
  • Deciding when to leave the view and return to Landing.
• Relevant inputs or decisions: the Enter action; pointer movement; the fire input (click/tap or fire key); the return action.
• Interactions with other accepted participants: none — the experience is single-player and ephemeral; there is no counterparty, recipient, or shared state.
• Observable success: the gun is visibly first-person, sways with the pointer, kicks on fire, emits a teal muzzle burst, and the corner readouts count shots, hits and accuracy upward. The Player can leave and re-enter cleanly.

5. Core User Flows

Flow A — Enter and hold the first-person gun

1. The Player opens the application and lands on Landing (anonymous; no account).
2. Landing shows the headline top-left over the dark void, the 3D gun low right with a warm rim light, and the teal particle field flowing behind it.
3. The Player moves the pointer; the gun sways gently in the preview.
4. The Player activates Enter.
5. The Play view opens: the gun is rendered in first-person position, filling the screen, and the corner readouts show shots 0, hits 0, accuracy 0%.
6. The Player moves the pointer; the gun sways with the movement.
7. Failure/recovery: if the 3D scene fails to initialize, a mono message states the view is unavailable with a retry; the Player retries or returns to Landing.
8. Continuation: the Player is now holding the gun and ready to fire.

Flow B — Fire and read the shot data

1. From the held first-person view in Play, the Player fires (click/tap or fire key).
2. The gun kicks sharply and briefly, then settles.
3. A teal particle burst spreads from the muzzle into the background field.
4. The corner readouts update: shots fired increments; hits increments if the shot registers a hit; accuracy recomputes as hits ÷ shots.
5. The Player fires again; steps 2–4 repeat, and the numbers count up on each shot.
6. Failure/recovery: under prefers-reduced-motion, the gun stays still, a static muzzle flash replaces the kick and burst, and the readouts still update so firing remains fully usable.
7. Continuation: the Player keeps firing or leaves the view.

Flow C — Leave and restart the session

1. From Play, the Player activates the return control.
2. The Play view closes and the session's shot record is discarded.
3. Landing is shown again.
4. The Player activates Enter; Play opens with readouts reset to shots 0, hits 0, accuracy 0%.

6. Visuals Colors and Theme

The creative direction — Data made physical for a first-person gun, muse Refik Anadol — is authoritative for this section.

Mode: dark only. Near-black ground holds roughly 80% of the screen.

Colour tokens (exact hex, by role):

Typography:

• Headings: Space Grotesk — wide, light, mixed case, tight tracking at large sizes.
• Body and labels: IBM Plex Mono; uppercase mono labels at 12px.
• Modular scale (1.333): 96 / 64 / 48 / 32 / 20 / 14 desktop; 48 / 36 / 28 / 20 / 16 / 12 mobile. Headline sizes use clamp(...) with their mobile size as the floor.

Shape language: full-bleed dark canvas; thin luminous strokes; soft particle fields; round data rings. No hard cards.

Layout: the play view fills the screen. A thin data rail sits at the left edge. Readouts hug the corners and stay clear of the centre. The headline sits top-left over empty black, not centred.

Imagery: a generative particle field made from shot data; the gun is a real-time 3D subject with a dark metal finish and a warm rim light.

Readability rule: headlines, wordmarks, labels, numbers and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit, and no imagery, decoration or motion covers any part of them.

Avoid: a centred headline with a blue button and a gradient blob; flat clip-art guns or stock soldier photos; a grid of identical cards with hover lift; bright white backgrounds or pastel gradients; the generic indigo/blue-on-white SaaS template.

7. Signature Design Concept

The public entry is a full-bleed dark scene that makes the gun's data physical before the player ever fires.

• First frame: near-black #07080A fills the viewport. The headline sits top-left at 96px in light Space Grotesk, mixed case, tight tracking, over empty black — deliberately not centred. The real-time 3D gun sits low right at large scale, dark metal catching a warm #FF6A1A rim light. A teal #5CE1C8 particle field flows slowly behind it, like Anadol's luminous data fields.
• Signature moves carried into the entry: the gun sways with the pointer; the particle field drifts in a slow generative flow; a thin data rail runs down the left edge; a single Enter control in hot orange sits fully visible and uncovered.
• Gesture: the composition is asymmetric and cinematic — void top-left, mass low-right — so the eye reads the headline first, then the gun, then the Enter control.
• Reduced motion: the gun and particle field hold a still composed frame; the headline and Enter control remain whole and readable.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the real-time 3D gun, low right at large scale with a warm rim light, set against a teal generative particle field.
• Input → transformation → outcome thesis: pointer movement over the scene → the gun sways and the particle field drifts in response → the player perceives a held, living weapon and activates Enter to take control of it in Play.
• Motion vocabulary: slow generative flow in the background; pointer-linked sway on the gun; soft particle drift; no abrupt cuts.
• Composed first frame: headline top-left at 96px over empty black; gun low right; teal field behind; Enter control fully visible; data rail at the left edge.
• Reduced-motion state: a still composed frame with the gun and particle field frozen in a balanced pose; headline and Enter control whole and readable.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

• One crafted real-time object: the gun, modeled as a dark-metal first-person weapon with a warm rim light, held low right.
• A compact particle system of teal points flows behind and around the gun, its density and drift driven by a slow generative field.
• The scene shows the product's defining state — a first-person weapon held in a luminous data field — before the player fires.
• Pointer input tilts the gun within a restrained range; the scene never covers the headline or the Enter control.
• Under reduced motion, the scene renders a single still frame.

Play motion: the gun sways with the pointer; each shot is a short sharp recoil kick plus a teal muzzle burst; corner readouts count up on each shot. Under reduced motion, the gun holds still, a static muzzle flash replaces the kick and burst, and readouts update immediately.

9. Non-Functional Requirements

• First-person only (explicit constraint): the gun view is first-person only; no third-person or external camera view is provided.
• Immediate feedback (explicit, from creative direction): firing must produce recoil, a muzzle burst, and readout updates without perceptible delay.
• Readability at every viewport (explicit, from creative direction): headlines, labels, numbers and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px; no imagery, decoration or motion covers them.
• Reduced motion (explicit, from creative direction): with prefers-reduced-motion, the experience provides a usable static arrangement — still gun, static muzzle flash, immediate readout updates — with all text and controls whole and readable.
• Anonymous, ephemeral access (required_inference): no account, sign-in, or persistent per-player state is required; the session's shot record is discarded when the player leaves Play.
• Performance (required_inference): the real-time 3D scene and particle field must sustain smooth interaction on a typical desktop browser; the headline and Enter control render before the 3D scene finishes initializing.
• Resilience (required_inference): failure of the 3D scene must not block entry or readouts; a retry path and a return to Landing are always available.

10. Tech Stack

• Frontend: React application UI, rendering the Landing and Play views; real-time 3D via WebGL/R3F for the gun and particle field.
• Backend: shared FastAPI process for application APIs and domain modules.
• Database: MariaDB, available for application-owned persistent data. The current experience keeps its shot record in-session only; no persistent domain entities are required by the accepted behavior.
• Infrastructure: docker-compose.yml with the frontend, backend and database services; the frontend reaches the backend, and the backend reaches MariaDB.

11. Assumptions and Constraints

• Assumption: the experience is single-player and ephemeral; no durable per-player state, account, or permission model is required (required_inference, consistent with the anonymous access contract).
• Assumption: "hits" are determined within the Play view by the shot registering against the scene's aim target; the exact hit rule is a client-side detail of the first-person view and does not introduce a separate scoring system (required_inference).
• Constraint: the gun view is first-person only (explicit).
• Constraint: the palette, fonts, surfaces, tone and layout of the creative direction are preserved; the generic indigo/blue-on-white SaaS template is forbidden (explicit).
• Constraint: readable text and controls stay whole at 375px, 768px and 1280px (explicit).
• Out of scope: additional weapons, campaigns, progression, multiplayer, leaderboards, and persistent score history — none are accepted by the source.

12. Glossary

• First-person perspective: a view rendered from the player's own eyes, with the gun visible in front of the camera.
• Player: the single active human persona who holds, sways and fires the gun.
• Landing: the anonymous public entry page that frames the experience and offers Enter.
• Play: the full-screen first-person gun view where the player sways and fires.
• Recoil kick: the short, sharp backward motion of the gun on each shot.
• Muzzle burst: the teal particle emission that spreads from the gun's muzzle on each shot.
• Readouts: the corner mono-type displays counting shots fired, hits, and accuracy.
• Accuracy: hits ÷ shots, displayed as a percentage.
• Data rail: the thin luminous strip at the left edge of the Play view.
• Reduced motion: the prefers-reduced-motion state in which animation is replaced by a usable static arrangement.