Skip to content

unity-integration.md

Latest commit

 

History

History
65 lines (42 loc) · 4.02 KB

unity-integration.md

File metadata and controls

65 lines (42 loc) · 4.02 KB
Raw

Unity integration

How to use MAGIC in a Unity project: compile your Clojure to .clj.dll with the nos CLI outside Unity, then load it at play time through the magic-unity UPM package. The package also rewrites MAGIC's IL during IL2CPP builds (iOS, Android, consoles).

This is the consumer-side guide. For what the package contains and how its internals work, see magic-unity. For the deps.edn / magic.edn compile workflow in depth, see Porting a Clojure library to MAGIC.

Steps

  1. Install nos (build-time only; needs the mono runtime, no .NET SDK). See Install in the root README for the one-line installer.

  2. Add the package to Packages/manifest.json, pinned to a tag from the releases page. Pick one variant (see Choosing a variant):

    {
  "dependencies": {
    "sg.flybot.magic.unity": "https://github.com/flybot-sg/magic.git?path=magic-unity#<tag>"
  }
}

  3. Add deps.edn and magic.edn at your project root. deps.edn declares your source :paths and any :deps; magic.edn points the build at Unity's plugins folder:

    ;; magic.edn
{:build {:namespaces [my.game.core] :out "Assets/Plugins/Magic"}}

    A project with custom build/test steps can still hand-write a dotnet.clj instead (see the porting guide); unity-examples/magic-unity-smoke does, because its test runner is not clojure.test.

  4. Compile before opening Unity:

    nos build

    This drops your .clj.dll into Assets/Plugins/Magic/, where Unity loads them.

  5. Open Unity and hit Play. For CI, nos test runs the Mono-side clojure.test suites without Unity. IL2CPP-only regressions need a real Unity build.

Choosing a variant

The package ships in two variants, identical except for whether the runtime .clj.dll plugins are visible to the Editor:

sg.flybot.magic.unity (default) sg.flybot.magic.unity.dual
Runtime in the Editor loadable excluded (!UNITY_EDITOR)
MAGIC in Editor Play mode works not available (Editor uses stock ClojureCLR)
Alongside stock ClojureCLR benign console noise, handled by the guard silent (runtime absent from the Editor)
Player builds (Mono / IL2CPP) identical identical
  • Default if MAGIC runs in your Editor (Play mode, edit-mode tooling) and there is no stock ClojureCLR.
  • .dual if your Editor runs stock ClojureCLR (REPL / hot-reload) and MAGIC ships only in player builds. Pin ?path=magic-unity-dual#<tag>.

Full comparison and rationale: magic-unity, Package variants.

Coexistence with stock ClojureCLR

A project that keeps stock ClojureCLR in the Editor and ships MAGIC in players runs both runtimes. With the default variant the Editor prints one benign Assembly is incompatible with the editor line per runtime .clj.dll on each domain reload (Unity narrating the intended exclusion; player builds are unaffected). The .dual variant excludes the runtime from the Editor by construction, so those lines never appear. Either way the stock probe for clojure.core.clj is kept away from the fork assemblies (#25).

The in-repo reproduction is unity-examples/magic-unity-coexist: bb coexist-noise checks that the dual variant is silent, bb coexist-noise magic-only reproduces the noise on the default variant.

Examples