A 3D browser survival game built with Three.js, TypeScript, and Vite
Hunt · Grow · Survive
Wild Roads is a snake-inspired survival game rendered in full 3D. You slither through an endlessly generated wilderness, hunting deer and evasive foxes while surviving wolves and territorial bulls. The world streams in dynamically around the player, cycles through day and night, and is built entirely with a hand-rolled Three.js rendering pipeline — no game engine, just the raw graphics stack.
The project doubles as an exploration of real-time 3D web game architecture: chunk-based procedural terrain, animated GLTF/FBX creature AI, dynamic lighting, and mobile-first touch controls, all shipped as a fast, dependency-light Vite app.
- 🐍 3D Snake Movement — Smooth, physically responsive steering and segment-following movement in a full 3D world (not a grid).
- 🦌 Hunting & Growth Loop — Chase deer to grow, or intercept faster zigzagging foxes for score and stamina.
- 🐺 Distinct Threat AI — Wolves stalk and bite while bulls warn, lock a direction, and commit to a dodgeable charge.
- 🦊 Biome Wildlife Ecology — A shared quality-scaled population budget blends species by biome without stacking extra actors onto the scene.
- 🪵 Meaningful Terrain — Mud slows movement, brambles drain stamina, and authored log gates and rock passages offer a safe detour or a rewarded risky shortcut.
- 🧭 Encounter Director — Runs open with prey-only learning, rise into single threats and authored wildlife combinations, then grant 6–8 second recovery windows.
- 🔥 Trail Camps & Run Builds — Every 300 metres, bank the run or continue at higher risk and choose one of five deterministic, rankable adaptations.
- 🗺️ Biome Chapters — Each biome has a readable chapter objective, exact-once reward, and route-spacing identity that changes how the trail unfolds.
- 🐾 Wildlife Ecosystem — Wolves pressure prey, Bulls scatter nearby animals, and panicked Foxes can alarm Deer independently of the player.
- 📅 Daily Trail — A UTC-seeded daily challenge uses canonical gameplay budgets across graphics settings and races you against your saved personal-best ghost.
- 🌧️ Mechanical Weather — Rain deepens mud, wind direction changes boost efficiency, mist aids recovery, and storms make risky terrain more punishing.
- 🏅 Skill Scoring — Chain catches up to a 4× multiplier, earn boost-catch and Bull near-miss bonuses, and score clean Wolf escapes.
- 🌍 Procedural World Streaming — Terrain is generated in chunks using simplex noise and streamed in/out around the player for a seamless, infinite map.
- 🌗 Dynamic Day/Night Cycle — A continuous lighting cycle shifts sun color, ambient light, and sky mood between day, sunset, and night.
- ✨ Stamina & Boost System — Sprint through danger or toward prey using a stamina-gated speed boost with regen mechanics and timed power-ups.
- 🎮 Cross-Platform Controls — Full keyboard support (WASD / arrow keys + Shift/Space to boost) alongside on-screen touch controls for mobile play.
- 🔊 Reactive Audio — A looping ambient soundscape plus distinct procedural Fox, Wolf, and Bull cues with pause, visibility, and mute lifecycle handling.
- 🎨 Procedural Textures & Effects — Ground textures, glow sprites, screen shake, and hit/eat particle bursts generated at runtime rather than pre-baked.
- 📊 Live HUD & Tutorial — Real-time score, stamina, terrain state, streak feedback, and a skippable first-run guide to route and wildlife warnings.
- ⚡ Performance Monitoring — Integrated with Vercel Speed Insights for real-world performance tracking.
| Category | Technology |
|---|---|
| Language | TypeScript |
| 3D Rendering | Three.js |
| Build Tool | Vite |
| Procedural Noise | simplex-noise |
| Models | FBX / GLTF (loaded via Three.js FBXLoader / GLTFLoader) |
| Analytics | @vercel/speed-insights |
| Deployment | Vercel |
wild-roads/
├── public/
│ ├── models/ # FBX/GLTF assets — terrain props and animated wildlife
│ └── sounds/ # Ambient and SFX audio
├── src/
│ ├── entities/ # Animal AI: animatedAnimal.ts, animalManager.ts
│ ├── gameplay/ # Camps, upgrades, chapters, Daily Trail, pacing, scoring
│ ├── player/ # Player-controlled snake logic (snake.ts)
│ ├── world/ # Scene, chunk streaming, lighting, sky, camera
│ ├── utils/ # Asset loading, audio, input, effects, UI, FPS counter
│ ├── main.ts # Game bootstrap, loop, and state management
│ └── style.css # HUD and menu styling
├── index.html
├── package.json
└── tsconfig.json
- Node.js 22.18+
- npm (bundled with Node.js)
# Clone the repository
git clone https://github.com/Faisal01011/wild-roads.git
cd wild-roads
# Install dependencies
npm installnpm run devOpens the game with hot module reload, typically at http://localhost:5173.
npm run buildType-checks the project with tsc and outputs an optimized production build via Vite.
npm test
npm run test:typesRuns the deterministic gameplay harnesses and type-checks both application and test code.
npm run previewServes the production build locally for a final check before deployment.
| Action | Keyboard | Touch |
|---|---|---|
| Steer Left | A / ← |
Left on-screen button |
| Steer Right | D / → |
Right on-screen button |
| Boost | Shift / Space |
Boost on-screen button |
Eat deer to grow. Catch faster foxes for extra score and stamina. Avoid wolves, and sidestep the red warning lane before a bull commits to its charge. Hostile hits shrink your snake and cost points. Boosting drains stamina, so time your sprints carefully.
Read the road as well as the wildlife: pale green markers lead around an obstacle safely, while amber markers identify a direct shortcut through mud or brambles. Chaining catches within six seconds raises the catch multiplier; boosting through a catch, narrowly dodging a Bull, and escaping a Wolf pursuit without damage award additional points.
The weather chip states the current trail rule. Rain makes mud grip harder, hard wind taxes boost only when you turn into it, mist improves recovery, and storms punish overcommitting to hazardous shortcuts. Threat arrows and Bull charge lanes remain authoritative even in poor visibility.
At each Trail Camp, Extract to bank the run safely or Continue for a larger reward multiplier and one run-long adaptation. Daily Trail uses the same route seed for everyone that UTC day and replays your best saved path as a non-colliding ghost.
Wild Roads is deployed on Vercel and live at wild-roads.vercel.app. The default build expects to be served from a domain root; subpath hosts such as GitHub Pages require matching Vite base and asset-path configuration.
- Additional prey and threat species (Fox and Bull)
- Environmental hazards, authored route choices, and paced encounters
- Skill bonuses and first-run warning tutorial
- Trail camps, run upgrades, biome chapters, and wildlife interactions
- Daily seeded runs with a personal-best ghost
- Deterministic mechanical weather
- Persistent leaderboard
- More camp upgrade families and rare adaptations
- Alternate vehicle/movement modes
Contributions, issues, and feature requests are welcome.
- Fork the project
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project does not currently specify a license. All rights reserved by the author unless otherwise stated.
Third-party models retain their original licenses. See THIRD_PARTY_ASSETS.md for model sources, licensing, and processing notes.
Faisal Fayaz
- GitHub: @Faisal01011
- LinkedIn: faisal-fayaz
If you enjoyed playing, consider giving the repo a ⭐