HRAGE — Hrvatski RAGE 🇭🇷

A next-generation, cross-platform game engine written entirely in Rust.

Built to power GTA VII — and any open-world AAA title that refuses to be locked to a single platform.

---

What Is This?

HRAGE (Croatian RAGE) is an open-architecture game engine that compiles a single Rust codebase to every major platform on earth:

Platform	Graphics API	Status
🪟 Windows	DirectX 12	Tier 1
🍎 macOS	Metal 3	Tier 1
🐧 Linux	Vulkan 1.3	Tier 1
📱 Android	Vulkan 1.1	Tier 2
📱 iOS	Metal 2	Tier 2
🎮 Steam Deck	Vulkan 1.3	Tier 2
📱 HarmonyOS	Vulkan / OpenGL ES	Tier 3
🔧 Debug (any)	OpenGL 4.6 / ES 3.2	Fallback

Tier 1 = full feature parity, CI-gated on every commit. Tier 2 = full gameplay, scaled visuals, CI-gated. Tier 3 = experimental, best-effort, community-driven.

---

Why?

Because players shouldn't care what OS they're running. Because Rust gives us memory safety and fearless concurrency without sacrificing performance. Because the best game engine is the one that ships everywhere from a single codebase.

---

Architecture at a Glance

hrage/
├── crates/
│   ├── hrage_hal/          ← Vulkan / Metal / DX12 / OpenGL abstraction
│   ├── hrage_renderer/     ← Render graph, materials, lighting
│   ├── hrage_ecs/          ← Entity-Component-System runtime
│   ├── hrage_physics/      ← Rigid body, vehicles, deformation
│   ├── hrage_audio/        ← Spatial audio, streaming, DSP
│   ├── hrage_net/          ← Multiplayer networking
│   ├── hrage_ai/           ← NPC behaviour, pathfinding, traffic
│   ├── hrage_scripting/    ← Lua + Rhai scripting
│   ├── hrage_ui/           ← Game UI toolkit
│   ├── hrage_assets/       ← Asset pipeline & streaming
│   ├── hrage_input/        ← Unified input (KB/mouse/gamepad/touch/gyro)
│   ├── hrage_platform/     ← OS windowing, lifecycle, permissions
│   ├── hrage_animation/    ← Skeletal, IK, motion matching
│   ├── hrage_vfx/          ← GPU particles, volumetrics, weather
│   ├── hrage_world/        ← Open-world streaming, LOD, terrain
│   └── hrage_editor/       ← In-engine editor (egui)
├── game/gta7/              ← GTA VII — the first game built on HRAGE
├── tools/                  ← Asset compiler, shader compiler, profiler
└── platforms/              ← Per-platform packaging (Android, iOS, etc.)

Every engine system is its own crate. The game layer (gta7) consumes the engine as a library — it never reaches past the public API.

---

Key Design Decisions

• Pure Rust. No C/C++ in first-party code. FFI only at the platform SDK boundary.
• Native graphics per platform. Vulkan on Linux/Android, Metal on Apple, DX12 on Windows. OpenGL as a debug-only fallback.
• ECS-first. All gameplay state lives in the Entity-Component-System. No god objects.
• Data-driven everything. Maps, missions, AI, physics tuning, UI — all in declarative files (RON/MessagePack). Hot-reload in the editor.
• Frame budget is law. 16.6 ms (60 fps) on console-class hardware. Every system declares its budget.
• Deterministic simulation. Fixed-timestep physics and ECS for networking and replay.

---

Documentation

Document	Purpose
CLAUDE.md	Start here. Project rules, conventions, repo layout, AI assistance guidelines.
SPECS.md	Full technical specification — 22 sections covering every engine subsystem.
CONTRIBUTING.md	How to contribute, claim ownership, submit PRs.
UNSAFE_AUDIT.md	Registry of every unsafe block in the codebase. (Created when code begins.)

If you're using an AI assistant (Claude, etc.) to work on this project, point it at CLAUDE.md first. It contains explicit instructions for AI-assisted development.

---

Getting Started

Prerequisites

• Rust (latest stable, edition 2024)
• Platform SDKs as needed:
  • Vulkan SDK (Linux, Android)
  • Xcode (macOS, iOS)
  • Windows SDK + DX12 Agility SDK (Windows)
  • DevEco Studio (HarmonyOS)
  • Android NDK (cargo-ndk)

Build

# Build entire workspace (native platform, default backend)
cargo build --workspace

# Run GTA7
cargo run -p gta7

# Run with OpenGL debug fallback
cargo run -p gta7 -- --gfx=opengl

# Run the editor
cargo run -p hrage_editor --features editor

# Run all tests
cargo test --workspace

# Benchmarks
cargo bench -p hrage_physics

Cross-Compile

# Android (ARM64)
cargo ndk -t arm64-v8a build -p hrage_platform --features android

# iOS
cargo build -p hrage_platform --target aarch64-apple-ios --features metal

---

GTA VII

The first (and flagship) game built on HRAGE. A fully cross-platform Grand Theft Auto — same game, same world, every device.

Highlights:

• Open-world city at GTA scale with seamless streaming
• Vehicle physics: cars, bikes, boats, helicopters, planes, submarines
• 5-star wanted system with escalating AI
• Multiplayer: 32 players on PC/console, 16 on mobile
• In-game phone with apps, contacts, browser, stock market
• Full modding support via sandboxed Lua scripting
• Touch controls auto-generated from the input map on mobile

See SPECS.md §19 for the full game layer specification.

---

Current Status

🚧 Pre-alpha — architecture and specification phase.

The engine is currently defined in documentation. Code scaffolding is next. This is where you come in.

What Needs Building (Roughly in Order)

1. hrage_platform — windowing and lifecycle on at least one Tier 1 platform
2. hrage_hal — Vulkan backend first (most explicit API, easiest to validate)
3. hrage_renderer — basic render graph, triangle on screen
4. hrage_ecs — core ECS runtime with system scheduling
5. hrage_input — keyboard + mouse on desktop
6. hrage_physics — rigid body basics, character controller
7. Everything else grows from there

---

Contributing

See CONTRIBUTING.md for the full guide. The short version:

1. Read CLAUDE.md (non-negotiable)
2. Pick an issue or claim an unclaimed area
3. Fork, branch, build, test on as many platforms as you can
4. PR with tests — CI must pass on all Tier 1 + Tier 2 platforms
5. One approval required for merge

We actively welcome contributors using AI assistants — just make sure the AI reads CLAUDE.md first.

---

Team

Area	Owner	Status
Engine Architecture	@ZlatanOmerovic	Active
Graphics / HAL	Open	Claim it →
Physics	Open	Claim it →
Networking	Open	Claim it →
GTA7 Game Logic	Open	Claim it →
Mobile Platforms	Open	Claim it →
Audio	Open	Claim it →
AI / NPC Systems	Open	Claim it →
Editor	Open	Claim it →

Want to own a subsystem? Open an issue titled [OWNERSHIP] Claim: <area> with a brief pitch of your experience.

---

License

Proprietary. All rights reserved. See LICENSE for details.

---

HRAGE — Hrvatski RAGE
Built in Bosnia & Herzegovina 🇧🇦 • Written in Rust 🦀 • Runs everywhere 🌍