Asset Loading

Load images, fonts, and data files from your project or npm packages. The asset system automatically handles path resolution between Editor and Build modes.

Basic Usage

import { loadImage, loadFont, loadJson } from "onejs-unity/assets"

// Load user assets (from App/assets/)
const logo = loadImage("images/logo.png")
const font = loadFont("fonts/Inter.ttf")

// Load package assets (prefixed with @package-name/)
const bg = loadImage("@my-ui-kit/backgrounds/hero.png")
const config = loadJson("@my-ui-kit/config.json")

Available Functions

Function	Returns	Description
`loadImage(path)`	`Texture2D`	Load an image as a texture
`loadFont(path)`	`Font`	Load a font file
`loadFontDefinition(path)`	`FontDefinition`	Load font for UI Toolkit styling
`loadText(path)`	`string`	Load text file contents
`loadJson<T>(path)`	`T`	Load and parse JSON file
`loadBytes(path)`	`Uint8Array`	Load raw bytes
`assetExists(path)`	`boolean`	Check if asset exists
`getAssetPath(path)`	`string`	Get resolved full path

Project Assets

Place your assets in the App/assets/ folder:

App/
├── assets/
│   ├── images/
│   │   └── logo.png
│   ├── fonts/
│   │   └── Inter.ttf
│   └── data/
│       └── config.json
├── index.tsx
└── esbuild.config.mjs

Load them with simple paths:

const logo = loadImage("images/logo.png")
const config = loadJson("data/config.json")

Package Assets

npm packages can distribute assets that integrate seamlessly with your project.

Using Package Assets

import { loadImage } from "onejs-unity/assets"

// Package assets use @package-name/ prefix
const background = loadImage("@rainbow-ui/backgrounds/gradient.png")

Creating Asset Packages

Use the @namespace/ folder convention inside an assets/ folder:

rainbow-ui/
├── package.json
├── assets/
│   └── @rainbow-ui/           ← namespace prefix (required)
│       ├── backgrounds/
│       │   └── gradient.png
│       └── icons/
│           └── check.svg
└── src/
    └── index.js

The @namespace/ folder is automatically detected. No package.json configuration needed.

Path Resolution

The asset loader automatically resolves paths based on the runtime context:

Context	`@pkg/bg.png`	`images/logo.png`
Editor	`App/node_modules/.../assets/@pkg/bg.png`	`App/assets/images/logo.png`
Build	`StreamingAssets/onejs/assets/@pkg/bg.png`	`StreamingAssets/onejs/assets/images/logo.png`

Build Setup

Add copyAssetsPlugin to your esbuild config:

import { copyAssetsPlugin } from "onejs-unity/esbuild"

const config = {
    plugins: [
        copyAssetsPlugin({ verbose: true }),
    ],
}

The plugin generates .onejs/assets-manifest.json for Editor path resolution.

During Unity builds, the JSRunnerBuildProcessor automatically:

Copies App/assets/ to StreamingAssets/onejs/assets/
Copies npm package assets to StreamingAssets/onejs/assets/

This keeps StreamingAssets clean during development and avoids Unity's asset import overhead for files that don't need importing.

Using with UI Toolkit

Background Images

import { loadImage } from "onejs-unity/assets"

function ImageBackground() {
    const [texture, setTexture] = useState(null)

    useEffect(() => {
        const tex = loadImage("images/bg.png")
        setTexture(tex)
    }, [])

    return (
        <View style={{
            backgroundImage: texture,
            width: 200,
            height: 200
        }} />
    )
}

Custom Fonts

import { loadFontDefinition } from "onejs-unity/assets"

function StyledText() {
    const [fontDef, setFontDef] = useState(null)

    useEffect(() => {
        const def = loadFontDefinition("fonts/CustomFont.ttf")
        setFontDef(def)
    }, [])

    return (
        <Label style={{ unityFontDefinition: fontDef }}>
            Custom styled text
        </Label>
    )
}

Notes

All load functions are synchronous (they block until loaded)
Paths are case-sensitive on most platforms
Supported image formats: PNG, JPG, TGA, BMP
Supported font formats: TTF, OTF