ThreadRunner

ThreadRunner is a lightweight 3D daily runner where yesterday's community commands shape today's hazards, and every failed run leaves a permanent visible mutation on the avatar.

This repository contains the hackathon vertical product: a dark three-lane thread tunnel, Cats / Drama / Alien hazards, Echo pickups, a deterministic obstacle director, death and mutation reveals, an Avatar Memory screen, a mocked community-results flow, and persistent local progression. It runs on React, TypeScript, Three.js, React Three Fiber, and Vite using WebGL.

Prerequisites

• Node.js 20.19+ or 22.12+
• npm
• A browser with WebGL support

Install and run

npm ci
npm run dev -- --port 5188

Open http://localhost:5188.

Quality and production commands:

npm run lint
npm run typecheck
npm test
npm run build
npm run check
npm run preview -- --port 4173

npm run check runs lint, type checking, domain tests, and the production build in sequence.

Controls

Desktop:

• Left / Right arrows or A / D: switch lanes
• Space, Up arrow, or W: jump
• Enter: start from Today's Run; Enter or R restarts after death
• F: toggle fullscreen
• Escape: leave Community Results
• Sound button: mute or unmute persistent audio

Mobile:

• Swipe left or right: switch lanes
• Swipe up: jump
• On-screen Left, Jump, and Right buttons provide the same actions

Current features

• Authored Today's Run, onboarding, active-run, mutation-reveal, Avatar Memory, and Community Results flow
• Smooth three-lane movement, buffered jump, close rear camera, and procedural character animation
• Nine distinct hazards: Yarn Ball, Cat Pounce, Laser Sweep, Reply Wall, Argument Burst, Thread Split, Watching Eye, Gravity Distortion, and Orbiting Shards
• Seeded obstacle director with a safe opening, escalation, intensity peaks, recovery beats, and validated safe lanes
• Echo score and combo, near misses, Thread Shield, milestones, speed progression, impact feedback, and reliable restart
• Six visible mutation memories with duplicate-safe persistence and run history
• Strict local command parsing for !curse cats, !trap drama, !bless wholesome, and !mutate alien
• Deterministic daily configuration and mocked community vote results behind a platform interface
• Gesture-safe procedural WebAudio cues, ambience, mute state, and persisted preferences
• Keyboard, swipe, and explicit mobile controls; responsive layouts for desktop and narrow screens
• WebGL fallback, loading treatment, test-state hooks, and local-storage migration

Project structure

public/assets/          Small transparent gameplay and UI emblems
scripts/                Executable domain-test runner
src/App.tsx             R3F scene, game loop integration, screens, and input
src/audio/              Procedural WebAudio system
src/data/               Local community fixtures
src/domain/             Daily-run, mutation, and profile rules
src/game/               Deterministic obstacle director and invariants
src/platform/           Platform contracts and local fallback adapter
src/styles.css          Shared visual system and responsive presentation
test-actions/           Short action bursts for browser game QA
progress.md             Recovery audit, verified work, and remaining tasks

Persistence and community data

The standalone build stores profile, run history, mutations, vote snapshots, leaderboard fallback data, and audio preferences in browser local storage. Community comments and the current user are mocked locally, but access goes through ThreadRunnerPlatform interfaces intended for a later Devvit adapter.

Branch workflow

Active completion work belongs on completion/showcase-pass. Do not push directly to main, force-push, or create or merge a pull request unless explicitly requested. Run npm run check, inspect the rendered desktop and 390x844 mobile flows, and stage only intentional files before committing.

Known limitations

• Devvit dependencies, manifest/configuration, Reddit API access, and Redis persistence are not installed or deployment-tested.
• Community results are deterministic local fixtures, not live comment data.
• Audio is synthesized in WebAudio and remains replaceable placeholder production audio.
• Character and hazard motion are lightweight procedural animation rather than skeletal or authored keyframe animation.
• The small generated emblem decals can reveal their flat texture origin at extreme close range.
• Domain systems are automated; rendered gameplay is validated with browser QA rather than a fully automated end-to-end suite.