Quickstart — OxHeart in 5 Minutes

This is the canonical first-run path. Follow it once and you'll have a working OxHeart project with a playable demo scene.

What You Get

By the end of this guide:

1. A ServiceConfiguration asset that controls which engine services run
2. A bootstrapped scene that initializes the engine on Play
3. A working sound playing through the audio service
4. A foundation you can clone for every other system (save/load, localization, pooling, etc.)

Total time: ~5 minutes if you already have Unity 6000.0 open.

---

Step 1 — Install (30 seconds)

If you got OxHeart from the Asset Store, it's already in your project. Skip to Step 2.

Confirm install by checking that Window → Package Manager → OxHeart is visible.

---

Step 2 — Run the Setup Wizard (90 seconds)

The wizard creates a ServiceConfiguration asset for your project — one file that toggles which engine services start.

1. Open Tools → OxHeart → Setup Wizard.
2. Pick the Default profile (enables every service except experimental ones).
3. Accept the default output path, Assets/Resources/Configs/ — your game's own Resources folder. Configs must never go in Assets/OxHeart/...: that folder is engine-owned and is replaced when you update the package, which would delete your settings. To put them elsewhere, untick Use default path; the folder still has to sit under a Resources/ folder so Resources.Load can find it at runtime.
4. Click through to the end. The wizard creates:
5. ServiceConfiguration.asset — the master toggle list
6. DefaultOxHeartConfig.asset — engine-wide settings
7. DefaultAudioConfig.asset, DefaultSaveConfig.asset, etc. — per-service settings
8. Verify the assets appear under Assets/Resources/Configs/.

Note: You can have more than one ServiceConfiguration. Pick which one a scene uses by assigning it to the Service Configuration field of the ImprovedGameInitializer component (next step).

---

Step 3 — Open a Demo Scene (10 seconds)

Seven demo scenes ship pre-wired under Assets/OxHeart/Samples/:

Scene	Path
Getting Started	Scripts/Scenes/00_GettingStarted.unity
Audio Playback	BasicAudio/Scenes/AudioPlayback.unity
Save / Load	DataPersistence/Scenes/SaveLoad.unity
Bullet Pool	ObjectPooling/Scenes/BulletPool.unity
Localization	Localization/Scenes/LocalizedText.unity
RNG Demo	Rng/Scenes/RngDemo.unity
Notifications	NotificationSystem/Scenes/Notifications.unity

Optional — regenerate scenes: Run Tools → OxHeart → Create Sample Scenes to rebuild the bundled .unity files (for example after a Unity upgrade reserializes them). This overwrites the existing scenes.

Each demo scene is self-contained: it references its own bundled per-sample ServiceConfiguration (in that sample's Configs/ folder), not the project config you created in Step 2. The scenes open and run standalone — you do not need to re-wire them to your Step 2 asset.

Package Manager → Samples → Import adds optional sample folders (scripts, audio, CSVs). The .unity scenes above are already in the package; import is not required to open them.

---

Step 4 — Press Play on the Audio Demo (60 seconds)

1. Open Assets/OxHeart/Samples/BasicAudio/Scenes/AudioPlayback.unity.
2. Verify the Hierarchy contains: EngineInitializer, Main Camera, AudioController, AudioCanvas (with three buttons), EventSystem.
3. Press Play.
4. Click Play SFX — you'll hear Demo_Click.wav (a short UI click).
5. Click Play Music — you'll hear Demo_Music.wav fade in over 2 seconds.
6. Click Stop All — everything stops.

If anything fails, check the Troubleshooting section at the bottom.

---

Step 5 — Use a Service in Your Own Code (90 seconds)

Now write your own MonoBehaviour that uses an engine service. Create a new C# script anywhere in Assets/Scripts/:

using OxHeart.Core.Audio.Extensions;
using OxHeart.Core.DataPersistence.Interfaces;
using OxHeart.Core.Localization.Interfaces;
using OxHeart.Core.Rng;
using OxHeart.Core.ServiceManagement.Service;
using OxHeart.Runtime;
using UnityEngine;

public class MyController : MonoBehaviour
{
    void Start()
    {
        // Wait for all engine services to initialize before using them
        ServiceAwaiter.WaitForServices(this, OnReady, OnTimeout);
    }

    void OnReady()
    {
        // Play the demo click — same audio service the sample uses
        this.PlaySound("Demo_Click", AudioExtensions.UITrack);
    }

    void OnTimeout()
    {
        Debug.LogError("Engine services failed to initialize within timeout.");
    }
}

Add this script to a new GameObject in any scene that has an EngineInitializer. Press Play — you'll hear the click.

That's it. Every other engine service follows the same pattern:

var save = ServiceLocator.Instance.Get<ISaveSystem>();
var rng  = ServiceLocator.Instance.Get<IRngService>();
var loc  = ServiceLocator.Instance.Get<ILocalizationService>();

---

What's Next?

Goal	Read
Full setup walkthrough (manual config, every service)	GettingStarted.md
Understand the service locator pattern	ServiceLocator.md
Add your own services to the engine	02-SERVICES-CHECKLIST.md
Set up persistent saves	DataPersistence.md
Add multi-language text	Localization.md and LOCALIZATION_MIGRATION.md
Cheat-sheet for every system	CHEATSHEET-How-To-Use.md
Architectural decisions and rationale	Architecture.md

---

Troubleshooting

Symptom	Most likely cause	Fix
Console: "ServiceConfiguration not found"	Wizard wasn't run, or asset is in wrong folder	Re-run Tools → OxHeart → Setup Wizard
Console: "ImprovedGameInitializer: timeout"	One of the enabled services failed to initialize	Look for the first [ERROR] line above the timeout — that's the root cause
Audio plays silently	Volume is muted or AudioConfig master volume is 0	Check DefaultAudioConfig.asset → Master Volume
"Service not found: IFooService"	Service is disabled in ServiceConfiguration	Open the asset, check the Enable Foo Service toggle
Demo scenes missing	Wrong package path or partial copy	Confirm Assets/OxHeart/Samples/…/Scenes/*.unity exists; re-import package or run Create Sample Scenes
Buttons in demo do nothing	EventSystem missing or wrong Input Module	Ensure an EventSystem with StandaloneInputModule or InputSystemUIInputModule matching your project's active input backend

For deeper issues, check Troubleshooting.md.

---

Unity: 6000.0+ — engine version: see package.json or CHANGELOG.md