Technical Overview

Technical Overview

Home · Installation · Configuration · Multiplayer · Graphics

Stack

Layer	Technology
Application/UI	React 19, TypeScript 5, Tailwind CSS, lucide-react
Rendering	Three.js; native examples modules for post-processing/loaders
Physics	@dimforge/rapier3d-compat, lazy-loaded for solo enemy ragdolls
Multiplayer	PeerJS data connections; host-authoritative enemy simulation
Backend	Convex reactive database and serverless functions
Authentication	@convex-dev/auth, username/password flow
Build	Vite 7, React compiler plugin, PostCSS/Autoprefixer
Hosting config	Vercel

Runtime architecture

flowchart LR
  UI[React menus and HUD] --> APP[App.tsx game coordinator]
  APP --> THREE[Three.js scene and render loop]
  APP --> SYS[Gameplay utility systems]
  APP --> NET[PeerJS multiplayer manager]
  UI --> DATA[Convex React client]
  APP --> DATA
  DATA --> BACKEND[Convex auth, progression, daily, leaderboard, photos]
  NET --> PEERS[Host and guest peers]

Loading

src/App.tsx is the central imperative game coordinator. It creates the scene, camera, renderer, world, game loop, input listeners, combat entities, and system integration. React components are layered on top for menus and HUD rather than owning the frame-by-frame Three.js scene.

Key folders

src/
  App.tsx                 Core game setup, loop, input, combat, networking glue
  main.tsx                React / Convex application entry
  components/             HUD, menus, lobby, settings, touch UI, overlays
  hooks/                  Device detection and current player-data provider
  types/game.ts           Weapon, enemy, bullet, pickup, terrain, game-state types
  utils/                  Rendering, AI, networking, progression, world, audio systems
convex/
  schema.ts               Convex database schema
  auth.ts                 Username/password auth flow
  playerStats.ts          Progression, skill, mastery, settings mutations
  daily.ts                Daily progress and claims
  leaderboard.ts          Public leaderboard query
  photos.ts               Photo upload/list/delete flow
  gameLimits.ts           Input caps, score/rank economy validation
public/
  Forest.png              App icon / social image
  audio/Beyond_The_Overgrowth.mp3

convex/_generated/ is generated Convex client/server type output. Do not hand-edit it.

Gameplay modules

Concern	Key modules
Weapons and entities	src/types/game.ts, src/utils/GunModel.ts, src/App.tsx
Character classes	CharacterAbilityRegistry.ts, CharacterPassiveRegistry.ts, CharacterModels.ts
Enemies and AI	SmartEnemyManager.ts, AIBehaviorSystem.ts, EnemyArchetypes.ts, TacticalDirector.ts, EnemyPerception.ts, AttackSystem.ts, BulletDodging.ts
World	MapSystem.ts, BiomeSystem.ts, TerrainSystem.ts, TerrainInstancer.ts, WeatherSystem.ts, DayCycleSystem.ts, HazardSystem.ts
Progression	WavePerkRegistry.ts, RunModifierSystem.ts, WeaponMasterySystem.ts, SmartSkillTreeSystem.ts, AchievementSystem.ts, DailyChallengeRegistry.ts
Multiplayer	MultiplayerManager.ts, RemotePlayerManager.ts, SnapshotInterpolator.ts
Presentation	PostProcessing.ts, Shaders.ts, Effects.ts, SoundManager.ts, RagdollSystem.ts

Networking details

PeerJS sessions are peer-to-peer. The host owns the enemy simulation and broadcast stream; each player publishes their own player state. Compact, quantized enemy records contain ID, type code, position, yaw, current/max health, and death status. Remote players and enemies are rendered from snapshot buffers rather than lerping toward the latest packet.

This is deliberately distinct from Convex: Convex stores account and progression data, but it does not act as the live game server.

Data model

playerStats is the main persistent profile document. It contains skill points, skill levels, achievement bitmask, avatar, privacy preferences, rank XP and recent difficulty history, settings blob, weapon-mastery XP, title, and solo/multiplayer aggregates. Separate tables hold photo pointers, daily progress, auth records, signup/device guards, and app metadata.

Server mutations clamp and rate-limit submitted values. This bounds obvious client-side manipulation but does not make PeerJS gameplay fully authoritative or cheat-proof.

Build and deployment

• npm run dev starts Vite for local development.
• npm run build runs TypeScript project build checks then Vite production build.
• Vite splits three and peerjs into manual output chunks and raises its chunk warning threshold to 1,500 kB for the large renderer bundle.
• vercel.json deploys via npx convex deploy --cmd 'npm run build', runs npm install, and publishes dist.

Implementation references: package.json, vite.config.ts, src/main.tsx, src/App.tsx, convex/schema.ts, vercel.json.