OxHeart – Game Framework for Unity

OxHeart is a modular Unity 6 game-development framework that gives you production-grade versions of the systems every game rebuilds from scratch without locking you into a genre or art style.

Toggle services on or off. Extend the engine with your own game services. Ship on desktop and mobile with IL2CPP-safe patterns and docs written for real projects.

Built for Unity 6000.0+ Pipeline-agnostic (works with Built-in, URP, and HDRP).

⚠️ Required before importing — Newtonsoft JSON and Addressables

OxHeart compiles against Unity's free Newtonsoft JSON and Addressables packages, and a Unity package (.unitypackage) does not auto-install dependencies so add both before you import:

1. Open Window → Package Manager

2. Click the + button → Add package by name…

3. Enter com.unity.nuget.newtonsoft-json and click Add

4. Repeat for com.unity.addressables (version 2.9.1+)

5. Import OxHeart once both finish installing

If you import first and see missing Newtonsoft or Addressables types, add the packages above and let Unity recompile. Addressables is a compile-time dependency; using it at runtime remains optional, and the default configuration uses Resources until you enable Addressables.

Why OxHeart?

⚡ Modular by design: Enable only what you need via ServiceConfiguration ScriptableObjects. Core-only for prototypes; full stack for production.

🏗️ Clean architecture : Service Locator + interfaces (IAudioService, ISaveSystem, IEventManager, …). No singleton soup. Game-specific services register via auto-discovered IServiceRegistrar.

📦 Addressables-ready : IResourceService loads via Addressables with Resources fallback. AssetReference support included.

🎲 Deterministic gameplay : Named RNG streams, snapshot save/load, ModelDb content registry, TypedPoolBag, and AntiPityOdds for roguelike/deckbuilder-style systems.

💾 Saves/Loads : Async save/load, encryption & compression, per-domain schema migration, corrupt-file quarantine, pluggable ISaveStore backends.

🔊 Audio that scales : Tracks, pooling, fades, and a Music Playlist Service with gapless crossfade and per-track gain.

🌍 Modern localization : CSV tables plus LocString / DynamicVar for tooltips, upgrades, and runtime substitution.

📚 Documented & tested : Quickstart guide, per-system docs, architectural decision records, bundled samples, and extensive EditMode/PlayMode test coverage.

Key features

• Service Locator & Initializer: ImprovedGameInitializer , dependency ordering, Setup Wizard, Default/Minimal presets
• Type-safe Event Bus: Pooled events, safe listener dispatch, MonoBehaviour extensions
• Resource Management: Addressables-first, async loading, memory budget, AssetReference API
• Object Pooling: Spawn/Despawn extensions, pre-warming, statistics
• Audio System: Multi-track mixer support, fades, 3D audio, source pooling
• Music Playlists: Shuffle/sequential modes, equal-power crossfade, preload lookahead, now-playing metadata
• Save System: Multi-slot, auto-save, quick-save, migration chains, quarantine on corrupt files
• Localization: Multi-language CSV, runtime language switch, LocString formatters
• Time Service: Global pause, channels, timers, scheduler
• Game State Manager: Extensible state machine (Menu / Gameplay / Paused + custom states)
• Notifications: Categorized in-game messages with priority and duration
• Deterministic RNG: SplitMix64 streams, save snapshots, test override injection
• Content Registry ( ModelDb ): IL2CPP-safe explicit registration, canonical/mutable AbstractModel boundary
• Probabilistic utilities: TypedPoolBag , AbstractOdds , AntiPityOdds
• Logging: Sink-based OxLogger + game-facing GameLogger
• Extensibility: IServiceRegistrar , inspector-driven custom services, LateInitialize() hook

What's Included

• Four runtime assemblies plus editor tooling and default configuration assets
• 13 importable samples: Basic Audio, Data Persistence, Event System, Game Settings, Game State, Localization, Notifications, Object Pooling, Deterministic RNG, Resource Management, Scene Management, Third-Party Notices, and Core Script Examples
• 14 playable scenes, including the two-scene Scene Management transition demo
• 33 documentation guides: https://oxheart.moomoo.games/latest/
• Root link.xml for IL2CPP managed stripping protection

Platform Support

• Windows, macOS, and Linux - Mono and IL2CPP
• iOS and Android - IL2CPP

⚠️ WebGL is not supported because async save/load, obfuscation, and file logging use background threads.

Important scope notes

⚠️ Not a genre template - OxHeart is infrastructure and provides systems, not a complete RPG/FPS/RTS template. You bring gameplay, art, and scenes.

⚠️ There is no networking, multiplayer, cloud-save adapter, input service, tweening library, or general UI framework.

⚠️ The Input System package is optional; the engine never reads input, and samples adapt to the available input backend.

⚠️ No AI model, inference runtime, or AI service call is included.

LEARN MORE AND SUPPORT

• Documentation: https://oxheart.moomoo.games/latest/

• Architecture guide: https://oxheart.moomoo.games/latest/Architecture/

• Dev logs: https://moomoo.games/#/devlog

• Support: unitysupport@moomoo.games · https://moomoo.games

When reporting an issue, include your Unity version, OxHeart version, platform, and steps to reproduce.