Skip to content

HumanitZ Module

The first and reference QS-Bridge game module. A pure Rust UE4 4.27 interceptor that transforms HumanitZ servers from 16-player single-threaded instances into high-performance, moddable, database-driven systems.

Overview

The HumanitZ module is a GameInterface implementation that lives in a separate repository (howyagarn-server/). It is the proof-of-concept that validates QS-Bridge's architecture — and the most complex module, since UE4 4.27 requires low-level vtable hooking and direct memory manipulation.

Metric Value
Repository howyagarn-server/ (7 Rust crates)
Engine Unreal Engine 4.27
STDB Tables 49
STDB Reducers 117+
Unit Tests 748+ (860+ assertions)
Enums 19
Worker Threads 4
Optimisation Layers 15+

Architecture

graph TD
    Server["HumanitZ Server Process (HumanitZServer-Linux-Shipping)"]

    Server --> LDP["LD_PRELOAD → libqsbridge.so"]
    Server --> Vanilla["Vanilla UE4 (rendering, physics, networking)"]

    subgraph Bridge["libqsbridge.so"]
        LDP --> EA["Engine Adapter (UE4 4.27)"]
        LDP --> GM["Game Module (HumanitZ GameInterface)"]
        LDP --> STDB["STDB Client → SpacetimeDB (WebSocket, BSATN)"]
    end

    EA --> VT["vtable hook interception"]
    EA --> PE["ProcessEvent capture"]
    EA --> SA["SpawnActor/DestroyActor tracking"]
    EA --> TL["Tick loop injection"]

    GM --> RPC["42+ RPC hooks"]
    GM --> Schema["218 schema definitions"]
    GM --> Workers["Worker threads"]
    GM --> Sphere["Sphere/Signal System"]
    GM --> Horde["Horde Brain"]
    GM --> ZR["Zombie Recycling"]

    Workers --> AI["AI thread @ 2 Hz"]
    Workers --> World["World thread @ 2 Hz"]
    Workers --> Budget["Budget thread @ 2 Hz"]
    Workers --> Events["Events thread @ 1 Hz"]

    Sphere --> ActiveZ["Active zone (full sim)"]
    Sphere --> PhysZ["Physics zone (collision only)"]
    Sphere --> FrozenZ["Frozen zone (no sim, recyclable)"]

    Horde --> Leader["Leader-follower AI"]
    Horde --> SharedPath["Shared pathfinding"]

    ZR --> Teleport["Teleport frozen → active (near underbudget players)"]

Crate Structure

The module is organised as a Rust workspace with 7 crates:

Crate Purpose
stdb-module SpacetimeDB WASM module — 49 tables, 117+ reducers
bridge-core Core bridge logic, RPC dispatch, message queuing
engine-ue4 UE4 4.27 engine adapter, vtable hooks, memory offsets
game-humanitz HumanitZ-specific game logic, RPC handlers
shell-brain AI system — sphere/signal, horde brain, zombie management
optimisation 15+ optimisation layers, worker threads
shared Common types, error handling, logging

Performance Impact

The core reason this module exists: UE4 4.27's actor replication scales O(n²), capping HumanitZ servers at ~16 players. QS-Bridge offloads state to SpacetimeDB, which scales O(changed_rows × log(subscriptions)).

Subsystem Before (Vanilla) After (QS-Bridge)
Max Players ~16 64+ (target)
Zombie Limit ~100 2,000+
AI Perception O(n²) actor checks Grid-based spatial queries
Replication UE4 generic actor graph MMO-aware priority scheduling
State Management In-memory, volatile SpacetimeDB, persistent
Admin Tools Server console only Full web panel

15+ Optimisation Layers

The module doesn't just observe game state — it takes ownership of subsystems:

  1. Sphere/Signal System — Active, Physics, and Frozen zones with hysteresis to prevent zone flicker
  2. Zombie Recycling — Teleport zombies from frozen zones to active zones near underbudget players
  3. Horde Brain — Leader-follower AI with shared pathfinding (N zombies, 1 pathfind)
  4. Worker Threads — AI, world, budget, and events on dedicated threads at controlled frequencies
  5. Tick Budget Manager — Cap per-frame work to maintain target frametime
  6. Grid-Based Spatial Queries — Replace O(n²) distance checks with O(1) grid lookups
  7. Priority Replication — MMO-aware: nearby players get frequent updates, distant players get sparse
  8. Batch State Writes — Accumulate changes, write to STDB in batches (not per-tick)
  9. Memory-Mapped State — Direct reads from game memory (no UE4 API overhead)
  10. Spawn Pooling — Pre-allocated actor pools, no allocation during gameplay
  11. LOD AI — Full AI near players, simplified AI at distance, no AI when frozen
  12. Event Coalescing — Merge redundant events before sending to STDB
  13. Conditional Hooks — Only intercept RPCs when relevant (e.g., skip damage when no players nearby)
  14. Async STDB Writes — Non-blocking reducer calls from worker threads
  15. Heartbeat Compression — Only send changed fields in periodic updates

STDB Schema — 49 Tables

The HumanitZ sub-database contains 49 game-specific tables (separate from the 12 platform tables):

Category Tables Examples
Player State 8 PlayerPosition, PlayerVitals, PlayerInventory, PlayerSkills
World State 7 BasePiece, Vehicle, Container, CropPlot, FishTrap
AI State 5 ZombiePosition, ZombieBrain, AnimalState, HordeLeader, SpawnPool
Social 6 FactionDef, FactionMember, Territory, AllianceDef, ChatLog, MailMessage
Economy 4 TradePost, TradeOffer, ShopInventory, Recipe
Quest 3 QuestDef, QuestProgress, QuestReward
Events 4 GameEvent, SecurityEvent, WeatherState, WorldEvent
Config 5 SpawnConfig, LootTable, DifficultyConfig, ZoneConfig, MapMarker
Meta 7 PlayerStats, Leaderboard, ServerStats, SessionLog, DeathLog, KillLog, CombatLog

117+ Reducers

Category Count Examples
Player Actions 35+ move_player, damage_player, heal_player, craft_item, place_building
World Actions 20+ spawn_zombie, destroy_building, grow_crop, update_vehicle
Social Actions 15+ create_faction, invite_member, declare_war, send_chat
Admin Actions 12+ admin_teleport, admin_give_item, admin_kick, admin_set_weather
System 20+ heartbeat_tick, ai_tick, world_tick, cleanup_stale, migrate_schema
Log-Only Stubs 13 apply_buff, remove_buff, select_profession, set_appearance, etc.

19 Enums

Custom SpacetimeDB enums for type-safe game state:

Enum Variants Purpose
PlayerStatus Alive, Dead, Unconscious, Loading Character state
ZombieState Active, Frozen, Recycling, Dead AI lifecycle
BuildingType Wall, Floor, Roof, Door, Window, Foundation, ... Structure classification
DamageType Melee, Ranged, Explosive, Fire, Fall, Zombie, Animal Combat damage source
FactionRole Leader, Officer, Member, Recruit Hierarchy
WeatherType Clear, Rain, Storm, Fog, Snow Environmental state
... ... ...

Publishing

The HumanitZ module is published on wiki.qs-zuq.com as a downloadable server-side mod. Server operators install it via:

  1. Download libqsbridge-humanitz.so from the wiki
  2. Configure LD_PRELOAD for their HumanitZ server
  3. Point the bridge at their SpacetimeDB instance
  4. Start the server — the bridge registers automatically