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; files extract to disk as soon as it is assigned (and automatically on first run and during builds)

Files are extracted to @cartridges/{slug}/ inside your working directory, along with a .d.ts file for autocomplete. Automatic extraction never overwrites an existing folder; after changing a cartridge, use the tab's delete and extract buttons to refresh it. Give the cartridge a Version (e.g. 1.0.0) and bump it whenever its files change: the tab then flags stale extractions as Outdated, and a console warning points at them on the next run.

Accessing Files#

Cartridge files are regular source files that esbuild can import. Import them by relative path (there is no package alias, so the path is relative to the importing file):

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}/.

Premade Cartridges#

You can consume a cartridge someone else made the same way: add the asset to the Cartridges tab and import from the extracted folder. The Asset Store version of OneJS ships six under the singtaa namespace: three onejs-ui themes and three sample apps. Themes register in one line via onejs:themes; a sample exports components:

import "onejs:themes"  // registers every extracted cartridge theme
import { Inventory } from "./@cartridges/@singtaa/inventory/inventory"

onejs:themes (the themesPlugin() from onejs-unity/esbuild, in scaffolded configs since onejs-unity 0.2.19) picks up any extracted module named *Theme.ts, so name your module that way if you author a theme cartridge and want it auto-registered. See Premade Themes for the full walkthrough.

Builds#

The build processor extracts cartridge files automatically during Unity builds, overwriting the extracted folders with the cartridge's current content. Treat extracted files as generated output: keep your own edits in your own source files. Cartridge objects are injected into the JavaScript context at startup, so __cart() is available immediately when your app runs.