UI Cartridges#

Cartridges package reusable source files and Unity assets into a single ScriptableObject. Drop one onto a JSRunner and its files become importable modules, its objects become accessible from JavaScript.

Quick Example#

A theme cartridge bundles a stylesheet and some Unity assets:

Cartridge: "theme"
  Files:    variables.uss
  Objects:  logo -> LogoTexture, font -> InterFont

In your app:

import "@cartridges/theme/variables.uss"

function Header() {
    const { logo, font } = __cart("theme")

    return (
        <View className="header">
            <Image src={logo} />
            <Label text="My App" style={{ unityFontDefinition: font }} />
        </View>
    )
}

Setup#

1. Create -- Right-click in the Project window, Create > OneJS > UI Cartridge
2. Configure -- Set a slug (e.g., theme), add files and/or objects in the inspector
3. Add to JSRunner -- Drag the asset into the Cartridges tab
4. Extract -- Click Extract to write files to disk (also happens automatically on first run and during builds)

Accessing Files#

Cartridge files are regular source files that esbuild can import:

import { ColorWheel } from "@cartridges/color-picker/index"
import "@cartridges/theme/variables.uss"

Accessing Objects#

Object entries are available at runtime as properties on the cartridge:

const palette = __cart("color-picker").palette    // Texture2D
const config = __cart("color-picker").config      // ScriptableObject

Each cartridge auto-generates a .d.ts file, so you get full autocomplete and type checking for object keys.

Namespaces#

Optional namespaces organize cartridges like npm scoped packages. Set the Namespace field in the inspector:

__cart("color-picker")              // no namespace
__cart("@acme/color-picker")        // with namespace "acme"

Namespaced cartridges extract to @cartridges/@{namespace}/{slug}/.

Builds#

The build processor extracts cartridge files automatically during Unity builds. Cartridge objects are injected into the JavaScript context at startup -- __cart() is available immediately when your app runs.