Unity Package

Quantum Forge for Unity provides native C# integration via the Unity Package Manager. Add quantum mechanics to GameObjects with inspector-driven components — no WASM, no TypeScript, just drag-and-drop.

Requirements

• Unity 2022.3.1f1 or later
• Windows, Mac, Linux, or WebGL build targets

Installation

1. Open the Unity Package Manager (Window > Package Manager)
2. Click the + button in the top left corner
3. Select Add package from git URL...
4. Enter:

   https://github.com/quantum-realm-games/quantum-forge.git?path=unity-package

5. Click Add

Version pinning

Pin to a specific release by appending a tag:

https://github.com/quantum-realm-games/quantum-forge.git?path=unity-package#unity-v1.2.0

Core Concepts

Quantum Forge is built on three concepts:

• Basis — The values your quantum property can exist in (either classically or in superposition). Created as a ScriptableObject via Assets > Create > Quantum > Basis.
• QuantumProperty — A MonoBehaviour that gives a GameObject quantum state. Set its Basis and initial value in the Inspector.
• Actions — MonoBehaviour components (Hadamard, Cycle, Clock, etc.) that manipulate quantum state. Wire them to buttons or call Apply() from code.

Quick Start

1. Create a Basis

Navigate to Assets > Create > Quantum > Basis. Define the values this basis can have — for example, a rock-paper-scissors basis with values "rock", "paper", "scissors".

2. Add QuantumProperty

Add the QuantumProperty component to a GameObject. Drag your Basis into the Basis field and set the initial classical value.

3. Visualize Probabilities

Add the ProbabilityTracker component to the same GameObject. It automatically reads the quantum state and exposes the probability distribution.

4. Apply Quantum Operations

Create a UI Button. Add a Hadamard component to the button. Drag the GameObject with the QuantumProperty into the Hadamard's Target Properties field. Add the Hadamard's Apply() method to the button's onClick event.

When you run the game and click the button, the probability distribution changes as the property enters superposition.

Example: Quantum Door

A simple quantum game mechanic:

using QRG.QuantumForge.Runtime;
using UnityEngine;

public class QuantumDoor : MonoBehaviour
{
    public QuantumProperty doorProperty;

    public void PutInSuperposition()
    {
        // Equal chance of each basis state
        doorProperty.Hadamard();
    }

    public void OpenDoor()
    {
        // Collapse to a definite state
        int[] result = QuantumProperty.Measure(doorProperty);
        string world = doorProperty.basis.values[result[0]].Name;
        Debug.Log($"Door opened to: {world}");
    }
}

Testing Your Setup

1. Open Packages/manifest.json
2. Add quantum-forge to the testables list:

   {
     "dependencies": { },
     "testables": ["com.qrg.quantum-forge"]
   }

3. Open the Test Runner (Window > General > Test Runner)
4. Click Run All

Troubleshooting

DLL not found / tests fail

Close and reopen Unity. The editor sometimes has issues loading the native quantum-forge library immediately after installation.

macOS security warning

The quantum-forge native library is not code-signed yet. Under System Preferences > Security & Privacy > General, click Open Anyway for the quantum-forge library.

Next Steps

• Advanced Topics — Entanglement, phase, controlled operations, debugging
• API Reference — Complete QuantumProperty, Actions, and Trackers reference
• Samples — Included sample projects