# Files

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

```tsx
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](/docs/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](/docs/3d) (`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:

```tsx
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:

```tsx
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:

```json
{
    "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.

```tsx
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:

```tsx
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:

```html
<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.
