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.5f1 or later. The package manifest declares "unity": "2022.3" with "unityRelease": "5f1", and UPM enforces it
• 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-native/quantum-forge-unity.git

5. Click Add

Version pinning

Pin to a release by appending a tag:

https://github.com/quantum-native/quantum-forge-unity.git#unity-v1.4.0

Use 1.4.0 or later. Every earlier tag shipped a package that does not compile in Unity.

Basis size limit

The shipped native plugin is compiled for a maximum dimension of 3 and 12 interacting quantum properties, with no dynamic fallback. A Basis with more than 3 values fails when the QuantumProperty is created, and the component logs a warning instead of running. Keep every Basis at 2 or 3 values. See Advanced Topics for how to design around it.

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".

A Basis can hold at most 3 values. The shipped plugin is built with MAX_DIMENSION=3 and dynamic fallback off, so a 4-value Basis fails when the QuantumProperty creates its native state. Awake logs a warning and the component stays inert.

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.quantumforge"]
   }

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