System Requirements Document for tamil-horror

1. Introduction

IRUL — THE LAST NIGHT (இ\xe0\xae\xb0\xe0\xaf\x81\xe0\xae\xb3\xe0\xaf\x8d — கடைசி இரவு) is a complete, playable, browser-based 3D Tamil psychological horror game. The protagonist receives a mysterious message and returns to an abandoned Tamil village, deserted after a strange incident twenty years earlier. Across seven chapters the player must discover what happened to the missing children, why the temple is sealed, who is following them, why the entity knows their name, and what happened on the final night.

This document specifies the game as an actual playable product built inside the workspace — not a demo, landing page, static 3D scene, or fake UI. It is written for the engineering team that will build, run, test, debug, and continuously improve the game, and it is the single source of truth for scope, behavior, ownership, and acceptance.

The audience is a single active human role — the Player (Protagonist) — playing first-person on a modern desktop browser. The game is delivered as a first-party web application with a public entry surface and a cohesive in-game workspace.

2. System Overview

IRUL — THE LAST NIGHT is a first-person horror experience rendered in real time in the browser. The player explores a connected night-time Tamil village environment, manages movement, stamina, flashlight and battery, interacts with the world, collects inventory items and clues, solves environmental puzzles, and survives encounters with a sophisticated entity named TheEntity / அவள் that hears footsteps, investigates noise, reacts to the flashlight, searches rooms, stalks, and initiates major chase sequences.

The game is built with React + TypeScript + Vite + Three.js, using React Three Fiber where useful, Drei, the Web Audio API, CSS, and GLTF/GLB asset support, in a clean modular architecture with no single giant component. The world is a connected environment spanning an abandoned road and bus stop, a Tamil village with houses, tea shop, water tank and shrine, a large abandoned old house, an abandoned school, a rural temple, a dark forest, and an underground final chamber. Environmental storytelling is carried by old photographs, diaries, toys, radios, broken furniture, Tamil writing, footprints, locked doors and hidden passages.

Horror is built through silence, shadows, distant movement, footsteps, hallucinations, environmental changes and uncertainty — the monster is not constantly shown. A reusable HorrorEventManager drives random and scripted events, including a bathroom mirror sequence and a school child-whisper event. Tamil subtitles and dialogue, positional 3D audio, and strategic silence carry the atmosphere. Five environmental puzzles gate progression, each with discoverable clues. The story runs through seven chapters and resolves into at least three endings based on clues and choices. The player has no conventional weapons and survives through hiding, running, light, puzzles and strategy.

2a. Product Interpretation and Delivery Boundary

The product is a first-party, browser-delivered game. Delivery and access ownership are as follows:

• Landing is the anonymous public entry surface. It presents the title IRUL — THE LAST NIGHT, its Tamil psychological-horror premise, and how to begin. It requires no identity and establishes no account.
• Game is the cohesive first-person local-device game workspace. It owns exploration, movement, inventory, puzzles, chapters, horror events, entity encounters, audio, saves, and endings. It is reachable without an account; progression continuity is provided by local-device save/load via localStorage, not by a server account.

No application-owned account, login, registration, or permission system is part of the current scope. Identity continuity is local-device only. There is no differentiated role-based visibility or permission control over shared product state; the single active human role has full access to the game's own state.

Current scope covers everything specified in this document: the playable game, its world, player systems, entity AI, horror events, Tamil audio, puzzles, seven chapters, three endings, cinematic visuals, and performance optimization.

Future scope is not defined by the source. No future features are committed here.

2b. Source Content Inventory

Not applicable. No reference directive with content_source authority was supplied.

2c. Page Content and Component Coverage

The page inventory is the closed, ordered page contract: Landing and Game.

Landing

• Information and state: Game title IRUL — THE LAST NIGHT with Tamil subtitle இ\xe0\xae\xb0\xe0\xaf\x81\xe0\xae\xb3\xe0\xaf\x8d — கடைசி இரவு; a short statement of the Tamil psychological-horror premise (return to a village abandoned after a strange incident twenty years ago); a clear call to begin gameplay; a clear path to resume an existing local save when one exists.
• Primary action: Begin the game (enter the Game workspace).
• Supporting actions: Continue from an existing local save when present; view the premise text.
• Domain entities: Title/branding, premise copy, local save presence indicator.
• Component responsibilities: Cinematic title presentation; premise copy block; primary "begin" control; conditional "continue" control reflecting local save availability; loading state while the game bundle and initial assets prepare.
• States:
  • Loading: cinematic loading presentation while the game bundle and initial assets prepare.
  • Empty: no local save present — only the begin control is offered.
  • Success: the player proceeds into the Game workspace.
  • Error/recovery: if the game bundle or required assets fail to load, present a clear failure message and a retry control; do not enter a broken game state.

Game

• Information and state: First-person view of the abandoned Tamil village at night; current chapter (The Village → The House → The School → The Forest → The Temple → The Truth → The Last Night); current objectives; inventory contents; stamina; flashlight on/off and battery level; fear/sanity state; interaction prompts; Tamil subtitles/dialogue; puzzle state; save/load state.
• Primary actions: Move (WASD), look (mouse look with pointer lock), sprint, crouch, toggle flashlight, interact using E, use inventory items, solve puzzles, hide, run, save, load, and reach an ending.
• Supporting actions: Read environmental storytelling objects (photographs, diaries, Tamil writing, footprints); listen to positional audio and dialogue; observe horror events; manage battery and stamina; review objectives.
• Domain entities: Player (Protagonist); TheEntity / அவள்; world locations (abandoned road and bus stop, village houses, tea shop, water tank, shrine, old house, school, temple, forest, underground final chamber); inventory items; clues; puzzles (old clock, school number sequence, temple symbols, radio frequency, underground final door); chapters; horror events; audio sources; save data in localStorage; endings.
• Component responsibilities: Renderer and scene management; player controller (movement, look, sprint, crouch, stamina); flashlight and battery; interaction system (E); inventory; objectives; fear/sanity; save/load; world modules per location; environmental storytelling props; HorrorEventManager; TheEntity AI; chase orchestration; audio system (positional 3D audio, Tamil dialogue/subtitles, strategic silence); puzzle modules; chapter/story progression; ending resolution; cinematic night visuals (fog, rain, moonlight, lanterns, flashlight shadows, particles, subtle bloom, vignette, film grain); performance systems (frustum culling, lazy loading, limited dynamic lights, efficient particles, resource disposal, distance-based AI updates); premium dark UI.
• States:
  • Loading: chapter/location load with cinematic loading presentation; lazy-loaded assets stream in.
  • Empty: no inventory items or clues yet collected; objectives show the current chapter's first goal.
  • Success: objectives complete, puzzles solved, chapters advance, an ending is reached.
  • Error/recovery: if a save is corrupt or unreadable, present a clear message and allow starting fresh without losing the ability to play; if the player is caught by TheEntity during a chase, apply the accepted failure/recovery behavior and allow continuation.

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance. Provenance is explicit (source-stated), basic_default (accepted default), or required_inference (indispensable inferred mechanics).

FR-1 — Playable game delivery As the Player (Protagonist), I should play a complete, playable browser-based 3D Tamil psychological horror game inside the workspace, so that I experience an actual game rather than a demo, landing page, static 3D scene, or fake UI.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = opening the game; observable result = a playable first-person horror experience; failure/recovery = build/console errors are fixed so the game runs; continuation = the player proceeds through the game.
• Acceptance: the game runs in a modern desktop browser and is genuinely playable end to end.

FR-2 — Technology and architecture As the Player (Protagonist), I should play a game built with React + TypeScript + Vite + Three.js, React Three Fiber where useful, Drei, the Web Audio API, CSS, and GLTF/GLB support, in a clean modular architecture, so that the game is maintainable and performant.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = running the game; observable result = the game runs on the specified stack; failure/recovery = build errors are inspected and fixed; continuation = development proceeds module by module.
• Acceptance: the specified technologies are used; no single giant component exists.

FR-3 — Premise and setting As the Player (Protagonist), I should play a first-person horror experience set in an abandoned Tamil village at night, where the protagonist receives a mysterious message and returns to a village abandoned after a strange incident 20 years ago, so that the story has its intended context.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = beginning the game; observable result = the first-person night-time Tamil village setting and the mysterious-message premise are presented; failure/recovery = n/a; continuation = the player explores the village.
• Acceptance: the setting and premise are present and consistent.

FR-4 — Mystery questions to discover As the Player (Protagonist), I should be able to discover what happened to the missing children, why the temple is sealed, who is following them, why the entity knows their name, and what happened on the final night, so that the central mysteries resolve through play.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = exploration and clue discovery; observable result = each mystery is answered through discovered content; failure/recovery = clues remain discoverable; continuation = answers feed the endings.
• Acceptance: all five mystery questions are answerable through in-game discovery.

FR-5 — Connected world As the Player (Protagonist), I should explore a connected environment containing an abandoned road and bus stop, a Tamil village with houses, tea shop, water tank and shrine, a large abandoned old house, an abandoned school, a rural temple, a dark forest, and an underground final chamber, so that the world is cohesive and traversable.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = movement through the world; observable result = all listed locations are reachable and connected; failure/recovery = locked doors and hidden passages gate access as intended; continuation = the player progresses between locations.
• Acceptance: every listed location exists and is connected.

FR-6 — Environmental storytelling As the Player (Protagonist), I should encounter realistic environmental storytelling through old photographs, diaries, toys, radios, broken furniture, Tamil writing, footprints, locked doors and hidden passages, so that the world tells its story.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = exploration and interaction; observable result = storytelling elements are present and readable; failure/recovery = n/a; continuation = discovered elements inform the mysteries.
• Acceptance: all listed storytelling element types are present.

FR-7 — Player movement and look As the Player (Protagonist), I should use WASD movement and mouse look with pointer lock, so that I can navigate the world in first person.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = keyboard/mouse input; observable result = the player moves and looks; failure/recovery = pointer lock is re-acquirable; continuation = navigation continues.
• Acceptance: WASD movement and pointer-locked mouse look function.

FR-8 — Sprint, crouch, and stamina As the Player (Protagonist), I should sprint and crouch, with stamina governing exertion, so that movement has tactical cost.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = sprint/crouch input; observable result = movement speed changes and stamina depletes/recovers; failure/recovery = stamina exhaustion limits sprinting until recovery; continuation = the player manages stamina.
• Acceptance: sprint, crouch, and stamina function and interact.

FR-9 — Flashlight and battery As the Player (Protagonist), I should use a flashlight with a battery, so that light is a resource and a survival tool.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = toggling the flashlight; observable result = the flashlight illuminates and the battery drains; failure/recovery = the battery can be replenished or the flashlight fails when depleted; continuation = the player manages light.
• Acceptance: the flashlight toggles, casts light and shadows, and consumes battery.

FR-10 — Interaction using E As the Player (Protagonist), I should interact with the world using E, so that I can open doors, pick up items, read objects, and operate puzzle elements.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = pressing E near an interactable; observable result = the interaction occurs; failure/recovery = locked or invalid interactions give clear feedback; continuation = the player continues interacting.
• Acceptance: E performs interactions with clear prompts.

FR-11 — Inventory As the Player (Protagonist), I should have an inventory, so that collected items and clues are tracked and usable.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = collecting an item; observable result = the item appears in the inventory; failure/recovery = n/a; continuation = items can be used for puzzles and progression.
• Acceptance: the inventory tracks collected items and clues.

FR-12 — Objectives As the Player (Protagonist), I should have objectives, so that I know the current goal.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = chapter/progress changes; observable result = objectives update; failure/recovery = n/a; continuation = the player pursues the current objective.
• Acceptance: objectives reflect current progress.

FR-13 — Fear/sanity As the Player (Protagonist), I should have a fear/sanity state, so that horror has a mechanical dimension.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = horror events and entity proximity; observable result = fear/sanity changes and affects the experience; failure/recovery = the state recovers over time or through safe behavior; continuation = the player manages fear.
• Acceptance: fear/sanity changes in response to horror and affects play.

FR-14 — Save/load using localStorage As the Player (Protagonist), I should save and load using localStorage, so that my progress persists on my device.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = saving or loading; observable result = progress is written to and restored from localStorage; failure/recovery = corrupt or unreadable saves are handled with a clear message and the ability to start fresh; continuation = the player resumes from the saved state.
• Acceptance: save/load works via localStorage and handles failure gracefully.

FR-15 — TheEntity and AI states As the Player (Protagonist), I should encounter a sophisticated entity called TheEntity / அவள் with AI states IDLE, PATROL, INVESTIGATE, SEARCH, STALK, CHASE, ATTACK, and DISAPPEAR, so that the threat behaves believably.

• Provenance: explicit.
• Lifecycle: initiator = TheEntity (system-driven); trigger = player noise, light, and proximity; observable result = the entity transitions between the specified states; failure/recovery = the player can evade and the entity can lose track; continuation = the entity resumes patrolling or stalking.
• Acceptance: all eight states exist and transition based on player behavior.

FR-16 — Entity senses and behavior As the Player (Protagonist), I should have TheEntity hear footsteps, investigate noise, react to the flashlight, search rooms, stalk me, and initiate major chase sequences, so that my actions have consequences.

• Provenance: explicit.
• Lifecycle: initiator = TheEntity; trigger = player footsteps, noise, and flashlight use; observable result = the entity investigates, searches, stalks, or chases; failure/recovery = the player can hide, run, or use light and strategy to escape; continuation = the entity returns to patrol or stalk.
• Acceptance: each listed sense and behavior functions.

FR-17 — Horror through restraint As the Player (Protagonist), I should experience fear built through silence, shadows, distant movement, footsteps, hallucinations, environmental changes and uncertainty, with the monster not constantly shown, so that dread is sustained.

• Provenance: explicit.
• Lifecycle: initiator = system (HorrorEventManager and world); trigger = exploration and time; observable result = atmospheric horror events occur without constant monster visibility; failure/recovery = n/a; continuation = tension persists.
• Acceptance: the monster is not constantly shown and the listed fear mechanisms are present.

FR-18 — HorrorEventManager As the Player (Protagonist), I should experience a reusable HorrorEventManager driving random and scripted events — door opening, objects moving, radio activation, whispers, footsteps, lights failing, shadows, distant silhouettes, mirror events and sudden appearances — so that horror is varied and reusable.

• Provenance: explicit.
• Lifecycle: initiator = system; trigger = random or scripted conditions; observable result = the specified events occur; failure/recovery = n/a; continuation = events continue across the game.
• Acceptance: the manager is reusable and supports all listed event types, both random and scripted.

FR-19 — Bathroom mirror sequence As the Player (Protagonist), I should experience a bathroom mirror sequence where the reflection stops following the player and slowly turns its head, so that a signature horror moment occurs.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = entering the bathroom and looking at the mirror; observable result = the reflection stops following and slowly turns its head; failure/recovery = n/a; continuation = the player continues exploring.
• Acceptance: the mirror sequence plays as specified.

FR-20 — School child-whisper event As the Player (Protagonist), I should experience a school event where a child whispers "அண்ணா... இங்க வ\xe0\xae\xbe\xe0\xae\x99\xe0\xaf\x8d\xe0\xae\x95..." and later "நீ\x20\xe0\xae\x8fன் வந்த?", so that the school chapter carries its scripted horror.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = entering the school and progressing; observable result = the first whisper plays, and later the second whisper plays; failure/recovery = n/a; continuation = the player continues the school chapter.
• Acceptance: both whispers occur in the specified order with the exact Tamil text.

FR-21 — Tamil subtitles and dialogue As the Player (Protagonist), I should see natural Tamil subtitles and dialogue, so that the story is told in Tamil.

• Provenance: explicit.
• Lifecycle: initiator = system; trigger = dialogue and scripted events; observable result = Tamil subtitles/dialogue are displayed; failure/recovery = n/a; continuation = the story continues.
• Acceptance: Tamil subtitles/dialogue are present and natural.

FR-22 — Audio design As the Player (Protagonist), I should hear rain, insects, distant dogs, wind, wooden doors, footsteps, radio static, temple bells, whispers, and positional 3D audio, with silence used strategically, so that the soundscape carries the horror.

• Provenance: explicit.
• Lifecycle: initiator = system; trigger = environment and events; observable result = the listed sounds play, positional audio localizes sources, and silence is used strategically; failure/recovery = n/a; continuation = audio continues.
• Acceptance: all listed sounds and positional 3D audio are present, with strategic silence.

FR-23 — Environmental puzzles As the Player (Protagonist), I should solve meaningful environmental puzzles involving an old clock, a school number sequence, temple symbols, a radio frequency, and an underground final door, so that progression requires thought.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = encountering a puzzle; observable result = the puzzle can be solved; failure/recovery = incorrect solutions give feedback and can be retried; continuation = solving advances progression.
• Acceptance: all five puzzles exist and are solvable.

FR-24 — Discoverable clues for every puzzle As the Player (Protagonist), I should find discoverable clues for every puzzle, so that solutions are earned rather than guessed.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = exploration; observable result = clues for each puzzle are discoverable in the world; failure/recovery = n/a; continuation = clues enable solving.
• Acceptance: every puzzle has discoverable clues.

FR-25 — Seven chapters As the Player (Protagonist), I should progress through seven chapters — The Village → The House → The School → The Forest → The Temple → The Truth → The Last Night — so that the story has its intended structure.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = completing chapter objectives; observable result = chapters advance in the specified order; failure/recovery = n/a; continuation = the next chapter begins.
• Acceptance: all seven chapters exist in the specified order.

FR-26 — Major chase As the Player (Protagonist), I should experience a major chase through the house, village and forest, so that the game has its central pursuit sequence.

• Provenance: explicit.
• Lifecycle: initiator = TheEntity; trigger = story progression into the chase; observable result = a sustained chase through the house, village, and forest; failure/recovery = the player hides, runs, uses light, puzzles, and strategy to survive; continuation = the chase resolves and the story continues.
• Acceptance: the chase spans the house, village, and forest.

FR-27 — No conventional weapons As the Player (Protagonist), I should have no conventional weapons and survive through hiding, running, light, puzzles and strategy, so that survival is tactical.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = entity encounters; observable result = the player survives only through the listed means; failure/recovery = being caught applies the accepted failure behavior; continuation = the player continues.
• Acceptance: no conventional weapons exist and the listed survival means function.

FR-28 — At least three endings As the Player (Protagonist), I should reach at least three endings based on clues and choices — escape without complete truth, discover the truth and escape, or become trapped underground — so that my choices matter.

• Provenance: explicit.
• Lifecycle: initiator = Player; trigger = clues collected and choices made; observable result = one of the three endings is reached; failure/recovery = n/a; continuation = the ending concludes the playthrough.
• Acceptance: all three endings exist and are determined by clues and choices.

FR-29 — Cinematic night visuals As the Player (Protagonist), I should see cinematic night lighting, fog, rain, moonlight, lanterns, flashlight shadows, particles, subtle bloom, vignette and film grain, with playable visibility, so that the game is atmospheric and readable.

• Provenance: explicit.
• Lifecycle: initiator = system; trigger = rendering; observable result = the listed visual effects are present and visibility remains playable; failure/recovery = n/a; continuation = rendering continues.
• Acceptance: all listed visual effects are present and visibility is playable.

FR-30 — Cinematic title/loading screens and premium dark UI As the Player (Protagonist), I should see cinematic title/loading screens and a premium dark UI, so that presentation matches the game's tone.

• Provenance: explicit.
• Lifecycle: initiator = system; trigger = launch and loading; observable result = cinematic title/loading screens and a premium dark UI are shown; failure/recovery = load failures present a clear message and retry; continuation = the game proceeds.
• Acceptance: title/loading screens and the dark UI are present.

FR-31 — Performance optimization As the Player (Protagonist), I should experience smooth performance on modern desktop browsers, achieved through frustum culling, lazy loading, limited dynamic lights, efficient particles, resource disposal and distance-based AI updates, so that the game runs well.

• Provenance: explicit.
• Lifecycle: initiator = system; trigger = rendering and simulation; observable result = the listed optimizations are applied and performance is smooth; failure/recovery = performance issues are profiled and fixed; continuation = play continues smoothly.
• Acceptance: all listed optimizations are implemented and performance is smooth.

FR-32 — Systematic development and testing As the Player (Protagonist), I should receive a game built systematically (architecture → renderer → player → world → flashlight → interaction → inventory → puzzles → audio → horror → entity AI → chase → story → endings → optimization → testing), with the project run after every major step, console/build errors inspected and fixed, and no core TODOs, fake functions, broken imports or unfinished gameplay, so that the final product is complete.

• Provenance: explicit.
• Lifecycle: initiator = developer; trigger = each major step; observable result = the project runs and errors are fixed; failure/recovery = errors are resolved before continuing; continuation = the next step begins.
• Acceptance: the build order is followed, the project runs after each step, and no core TODOs, fake functions, broken imports or unfinished gameplay remain.

FR-33 — Anonymous entry before gameplay As the Player (Protagonist), I should reach the anonymous Landing entry before starting gameplay, so that I can understand the game and begin.

• Provenance: required_inference.
• Lifecycle: initiator = Player; trigger = opening the game; observable result = the Landing surface presents the title, premise, and how to begin; failure/recovery = load failures present a clear message and retry; continuation = the player enters the Game workspace.
• Acceptance: Landing is anonymously reachable and leads into the Game.

FR-34 — Begin or resume a local-device save As the Player (Protagonist), I should begin or resume a local-device save through the Game experience, so that I can start fresh or continue.

• Provenance: required_inference.
• Lifecycle: initiator = Player; trigger = choosing begin or continue; observable result = a new game starts or an existing local save loads; failure/recovery = corrupt saves are handled with a clear message and the option to start fresh; continuation = play proceeds.
• Acceptance: beginning and resuming both work.

FR-35 — Load locally stored progression on return As the Player (Protagonist), I should have my locally stored progression loaded when I return, so that continuity is preserved on my device.

• Provenance: required_inference.
• Lifecycle: initiator = Player; trigger = returning to the game; observable result = the locally stored progression is loaded when available; failure/recovery = missing or corrupt saves fall back to a fresh start; continuation = the player resumes.
• Acceptance: returning play loads local progression when available.

FR-36 — Clues and puzzles gate later chapters and endings As the Player (Protagonist