scene.json Schema Reference

scene.json is the main configuration file generated by the exporter. It describes everything the runtime needs to set up and run the AR scene.

Current version: 0.3

---

Root structure

{
  "runtime_version": "0.3",
  "settings": {},
  "assets":   {},
  "objects":  [],
  "components": [],
  "events":   [],
  "hotspots": []
}

Field	Type	Description
runtime_version	string	Schema version. The runtime checks this on load.
settings	object	Scene-level runtime configuration.
assets	object	References to asset files in the output folder.
objects	array	One entry per exported Blender object.
components	array	Continuous per-frame behaviors from the node tree.
events	array	Triggered behaviors from the node tree.
hotspots	array	Interactive annotation points.

---

settings

"settings": {
  "ar_mode": "hit_test",
  "reference_size": 0.3,
  "background_color": [0.05, 0.05, 0.05],
  "shadow_plane": { "enabled": true, "opacity": 0.4 },
  "debug": { "enabled": false },
  "ui": { "show": true, "title": "My Product", "instructions": "Tap to place" },
  "interactions": { "tap": true, "gesture_rotate": true, "gesture_scale": true },
  "viewer": { "auto_rotate_speed": 0.0 }
}

Field	Type	Values	Description
ar_mode	string	hit_test / image_tracking / viewer	AR placement mode
reference_size	float	e.g. 0.3	Target bounding-box size in meters
background_color	float[3]	linear RGB	Scene background (Viewer mode only)
shadow_plane.enabled	bool	—	Render shadow-receiver plane
shadow_plane.opacity	float	0–1	Shadow plane transparency
debug.enabled	bool	—	Show debug stats overlay
ui.show	bool	—	Show title/instructions overlay
ui.title	string	—	Overlay title
ui.instructions	string	—	Overlay instructions
interactions.tap	bool	—	Enable tap events on objects
interactions.gesture_rotate	bool	—	Enable drag-to-rotate
interactions.gesture_scale	bool	—	Enable pinch-to-scale
viewer.auto_rotate_speed	float	0 = off	Auto-rotation speed

---

assets

"assets": {
  "model": "scene.glb",
  "marker_image": "textures/marker.jpg",
  "marker_width": 0.2,
  "animations": ["Idle", "Walk"]
}

Field	Type	Description
model	string	GLB or glTF filename
marker_image	string	Marker image path (Image Tracking only). Empty string if unused.
marker_width	float	Real-world marker width in meters
animations	string[]	Animation clip names embedded in the model

---

objects[]

One entry per exported Blender object. Names must match the node names in the GLB.

{
  "name": "Wheel",
  "type": "MESH",
  "behavior": "ANIMATED",
  "js_animation": { "type": "ROTATE_Y", "speed": 1.5 },
  "on_click": null,
  "metadata": ""
}

Field	Type	Description
name	string	Must match GLB node name exactly
type	string	MESH / ARMATURE / EMPTY / LIGHT
behavior	string	STATIC / ANIMATED / INTERACTIVE
js_animation	object | null	Continuous JS animation. null if not animated.
js_animation.type	string	NONE / ROTATE_Y / ROTATE_X / ROTATE_Z / FLOAT / PULSE / SPIN
js_animation.speed	float	Speed multiplier
on_click	string | null	JavaScript executed on tap. null if not interactive.
metadata	string	Free-form JSON string for external integrations

---

components[]

Continuous behaviors compiled from animation nodes (Pulse, Spin, JS Animation).

{ "object": "Wheel", "type": "pulse", "speed": 2.0, "amplitude": 0.1 }
{ "object": "Spinner", "type": "spin", "axis": [0, 1, 0], "speed": 3.0 }

Field	Type	Description
object	string	Target object name
type	string	pulse / spin / js_animation
speed	float	Speed multiplier
amplitude	float	Motion amplitude (pulse only)
axis	float[3]	Rotation axis unit vector (spin only)

---

events[]

Triggered behaviors compiled from event nodes (Tap, Update, Timer).

{
  "event": "tap",
  "target": "Button",
  "actions": [{ "type": "toggle_visibility" }]
}
{
  "event": "timer",
  "target": "Wheel",
  "interval": 3.0,
  "actions": [{ "type": "set_rotation", "value": 0.0 }]
}

Field	Type	Description
event	string	tap / update / timer
target	string	Target object name
interval	float	Seconds between triggers (timer only)
actions[].type	string	toggle_visibility / set_rotation / set_scale / play_animation
actions[].value	float | null	Numeric value for set_rotation / set_scale
actions[].name	string | null	Animation clip name for play_animation

---

hotspots[]

{
  "id": "MotorInfo",
  "position": [0.0, 0.35, 0.12],
  "title": "Main Motor",
  "description": "500W motor with liquid cooling.",
  "image": "textures/motor_detail.jpg",
  "audio": "",
  "url": "https://example.com/product",
  "icon": "info"
}

Field	Type	Description
id	string	Matches the Blender Empty object name
position	float[3]	World position in Three.js Y-up space ([x, y, z])
title	string	Popup title
description	string	Popup body text
image	string	Image filename (relative to scene.json). Empty if unused.
audio	string	Audio filename. Empty if unused.
url	string	External URL. Empty if unused.
icon	string	info / star / camera / location

Coordinate space

Blender Z-up (X, Y, Z) is converted to Three.js Y-up (X, Z, −Y) automatically at export time.

---

Schema changelog

Version	Changes
0.1	Initial flat schema
0.2	Added node tree objects, components, events
0.3	Consolidated into settings + assets. Full snake_case. Complete objects metadata.