1 / 6

Mara Simulator: Web-Based African Savanna Survival Game

Immersive Multiplayer Ecosystem Simulation

Project Overview

Mara Simulator is an ambitious web-based multiplayer survival game that recreates the dynamic ecosystem of the Maasai Mara and Serengeti regions. The game challenges players to survive in a realistic African savanna environment where they must hunt for food, navigate treacherous terrain, avoid predators, and cooperate with other players—all while managing health, hunger, and stamina in real-time.

Drawing visual inspiration from the critically acclaimed indie game Art of Rally, Mara Simulator features a stylized low-poly aesthetic with an overhead camera perspective, minimalistic terrain design, and smooth animations. The game emphasizes realism in wildlife behavior and survival mechanics: no human can outrun a lion, large prey requires cooperation to hunt, and the ecosystem dynamically responds to player actions.

Developed as a solo project over an intensive 3-week period, Mara Simulator demonstrates advanced web game development capabilities, including real-time 3D rendering, physics simulation, AI-driven wildlife behavior, multiplayer networking infrastructure, and complex game state management—all running entirely in the browser without requiring downloads or user accounts.

Live Demo: mara.ike.work

Currently in active development, the project showcases the ability to rapidly prototype and implement complex technical systems while maintaining code quality and architectural integrity.

Key Features

Realistic Survival Mechanics

Resource Management System: Players must actively manage three critical survival metrics: health, hunger, and stamina. Hunger depletes over time, forcing players to hunt or scavenge for food. Stamina drains during sprinting and regenerates when idle, creating strategic decisions about when to run from predators versus conserving energy. The game implements realistic weight and speed mechanics where consistent overeating affects player movement speed over time.

Dynamic Health System: Player health responds to various environmental factors including starvation, predator attacks, food poisoning, and injuries. The game features a 1% daily chance of random catastrophic events such as sudden illness, injuries that reduce movement speed, or ambush predator attacks, adding unpredictability to the survival experience.

Hunting and Feeding: Different animals provide varying amounts of food (antelopes feed 5 players, buffalos feed 10), while some carnivores are edible but carry a 50% sickness probability. Large prey requires cooperative hunting, encouraging player collaboration.

AI-Driven Wildlife Ecosystem

Intelligent Animal Behavior: The game features multiple animal species with distinct AI behaviors programmed using realistic movement patterns and decision-making algorithms. Herbivores (antelopes, zebras, giraffes, buffalos) move in herds with flocking behaviors, while carnivores (lions, leopards, cheetahs) hunt independently or in small groups with predator-prey dynamics.

Herd Management: Lions and other pack animals utilize sophisticated herd AI where individuals maintain cohesion while exhibiting natural behaviors like roaming, hunting, and resting. The system dynamically spawns animals near water sources and maintains ecosystem balance by ensuring herbivore populations stay at approximately 30% of player count.

Predator-Prey Dynamics: Carnivores actively hunt both wildlife and players, creating genuine danger zones. The AI evaluates threat levels, pursuit distances, and attack opportunities, making predator encounters unpredictable and challenging.

Procedural Terrain and Environment

Dynamic Terrain Generation: The game world features procedurally generated terrain with realistic elevation changes, hills, valleys, and plains. The terrain system uses height mapping and physics collision detection to create a believable African savanna landscape spanning thousands of square meters.

Environmental Features: No-go zones include rocks, trees, bushes, and water bodies that obstruct movement and provide strategic cover. Rivers and ponds are inhabited by dangerous crocodiles, hippos, and snakes, making water crossings high-risk decisions. The environment includes multiple vegetation types (dead trees, twisted trees, normal trees, various grass types, flowering bushes) that populate the landscape for visual variety and tactical positioning.

Dynamic Vegetation System: Vegetation is placed procedurally across the terrain with different density zones and variety, creating realistic savanna biomes. The system uses instanced rendering for performance optimization while maintaining visual richness.

Real-Time Multiplayer Networking

WebSocket-Based Synchronization: The game implements real-time multiplayer using Socket.IO for WebSocket communication, enabling seamless player interaction without loading screens. Player positions, actions, health states, and hunting activities synchronize across all connected clients.

Instant Join System: No user accounts required—players receive randomly generated names upon spawning and can join the world immediately. The system supports dynamic player entry and exit without disrupting ongoing gameplay.

Collaborative Gameplay: Players can cooperate on hunts, share kills, and work together to take down large prey. The networking infrastructure tracks shared hunting contributions and distributes rewards fairly.

Advanced Camera and Controls

Third-Person Camera System: Inspired by Art of Rally, the game features a dynamic third-person camera that smoothly follows the player character while maintaining optimal viewing angles. The camera system includes intelligent collision detection to prevent clipping through terrain or obstacles.

Responsive Input System: Support for both keyboard controls (WASD/Arrow keys for movement, Shift for sprint, E for interaction, Space for actions) and mobile touch controls with virtual joystick and sprint button. The input system debounces rapid actions and provides smooth, responsive character movement.

Adaptive Camera Behavior: The camera adjusts its distance and angle based on player speed, terrain elevation, and nearby obstacles, ensuring optimal visibility during both exploration and combat situations.

Visual Polish and Aesthetics

Low-Poly Art Style: Stylized low-poly 3D models for characters, animals, and environmental objects create a distinctive visual identity while optimizing performance. The aesthetic balances visual appeal with technical efficiency for smooth browser-based gameplay.

Advanced Lighting System: Multiple light sources including ambient lighting, directional sun lighting with dynamic shadows, and hemisphere lighting create depth and atmosphere. The lighting system uses PCF soft shadow mapping for realistic shadow rendering.

Performance Optimization: The renderer utilizes logarithmic depth buffering for improved Z-fighting prevention, ACES filmic tone mapping for cinematic color grading, and adaptive pixel ratio limiting to maintain smooth frame rates across various devices.

Technology Stack

Frontend Architecture

3D Rendering: Three.js 0.158.0 (WebGL-based 3D graphics engine)
Physics Engine: Cannon-ES 0.20.0 (JavaScript physics simulation with rigid body dynamics)
Language: TypeScript 5.2.2 with strict type checking
Build Tool: Vite 5.0.0 (modern frontend build tool with hot module replacement)
Styling: Tailwind CSS 4.0.14 with PostCSS processing
Module System: ES Modules with bundler module resolution

Game Engine Components

Scene Management: Three.js scene graph with fog effects and color grading
Camera System: Perspective camera with dynamic FOV and adaptive positioning
Physics World: Cannon.js world with SAP broadphase, custom materials, and contact material configurations
Rendering Pipeline: WebGL renderer with shadow mapping, antialiasing, and high-performance settings
Animation System: Custom animation managers for character and animal movements

Game Systems Architecture

Entity System: Modular entity management with separate managers for players, animals, terrain, and world objects
Player Management: Comprehensive player controller with position tracking, state management, health/hunger/stamina systems
Animal Management: AI-driven animal behavior with herd dynamics, hunting logic, and spawning systems
World Management: Procedural terrain generation, vegetation placement, water body management, and frustum culling
Input Management: Abstracted input handling supporting keyboard, mouse, and touch controls with callback systems
Network Management: Socket.IO client integration for real-time multiplayer synchronization
UI Management: HUD elements, stat displays, notifications, minimap, and compass
Audio Management: Sound effect and ambient audio system

Technical Infrastructure

Type Safety: Comprehensive TypeScript configuration with strict mode, no unused locals/parameters, and no fallthrough cases
Module Imports: Path aliasing (@/* for src/*) for clean import statements
Development Server: Vite dev server with fast HMR (Hot Module Replacement)
Production Builds: Optimized production builds with tree-shaking and code splitting
Asset Loading: GLTF/GLB model loading, texture loading with multiple formats (PNG normal maps, diffuse maps)

Deployment Infrastructure

Hosting: Firebase Hosting configured for single-page application deployment
Build Output: Production-ready distribution builds to dist/ directory
Asset Management: Static assets including 3D models (GLTF/GLB, binary buffers), textures (bark, leaves, grass, flowers, rocks), and environmental objects

Development Tools

Linting: ESLint integration for code quality
Version Control: Git with GitHub repository
Package Management: npm with lockfile for dependency stability
Cross-Platform: Support for Windows, macOS, Linux development environments

Technical Implementation Highlights

Physics-Based Movement System

Engineered a sophisticated physics-driven character controller using Cannon.js (a pure JavaScript 3D physics engine implementing impulse-based rigid body dynamics). The implementation required deep understanding of numerical integration methods and constraint solvers:

Fixed Timestep Integration: Implemented a semi-fixed timestep scheme running at 120Hz (PHYSICS_TIMESTEP = 1.0/120) with adaptive substepping (PHYSICS_MAX_SUBSTEPS = 4). This approach separates physics simulation from variable frame rates, ensuring deterministic behavior critical for multiplayer synchronization. The system uses velocity Verlet integration for position updates, providing second-order accuracy while maintaining energy conservation.

Contact Material Engineering: Developed custom ContactMaterial configurations between player and terrain bodies, tuning friction coefficients (μ = 1.0 for terrain, μ = 0.8 for player) and restitution values (e = 0.0 to eliminate bouncing). The contact equation solver uses:

Stiffness parameter: 1e8 (effectively rigid contacts with minimal interpenetration)
Relaxation parameter: 3 iterations (Gauss-Seidel successive over-relaxation for convergence)
Friction equation stiffness: 1e8 (prevents sliding on steep slopes up to approximately 55° incline)

Broadphase Collision Detection: Utilizes Sweep and Prune (SAP) algorithm for efficient broadphase culling, sorting collision bodies along principal axes to identify potential collision pairs in O(n log n) time complexity before expensive narrowphase calculations.

Velocity-Based Movement: Player input translates to impulse forces applied to the physics body's velocity vector rather than direct position manipulation. This preserves momentum, allows physics-based interactions with other entities, and enables realistic sliding on ice-like surfaces through damping coefficient tuning (linear damping = 0.3, angular damping = 0.999 to prevent unrealistic rotation).

Sprint Mechanics Integration: Dynamically modulates applied force magnitude based on stamina state, creating emergent gameplay where exhausted players move significantly slower, affecting escape scenarios from predators.

The player physics body uses a capsule collider (cylinder with hemispherical caps) for smooth collision response on uneven terrain, avoiding the "stuck on edges" problem common with box colliders. Mass is set to 70kg (realistic human weight) with center of mass positioned for stable upright posture.

Dynamic Terrain System with Heightfield Physics

Implemented a procedural terrain generation system that creates realistic African savanna landscapes with physics-accurate collision detection:

Heightfield generation using multiple octaves of Perlin noise for natural elevation variation
Physics terrain using Cannon.js HeightfieldShape synchronized with visual Three.js mesh
Terrain materials with high friction values to enable slope traversal
Frustum culling for performance optimization by rendering only visible terrain chunks
Dynamic LOD (Level of Detail) system to reduce polygon count for distant terrain

The terrain system stores height data in efficient arrays and provides height lookup methods for positioning entities at correct elevations.

AI State Machine for Wildlife

Developed a behavior-driven AI system for animal entities using state machines with multiple behavioral states:

Roaming state: Animals wander using Perlin noise-based movement patterns for natural unpredictability
Hunting state: Predators identify prey, calculate pursuit vectors, and execute coordinated attacks
Fleeing state: Herbivores detect threats and flee in realistic panic behaviors
Herd cohesion: Flocking algorithms maintain group formations while allowing individual variation
Water-seeking behavior: Animals spawn and congregate near procedurally placed water sources
Player interaction: Dynamic threat assessment based on proximity and player actions

Each animal maintains its own physics body, visual mesh, and behavioral state, updating independently while maintaining performance through efficient spatial indexing.

Multiplayer Network Architecture

Architected a real-time multiplayer system implementing client-server networking over WebSocket protocol (Socket.IO library providing fallback to HTTP long-polling for firewall traversal). The design addresses fundamental distributed systems challenges inherent to real-time games:

Transport Layer: WebSocket provides full-duplex communication channels over a single TCP connection, eliminating HTTP request/response overhead. Socket.IO adds automatic reconnection, heartbeat mechanisms, and message queuing during temporary disconnections. The protocol supports both binary (for position data using Float32Arrays) and JSON (for game events) serialization.

Client-Side Prediction: To mask network latency (typically 50-150ms RTT), the client immediately applies player input to local physics simulation without waiting for server confirmation. This creates responsive controls despite network delay. The system maintains a circular buffer of recent input commands with timestamps for reconciliation.

Server Reconciliation: When authoritative position updates arrive from the server, the client compares local predicted position against server position. If divergence exceeds a threshold (typically 0.5 meters), the client rewinds simulation state to the server's timestamp and replays buffered inputs, correcting prediction errors smoothly over several frames to avoid jarring teleportation.

Entity Interpolation: Other players' positions are rendered 100ms in the past using linear interpolation between buffered position snapshots. This delay masks packet loss and jitter while maintaining smooth motion. Dead reckoning algorithms estimate entity positions when packets are dropped, using last known velocity and acceleration vectors.

State Synchronization Protocol:

Player updates: Position (Vector3), rotation (quaternion), velocity, health/hunger/stamina sent at 20Hz
Event messaging: Attacks, kills, hunting actions broadcast immediately via reliable ordered channels
World state: Initial world seed sent on connection for deterministic procedural generation
Delta encoding: Only changed state properties transmitted, reducing bandwidth by ~70%

Scalability Architecture: The frontend connects to a planned Node.js backend using Socket.IO server rooms for spatial partitioning (dividing the large game world into sectors). Each room runs independent game loop instances, with cross-room entity visibility handled via inter-room messaging. This architecture scales horizontally by distributing rooms across multiple server instances with Redis pub/sub for inter-server communication.

Authoritative Server Model: Server maintains canonical game state, performs all critical game logic (combat calculations, hunting outcomes, death events), and validates client actions to prevent cheating. Clients send inputs; server computes results and broadcasts state updates.

Latency Compensation for Combat: Hit detection uses lag compensation techniques: when a client fires/attacks, the server rewinds other players' positions by the attacker's latency, performs hit testing against historical positions, preventing the "shoot where they were" problem in high-latency scenarios.

The network manager architecture uses event-driven callbacks (onPlayerJoin, onPlayerLeave, onPositionUpdate, onAnimalUpdate) allowing game systems to subscribe to network events without tight coupling to Socket.IO implementation, facilitating potential migration to alternative networking solutions (WebRTC for peer-to-peer, custom UDP protocols via WebTransport).

Advanced 3D Rendering Pipeline

Configured a high-performance WebGL rendering pipeline optimized for browser-based 3D gaming:

Shadow mapping: Directional light with 4096x4096 shadow maps and PCF soft shadows
Tone mapping: ACES Filmic tone mapping for cinematic color response
Color space management: sRGB color space for accurate color reproduction
Fog system: Exponential fog for atmospheric depth perception
Multi-light setup: Ambient, directional, and hemisphere lights for balanced illumination
Performance optimization: Adaptive pixel ratio (max 2x), logarithmic depth buffer, efficient shader compilation

The renderer maintains 60 FPS on modern hardware while rendering complex scenes with terrain, vegetation, multiple animated characters, and dynamic shadows.

Modular Component Architecture

Architected the codebase using separation of concerns with dedicated manager classes:

WorldManager: Terrain, vegetation, water, objects, and culling systems
PlayerManager: Player entity, controls, camera, physics, model, animation, and state
AnimalManager: Animal spawning, AI behavior, herd management, and lifecycle
InputManager: Keyboard, mouse, touch input abstraction with callback registration
UIManager: HUD rendering, stat bars, notifications, minimap, and compass
NetworkManager: WebSocket connection, event handling, and state synchronization
AudioManager: Sound effects, ambient audio, and spatial audio positioning

Each manager encapsulates specific functionality with clear initialization lifecycles and update loops, enabling independent development and testing of game systems.

Asset Pipeline and Resource Management

Established a comprehensive asset management system:

3D Models: GLTF/GLB format with binary buffers for efficient loading
Textures: High-resolution diffuse and normal maps for terrain, vegetation, and models
Model variants: Multiple variations for environmental objects (5 dead trees, 6 square pebbles, 5 round pebbles, etc.) for visual diversity
Lazy loading: Assets load asynchronously to prevent blocking game initialization
Resource disposal: Proper cleanup of GPU resources to prevent memory leaks

The asset pipeline supports rapid iteration during development while generating optimized production bundles with Vite's build system.

Current Development Status

Project Phase

Status: Active Development (January 2025)
Development Timeline: 3 weeks (intensive solo development)
Deployment: Live at mara.ike.work

Foundation Complete: Core game architecture, physics systems, rendering pipeline, and basic gameplay mechanics are fully implemented and functional. The game successfully initializes all managers, loads assets, renders the 3D environment, and handles player input with physics-based movement. Development from initial concept to deployable prototype demonstrates rapid prototyping capabilities and efficient technical decision-making under time constraints.

Working Features

Procedural terrain generation with physics collision
Player character with physics-based movement and controls
Third-person camera system with smooth following
AI-driven lion herds with behavioral state machines
Dynamic vegetation placement and environmental objects
Health, hunger, and stamina survival systems
FPS counter and performance monitoring
Desktop (keyboard/mouse) and mobile (touch) controls
SVG compass and minimap for navigation
Lighting system with dynamic shadows
Asset loading for 3D models and textures

Known Challenges & Active Work

The project is addressing several technical challenges typical of complex browser-based 3D games:

Physics Refinement: Fine-tuning player physics parameters for optimal feel, particularly on slopes and uneven terrain. Current work involves adjusting friction values, contact materials, and force application to achieve responsive yet realistic movement.

Performance Optimization: Implementing additional performance optimizations including LOD systems for distant objects, improved frustum culling, and vegetation instancing to maintain 60 FPS with large numbers of entities.

Multiplayer Backend: The frontend multiplayer infrastructure is present but requires a dedicated backend server implementation. Plans include Node.js server with WebSocket/TCP handling game state, player synchronization, and authoritative simulation.

Animation System: Expanding the animation system to include smooth character and animal animations during movement, attacking, and state transitions. Currently using placeholder models while developing the animation pipeline.

Additional Wildlife: Expanding beyond lions to include the full ecosystem (herbivores: antelopes, zebras, giraffes, buffalos; other predators: leopards, cheetahs; water creatures: crocodiles, hippos).

Development Roadmap

[Complete] Foundation: Core architecture, managers, rendering, physics
[In Progress] Polish: Animation integration, physics tuning, performance optimization
[Planned] Content Expansion: Additional animal species, diverse terrain biomes, weather system
[Planned] Multiplayer: Backend server implementation, player synchronization, cooperative mechanics
[Planned] Game Mechanics: Hunting system, cooperative gameplay, XP/leaderboard
[Future] Beta Testing: Public testing, balancing, user feedback integration

Technical Learnings

Browser-Based 3D Game Development

Gained comprehensive experience building a full-featured 3D game that runs entirely in the browser:

WebGL optimization for consistent performance across devices and browsers
Physics simulation with stable collision detection and realistic dynamics
Asset management strategies for loading and managing large numbers of 3D resources
Memory management to prevent leaks in long-running applications
Frame rate consistency techniques including fixed timesteps and adaptive quality settings

Complex State Management

Developed expertise in managing interconnected game systems with numerous entities:

Entity-component patterns for flexible, maintainable game object architecture
State synchronization between physics simulation and visual representation
Lifecycle management for entities with creation, update, and disposal phases
Callback architectures for decoupled communication between systems
Asynchronous initialization with dependency ordering and error handling

AI and Procedural Generation

Implemented sophisticated AI behaviors and procedural content generation:

Behavior trees and state machines for complex, realistic AI decision-making
Flocking algorithms for coordinated group movement with individual variation
Procedural noise (Perlin noise) for natural-looking terrain and movement
Spatial algorithms for proximity detection, pathfinding preparation, and threat assessment
Ecosystem balancing to maintain engaging population dynamics

TypeScript for Game Development

Leveraged TypeScript's type system for building robust game code:

Strict typing to catch errors during development before runtime
Interface design for manager communication and callback signatures
Generic types for reusable entity and component systems
Type safety in physics calculations, vector math, and state management
IDE support with autocomplete and refactoring for large codebases

Real-Time Multiplayer Concepts

Designed architecture for real-time multiplayer gaming:

Client-server models with server authority and client prediction
Network event design for efficient state updates
Latency handling strategies for smooth gameplay over networks
Scalable architecture preparing for concurrent player support

Skills Demonstrated

Full-Stack Game Development

Frontend Expertise: Advanced Three.js usage for 3D rendering, shader management, lighting, and shadows. Complex UI development with responsive design for desktop and mobile.

Physics Simulation: Deep understanding of physics engines (Cannon.js) including rigid body dynamics, collision detection, contact materials, and numerical stability.

AI Programming: State machine implementation, behavioral algorithms, procedural movement, and ecosystem simulation.

Performance Engineering: Profiling, optimization strategies, efficient rendering techniques, and memory management for maintaining 60 FPS.

Software Architecture

Design Patterns: Manager pattern, component architecture, dependency injection, callback systems, and state management patterns.

Modularity: Clear separation of concerns with dedicated modules for distinct functionality, enabling parallel development and testing.

Scalability: Architecture designed for extensibility, allowing addition of new animal types, terrain features, and game mechanics without major refactoring.

Error Handling: Comprehensive try-catch blocks, validation, and graceful degradation for robust runtime behavior.

Modern Web Technologies

Build Tools: Vite configuration for development and production, including hot module replacement and optimized builds.

TypeScript Mastery: Advanced TypeScript features including strict mode, generics, interfaces, and type inference.

Asset Pipelines: GLTF/GLB model loading, texture management, and efficient resource streaming.

Responsive Design: Cross-platform support for desktop and mobile with adaptive controls and UI.

Game Design Principles

Realism vs. Playability: Balancing realistic survival mechanics with engaging gameplay.

Risk-Reward Systems: Hunting mechanics where larger prey provides more food but requires cooperation.

Dynamic Difficulty: Ecosystem that adapts to player behavior and population.

Player Agency: Multiple viable strategies for survival (cooperation, solo play, different food sources).

Development Achievement

3-Week Solo Development

This project was architected, implemented, and deployed entirely by one developer in a 3-week sprint, demonstrating:

Rapid prototyping skills: Moving from concept to playable demo with complex systems integration
Technical breadth: Implementing 3D graphics, physics simulation, AI systems, networking, and game design simultaneously
Autonomous problem-solving: Researching and integrating unfamiliar technologies (Cannon.js physics, Three.js advanced rendering, WebSocket networking) without external support
Production deployment: Not just a prototype—deployed to production hosting with proper build optimization and browser compatibility testing
Code quality under pressure: Maintaining TypeScript strict mode, modular architecture, and comprehensive error handling despite aggressive timeline

The 3-week constraint forced architectural decisions prioritizing:

Modularity: Manager pattern allowed parallel development of independent systems
Existing libraries: Leveraging Three.js and Cannon.js rather than reinventing 3D/physics engines
Minimal viable features: Core survival mechanics first, aesthetic polish and advanced features iteratively
Automated tooling: Vite's HMR and TypeScript's compiler accelerated development feedback loops

Note: This project serves as a technical showcase and portfolio piece demonstrating full-stack game development capabilities.

Mara Simulator demonstrates advanced capabilities in web-based 3D game development, combining modern web technologies with complex game systems to create an immersive multiplayer survival experience entirely in the browser. The 3-week development timeline showcases the ability to rapidly architect, implement, and deploy production-ready software while maintaining code quality and technical sophistication.