Files

Sprites, sounds, fonts and covers

A cart can ship images, audio and fonts alongside its source. One function resolves a name to wherever those files ended up.

import { assetUrl, useTexture, useSound } from "oj"

const glow = useTexture("glow.png")   // in a component: a texture, or null while loading
const pop = useSound("pop.wav")       // a sound, or null while loading; pop?.play() on a tap

<Image src={assetUrl("logo.png")} />
assetUrl(name) The address of one of your files, as a string
loadTexture(name) Loads an image and resolves to a texture
useTexture(name) The hook form. null until it arrives
useSound(name) A sound, null until it arrives, unloaded with the component
audio.load(name) A Promise of a sound, for loading outside a component
loadSheet(name), useFlipbook(ref, name) A sprite sheet, and playing one on an element

Use the name as it appears in the sidebar

"glow.png" for a file at the top, "sprites/hero.png" for one in a folder. Never "assets/glow.png", and never an absolute path.

That is the whole rule, and it is what lets the same source run in two places that store files differently:

Where assetUrl("sprites/hero.png") resolves to
On play.onejs.com /assets/sprites/hero.png on the cart's own origin
In Unity ~/assets/, the same folders, copied there on every build

Folders are part of the name rather than something you create: putting a file at sprites/hero.png is what makes sprites exist, and it is gone when the last file leaves it.

A leading ./ is accepted and stripped, and so is a leading assets/. That is why assets is the one folder name your files may not use at the top level. Anything that already resolves, like a full URL, is handed back untouched, so passing a remote image through assetUrl is harmless.

loadTexture, useTexture, useSound and audio.load all take the bare name too.

What you can ship

Images (png, jpg), audio (ogg, wav, mp3), fonts (ttf, otf, woff, woff2) and 3D models (glb). A picture in another format, such as webp, is converted to one of those as you add it in the editor.

One file 100 MB
Files under 1 MB, all together 64 MB
Files of 1 MB or more, across all your carts 1 GB
How many 200

Files are stored apart from your source and served from the cart's own origin. A save re-uploads your code and leaves the art alone, which is what you want given art changes far less often than code.

A file of 1 MB or more is kept out of your cart's history: what the cart holds is a short note of the file's hash and size, and the file itself goes to the store once. The editor shows a bar on its row while it sends. From a terminal, npx ojplay init sets up the clone so git add and git push do the same, and plain git without it takes files up to 16 MB. Every version you have pushed stays available while the cart names it.

A file you add is uploaded straight away, so pressing Run loads it immediately, and deleting one takes it out of your preview straight away too. Like your code, it reaches what everybody plays with your next Push.

Loading takes a frame or two

useTexture returns null until the file arrives, so render a placeholder rather than assuming:

function Sparks() {
    const ref = useRef(null)
    const glow = useTexture("glow.png")

    useParticles(ref, {
        emitters: [{ rate: 40, texture: glow, glow: 1 }],
    }, [glow])

    return <View ref={ref} style={{ flexGrow: 1 }} />
}

useParticles reads its options once, when it mounts, so the [glow] at the end is what rebuilds it with the texture once that arrives. Without it the particles keep the plain dot they started with.

Textures are cached by URL, so a second component asking for the same file does not pay for the bytes again, and a component that unmounts mid-load does not cancel it.

Fonts

Text draws in your own font once you load it and name it with fontFamily. useFont returns the font, or null for the frame or two its file takes, when text draws in the default face:

import { View, Text, useFont } from "oj"

function Title() {
    const display = useFont("fonts/Display.ttf")
    return (
        <View style={{ fontFamily: display }}>
            <Text style={{ fontSize: 32 }}>Level 1</Text>
            <Text>Pack 12 crates by dusk</Text>
        </View>
    )
}

fontFamily is inherited, as on the web, so a font on a View reaches every Text inside it. A font's name is not a font: nothing is installed by name, so fontFamily: "Arial" draws in the default face and says so in the console. Text draws from ttf and otf files; a woff or woff2 ships, but text cannot draw with it.

loadFont is the same as a promise, for code outside a component. A font is built once per file however many ask, and a font in preload is ready on the cart's first frame.

Loading first

Files a cart needs from its first frame, like the music or the level it opens on, go in preload in oj.json. They load before the cart appears, behind a plain bar, so the first useTexture, useModel or useFont of them is instant:

{
    "name": "Storm",
    "preload": ["music/theme.ogg", "levels/1/"]
}

A name ending in / means every file in that folder. A name that matches no file is a warning when you push, and the cart starts anyway.

Later on, the same thing from code: preload loads files ahead of their first use, and says how far it has got.

import { preload } from "oj"

await preload(["levels/2/"], (got, total) => setProgress(got / total))

Letting go

unload frees files the cart no longer needs, so a long cart does not keep every level in memory. Pictures, models and fonts are released, and the next use loads them again:

import { unload } from "oj"

unload(["levels/1/"])

Unload what nothing shows any more: a picture still on screen goes blank, and a model with a copy still in the scene stays loaded until its last copy is gone. Sounds free themselves when their component goes, so they need nothing.

Covers

Your cart's card in the catalog is a picture. There are three ways to decide it, and the first is doing nothing.

You do The card shows
Nothing A graphic the site draws
Put cover.png or cover.jpg at the top of your cart That picture
Put pictures in .oj/covers/ The first one at rest, the rest as you hover it

Doing nothing is a supported choice, not a gap. Most carts want the second row.

If you have both, .oj/covers/ wins and the publish says your root picture was ignored.

The Cover button

Press Cover, on the bar above the preview, and whatever the preview is showing lands in your files as cover.png. That is the whole workflow: play your cart until it looks right, then press the button.

It never overwrites. A second press writes cover_1.png, a third cover_2.png. Only cover.png is the card, so the numbered ones are drafts sitting in your files: keep the one you like by renaming it over cover.png, and delete the rest.

The picture is the canvas at its current size, as a png, so it is as large as your preview pane. Crop or shrink it yourself if you want it smaller. It lands in your tree like any file you uploaded, goes out with your next Push, and counts against your storage.

A set to cycle on hover

Pictures for the hover preview go in .oj/covers/, and arranging them is yours to do. They are ordered by file name, so zero-pad them:

index.tsx
oj.json
.oj/
  covers/
    01.jpg
    02.jpg
    03.jpg

The first is what rests on the card and the rest cycle as a visitor hovers it.

How many 8
One picture 2 MB
All of them together 6 MB

Past those limits nothing is refused; the extra is ignored and the publish says so. Read what comes back after a push, because that note is the only sign a ninth picture did nothing.

A file in there that is not a png or jpg is ignored, and the publish says that too. A webp dropped in the covers folder shows nothing and changes nothing. They count against the same 64 MB your other files do.

Embedding

A published cart can go on another page. Paste its link on its own line on a site that supports oEmbed, or write the tag yourself with the cart's id:

<iframe src="https://play.onejs.com/c/abc123/embed" title="Tuner on OJPlay"
    width="960" height="540"
    style="width:100%;max-width:960px;aspect-ratio:960/540;height:auto;border:0;border-radius:6px"
    allow="fullscreen; gamepad; clipboard-write; web-share" loading="lazy"></iframe>

Three things about it are worth keeping:

  • The allow list is not decoration. A permission only reaches a cart if every frame on the way delegates it, so a tag without it gives the cart no fullscreen and no controller, and nothing reports why.
  • The size is carried twice on purpose. The attributes are what a page that strips inline styles keeps; the style is what a page that keeps it uses, shrinking the frame to its column while holding the stage's aspect.
  • An embed waits to be asked, because every reader who scrolled past would otherwise download the runtime. Add ?autoplay=1 when the cart is the point of the page.

The frame is 960 by 540 by default; to change it, change the width and height everywhere they appear in the tag.

In a Unity project

A clone keeps your files where they are. Every build copies them into ~/assets/, where OneJS looks, in the same folders. Same source, runs unchanged.

.oj/, your catalog art, stays out of the copy.

The name the sidebar shows is the one form that means the same thing on both sides.