Assets and Media

This page is the short, practical guide to what content formats AuraJS expects today.

If you only remember one rule, remember this:

use explicit, known-good formats
load them through the committed runtime APIs
do not assume codec or browser parity that the engine does not explicitly promise

Asset and media truth table

Kind	Preferred path	Use this API	Supported now	Avoid or treat as unsupported	Notes
Images and sprites	`.png` first	`aura.assets.load(...)` -> `aura.draw2d.sprite(...)` or 3D texture/material use	`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`	`.bmp`, `.tga`, `.tiff`	Use `png` for UI, sprites, and authored game art unless you have a reason not to.
Audio	`.wav` for safest startup path, compressed formats after that	`aura.assets.load(...)` then `aura.audio.play(...)`	`.wav`, `.ogg`, `.flac`, `.mp3`	`.aac`, `.m4a`, `.wma`	Critical title or boot audio should use a known-good tested asset.
Dynamic fonts	`.ttf` first	`aura.assets.loadFont(...)` and pass the returned handle to `aura.draw2d.text(...)`	`.ttf`, `.otf`, `.woff2`	`.woff`	`loadFont(...)` returns a reason-coded result payload instead of throwing.
Bitmap fallback font	built-in runtime bitmap font	`aura.assets.loadBitmapFont(...)`	runtime `8x8` bitmap font	custom non-`8x8` bitmap assumptions	Use this when you want a guaranteed fallback instead of shipping a TTF.
JSON and text	`.json`, `.txt`, dialogue/config files	`aura.assets.loadJson(...)` or `aura.assets.loadText(...)`	`.json`, text files, binary bytes through `load(...)`	malformed JSON or invalid UTF-8	Keep gameplay data explicit and machine-readable.
Raw bytes and data blobs	`.bin`, `.dat`, `.raw`	`aura.assets.load(...)`	supported	vague custom formats without your own parser	Good for authored runtime blobs and generated data.
3D models	`.glb` first, `.gltf` when external files are intentional	`aura.scene3d.loadGltfScene(...)` or `aura.assets.load(...)` for raw bytes	`.gltf`, `.glb`	other model formats without a conversion step	Use `glb` when you want a simpler single-file asset story.
Video-like playback	native `.mp4` on desktop, frame sequence or sprite sheet as portable fallback	`aura.video.load(...)`	native `.mp4`, frame directories, sprite sheets	`.webm`, `.mov`, `.mkv`, `.avi`, or any browser `.mp4` assumption	Current `aura.video` is a visual playback surface. Native `.mp4` is supported on desktop hosts only.
Media presentation audio	separate audio asset, coordinated by the native media-presentation helper or your own game logic	`@auraindustry/aurajs/cutscene` plus `aura.audio.*`	native desktop separate-audio orchestration	engine-level synchronized muxed video audio	The current authored path is native-only and still keeps synced muxed A/V out of scope.

The safest loading recipes

Use these patterns by default:

Images

const player = aura.assets.load('player.png');

Audio

aura.assets.load('music/title.wav');
const music = aura.audio.play('music/title.wav', { loop: true, bus: 'music' });

Dynamic fonts

const fontResult = aura.assets.loadFont('ui/PressStart2P-Regular.ttf');
if (fontResult.ok) {
  ui.font = fontResult.font;
}

JSON data

const waves = aura.assets.loadJson('waves.json');

Imported 3D scene

const imported = aura.scene3d.loadGltfScene('scene.glb');

Native desktop MP4

const handle = aura.video.load('cutscenes/intro.mp4', {
  type: 'mp4',
  looping: true,
});

Native .mp4 decode is handled in-process via the embedded video codec library. No external tools are required for video playback.

Frame-based video fallback

const handle = aura.video.load('cutscenes/intro-sheet.png', {
  type: 'spritesheet',
  columns: 4,
  rows: 2,
  frameCount: 8,
  fps: 12,
});

Use `getFormatSupport` when you are unsure

If you are writing tools, validating content, or choosing between formats, ask the runtime first:

const support = aura.assets.getFormatSupport('music/title.mp3');

That gives you a deterministic support payload without trying to read the file.

Validate a project asset folder

AuraJS now ships a repo validator for asset/media extensions:

node ./scripts/check-asset-media.mjs --root /path/to/your-game

It scans <root>/assets by default, reports unsupported or suspicious files with reason codes, and is especially useful for catching:

unsupported audio extensions like .m4a
unsupported video containers like .webm
empty placeholder assets
unknown extensions that should be converted or explicitly validated

Operational guidance

These are the practical choices that reduce surprises:

use png for 2D artwork
use wav for must-work startup audio
use ttf for shipped UI fonts
use glb for simplest 3D authored content import
use native .mp4 on desktop when you want the shortest cutscene path
use createMediaPresentationController(...) when you want one authored native screen-plus-audio path
use frame sequences or sprite sheets when you need the portable fallback

What this page does not promise

This page does not promise:

full browser parity with native
browser .mp4 playback parity
synchronized video audio from the engine
arbitrary authoring formats without a conversion step

For exact signatures and validation behavior, use:

AURA

JSGG