Skip to content

RentEarth Technical Guides

RentEarth Technical Guides

Section titled “RentEarth Technical Guides”

Welcome to the RentEarth technical documentation. This guide collection covers the complete architecture, systems, and implementation details for the RentEarth survival action game.

Overview

Section titled “Overview”

RentEarth is a survival action game built with a modern tech stack spanning Unity (client), Rust/Axum (server), and Astro (web). The architecture emphasizes server-authoritative gameplay, reactive programming patterns, and clean separation of concerns.

Guide Categories

Section titled “Guide Categories”

Game Design Document

Core game design, Unity architecture, and client-side systems including VContainer DI, UniTask async, R3 reactive programming, and Cinemachine cameras.

Read the GDD

Axum Server Architecture

Rust game server documentation covering MSCP message protocol, WebSocket handling, LRU caching, SharedWorker integration, and gRPC transport.

Read Axum Guide

Pool Oracle System

Prefab library, entity pooling, tag/label system, variant architecture, LOD integration, and composite prefab design.

Read Pool Oracle Guide

ECS Architecture

Entity Component System design using bevy_ecs for the Rust game server, including component inventory, system scheduling, and migration plans.

Read ECS Guide

Pathfinding & Navigation

Server-authoritative pathfinding, waypoint graphs, A* navigation, spatial data structures, and NPC movement systems.

Read Pathfinding Guide

Combat System

Combat mechanics, HP/MP/EP stats, movement modifiers, entity state machines (emotional, behavioral, combat states), and damage calculations.

Read Combat Guide

Billboard System

LOD-based billboard rendering for WebGL optimization, including camera-facing sprites, texture atlases, and GPU instancing.

Read Billboard Guide

Quick Reference

Section titled “Quick Reference”

Technology Stack

Section titled “Technology Stack”
LayerTechnologyPurpose
Client (Game)Unity + C#3D game rendering, player input, visual feedback
Client (Web)Astro + TypeScriptDocumentation, web dashboard, SharedWorker
ServerRust + AxumGame logic, entity state, physics (Rapier3D)
ProtocolProtobufBinary serialization for network messages
DatabaseSupabaseAuthentication, persistence, realtime subscriptions

Key Architectural Patterns

Section titled “Key Architectural Patterns”
PatternLocationDescription
MSCPServerMessage Service Communication Protocol - all game mutations flow through typed commands
ECSServerEntity Component System via bevy_ecs for efficient state management
ReactiveClientR3 observables for UI binding and event streams
DIClientVContainer for dependency injection and lifecycle management
Server-AuthNetworkServer is single source of truth; clients interpolate and render

Implementation Status Overview

Section titled “Implementation Status Overview”
SystemStatusGuide
Core Game Loop CompleteGDD
WebSocket Protocol CompleteAxum
Prefab Pool System CompletePool Oracle
A* Pathfinding CompletePathfinding
NPC State Machine CompleteCombat
Basic Movement CompleteCombat
ECS Migration=2 PlannedECS
Billboard LOD=2 PlannedBillboard
Combat System=2 PlannedCombat
gRPC Transport=2 PlannedAxum
Flow Fields=2 PlannedPathfinding

Guide Summaries

Section titled “Guide Summaries”

Game Design Document (GDD)

Section titled “Game Design Document (GDD)”

The foundational document covering RentEarth’s Unity client architecture:

  • Core Technologies: VContainer (DI), UniTask (async), R3 (reactive), Cinemachine (camera)
  • Manager Architecture: GameLifetimeScope, GameManager, EventManager, InputManager
  • UI System: UI Toolkit with MainMenuManager
  • AI-Assisted Development: MCP integration with Unity Editor
  • Performance Focus: Zero-allocation patterns, frame-based operations

Axum Server Architecture

Section titled “Axum Server Architecture”

Server-side game logic and network communication:

  • MSCP Pattern: GameHandle with mpsc channels for command routing
  • Dual Response: Same commands serve HTTP (HTML) and WebSocket (binary) clients
  • Caching Strategy: LRU cache for ServerMessage responses with version-based invalidation
  • SharedWorker Upgrade: Path from JSON to Protobuf in browser worker
  • gRPC Transport: Future server-to-server and admin tool communication

Pool Oracle System

Section titled “Pool Oracle System”

Comprehensive prefab management and entity pooling:

  • PrefabRegistry: Centralized prefab metadata, routes, and validation
  • Tag System: Functional, visual, physics, performance, and semantic tags
  • Variant Architecture: MaterialOnly, PropertyOverride, Additive modes with component preservation
  • LOD Integration: WebGL-optimized LOD with impostor support
  • Composite Prefabs: Base + attachment system for visual variations
  • Content Pipeline: Astro MDX � JSON � Unity ScriptableObjects

ECS Architecture

Section titled “ECS Architecture”

Migration plan from custom EntityState to bevy_ecs:

  • Component Decomposition: EntityState � Position, Health, NpcState, etc.
  • Resource System: GameTime, SpatialIndex, NetworkIdLookup, WaypointGraph
  • System Scheduling: Input � PreUpdate � Update � PostUpdate � Sync phases
  • Change Detection: Built-in Changed<T> and Added<T> queries
  • Migration Phases: 10-phase plan from dependencies to legacy cleanup

Pathfinding & Navigation

Section titled “Pathfinding & Navigation”

Server-authoritative navigation systems:

  • WaypointGraph: Graph-based A* pathfinding with typed waypoints
  • Waypoint Types: Navigation, Patrol, GuardPost, Spawn, Combat, Cover
  • Combat Shortcuts: Direct pursuit bypasses graph during combat
  • Spatial Structures: Chunk-based hashing (current), Quadtree/KD-Tree (planned)
  • Flow Fields: Planned for mass unit movement (100+ entities)
  • Unity Editor: Visual waypoint placement and connection tools

Combat System

Section titled “Combat System”

Stats, movement, and entity state machines:

  • Stats: HP (health), MP (mana), EP (energy) with regeneration
  • Movement: Sprint modifier (1.5x speed, EP cost), per-entity speed modifiers
  • Emotional State: Calm, Alert, Angry, Afraid, Happy, Sad, Confused
  • Behavior State: Idle, Patrol, Chase, Flee, Guard, Harvest, Attack
  • Combat State: OutOfCombat, Engaging, InCombat, Disengaging, Dead
  • Threat System: Threat list with priority targeting

Billboard System

Section titled “Billboard System”

WebGL performance optimization for distant objects:

  • LOD Tiers: Hot (full 3D + colliders) � Warm � Cool � Cold (billboard)
  • BillboardRenderer: Camera-facing quads with Y-axis lock
  • Texture Atlas: Batched rendering with UV-based sprite selection
  • GPU Instancing: Shared quad mesh and material for all billboards
  • Performance: 100 objects: 100 draw calls � 1-5 draw calls

Architecture Diagrams

Section titled “Architecture Diagrams”

Client-Server Communication

Section titled “Client-Server Communication”
�����������������������������������������������������������������
                      AXUM SERVER (Rust)                          
�����������������������������������������������������������������$
  HTTP Routes ��,�� WebSocket ��,�� Future: gRPC                 
                                                                
                �������,�������                                 
                    GameHandle (mpsc tx)                          
                         GameCommand                             
                    World Runtime                                 
         ��������������<��������������                         
                                                              
    EntityState    Environment    PhysicsWorker                  
      Manager        Manager       (Rapier3D)                    
�������������������������,���������������������������������������
                           WebSocket (10 Hz snapshots)
�����������������������������������������������������������������
                      CLIENTS                                     
�����������������������������������������������������������������$
     Unity (Game)        Browser (Astro/JS)       SharedWorker 
�����������������������������������������������������������������

Entity State Flow

Section titled “Entity State Flow”
������������������     ������������������     ������������������
  EMOTIONAL STATE �����  BEHAVIOR STATE  �����   COMBAT STATE   
  ����������������       ����������������       ����������������
  Calm                   Idle                   OutOfCombat     
  Alert                  Patrol                 Engaging        
  Angry                  Chase                  InCombat        
  Afraid                 Flee                   Disengaging     
  Happy                  Guard                  Dead            
������������������     ������������������     ������������������

Getting Started

Section titled “Getting Started”

  1. New to RentEarth? Start with the Game Design Document for an overview of the client architecture and core technologies.

  2. Working on server features? Read the Axum Server Architecture and ECS Architecture guides.

  3. Implementing NPCs? Check Pathfinding for navigation and Combat for state machines.

  4. Optimizing performance? See Pool Oracle for prefab management and Billboard for LOD systems.

Contributing

Section titled “Contributing”

When adding new documentation:

  1. Create a new .mdx file in astro/src/content/docs/guides/
  2. Add frontmatter with title and description
  3. Update this index with a card and summary
  4. Follow the existing documentation patterns for consistency
Section titled “Related Resources”
  • Proto Definitions: proto/rentearth/snapshot.proto, proto/rentearth/pool.proto
  • Unity Scripts: unity/rentearth/Assets/Scripts/
  • Server Code: website/axum/src/
  • Astro Content: astro/src/content/