Skip to main content

Assets

Assets are resources used by the scene, such as 3D models, textures, scripts, and audio files. All assets must be defined in the assets array before they can be used in instances.

Asset Structure​

All assets have this basic structure:

{
  "id": "unique-asset-id",
  "type": "asset-type",
  "uri": "https://example.com/resource.ext",
  "mediaType": "type/subtype"
}

Required Properties​

  • id (string): Unique identifier for the asset. Must be unique within the scene.
  • type (string): Asset type (see types below)
  • uri (string): URL to the asset file. Must be HTTPS.
  • mediaType (string): MIME type of the asset

Asset Types​

Model (type: "model")​

3D geometry files in OBJ format.

{
  "id": "my-model",
  "type": "model",
  "uri": "https://example.com/model.obj",
  "mediaType": "model/obj"
}

Supported formats: OBJ (.obj files) Media types: model/obj Materials: Use separate material assets (MTL files)

Material (type: "material")​

Material definitions in MTL format.

{
  "id": "my-material",
  "type": "material",
  "uri": "https://example.com/material.mtl",
  "mediaType": "model/mtl"
}

Supported formats: MTL (.mtl files) Media types: model/mtl Usage: Referenced by OBJ models

Texture (type: "texture")​

Image files used for textures.

{
  "id": "my-texture",
  "type": "texture",
  "uri": "https://example.com/texture.jpg",
  "mediaType": "image/jpeg"
}

Supported formats: PNG, JPG, JPEG, TGA Media types: image/png, image/jpeg, image/jpg, image/tga Usage: Referenced by materials or pictureboxes

Script (type: "script")​

Lua/Luau script files for interactive behaviors.

{
  "id": "my-script",
  "type": "script",
  "uri": "https://example.com/script.luau",
  "mediaType": "application/x-luau"
}

Supported formats: Luau (.luau files) Media types: application/x-luau Usage: Attached to instances via the script property

Font (type: "font")​

TrueType font files for text rendering.

{
  "id": "my-font",
  "type": "font",
  "uri": "https://example.com/font.ttf",
  "mediaType": "font/ttf",
  "font": {
    "size": 16,
    "style": "normal"
  }
}

Supported formats: TTF (.ttf files) Media types: font/ttf Font properties:

  • size (number, optional): Font size in pixels
  • style (string, optional): Font style - "normal", "bold", or "italic"

Audio (type: "audio")​

Audio files for sound effects and music.

{
  "id": "my-audio",
  "type": "audio",
  "uri": "https://example.com/sound.wav",
  "mediaType": "audio/wav",
  "audio": {
    "format": "wav",
    "ambient": false
  }
}

Supported formats: WAV (.wav files) Media types: audio/wav Audio properties:

  • format (string, required): Audio format - currently only "wav"
  • ambient (boolean, optional): Whether audio is ambient (constant volume)

Textbox (type: "textbox")​

Textbox asset definitions for displaying text.

{
  "id": "my-textbox",
  "type": "textbox",
  "uri": "data:text/plain,textbox",
  "mediaType": "application/json",
  "textbox": {
    "text": "Hello, World!",
    "title": "Welcome",
    "font": "my-font",
    "size": 1.0,
    "color": {"x": 1.0, "y": 1.0, "z": 1.0}
  }
}

Textbox properties:

  • text (string, required): Text content
  • title (string, optional): Title text
  • font (string, optional): Font asset ID
  • size (number, optional): Text size multiplier
  • color (vec3, optional): Text color (RGB, 0-1)

Picturebox (type: "picturebox")​

Picturebox asset definitions for displaying images.

{
  "id": "my-picturebox",
  "type": "picturebox",
  "uri": "data:text/plain,picturebox",
  "mediaType": "application/json",
  "picturebox": {
    "texture": "my-texture",
    "width": 2.0,
    "height": 2.0
  }
}

Picturebox properties:

  • texture (string, required): Texture asset ID
  • width (number, required): Width in world units (must be > 0)
  • height (number, required): Height in world units (must be > 0)

URI Formats​

Assets can use two URI formats:

HTTPS URLs​

Standard web URLs (required for most assets):

"uri": "https://example.com/model.obj"

Requirements:

  • Must use HTTPS (HTTP is not supported)
  • Must be publicly accessible
  • Should use proper file extensions

Data URIs​

Inline data for textbox and picturebox assets:

"uri": "data:text/plain,textbox"

Use case: Textbox and picturebox assets that don't need external files

Media Types Reference​

Asset TypeMedia Type
Model (OBJ)model/obj
Material (MTL)model/mtl
Texture (PNG)image/png
Texture (JPG)image/jpeg or image/jpg
Texture (TGA)image/tga
Script (Luau)application/x-luau
Font (TTF)font/ttf
Audio (WAV)audio/wav
Textboxapplication/json
Pictureboxapplication/json

Asset Colliders​

Model assets can optionally specify collider information:

{
  "id": "model-with-collider",
  "type": "model",
  "uri": "https://example.com/model.obj",
  "mediaType": "model/obj",
  "collider": {
    "type": "mesh"
  }
}

Collider types:

  • "mesh": Use the mesh geometry as collider
  • "box": Axis-aligned bounding box
  • "sphere": Bounding sphere

Asset Examples​

Complete Asset Set​

"assets": [
  {
    "id": "capsule-model",
    "type": "model",
    "uri": "https://example.com/capsule.obj",
    "mediaType": "model/obj"
  },
  {
    "id": "capsule-material",
    "type": "material",
    "uri": "https://example.com/capsule.mtl",
    "mediaType": "model/mtl"
  },
  {
    "id": "capsule-texture",
    "type": "texture",
    "uri": "https://example.com/capsule.jpg",
    "mediaType": "image/jpeg"
  },
  {
    "id": "pingpong-script",
    "type": "script",
    "uri": "https://example.com/pingpong.luau",
    "mediaType": "application/x-luau"
  },
  {
    "id": "test-audio",
    "type": "audio",
    "uri": "https://example.com/sound.wav",
    "mediaType": "audio/wav",
    "audio": {
      "format": "wav",
      "ambient": false
    }
  }
]

Best Practices​

  • Use descriptive IDs: Make asset IDs clear and meaningful
  • Organize assets: Group related assets together
  • Optimize files: Compress textures and models for faster loading
  • Use HTTPS: All URIs must be HTTPS
  • Validate media types: Ensure media types match file formats

Next Steps​