Skip to content

Assets ​

How tiles are packaged and distributed to users ​

  • A tile is downloaded and cached on the user's device as a single .tar bundle: its code and every asset it needs to run.
  • One request fetches everything, unlike a traditional web app that makes many network requests. Once the bundle is on the device, the tile runs with no further waits, offline included.
  • Some large assets, such as audio and video, can be left out of the bundle and downloaded lazily the first time the tile asks for them (deferred files).
  • The Joiner Vite plugin (poeTile()) does this packaging: it builds the bundle into dist/, and poe-tiles publish moves deferred files out of it. For bundle size limits, see cli-limitations.md.

Creating assets ​

  • Use real assets, not emoji. For icons, glyphs and decorative art, ship SVGs or generated images. Emoji render inconsistently across devices and make a tile look cheap. Emoji that users write (chat, reactions) are content and are fine.
  • Use the image-generation skill to generate sprites, backgrounds and other images.
  • Use the audio-generation skill to generate music and sound effects.
  • Bundle every asset; never hot-link a remote URL. Tiles start offline and render before the network is up, and the tile frame's Content Security Policy blocks images, scripts and fetches from other hosts (see sandbox-limitations.md). Remote URLs are only for platform-served content, such as a member's profile picture or a store.files.url(...) upload.

Loading an asset in your tile ​

Paths start at the bundle root. In a scaffolded tile the Vite root is tile/, so a file at tile/public/assets/hero/image.png ships as dist/assets/hero/image.png and loads as /assets/hero/image.png. The generation skills save files to <tileDir>/assets/, outside the Vite root. Generated images stay there and load with ?url imports, as the image-generation skill describes; copy each other file the tile loads with loadAsset, such as generated audio, into tile/public/ so it ships. For the whole layout, see scaffolded-tile-folder-structure.md.

  • Assets in the bundle: Poe.bundle.loadAsset("/assets/hero/image.png"). These load even when the device is offline. Poe.bundle needs SDK 67, and the plugin raises the tile's minimum for it only when the tile has deferred files, so set poeTile({ minSdkVersion: 67 }) in vite.config.ts. Players do not need to update their app (see Minimum SDK Version).
  • Large, lazily loaded files: put them in tile/public/deferred/ and load them with Poe.bundle.loadAsset("/deferred/intro.mp4"). See Deferred files.
  • Small files the first screen needs synchronously:import logoUrl from "./logo.svg?url" base64-encodes the file into the tile's code as a data: URL, which the CSP allows for images, CSS, fonts, audio, video and fetch(). Keep it to small files: every inlined byte is base64 in the tile's code, so load music and video with loadAsset instead. Raise build.assetsInlineLimit in vite.config.ts (for example to 10 * 1024 * 1024), or the import is a plain path that nothing serves.
typescript
const { url } = await Poe.bundle.loadAsset("/assets/hero/image.png");
img.src = url;

loadAsset resolves { url, contentType, size, source }, where url is a blob: URL that works for images, media and fetch(). For the call signatures, options and errors, see client-api.md.

A dynamic import("./module") of code is also loaded from the bundle; the Vite plugin handles it, and lazy CSS loads with its chunk (see Code Splitting).

Deferred files ​

When to defer. Keep all code and small assets in the bundle: sprites, icons, UI art, fonts and level data. Defer only big media (music, videos, large images) that the game does not need in order to play, or that players reach only deep into the game. A deferred file waits on the network the first time the tile uses it, and is unavailable offline until it is cached.

Put deferred files in tile/public/deferred/. The build copies them to dist/deferred/ unchanged, and poe-tiles publish uploads each file on its own instead of in the .tar. A loaded file is cached on the device by default; pass cache: false for a file the tile plays only once.

typescript
const { url } = await Poe.bundle.loadAsset("/deferred/intro.mp4");
await Poe.bundle.loadAsset("/deferred/credits.mp4", { cache: false });

// The Vite plugin compiles a dynamic import of a deferred file to loadAsset:
const { url: theme } = await import("/deferred/music/theme.mp3");
  • Only through loadAsset or import(). A static import, an eager import.meta.glob, or a reference from HTML or CSS (<img src="/deferred/a.png">, url(/deferred/a.png)) fails the build. Add "poe-tiles-sdk/vite-client" next to "vite/client" in tsconfig compilerOptions.types to type the imports.

  • Handle failures. Offline before the first load, the call rejects; call it again to retry. Do not reload the page from a vite:preloadError listener.

  • Minimum app version. Any deferred file raises the tile's minimum SDK runtime to 67; players do not need to update their app (see Minimum SDK Version). A tile without Vite declares it in .poe-tile-runtime.json at the bundle root: { "minKernelVersion": 67 }.

  • Deferred code. A big screen most players never open (an editor, an admin page, a rarely used tool) can be deferred too: add ?deferred to its dynamic import. The module becomes its own chunk under dist/deferred/ and loads on first use like any deferred file. Cast the import to keep its type, and never import the module statically, which fails the build:

    typescript
    const Editor = lazy(
      () => import("./editor?deferred") as Promise<typeof import("./editor")>,
    );
  • Limits. One deferred file may be up to 50 MiB, and a tile may defer up to 1,000 files and 250 MiB in all, on top of its 100 MiB bundle. A file near 50 MiB briefly needs several times its size in memory, so split very large content when phones are the target.