Scene document components

Every component id a scene document can hold, with each field's type and default. A test fails when a registered component or field has no row here.

A component is one entry of a node's components array, named by its component key. For the file around it, see Scene document schema. Types use the value types of the schema page.

All components

A component loads only once its module is registered. "Registered by" names the call that registers it.

Component id	ECS component	Module	Registered by	Guide
ambient_light	AmbientLight	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Lights and shadows
audio_source	AudioSource	com.awakekt.awake.scene:audio	registerAudio()	—
behavior_tree	BehaviorTreeAsset	com.awakekt.awake.scene:ai	registerAiBehaviors()	AI
blueprint	BlueprintComponent	com.awakekt.awake.scene:blueprint	registerBlueprints()	—
camera	Camera	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Cameras
camera_rig	CameraRig	com.awakekt.awake.scene:controls	registerControls()	Cameras
canvas_appearance	CanvasAppearance	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_bar	CanvasBarWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_bind	CanvasBinding	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_button	CanvasButtonWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_cluster	CanvasCluster	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_controls	CanvasControls	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_element	CanvasElement	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_follow	CanvasFollow	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_follow_arrow	CanvasFollowArrow	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_follow_limit	CanvasFollowLimit	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_follow_occlusion	CanvasFollowOcclusion	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_image	CanvasImageWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_input	CanvasInput	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_joystick	CanvasJoystickWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_layout	CanvasLayout	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_look_area	CanvasLookAreaWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_particles	CanvasParticles	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_rect	CanvasRect	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_scaler	CanvasScaler	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_stepper	CanvasStepperWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_sweep	CanvasSweepWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_text	CanvasText	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_text_field	CanvasTextFieldWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_tooltip	CanvasTooltip	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
canvas_view	CanvasViewWidget	com.awakekt.awake.scene:canvas	DefaultSceneComponentResolvers.install()	Game UI
character_controller	CharacterController	com.awakekt.awake.scene:character	registerCharacter()	Character controller
chase	ChaseBehavior	com.awakekt.awake.scene:ai	registerAiBehaviors()	AI
custom	—	com.awakekt.awake.scene:document	Built in	Scene documents
day_cycle	DayCycle	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Sky and fog
factions	Factions	com.awakekt.awake.scene:ai	registerAiBehaviors()	AI
flee	FleeBehavior	com.awakekt.awake.scene:ai	registerAiBehaviors()	AI
fog	Fog	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Sky and fog
input_actions	InputActions	com.awakekt.awake.scene:controls	registerControls()	Cameras and controls
keyframe_animation	KeyframeAnimation	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Animation
light	Light	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Lights and shadows
locomotion_animation	LocomotionAnimation	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Animation
mesh_renderer	MeshRenderer	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Meshes and materials
movement_control	MovementControl	com.awakekt.awake.scene:controls	registerControls()	Character controller
navigation	NavigationGrid	com.awakekt.awake.scene:navigation	registerAiBehaviors()	AI
navigation_agent	NavigationAgent	com.awakekt.awake.scene:navigation	registerAiBehaviors()	Navigation
particle_emitter	ParticleEmitterSource	com.awakekt.awake.scene:particles	DefaultSceneComponentResolvers.install()	Particles
particle_emitter_2d	ParticleEmitter2D	com.awakekt.awake.scene:scene2d	DefaultSceneComponentResolvers.install()	Particles
patrol	PatrolBehavior	com.awakekt.awake.scene:ai	registerAiBehaviors()	AI
pbr_material	PbrMaterial	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Meshes and materials
perceivable	Perceivable	com.awakekt.awake.scene:ai	registerAiBehaviors()	AI
perceiver	Perceiver	com.awakekt.awake.scene:ai	registerAiBehaviors()	AI
physics_body	PhysicsBody	com.awakekt.awake.scene:physics	registerPhysics()	Physics
post_processing	PostProcessing	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Lights and shadows
prefab_link	PrefabLink	com.awakekt.awake.scene:document	Built in	Scene documents
shader_effect	ShaderEffectSource	com.awakekt.awake.scene:shader	DefaultSceneComponentResolvers.install()	Render plans and shaders
skybox	Skybox	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Sky and fog
spin_control	SpinControl	com.awakekt.awake.scene:scene-core	DefaultSceneComponentResolvers.install()	Scene documents
sprite	Sprite	com.awakekt.awake.scene:scene2d	DefaultSceneComponentResolvers.install()	Component map
sprite_clips	SpriteClips	com.awakekt.awake.scene:scene2d	DefaultSceneComponentResolvers.install()	Component map
state_machine	StateMachineAsset	com.awakekt.awake.scene:ai	registerAiBehaviors()	AI
static_transform	StaticTransform	com.awakekt.awake.scene:scene-core	DefaultSceneComponentResolvers.install()	Scene documents
tag	Tags	com.awakekt.awake.scene:scene-core	DefaultSceneComponentResolvers.install()	Scene documents
terrain	TerrainComponent	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Terrain
texture_animation	TextureAnimation	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Meshes and materials
texture_clips	TextureClips	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Meshes and materials
tilemap	Tilemap	com.awakekt.awake.scene:scene2d	DefaultSceneComponentResolvers.install()	Component map
tone_mapping	ToneMapping	com.awakekt.awake.scene:scene3d	DefaultSceneComponentResolvers.install()	Lights and shadows
trail_renderer	TrailRenderer	com.awakekt.awake.scene:trail	DefaultSceneComponentResolvers.install()	Trails
world_text	WorldText	com.awakekt.awake.scene:worldtext	DefaultSceneComponentResolvers.install()	Game UI

Registration

Call	Module	Registers
Built in	com.awakekt.awake.scene:document	custom, prefab_link
DefaultSceneComponentResolvers.install()	com.awakekt.awake.scene:runtime	ambient_light, camera, canvas_appearance, canvas_bar, canvas_bind, canvas_button, canvas_cluster, canvas_controls, canvas_element, canvas_follow, canvas_follow_arrow, canvas_follow_limit, canvas_follow_occlusion, canvas_image, canvas_input, canvas_joystick, canvas_layout, canvas_look_area, canvas_particles, canvas_rect, canvas_scaler, canvas_stepper, canvas_sweep, canvas_text, canvas_text_field, canvas_tooltip, canvas_view, day_cycle, fog, keyframe_animation, light, locomotion_animation, mesh_renderer, particle_emitter, particle_emitter_2d, pbr_material, shader_effect, skybox, spin_control, sprite, sprite_clips, static_transform, tag, terrain, texture_animation, texture_clips, tilemap, tone_mapping, trail_renderer, world_text. SceneManager and SceneAppLifecycleRuntime call it for you.
SceneComponentRegistry.registerControls()	com.awakekt.awake.scene:controls	movement_control, camera_rig, input_actions
SceneComponentRegistry.registerPhysics()	com.awakekt.awake.scene:physics	physics_body
SceneComponentRegistry.registerCharacter()	com.awakekt.awake.scene:character	character_controller
SceneComponentRegistry.registerAiBehaviors()	com.awakekt.awake.scene:ai	patrol, chase, flee, navigation, navigation_agent, behavior_tree, state_machine, factions, perceivable, perceiver
SceneComponentRegistry.registerBlueprints()	com.awakekt.awake.scene:blueprint	blueprint
SceneComponentRegistry.registerAudio()	com.awakekt.awake.scene:audio	audio_source
loadProject(...)	com.awakekt.awake.project:runtime	The defaults, plus movement_control, camera_rig, input_actions, physics_body, character_controller, patrol, chase, flee, navigation, navigation_agent, audio_source, and the components of the capabilities passed to it

ambient_light

Uniform light added to every surface. SceneAmbientLight.

Field	Type	Default	What it does
intensity	number	0.2	Brightness of the ambient term.
color	color	white	Ambient color.
colorR	number	none	Legacy red channel. When colorR, colorG and colorB are all set, they replace color.
colorG	number	none	Legacy green channel.
colorB	number	none	Legacy blue channel.

audio_source

A sound this node plays: a clip from the project's files, placed at the node for a 3D sound. loadProject reads each clip once, as a 16-bit PCM WAV file; a clip that can't be read or decoded is logged with the node, and that source stays silent while the scene plays on. During play a 3D sound fades with distance from the active camera and pans with its direction. SceneAudioSource.

Field	Type	Default	What it does
clip	string	"unassigned"	Project path of the clip's WAV file. "unassigned" is a source with no clip picked yet; nothing is read for it.
volume	number	1	Loudness, 0 for silent, 1 as recorded. Not negative.
isSpatial3D	boolean	true	Whether it fades with distance and pans with direction.
maxDistance	number	50	The distance a 3D sound fades out at. Above 0.
autoPlay	boolean	false	Whether it starts as soon as the scene plays.
loop	boolean	false	Whether it starts again when it ends.

behavior_tree

Runs the behaviour tree in a definition file. SceneBehaviorTree. A played project reads and checks the file when it loads, and gives the entity a BehaviorTreeComponent built from it.

Field	Type	Default	What it does
asset	string	required	Path of the definition, a BehaviorTreeDefinition as JSON. Must not be blank.
seed	integer or none	none	Seeds the tree's random nodes. None gives each entity its own.
enabled	boolean	true	Whether the tree runs.

blueprint

Runs a blueprint graph on the entity. SceneBlueprint.

Field	Type	Default	What it does
graph	string	required	Path of the graph. Must not be blank.
variables	object of string, number or boolean	{}	Starting values for the graph's variables, by name.

camera

A camera lens. At most one per node. SceneCamera.

Field	Type	Default	What it does
eye	vector	{x: 0, y: 0, z: 5}	World-space eye position.
center	vector	{x: 0, y: 0, z: 0}	World-space point the camera looks at.
up	vector	{x: 0, y: 1, z: 0}	Up direction.
fovYDegrees	number	60	Vertical field of view in degrees. Between 0 and 180, exclusive.
near	number	0.1	Near clipping distance. Above 0.
far	number	100	Far clipping distance. Above near.
primary	boolean	true	Whether this camera renders the main view.
projection	perspective · orthographic	perspective	orthographic keeps things the same size at any distance, as a 2D game wants, and ignores fovYDegrees.
orthoHalfHeight	number	about 2.07	Half the vertical world extent an orthographic view covers; the width follows from the aspect ratio. Above 0. Used only when projection is orthographic.
viewport	object	none	Optional orthographic virtual viewport: positive finite width and height in world units, and scaling (fit, extend, fill, stretch, screen; default fit). Replaces orthoHalfHeight for rendering. Fit centers bars; Extend reveals more world; Fill crops; Stretch scales each axis; Screen uses one world unit per physical framebuffer pixel. Omit for the existing camera framing.

camera_rig

How a camera follows or orbits. SceneCameraRig.

Field	Type	Default	What it does
mode	FirstPerson · ThirdPerson · FreeFly · Cinematic · TopDown	ThirdPerson	Camera behavior.
target	string	none	Name of the node to follow.
distance	number	5	Distance from the target.
minDistance	number	2	Closest zoom.
maxDistance	number	20	Farthest zoom.
pitch	number	0	Pitch in radians. Negative looks down.
yaw	number	0	Yaw in radians.
offset	vector	{x: 0, y: 1.8, z: 0}	Aim point relative to the target, or the pivot when there is none.
flySpeed	number	10	Speed in FreeFly mode. Above 0.
collision	object	none	ThirdPerson camera collision; see below. Without it the eye goes wherever the rig puts it.
occluderFade	object	none	Fades what stands between a ThirdPerson eye and its target; see below. Without it nothing fades.

collision keeps a third-person eye above the ground and in front of the terrain. Props, trees and buildings don't pull it in unless their physics layer is listed in obstacleLayers. A played project answers the ground from its terrain and paged_terrain heights, and the obstacle layers from its physics world.

Field	Type	Default	What it does
ground	boolean	true	Keep the eye groundMargin above the ground, sampled around it the size of the near plane.
terrain	boolean	true	Pull the eye in front of the ground where it rises between the pivot and the eye.
groundMargin	number	0.3	Least height of the eye above the ground. At least 0.
radius	number	0.2	Clearance kept between the line from the pivot to the eye and what blocks it. At least 0.
easeOutSeconds	number	0.25	Half-life of the ease back out once the way clears. Pulling in is immediate. At least 0.
obstacleLayers	list of integers	[]	Physics layers whose bodies also pull the eye in, through a swept sphere. Not negative.

occluderFade fades the static bodies between a third-person eye and its target: each frame a played project with a physics world casts rays from the eye to the target's feet, chest and head, and every body hit other than terrain fades. Its meshes take a dither fade: the shader discards a share of their pixels in a fixed pattern, so they stay opaque, need no sorting and keep their shadow.

Field	Type	Default	What it does
opacity	number	0.35	Opacity an occluder fades to, 0 to 1.
fadeSeconds	number	0.2	Half-life of the fade, both ways. At least 0.

canvas_controls

What every on-screen control on the scene's canvas shares. A scene has one, on any node; without one, touch controls show as the host says. SceneCanvasControls, saved from the live CanvasControls.

Field	Type	Default	What it does
touchVisibility	Host · Auto · Always · Never	Host	When touchOnly elements show. Host as the host says; Auto once a finger touches the screen, and hidden once a controller, a key or the mouse is used, switching live, as the host says until any is used; Always; Never. A control hidden mid-press lets go of its pointer.
theme	object	none	How every control looks, slot by slot. preset (MinimalFlat · Glass · Textured · None) is the built-in look it starts from; colors and images are tokens, by name, a slot writes as @name in a colour or an image path, over the preset's own; transitionSeconds sets the default interpolation duration for element style states (hovered, pressed, disabled) that leave their own unset; skin sets slots over the preset's: joystick (base, knob, sprintRing, arrows), button (background, icon, label, cooldown, charges, aimCursor, aimRange, cancelZone) and look (feedback). A slot is a style (as canvas_element.style), a size, circle, frames (images, fps, loop), custom (a composable the host registered by that name), hidden, transitionSeconds, and states by Idle · Pressed · Held · Disabled · CoolingDown · Ready · Aiming · Cancelling, each changing its style, scale, alpha, frames or hidden. A token neither the theme nor its preset has is reported. None draws each control plainly from its own colours. See Game UI.
playerLayout	object	{}	The layout the scene starts with, before a player's saved one replaces it: every touch control's scale (1) and opacity (1), and controls, each control's own offsetX, offsetY (dp, right and down), scale and opacity by its controlId.
minTouchSize	number	44	The smallest a stick, action button or look area is to a thumb, in dp: one drawn smaller takes a touch up to this size around its centre. 0 takes touches only on what is drawn. Not negative.

canvas_element

The older, single form of a canvas element, read so scenes and prefabs saved before the split load unchanged: it loads as the canvas components below, canvas_rect and the rest, that draw it the same way, and a scene saves those, never this. A field its kind never used, such as a Panel's text, is dropped. Sizes and offsets are in dp. SceneCanvasElement.

Field	Type	Default	What it does
kind	Text · Panel · Bar · Button · TextField · Joystick · Image · View · LookArea · Sweep · Stepper	Text	What the element is. A View shows what a camera sees; a LookArea is a region where a swipe looks and a pinch zooms; a Sweep fills its value of a turn; a Stepper holds a number between minus and plus buttons.
anchor	TopLeft · TopCenter · TopRight · CenterLeft · Center · CenterRight · BottomLeft · BottomCenter · BottomRight	TopLeft	Screen point the element is placed from.
offsetX	number	16	Horizontal offset from the anchor: inward from a left or right edge, never past it, and right of centre on a centred axis, or left when negative.
offsetY	number	16	Vertical offset from the anchor: inward from a top or bottom edge, never past it, and below centre on a centred axis, or above when negative.
width	number	200	Width. Not negative.
height	number	40	Height. Not negative.
text	string	""	A Text element's content, a Button's label, or what is typed into a TextField: typing writes it, and a system writing it replaces the field's content, caret at the end. In a Text element with links true, a [[key|shown words]] span draws "shown words" in style's linkColor and reports key once through consumeLink() when clicked; [[ is reserved and has no escape. Plain text with no span draws unchanged.
textKey	string	""	A Text's or Button's words by key, from the project's strings/<locale>.json tables, in the active locale; they change when it does. Empty shows text. A key no table has shows as the key and is logged once. Set on another kind, or with text or bind.text, it is reported. See Localization.
textArgs	object	{}	Values for textKey's placeholders, by name, such as { "count": "3" }. A bind's textArgs reads one from a field instead. Set without textKey, it is reported.
fontSize	number	18	Text size. Above 0.
color	string	"#FFFFFF"	Foreground color, #RRGGBB or #RRGGBBAA.
background	string	"#00000000"	Background color, #RRGGBB or #RRGGBBAA.
value	number	1	A Bar's fill, from 0 to 1.
order	integer	0	Draw order. Lowest draws first.
visible	boolean	true	Whether the element is drawn.
action	string	""	Name of what the element does for the game, such as jump. The game decides what each name means. In a played project, an element naming one of the scene's input actions adds to it, and its presses are used up: a Joystick steers an axis such as move, and a Button holds and presses a button such as jump or run. Any other name is left for the game to read.
doubleAction	string	""	What a Button does when double-clicked: two presses within half a second. The second press also fires action. Like action, a name among the scene's input actions is pressed, and any other is left for the game to read with consumeDoublePress().
touchOnly	boolean	false	Draw only where touch controls are shown.
safeArea	boolean	true	Keep an anchored element on the canvas itself inside the screen's safe area, clear of a notch, rounded corners, a home indicator or overscan: its anchor and offsets are measured from the safe area's edges and centre. false measures them from the screen's own edges, for a backdrop that reaches under a notch. An element inside another, or one that follows a node, is placed the same either way.
style	object	{}	How the element looks beyond its colours, as an AwakeKt Compose Style: background, gradient (start, middle, end, horizontal), image, fillImage, fillImageMode, cornerRadius, borderWidth, borderColor, shadow (color, offsetX, offsetY, blur, spread), textColor, textShadow (color, offsetX, offsetY, blur), textOutline (color, width), alpha, rotation, linkColor, transitionSeconds, backdrop (blur, tint, saturation, fallback: frosted glass over what is drawn beneath the element, the 3D scene included, or fallback where blur does not run), and hovered, pressed and disabled states (each overriding fill, gradient, image, border and text colour, shadow, draw-only centre scale, and alpha). image is an Image's picture, a frame, or a Bar's track; fillImage is a Bar's fill, cut at value or, with fillImageMode Squeeze, drawn at the filled width with both end caps kept, or with fillImageMode Sweep, revealed clockwise from 12 o'clock over the Bar's whole box, like a cooldown overlay -- fillImage is optional there, and the colour fill sweeps on its own. Each image is a CanvasImage: path, a region (regionX, regionY, regionWidth, regionHeight), slice insets (sliceLeft, sliceTop, sliceRight, sliceBottom), repeatEdges, repeatCenter, tint and pixelated. rotation turns the element's image, background and content, children included, clockwise about its own centre in degrees; hit-testing still uses the unrotated box. linkColor colours a Text's [[key&#124;shown words]] spans; unset draws them in a default blue. See Game UI.
textAlign	TopLeft · TopCenter · TopRight · CenterLeft · Center · CenterRight · BottomLeft · BottomCenter · BottomRight	none	Where a Text's or Button's text sits in the element. None keeps the kind's own: top-left for a Text, centred for a Button.
follow	string	""	The name of a node the element follows on screen. Its anchor point stands on the node's projected position, nudged inward by its offsets, and it hides when the node is behind the camera or missing.
followOffset	vector	{x: 0, y: 0, z: 0}	World-space offset from the followed node, such as above its head.
followBounds	boolean	false	Cover the screen rectangle of the followed node's meshes instead of standing at its point. Its children anchor to that box's edges.
followRules	object	none	How a follower behaves with many on screen. cullOffScreen (true) leaves it out while its box is wholly off the screen; maxDistance (0, none) hides it farther than that from the camera, in world units; occlusion (false) hides it while a physics body other than the followed node's own stands between the camera and the point, within the budget of the scene's canvas_follow_occlusion. group ("") is the canvas_follow_limit it counts against, and priority (0) ranks it there. scale and fade are curves of its size and opacity by distance: points of at (a distance) and value, straight between them and held past the ends; it is left out when faded or scaled to nothing. pinToEdge (false) holds it to the screen's edge, edgeMargin dp in, on the side its target lies while that is off screen or behind the camera, instead of hiding it. None culls it off screen and hides it behind the camera. Set on an element that follows nothing, it is reported. See Game UI.
followArrow	boolean	false	Inside a follower, this element is the arrow of one pinned to the edge: drawn only while its parent is pinned, centred on its parent's edge toward the target and turned to point there, its picture pointing right before it turns; its style.rotation adds to the turn. Set on an element that follows a node itself, it is reported.
followOutset	number	0	With followBounds, how far the box reaches past the node's rectangle on each side, in dp, so corner children sit outside the node. Negative pulls it in, never below nothing.
layout	object	none	Lay the element's children out in rows or columns instead of anchoring each: direction (Row · RowReverse · Column · ColumnReverse), wrap, gap, padding, justify (Start · Center · End · SpaceBetween · SpaceAround · SpaceEvenly) and align (Start · Center · End · Stretch). A laid-out child keeps its width and height and ignores its anchor and offsets. See Game UI.
grow	number	0	In a parent with a layout, this element's share of its line's leftover space. Not negative.
bind	object	none	Game state the element shows without code. node names a node; value is a component.field for a Bar's fill, divided by max (a field or a number); text fills each {component.field}, or {component.field:n0} with a number format, in a Text's or Button's words. textArgs maps a textKey's argument names to component.fields, read each frame. For an action button, cooldown (divided by cooldownMax, a field or a number), charges and enabled read its live cooldown, uses left and whether it can be pressed. See Game UI.
wheel	boolean	false	Take the mouse wheel while the pointer is over this element or its children, instead of leaving it for gameplay. The innermost such element under the pointer takes it; read it back with consumeWheel().
draggable	boolean	false	Can be picked up: a ghost of it follows the pointer while dragging is true. A plain click still fires if the pointer never moves far enough to start a drag. Releasing on a dropTarget reports it there through dropped; releasing elsewhere reports it on this element's droppedOutside, a point in canvas units. Both are properties read once.
dropTarget	boolean	false	Receives a draggable element released over it, read back through dropped.
camera	string	""	A View's camera: the name of a node with a camera, whose picture fills the element's box, opaque, at its size in pixels, inside its style.cornerRadius and under its children. Give that camera primary: false so it does not become the main view. With no such node, or no renderer, the element draws only its style.
links	boolean	true	Whether a Text element's [[key&#124;shown words]] spans draw as links. false draws [[ and ]] as typed and no click reports a key -- set it for text the game cannot trust, such as player chat.
mask	string	""	A TextField's password mask: one character, such as *, drawn for each typed one. text keeps what was typed; copy and cut yield nothing, and accessibility services and the platform keyboard treat the field as a password. Empty draws the text as typed, so clearing it at runtime shows the password. Longer than one character, or set on another kind, is reported.
maxLength	integer	0	The most a TextField lets the player type, counted in maxLengthUnit; 0 for no limit. Typing, pasting and an IME stop at the limit, and never inside a character: an emoji, a flag or a letter with its accents goes in whole or not at all. A system writing text is not limited. Not negative; set on another kind, it is reported.
maxLengthUnit	Graphemes · CodePoints · Utf8Bytes	Graphemes	What maxLength counts. Graphemes are the characters a player sees, so a family emoji is one. Count CodePoints or Utf8Bytes to match the limit a server stores a line in, so a line the field accepts is never refused or cut there.
placeholder	string	""	The hint a TextField shows while it is empty and does not hold the keyboard, as a key in the project's string tables, such as chat.hint, in the field's text colour at half strength. textArgs fill in its placeholders. A key no table has shows as the key. Set on another kind, it is reported.
padding	object	{ "horizontal": 12, "vertical": 0 }	The space between a TextField's edge and its text, in dp. The default is shadcn's input px-3. Caret placement, selection and scrolling work inside it, and the field clips its text at its edge, so a leading j's tail and an Å's ring keep their ink. Vertical padding takes room from the centred line, so a field only as tall as its line should keep it 0. Negative or set on another kind, it is reported.
tooltip	string	""	A hint for any element, as a key in the string tables. It shows near the pointer after the pointer has been over the element for half a second, stays inside the canvas, and goes when the pointer leaves or presses the element. textArgs fill in its placeholders.
font	string	""	The font a Text's, TextField's or Button's words draw in. A path ending in .ttf or .otf, any case, names a TrueType or OpenType file from the project's root, loaded once with the scene; one that cannot be read or is not a font is logged once and draws in the default font. Any other value names a built-in family: default (Roboto) or bitmap (a fixed-pitch pixel font). Empty draws in the default font. Another name, or a path with another extension, is reported. See Game UI.
numerals	Proportional · Tabular	none	How a Text's, TextField's or Button's digits are spaced, from the font's OpenType features: Tabular (tnum) gives every digit the same width, so a counter, timer or score column keeps its place as it changes; Proportional (pnum) fits each digit's width to its shape. None keeps the font's default digits. A font without the feature draws its default digits.
pressable	boolean	false	Makes an Image or Panel take a tap as a Button does: consumePress() and consumePressAt() report it, and what is under the element doesn't get it. false leaves it watching the pointer only, so a tap passes through. A Button is always pressable; set on any other kind, it is reported.
button	object	none	Makes a Button an action button. trigger (Tap): fire action on a Tap released over it, or the moment it goes Down. Held longPressSeconds (0.5), it presses longPressAction, and the release is then not a tap. Let go anywhere, it presses releaseAction. Its live cooldown sweeps a shade over it and its charges show in a badge, set from code or bind; while cooling with no charge left it takes no press unless blockWhileCooling (true) is false. cooldownSeconds (0) gives it a cooldown of its own, run from 1 to 0 over that many seconds each time it fires; set with bind.cooldown, it is reported. aim makes it drag to aim and fire on release, wherever the thumb is: mode (Direction · Ground), radius (0, 120 dp), deadZone (0.2), a cancel zone (anchor, offsetX, offsetY, width, height) where letting go cancels, the axis aimAction pushed with the aim, and lockTarget, which asks the element's code-set aimLock for a target. Each action button follows only the pointer that landed on it first. Set on another kind, it is reported. See Game UI.
enabled	boolean	true	Whether a Button can be pressed. A disabled one takes no press, keeps it from what is under it, and draws in style.disabled, or dimmed. A bind.enabled field sets it each frame instead.
look	object	none	How a LookArea turns a swipe into a look and a pinch into a zoom: sensitivity (1), invertX, invertY, pinchZoom (true), zoomSensitivity (1), turnsCamera (true), which turns and zooms the active camera rig in a played project, and the axis zoomAction the pinch is pushed to as ln of its factor. The element's action names an axis action the swipe is pushed to. Set on another kind, it is reported.
cluster	object	none	Places the element's children as a button cluster instead of a layout: the first on a pivot (pivotX, pivotY, 1, shares of the element) unless primaryAtPivot is false, and the rest radius (96) dp from it, from startAngle (180) and spacing (45) degrees apart, clockwise from the right. Set with layout, it is reported.
skin	object	none	How this control looks, slot by slot, over the scene's canvas_controls theme: the same joystick, button and look slots as a theme's skin. A colour or image path written @name is the theme's token.
controlId	string	""	The name a player's saved layout knows this control by, such as move, so canvas_controls.playerLayout.controls can move, scale and fade it.
elementId	string	""	The stable id code finds this element by, such as health-bar: it survives a rename and repeats in each instance of a prefab, so code looks it up under one instance's root with World.findCanvasElement. Letters, digits, _, . and -, starting with a letter, digit or _; unique within a prefab. See Game UI.
bar	object	none	How a Bar draws as a progress bar: direction (LeftToRight · RightToLeft · BottomToTop · TopToBottom · Radial), a radial ring's thickness, a track colour, a trailColor fill that trails a drop by trailDelay seconds (0.5) and drains at trailSpeed (1.5), segments blocks segmentGap (2) dp apart, ticks in tickColor, and a label. Set on another kind, it is reported. See Game UI.
sweep	object	none	How a Sweep fills its value of a turn: startAngle degrees clockwise from 12 o'clock, clockwise (true), a mask (Box · Circle · Pill · CutCorner), a ring thickness (0 for a pie) and a track colour. Set on another kind, it is reported.
stepper	object	none	A Stepper's number: the value it starts at, min (0), max (100), step (1), decimals (0), and a held button's repeatDelay (0.4) and repeatInterval (0.08) in seconds. bind.value sets the number each frame instead. Set on another kind, it is reported.
joystick	object	none	How a Joystick moves and what it reports. mode (Fixed): Fixed centres the pad in the element; Floating makes the element a zone where the pad appears under the thumb, waiting at restX, restY (0.5, shares of the zone) while untouched; Dynamic also drags the pad along past its reach. radius (0) is the knob's reach in dp: half the element's shorter side when fixed, 60 otherwise. deadZone (0, below 1) reports nothing near the centre and stretches the rest back to full; response (Linear · Quadratic · Cubic) or a curve of points (at a deflection, value out) shapes it; directions (Analog · Four · Eight) snaps it. snapBack (true) centres it on release. Past sprintThreshold (0, never) of its reach it is sprinting, and in a played project holds the input action sprintAction. idleAlpha (1), idleDelay (0 s) and fadeSeconds (0.25) fade it while untouched. Each stick follows only the pointer that landed on it first. Set on another kind, it is reported.

canvas_appearance

How a canvas element looks beyond its words: its colours, style and skin. An element without one draws white content on nothing. SceneCanvasAppearance.

Field	Type	Default	What it does
color	string	"#FFFFFF"	Foreground colour, #RRGGBB or #RRGGBBAA: a Text's words, a Bar's or a Sweep's fill, a Joystick's knob.
background	string	"#00000000"	Background colour, #RRGGBB or #RRGGBBAA.
style	object	{}	Images, frames, fills, borders, corners, shadow, text shadow and outline, alpha, rotation, link colour, transitionSeconds, and hovered, pressed and disabled looks (including shadow and centre scale), as canvas_element.style describes.
skin	object	none	How this control looks, slot by slot, over the scene's canvas_controls theme, as canvas_element.skin describes.

canvas_bar

A progress bar: the element's widget. SceneCanvasBar.

Field	Type	Default	What it does
value	number	1	The fill, from 0 to 1. A canvas_bind value field reads it each frame instead.
settings	object	none	Its direction, track, trail, segments, ticks and label, as canvas_element.bar describes. None fills across from the left.

canvas_bind

Game state a canvas element shows without code, read from a node's fields. SceneCanvasBind.

Field	Type	Default	What it does
bind	object	required	The node and the fields read: value and max, text, textArgs, cooldown and cooldownMax, charges and enabled, as canvas_element.bind describes.

canvas_button

A button: the element's widget, an action button when it has settings. SceneCanvasButton.

Field	Type	Default	What it does
action	string	""	What it does for the game when pressed, such as jump.
doubleAction	string	""	What it does when double-clicked.
settings	object	none	Its trigger, long press, release, aim and cooldown, as canvas_element.button describes. None is a plain button, tapped on release.
enabled	boolean	true	Whether it can be pressed. A canvas_bind enabled field sets it each frame instead.

canvas_cluster

Places the element's children as a button cluster. Set with canvas_layout, it is reported. SceneCanvasCluster.

Field	Type	Default	What it does
cluster	object	{}	The pivot, radius, startAngle, spacing and primaryAtPivot, as canvas_element.cluster describes.

canvas_follow

A canvas element that follows a node on screen. SceneCanvasFollow.

Field	Type	Default	What it does
node	string	""	The name of the node followed. Blank is reported.
offset	vector	{x: 0, y: 0, z: 0}	World-space offset from the node, such as above its head.
bounds	boolean	false	Cover the screen rectangle of the node's meshes instead of standing at its point.
outset	number	0	With bounds, how far the box reaches past the node's rectangle on each side, in dp. Negative pulls it in.
rules	object	none	How a follower behaves with many on screen, as canvas_element.followRules describes.

canvas_follow_arrow

Inside a follower, marks this element as the arrow of one pinned to the edge, as canvas_element.followArrow describes. It has no fields. SceneCanvasFollowArrow.

canvas_image

A picture: the element's widget, drawing its canvas_appearance style image. It has no fields. SceneCanvasImage.

canvas_input

How a canvas element takes the pointer beyond what its widget does. SceneCanvasInput.

Field	Type	Default	What it does
pressable	boolean	false	Makes an Image or a Panel take a tap as a Button does. Set beside another widget, it is reported.
draggable	boolean	false	Can be picked up and dragged, as canvas_element.draggable describes.
dropTarget	boolean	false	Receives a dragged element released over it.
wheel	boolean	false	Take the mouse wheel while the pointer is over the element or its children.
moveHandle	boolean	false	Dragging the element moves its window, its nearest root element, by the pointer's travel, live and with no ghost: a title bar. A press under the drag threshold stays a click. Pressing in the window brings it to the front; when the move ends the window's moved reads its new offsets once. Not with draggable.
moveStrip	number	0	How much of a moveHandle's window, in the window's dp, stays on the canvas: that height of its top and that width. 0 keeps its top down to the handle's bottom. Not negative.

canvas_joystick

An on-screen stick: the element's widget. SceneCanvasJoystick.

Field	Type	Default	What it does
action	string	""	The axis action it steers, such as move.
settings	object	none	Its mode, reach, dead zone, response, directions, sprint and idle fade, as canvas_element.joystick describes.

canvas_layout

Lays the element's children out in rows or columns. SceneCanvasLayout.

Field	Type	Default	What it does
layout	object	{}	direction, wrap, gap, padding, justify and align, as canvas_element.layout describes.

canvas_look_area

A region where a swipe looks and a pinch zooms: the element's widget. SceneCanvasLookArea.

Field	Type	Default	What it does
action	string	""	The axis action the swipe is pushed to.
settings	object	none	Its sensitivity, inversion, pinch zoom, turnsCamera and zoomAction, as canvas_element.look describes.

canvas_particles

Canvas-space particle emitter attached to a canvas element alongside canvas_rect, stepped and drawn by CanvasOverlay on awake:core:particles's shared ParticleSimulation in logical dp units. At most one per node. SceneCanvasParticles.

Field	Type	Default	What it does
anchor	TopLeft · TopCenter · TopRight · CenterLeft · Center · CenterRight · BottomLeft · BottomCenter · BottomRight	Center	Point on the owning element's width × height box where particles spawn.
offsetX	number	0	Horizontal offset from anchor in dp (+ right, - left).
offsetY	number	0	Vertical offset from anchor in dp (+ down, - up).
placement	BehindContent · OverContent	OverContent	Paint layer relative to the element's background, widget and text.
clipped	boolean	true	Honours enclosing clips and canvas masks when true; escapes scissor/path clips and canvas masks within the active render target when false (never escaping an ancestor offscreen graphicsLayer target).
localSpace	boolean	true	Moves live particles with the element when true; trails in root canvas dp space when false.
additive	boolean	false	Draws with BlendMode.Plus instead of premultiplied BlendMode.SourceOver.
texture	string	""	Project image path loaded and premultiplied once through loadCanvasImages, or "" for untextured solid-tinted quads.
columns	integer	1	Sprite-sheet columns when texture is non-empty. At least 1.
rows	integer	1	Sprite-sheet rows when texture is non-empty. At least 1.
frameCount	integer	1	Animated cells played in reading order from 0 (1..columns*rows). At least 1.
frameRate	number	8	Sprite-sheet playback rate in frames per second. Not negative.
enabled	boolean	true	Whether CanvasOverlay steps and draws this emitter.
maxParticles	integer	64	Fixed pool size; spawning pauses while every slot is live. Above 0.
spawnRate	number	12	Continuous emission rate in particles per second. Not negative.
lifetime	number	0.8	Minimum seconds each particle lives. Above 0.
maxLifetime	number	none	Upper bound on random particle lifetime, at least lifetime. Above 0.
size	number	8	Particle quad height in dp at birth (width preserves cell aspect). Above 0.
endSize	number	none	Particle quad height in dp interpolated to at death. None keeps size. Not negative.
startAlpha	number	1	Opacity at birth. From 0 to 1.
alphaCurve	alpha curve	none	Fade-in / hold / fade-out envelope over normalized lifetime (fadeInEnd, fadeOutStart). None fades linearly from startAlpha to 0.
tint	color	white	Straight-alpha colour multiplier at birth.
endTint	color	none	Colour multiplier interpolated to at death. None keeps tint.
shape	object	{}	Spawn distribution around the resolved anchor in dp: kind (Point · Circle · Ring · Box · ElementRect · ElementEdge), radius, innerRadius, halfWidth and halfHeight (each not negative; innerRadius <= radius for Ring).
speed	number	48	Launch speed in dp per second. Not negative.
maxSpeed	number	none	Upper bound on random launch speed, at least speed. Not negative.
directionDegrees	number	-90	Base launch angle in degrees (0 = right, -90 = up on screen, 90 = down on screen).
spreadDegrees	number	360	Fan angle in degrees around directionDegrees (0 = beam, 360 = full circle). From 0 to 360.
radialSpeed	number	0	Outward speed in dp/s added away from the spawn origin.
convergeToOrigin	boolean	false	Sends spawned particles inward toward the spawn origin at launch speed.
gravity	object	{}	Constant 2D acceleration {x, y} in dp/s² (+Y pulls downward on screen; {x: 0, y: 0} by default).
drag	number	0	Linear velocity damping per second (0 disables). Not negative.
turbulence	number	0	Smooth sine flow-field perturbation strength (0 disables).
turbulenceFrequency	number	1	Spatial frequency of the turbulence flow field. Not negative.
spin	spin	none	Per-particle angular velocity range (minDegreesPerSecond, maxDegreesPerSecond, randomStartAngle).
burstCount	integer	none	Lifetime spawn cap; the emitter finishes once all spawned particles expire, and enabled stays as authored. Above 0.
burstCycle	burst cycle	none	Repeating pulsed emission schedule (cycleSeconds, activeSeconds, burstInterval, burstSize) replacing spawnRate.

canvas_rect

Where a canvas element sits and how big it is. A node with one is a canvas element: drawn by SceneCanvas, and found by its elementId. Sizes and offsets are in dp. SceneCanvasRect.

Field	Type	Default	What it does
anchor	TopLeft · TopCenter · TopRight · CenterLeft · Center · CenterRight · BottomLeft · BottomCenter · BottomRight	TopLeft	Screen point, or the parent's, the element is placed from.
offsetX	number	16	Horizontal offset from the anchor, as canvas_element.offsetX describes.
offsetY	number	16	Vertical offset from the anchor, as canvas_element.offsetY describes.
width	number	200	Width. Not negative.
height	number	40	Height. Not negative.
order	integer	0	Draw order. Lowest draws first.
visible	boolean	true	Whether the element is drawn.
touchOnly	boolean	false	Draw only where touch controls are shown.
safeArea	boolean	true	Keep an anchored element on the canvas itself inside the screen's safe area.
grow	number	0	In a parent with a canvas_layout, this element's share of its line's leftover space. Not negative.
elementId	string	""	The stable id code finds this element by, as canvas_element.elementId describes.
controlId	string	""	The name a player's saved layout knows this control by.

canvas_stepper

A number with minus and plus buttons: the element's widget. SceneCanvasStepper.

Field	Type	Default	What it does
settings	object	none	The value it starts at, min, max, step, decimals and repeat, as canvas_element.stepper describes. The live number is saved as value.

canvas_sweep

A radial fill, such as a cooldown: the element's widget. SceneCanvasSweep.

Field	Type	Default	What it does
value	number	1	The share of a full turn filled, from 0 to 1.
settings	object	none	Its start, direction, mask, ring and track, as canvas_element.sweep describes.

canvas_text

A canvas element's words. Without a widget beside it, the element is a Text. SceneCanvasText.

Field	Type	Default	What it does
text	string	""	A Text's content, a Button's label, or what is typed into a TextField, as canvas_element.text describes.
textKey	string	""	The words by key, from the project's string tables. Set with text or canvas_bind.bind.text, it is reported.
textArgs	object	{}	Values for textKey's, or a TextField's placeholder's, placeholders, by name.
fontSize	number	18	Text size. Above 0.
font	string	""	The font the words draw in, as canvas_element.font describes.
textAlign	TopLeft · TopCenter · TopRight · CenterLeft · Center · CenterRight · BottomLeft · BottomCenter · BottomRight	none	Where the words sit. None keeps the widget's own: top-left for a Text, centred for a Button.
links	boolean	true	Whether [[key|shown words]] spans draw as links.
numerals	Proportional · Tabular	none	How the digits are spaced, as canvas_element.numerals describes: Tabular gives every digit the same width, Proportional fits each to its shape. None keeps the font's default digits.

canvas_text_field

A line the player types into: the element's widget. What is typed is its canvas_text text. SceneCanvasTextField.

Field	Type	Default	What it does
mask	string	""	A password mask: one character drawn for each typed one.
maxLength	integer	0	The most the player may type, in maxLengthUnit; 0 for no limit. Not negative.
maxLengthUnit	Graphemes · CodePoints · Utf8Bytes	Graphemes	What maxLength counts.
placeholder	string	""	The hint shown while the field is empty and does not hold the keyboard, as a key.
padding	object	{ "horizontal": 12, "vertical": 0 }	The space between the field's edge and its text, in dp.

canvas_tooltip

A short hint shown near the pointer after it rests on the element. SceneCanvasTooltip.

Field	Type	Default	What it does
text	string	""	The hint's key in the string tables. Blank is reported.
textArgs	object	{}	Values for the hint's placeholders when the element has no canvas_text.

canvas_view

What a camera sees: the element's widget. SceneCanvasView.

Field	Type	Default	What it does
camera	string	""	The name of a node with a camera, as canvas_element.camera describes.
settings	object	none	Camera-picture transparency and masking, as described below. Omitted keeps the opaque default.

settings.transparent defaults to false. Set it to true for a portrait over a translucent or gradient panel: the runtime clears that camera target to transparent, omits the scene's sky, and composites the premultiplied picture. Geometry, lighting and fog remain. Translucent meshes still need an alpha-blended pipeline in the host's render plan, as in any other scene.

settings.mask defaults to Box, using the element's canvas_appearance.style.cornerRadius. Circle uses an inscribed circle; Pill fully rounds the short sides; CutCorner cuts the corners by the style's radius. These mask the camera picture, leaving the element's background and overlay children as authored. Explicit ancestor clips also constrain the picture. Target resolution follows the element's scaled pixel size; safe-area placement is unchanged.

{ "type": "canvas_view", "camera": "Portrait Camera", "settings": { "transparent": true, "mask": "Circle" } }

canvas_follow_limit

The most followers of one group the scene's canvas draws at once, keeping the most important: name plates over a crowd. A scene has one for each group it limits, each on any node. Only followers that would otherwise be drawn count, so one culled off screen, too far or occluded makes room for the next. SceneCanvasFollowLimit, saved from the live CanvasFollowLimit.

Field	Type	Default	What it does
group	string	""	The followRules.group it limits; empty limits the followers that name none.
max	integer	0	The most of them drawn at once; 0 for no limit. Not negative.
rankBy	Distance · Priority · Score	Distance	Which are kept: the nearest to the camera; the highest followRules.priority, then the nearest; or the highest followScore, which game code sets each frame, then the nearest.

canvas_follow_occlusion

The budget of the physics rays that hide followers whose followRules.occlusion asks while something stands between the camera and the point they follow. A scene has one, on any node; a scene whose followers ask casts with the defaults without one. A played project casts the rays when the scene has a physics world and either a follower asks or the scene has this component. SceneCanvasFollowOcclusion, saved from the live CanvasFollowOcclusion.

Field	Type	Default	What it does
raysPerFrame	integer	32	The most rays cast a frame, across every follower. The rest keep their last answer for another frame, those that waited longest cast first. At least 1.
reuseFrames	integer	6	How many frames an answer stands before its followed node is cast again. At least 1.
layer	integer	none	The one collision layer the rays hit, such as 0, the static world's, so walls and terrain hide followers and moving bodies do not. None hits every layer. Not negative.

canvas_scaler

How the scene's canvas, or one subtree of it, works its scale out from the screen's size, so a HUD designed at one resolution fits every screen. With scope Canvas, the default, a scene has one on any node, and without one the canvas draws at the scale its host passes; with Subtree, only the node it sits on and the nodes beneath it draw at that scale while the rest of the canvas keeps its own. Every canvas_element size, offset, font and image in its scope is multiplied by the scale. SceneCanvasScaler, saved from the live CanvasScaler.

Field	Type	Default	What it does
mode	ScaleWithScreenSize · ConstantPixelSize · ConstantPhysicalSize · DensityStep	ScaleWithScreenSize	Which rule works the scale out. ScaleWithScreenSize grows and shrinks the canvas with the screen; ConstantPixelSize keeps a unit a fixed number of the screen's pixels; ConstantPhysicalSize keeps a unit a fixed fraction of an inch; DensityStep draws as many whole steps of screen pixels per unit as still leave the short side referenceHeight units.
referenceWidth	number	1280	With ScaleWithScreenSize, the width the canvas is designed at, in units: on a screen this many dp wide, matching by width, a unit is a dp. Above 0.
referenceHeight	number	720	With ScaleWithScreenSize, the height the canvas is designed at, in units. With DensityStep, the fewest units the screen's short side keeps: 720 for a desktop HUD, 360 for a touch one. Above 0.
match	number	0.5	With ScaleWithScreenSize, what the scale follows: 0 the screen's width, 1 its height, and between them a blend taken on a log scale. From 0 to 1.
pixelsPerUnit	number	1	With ConstantPixelSize, how many of the screen's pixels one unit covers: 1 for pixel-exact art. With DensityStep, the step the pixels per unit move in: 1 for whole pixels, 0.5 for halves. Above 0.
referenceDpi	number	160	With ConstantPhysicalSize, the dots per inch the canvas is designed at: a unit is 1 / referenceDpi of an inch. 160 makes a unit a dp. Above 0.
minScale	number	0	The smallest scale the rule may give; 0 for no limit. Not negative, and not above a set maxScale.
maxScale	number	0	The largest scale the rule may give; 0 for no limit. Not negative.
playerScale	number	1	The player's own multiplier, applied after minScale and maxScale, so a settings menu can always make the UI larger or smaller. Above 0.
snap	None · WholeStep · HalfStep	None	Rounds the scale the rule gives to the nearest whole number or half before minScale and maxScale hold it, so pixel art lands on a whole number of screen pixels per art pixel. The layout is drawn at the rounded scale, so every size and offset moves by up to half a step in proportion: a 1.4125 scale draws at 1.5 with HalfStep, 6% larger, and at 1 with WholeStep, 29% smaller. A scale under one step is left as it is. Text needs no snapping; see Scale with the screen.
scope	Canvas · Subtree	Canvas	Which part of the canvas the scaler applies to. Canvas scales every element on the canvas when it is the scene's whole-canvas scaler; Subtree scales only the node it sits on (an element or a grouping node) and the nodes beneath it, from the canvas's box, with layout, clipping and hit-testing in that subtree using the scaled coordinates.

character_controller

A walking, jumping capsule moved by the physics character controller. SceneCharacterController.

Field	Type	Default	What it does
radius	number	0.5	Capsule radius. Above 0.
halfHeight	number	0.5	Half the capsule's cylinder height. Above 0.
stepHeight	number	0.3	Tallest step it climbs. Not negative.
slopeLimit	number	0.7853982 (45°)	Steepest walkable slope, in radians.
jumpSpeed	number	0	Upward speed of a jump. 0 means it cannot jump. Not negative.
gravity	number	-9.81	Vertical acceleration.

In a scene with a sensor (a physics_body with sensor set), the project player gives each character a kinematic body of its own, so a sensor detects the player and a blueprint's On Sensor Enter fires. The character moves the same either way. The body is solid, so other bodies rest on or bump into it, and it's destroyed with the character.

chase

Pursues another node along navigation paths. SceneChase.

Field	Type	Default	What it does
target	string	none	Name of the node to chase.
speed	number	2.5	Units per second. Above 0.
repathInterval	number	0.5	Seconds between path updates.
waypointRadius	number	0.3	Distance at which a waypoint counts as reached.

custom

Data for a component with no registered binding. Loads and saves unchanged; nothing is attached to the entity. SceneCustomComponent.

Field	Type	Default	What it does
type	string	required	Your component's type name. Must not be blank.
payload	any JSON	required	Your component's data.

day_cycle

Moves the sun over a day and blends the light, sky and fog between stops. Put it on the node of the directional light. SceneDayCycle.

The sun rises at sunriseAzimuthDegrees at time 0.25, is highest at noon (0.5), a quarter turn clockwise from where it rose, at noonElevationDegrees, sets opposite its rise at 0.75, and is as far below the horizon at midnight. The light keeps pointing at the sun below the horizon, so ground gets no direct light at night and the sky's moon stays opposite the sun; give night stops a low lightIntensity, a low ambient and a dark sky. Play runs it; a scene that is not playing shows its light, sky and fog as authored. Saving writes the authored time, not the time play reached.

Field	Type	Default	What it does
dayLengthSeconds	number	600	Seconds in one day. 0 holds the time still. Not negative.
time	number	0.5	Time of day the scene starts at: 0 midnight, 0.25 sunrise, 0.5 noon, 0.75 sunset. From 0 up to 1.
sunriseAzimuthDegrees	number	90	Where the sun rises, clockwise from −Z seen from above: 90 is +X.
noonElevationDegrees	number	60	The sun's height above the horizon at noon. Above 0, at most 90.
stops	list of stops	[]	How the scene looks at times of day, in time order.

Stop

Each stop is {"time": 0.25, ...} with time from 0 up to 1, plus any of the fields below. Between the stops that set a field, it blends linearly, wrapping from the day's last stop to its first across midnight. A field no stop sets keeps its authored value.

Field	Type	What it sets
horizonColor	color	The skybox horizon colour; a SolidColor sky's colour.
zenithColor	color	The skybox zenith colour.
lightColor	color	The light's color.
lightIntensity	number	The light's intensity. At least 0.
ambient	number	The light's ambient share. Above 0, at most 1.
fogColor	color	The fog colour.

The stops write the first skybox and fog in the scene. A Cubemap sky keeps its image. A rotated light node shines along its rotation and ignores the sun's direction.

factions

Who regards whom how, for every perceiver in the scene. SceneFactions. A scene has at most one; with none, every faction is neutral to every other and friendly to itself.

Field	Type	Default	What it does
relations	array of relation	[]	Rows of from, to, relation (hostile, neutral or friendly) and mutual (default true). Two rows may not contradict.
otherwise	hostile · neutral · friendly	neutral	The relation between factions no row names.
sameFaction	hostile · neutral · friendly	friendly	The relation of a faction to itself.

flee

Runs from another node along navigation paths. SceneFlee.

Field	Type	Default	What it does
threat	string	none	Name of the node to flee from.
panicRadius	number	6	Distance at which fleeing starts. Above 0.
safeRadius	number	12	Distance at which fleeing stops. Above panicRadius.
fleeDistance	number	10	How far to run.
speed	number	3.5	Units per second. Above 0.
repathInterval	number	0.4	Seconds between path updates.
waypointRadius	number	0.3	Distance at which a waypoint counts as reached.

fog

Distance fog. SceneFog.

Field	Type	Default	What it does
enabled	boolean	true	Whether fog is drawn.
density	number	0.001	Fog density.
color	color	{r: 0.55, g: 0.62, b: 0.70}	Fog color.
colorR	number	none	Legacy red channel. When colorR, colorG and colorB are all set, they replace color.
colorG	number	none	Legacy green channel.
colorB	number	none	Legacy blue channel.

input_actions

The scene's input actions and what triggers each, so a system reads an action such as jump and never a key. It becomes an InputActions (awake:core:input) on its entity, which code reads with world.inputActions(). A player's movement_control follows three: move steers, jump jumps and run runs. A scene that binds nothing gets the defaults: W A S D or the arrows move, Space jumps, and Shift runs while held. An action named like a default replaces it, and the other defaults stay. Put it on any node; only the first in a scene is used. SceneInputActions.

Field	Type	Default	What it does
actions	array of input actions	[]	The scene's own actions and the defaults it rebinds. Each name is letters, digits, _, . and -, starting with a letter, digit or _, and is used once. A key, or a chord, triggers one action, counting the defaults the scene keeps.

Input action

An entry of actions, named by its type key.

type	Fields	Defaults
button	name (string), keys (array of key names), buttons (array of Primary · Secondary · Middle · Back · Forward), trigger (Hold · Press · Toggle), startsOn (boolean), chords (array of chords)	required, [], [], Hold, false, []
axis	name (string), up, down, left, right (arrays of key names)	required, [] each

A button's trigger says when it is active: Hold while one of its keys or pointer buttons is held, Press for the frame one is pressed, and Toggle switched by each press, starting on when startsOn is true. An axis gives a direction from its keys, up and right being positive, a diagonal being of length 1. Key names are those of Key in awake:core:input, such as W, Space, Shift or ArrowUp. While a text field has the keys, held actions let go and toggles stay as they were. move is an axis, and jump and run are buttons.

Run unless X is pressed to walk, and press E to interact

{ "component": "input_actions", "actions": [
  { "type": "button", "name": "run", "keys": ["X"], "trigger": "Toggle", "startsOn": true },
  { "type": "button", "name": "interact", "keys": ["E"], "trigger": "Press" }
] }

Chord

An entry of a button's chords: a key or controller button pressed while modifiers are held, named by its type key. The most specific chord held when its key goes down takes the key, so Ctrl+1 does not also fire an action bound to 1; see Chords and rebinding.

type	Fields	Defaults
key	key (key name), modifiers (array of Ctrl · Alt · Shift · Meta), extraModifiers (Block · Allow)	required, [], Block
gamepad	button (South · East · West · North, the shoulders and triggers, the sticks, the d-pad, Select, Start, Home), modifiers (array of controller buttons), extraModifiers (Block · Allow)	required, [], Block

extraModifiers says whether a modifier the chord does not name, held as well, stops it: Block keeps Ctrl+S from firing for Ctrl+Shift+S. A chord binds one action, as a key does, and a chord with no modifiers is the plain key. A chord whose key is Unknown or one of its own modifiers does not load. Exporting a scene keeps the chords a player rebound while it ran.

Ctrl+1 or a shoulder held with the bottom face button uses the second hotbar's first slot

{ "type": "button", "name": "slot11", "trigger": "Press", "chords": [
  { "type": "key", "key": "Digit1", "modifiers": ["Ctrl"] },
  { "type": "gamepad", "button": "South", "modifiers": ["LeftShoulder"] }
] }

keyframe_animation

Loops keyframe tracks on its node: position, rotation, scale and material alpha. SceneKeyframeAnimation.

Keys sit at seconds into the loop and are interpolated linearly. Before a track's first key it holds that key's value, after its last key it holds that one, and every track starts over when the loop does. An empty track leaves its value as authored. Rotation keys are Euler radians, like the node's own, interpolated per axis: keys at 0 and 6.2832 make a full turn. Alpha replaces the base colour alpha of the node's own pbr_material, which shows on a textured mesh_renderer drawn transparent. Leave static_transform off an animated node and the nodes under it.

Field	Type	Default	What it does
duration	number	required	Seconds in the loop. Greater than 0.
position	list of vector keys	[]	Local position over the loop.
rotation	list of vector keys	[]	Local rotation over the loop, Euler radians.
scale	list of vector keys	[]	Local scale over the loop.
alpha	list of number keys	[]	The material's base colour alpha over the loop.

Key

Each key is {"time": 0.5, "value": ...}: time in seconds from the start of the loop, between 0 and duration, and in order within its track; value a vector for position, rotation and scale, a number for alpha.

light

A directional or point light. SceneLight.

Field	Type	Default	What it does
color	color	white	Light color.
intensity	number	1	Brightness multiplier.
type	Directional · Point	Point	Directional is a sun; Point is a lamp.
direction	vector	{x: 0.4, y: 0.8, z: 0.4}	Direction the light comes from, for Directional.
range	number	10	Falloff distance, for Point.
shadowsEnabled	boolean	true	Whether a directional light casts shadows.
shadowDistance	number	100	How far from the camera shadows reach. Finite and above 0.
ambient	number	none	This light's ambient share. Above 0 and at most 1.

locomotion_animation

Plays a skinned model's clip for how its entity moves: idle, walking, running, jumping, and optional 3D free motion. SceneLocomotionAnimation.

The scene component maps every field below to core:animation's LocomotionConfig and FreeLocomotionConfig. LocomotionPlayer owns the scene-independent movement measurement, clip phases and playback rate; LocomotionAnimationSystem supplies world position, ground contact, and free-motion state. Ground-speed and 3D-speed smoothing use damp with a 0.1-second time constant. Thresholds, fade times and reference speeds must be finite and satisfy the ranges below; scene validation rejects invalid settings before loading.

Speeds are measured from the entity's world position, so it animates however the entity is moved, and a model on a child node animates with it. Clip names are the model's own animations; a clip left out, or one the model lacks, keeps whatever already plays. With a character_controller on the entity or above it, the jump clips follow its ground contact, and CharacterMotionMode.Free switches playback to free (or reuses idle, walk and run against 3D speed) without firing takeOff or land. Otherwise a jump ends when the fall stops, so airborneAbove must exceed the vertical speed of running up the steepest walkable slope.

Field	Type	Default	What it does
idle	string	none	Clip while standing.
walk	string	none	Clip above walkAbove units per second across the ground.
run	string	none	Clip above runAbove.
jump	string	none	Clip while off the ground, or while rising when the phases below are set.
takeOff	string	none	Clip played once as it leaves the ground.
fall	string	none	Clip while coming down.
land	string	none	Clip played once as it touches down, unless it is already walking away.
walkAbove	number	0.1	Ground speed that starts the walk.
runAbove	number	4	Ground speed that starts the run; at least walkAbove.
airborneAbove	number	2	Vertical speed that counts as a jump without a character_controller; greater than 0.
crossFade	number	0.15	Seconds each clip change blends over. Not negative.
walkReferenceSpeed	number	none	Ground speed the walk cycle was authored for; set it to scale playback so the stride matches travel. Greater than 0.
runReferenceSpeed	number	none	Ground speed the run cycle was authored for; set it to scale playback so the stride matches travel. Greater than 0.
free	object	none	Optional 3D free-motion clips and speed thresholds (SceneFreeLocomotionAnimation), described below; none reuses idle, walk and run against 3D travel speed while in free motion.

free is a SceneFreeLocomotionAnimation object used while GroundContact.freeMotion is true:

Field	Type	Default	What it does
idle	string	none	Clip while hovering or stationary in 3D space.
move	string	none	Clip above moveAbove 3D travel speed when neither fast, ascend nor descend applies.
fast	string	none	Clip above fastAbove 3D travel speed.
ascend	string	none	Clip while climbing faster than verticalAbove and at least as fast vertically as horizontally.
descend	string	none	Clip while descending faster than verticalAbove downward and at least as fast vertically as horizontally.
moveAbove	number	0.1	3D travel speed that starts move. Not negative.
fastAbove	number	4	3D travel speed that starts fast; at least moveAbove. Not negative.
verticalAbove	number	0.5	Vertical speed magnitude above which ascend or descend can apply. Greater than 0.
crossFade	number	none	Seconds each clip change blends over while in free motion; none uses locomotion_animation.crossFade. Not negative.
moveReferenceSpeed	number	none	3D speed the move cycle was authored for; set it to scale playback to 3D travel. Greater than 0.
fastReferenceSpeed	number	none	3D speed the fast cycle was authored for; set it to scale playback to 3D travel. Greater than 0.

mesh_renderer

Draws a mesh with a material. Names are looked up in the scene's asset library. SceneMeshRenderer.

Field	Type	Default	What it does
mesh	string	required	Name of a registered or resolvable mesh. Must not be blank.
material	string	required	Name of a registered or resolvable material. Must not be blank.
cullMode	None · Back · Front	None	Face culling. Also read as cull_mode.
transparent	boolean	false	Draw in the transparent pass, blended and sorted back to front.
additive	boolean	false	With transparent, add its colour to what is behind it: glows and fire. A textured mesh draws unlit then, adding only its base and emissive colour, so black texels add nothing, unless its pbr_material sets litWhenAdditive.
billboard	boolean	false	Face the camera every frame, keeping the entity's position and scale. The mesh's +Z turns toward the eye. A billboard is not culled.
castsShadows	boolean	true	Draw the mesh into the shadow maps, whether the camera sees it or not. false for a decal, a ground card or distant filler; the mesh still draws and still receives shadows. A transparent mesh never casts.

movement_control

Moves the entity from player input, or from code such as AI or a network. A player follows the scene's move, jump and run input actions. SceneMovementControl.

Field	Type	Default	What it does
speed	number	none	Units per second. None uses the movement system's speed. Above 0 when set.
runSpeed	number	none	Units per second while running. None keeps speed. Above 0 when set.
turnSpeed	number	0	Radians per second it turns to face where it moves; 0 leaves its facing alone. Not negative.
driver	Player or Agent	Player	What sets the intent. Player: the keys and touch controls, relative to the camera. Agent: code writes a world-space direction, and player input leaves it alone.

navigation

The grid of cells agents can walk on, which patrol, chase and flee route over. SceneNavigation. A played scene with one of those behaviours and a navigation component runs them with nothing wired by the host; put it on any node, and only the first in a scene is used.

Field	Type	Default	What it does
rows	array of text	[]	One string per row of cells along z, each character one cell along x: . walkable, # blocked. Every row is the same length, and there is at least one.
cellSize	number	1	World size of one cell. Above 0.
originX	number	0	World x of the centre of cell (0, 0).
originZ	number	0	World z of the centre of cell (0, 0).

navigation_agent

Walks its node to a destination around the cells the scene's navigation blocks, re-planning when it is pushed off its route or stops making progress. SceneNavigationAgent. With a movement_control whose driver is Agent it walks through the control, so a character_controller carries it; without one it moves by its transform. Code sends it somewhere with NavigationAgent.moveTo. A scene with a navigation_agent and no navigation does not load. See Navigation.

Field	Type	Default	What it does
radius	number	0.4	Metres from its centre to its side; gaps narrower than twice this are closed to it. Not negative.
speed	number	3	Metres per second. Above 0.
arriveDistance	number	0.25	Metres from the destination that count as arriving. Above 0.
waypointRadius	number	0.35	Metres from a corner that count as reaching it. Above 0.
repathInterval	number	2	Seconds between re-plans while walking; 0 re-plans only when stuck. Not negative.
stuckSeconds	number	0.75	Seconds without progress before it re-plans. Above 0.
stuckDistance	number	0.1	Metres it must move in stuckSeconds to count as progress. Not negative.
destinationX	number	none	World x it heads for when the scene starts. Given with destinationZ.
destinationZ	number	none	World z it heads for when the scene starts. Given with destinationX.

particle_emitter

Spawns sprites at its node's world position, turned to the camera or lying flat, and follows the node. SceneParticleEmitter.

Sizes, speeds and spawnRadius are world units; the node's scale does not apply, and its rotation only tilts a Flat emitter's plane, turns the spawn ring with orientSpawnRing and, with inheritOrientation, turns the spawn ring and velocity. A Local space emitter is the exception: its particles live in the node's own axes and units, so they move, turn and scale with it. Each particle fades from startAlpha to 0 over its lifetime (or by alphaCurve), while its tint moves from color to endColor and its size from scale to endScale. runProject runs it; see Particles.

Field	Type	Default	What it does
texture	string	required	Project image the particles show.
maxParticles	number	64	Pool size; spawning pauses while every slot is live. Above 0.
spawnRate	number	10	Particles per second. Not negative.
lifetime	number	1	Seconds each particle lives. Above 0.
startAlpha	number	1	Opacity at birth, 0 to 1.
scale	number	0.2	Size at birth. Above 0.
endScale	number	none	Size at death. None keeps scale. Not negative.
velocity	vector	{x: 0, y: 1, z: 0}	Starting velocity.
velocityJitter	number	0	Random per-axis variation added to velocity.
coneHalfAngleDegrees	number	none	Spreads the direction within this angle of velocity, keeping its speed.
spawnRadius	number	0	Spawns on a horizontal ring of this radius. Not negative.
radialSpeed	number	0	Adds this speed horizontally away from the node, through the spawn point.
color	color	white	Tint at birth.
endColor	color	color	Tint at death.
frameCount	number	1	Treats the texture as a horizontal strip of this many frames. At least 1.
frameRate	number	8	Frames per second of that strip. Not negative.
additive	boolean	false	Adds to what is behind, for glows. Needs the particle pipeline built with buildAdditive.
facing	Camera · Flat	Camera	Camera turns each sprite to the camera. Flat lays it in the plane perpendicular to the node's up axis, on the ground for an upright node, its texture's top toward the node's -Z: ground glows, ripples, magic circles.
acceleration	vector	{x: 0, y: 0, z: 0}	A constant world-space acceleration in units per second squared, added to every live particle's velocity: {y: -9.8} is gravity. Finite.
inheritOrientation	boolean	false	The node's rotation turns the spawn ring and velocity (so also the cone's axis and the jitter axes). acceleration and radialSpeed stay in world space.
alphaCurve	alpha curve	none	Fades a particle in and out over its life. None is the linear fade from startAlpha to 0. Described below.
burstCycle	burst cycle	none	A pulsing emission that replaces spawnRate. None spawns continuously. Described below.
turbulence	number	0	Strength of a smooth flow-field wobble added to every particle's velocity. Finite.
turbulenceFrequency	number	1	How tight that wobble is. Finite, not negative.
convergeToOrigin	boolean	false	Aims each particle at the node, at the speed of velocity, instead of along it; with a spawnRadius they appear on a ring and close in. Ignores radialSpeed.
stretchWithVelocity	boolean	false	Stretches each sprite along its screen motion, for streaks.
stretchFactor	number	0.05	World units of stretch per unit of speed. Finite, not negative.
burstCount	number	none	Particles to spawn in the emitter's whole life. When they have all died the node carrying the emitter is removed from the world, so put a one-shot emitter on a node of its own. Above 0.
ground	ground	none	Where falling particles land. None lets them fall and fade. Described below.
spin	spin	none	A random spin for each particle, turning its sprite in its own plane. None leaves particles upright. A stretched particle (stretchWithVelocity) points along its motion and ignores it. Described below.
space	World · Local	World	World leaves each particle where it was emitted however the node moves next. Local keeps particles relative to the node and draws them through its current transform, so they move, turn and scale with it: an aura on a moving bone. velocity and the spawn ring are then in the node's axes and inheritOrientation adds nothing; acceleration still pulls in world space; camera-facing sprites still face the camera. A Local emitter cannot have a ground.
orientSpawnRing	boolean	false	The node's rotation tilts the spawn ring alone, so it lies in the plane a Flat emitter's sprites lie in, while velocity, acceleration and radialSpeed stay in world space. Adds nothing beside inheritOrientation or with space Local.
radialInRingPlane	boolean	false	radialSpeed pushes outward in the turned spawn ring's own plane instead of horizontally, when orientSpawnRing or inheritOrientation turns the ring: an outward ripple across a sloped surface. Adds nothing while the ring is not turned, or with space Local.

alphaCurve is an object with the fractions of a particle's life at which it reaches full opacity and starts to fade out, both within 0 to 1 with fadeInEnd not after fadeOutStart:

Field	Type	Default	What it does
fadeInEnd	number	0	Fraction of life at which opacity reaches startAlpha.
fadeOutStart	number	0	Fraction of life at which opacity starts to fall to 0.

spin gives each particle its own angular velocity, drawn uniformly between two rates when it spawns. Positive turns counter-clockwise as the viewer sees it, negative clockwise, so -90 to 90 sends particles both ways. Both rates are finite and minDegreesPerSecond is not above maxDegreesPerSecond:

Field	Type	Default	What it does
minDegreesPerSecond	number	required	The slowest, or most clockwise, spin.
maxDegreesPerSecond	number	required	The fastest, or most counter-clockwise, spin.
randomStartAngle	boolean	false	Also starts each particle at a random angle. Without it they all start upright.

burstCycle loops: for the first activeSeconds of every cycleSeconds, burstSize particles spawn every burstInterval seconds, then nothing spawns until the cycle repeats:

Field	Type	Default	What it does
cycleSeconds	number	required	Length of one cycle. Above 0.
activeSeconds	number	required	How much of the cycle bursts fire in. Above 0, at most cycleSeconds.
burstInterval	number	required	Seconds between bursts while active. Above 0.
burstSize	number	required	Particles per burst. Above 0.

ground makes falling particles land. A particle over a collider lands on its top face, otherwise on the plane at groundY, otherwise it never lands:

Field	Type	Default	What it does
groundY	number	none	Height of a flat ground plane. None has no plane.
restitution	number	0	Fraction of fall speed kept as a bounce: 0 stops the particle, 1 is lossless, above 1 gains energy. Not negative.
friction	number	1	Fraction of sideways speed kept on each bounce. Not negative.
colliders	array of box	[]	World-space boxes, each {min: vector, max: vector}, with min at or below max on every axis.

particle_emitter_2d

Spawns 2D quads on the XY plane through awake:core:particles's ParticleSimulation and draws them through the unlit sprite pipeline, sorted alongside sprite and tilemap nodes by sortingLayer and sortOrder. SceneParticleEmitter2D.

Sizes, speeds and shape extents are 2D world units. Leaving texture empty ("") draws solid-tinted quads; naming a project image resolves it through the scene's sprite batch with optional columns × rows frame sheets. See Particles.

Field	Type	Default	What it does
texture	string	""	Project image path for particle quads, or "" for untextured solid-tinted quads. Not blank when non-empty.
columns	integer	1	Sprite-sheet columns when texture is non-empty. At least 1.
rows	integer	1	Sprite-sheet rows when texture is non-empty. At least 1.
frameCount	integer	1	Animated cells played in reading order from 0 (1..columns*rows). At least 1.
frameRate	number	8	Sprite-sheet playback rate in frames per second. Not negative.
enabled	boolean	true	Whether the emitter steps and draws.
maxParticles	integer	64	Pool size; spawning pauses while every slot is live. Above 0.
spawnRate	number	12	Continuous emission rate in particles per second. Not negative.
lifetime	number	1	Minimum seconds each particle lives. Above 0.
maxLifetime	number	none	Upper bound on random particle lifetime, at least lifetime. Above 0.
size	number	0.25	Particle quad height in world units at birth (width preserves cell aspect). Above 0.
endSize	number	none	Particle quad height in world units at death. None keeps size. Not negative.
startAlpha	number	1	Opacity at birth. From 0 to 1.
alphaCurve	alpha curve	none	Fade-in / hold / fade-out envelope over normalized lifetime (fadeInEnd, fadeOutStart). None fades linearly from startAlpha to 0.
tint	color	white	Straight-alpha colour multiplier at birth.
endTint	color	none	Colour multiplier interpolated to at death. None keeps tint.
shape	object	{}	2D spawn distribution around the origin: kind (Point · Disc · Ring · Box · RectEdge), radius, innerRadius, halfWidth and halfHeight (each not negative; innerRadius <= radius for Ring).
speed	number	1	Launch speed in world units per second. Not negative.
maxSpeed	number	none	Upper bound on random launch speed, at least speed. Not negative.
directionDegrees	number	90	Base launch angle in degrees (0 = +X right, 90 = +Y up).
spreadDegrees	number	360	Fan angle in degrees around directionDegrees (0 = beam, 360 = full circle). From 0 to 360.
radialSpeed	number	0	Outward 2D speed added away from the emitter origin.
convergeToOrigin	boolean	false	Sends spawned particles inward toward the origin at launch speed.
gravity	object	{}	Constant 2D acceleration {x, y} in world units per second squared ({x: 0, y: 0} by default).
drag	number	0	Linear velocity damping per second (0 disables). Not negative.
turbulence	number	0	Smooth sine flow-field perturbation strength (0 disables).
turbulenceFrequency	number	1	Spatial frequency of the turbulence flow field. Not negative.
spin	spin	none	Per-particle angular velocity range (minDegreesPerSecond, maxDegreesPerSecond, randomStartAngle).
additive	boolean	false	Draws with additive blending on spriteScenePipeline(buildAdditive = true).
space	World · Local	World	World leaves each live particle where it spawned, trailing behind a moving node. Local keeps them attached to the node's Transform, so they move, turn and scale with it; gravity is then in the node's axes. The same names as particle_emitter's space.
localSpace	boolean	none	Deprecated: write space. Left out, it reads as false; true still reads as space Local. The field is not written back out.
inheritOrientation	boolean	false	Rotates shape and launch direction by the node's Z rotation when space is World.
sortingLayer	string	"Default"	Project sorting layer name, ordered alongside sprite and tilemap. Not blank.
sortOrder	integer	0	Paint order within sortingLayer; higher values draw over lower ones.
burstCount	integer	none	Lifetime spawn cap; destroys a non-pooled node once all spawned particles expire. Above 0.
burstCycle	burst cycle	none	Repeating pulsed emission schedule (cycleSeconds, activeSeconds, burstInterval, burstSize) replacing spawnRate.

patrol

Walks a list of stops along navigation paths. ScenePatrol.

Field	Type	Default	What it does
stops	array of vector	[]	Waypoints, in order.
style	loop · pingPong · once	loop	What happens after the last stop.
dwellSeconds	number	1	Wait at each stop. Not negative.
speed	number	1.8	Units per second. Above 0.
repathInterval	number	1	Seconds between path updates.
waypointRadius	number	0.3	Distance at which a waypoint counts as reached.

pbr_material

Physically based material values for the entity's mesh. ScenePbrMaterial.

Field	Type	Default	What it does
metallic	number	0	Metalness, 0 to 1.
roughness	number	0.5	Roughness, 0 to 1.
baseColorFactor	color	white	Base color multiplier.
emissiveFactor	color	{r: 0, g: 0, b: 0, a: 0}	Emitted light.
alphaMode	Opaque · Masked	Opaque	Masked discards fragments below alphaCutoff.
alphaCutoff	number	0.5	Alpha threshold for Masked, 0 to 1.
litWhenAdditive	boolean	false	Keeps a textured mesh drawn additive lit: it adds its colour as the sun, shadows, ambient and point lights shade it, not only its base and emissive colour. Fog fades it either way.
unlit	boolean	false	Draws baseColorFactor * texture * vertexColor as stored on textured and single-draw skinned meshes, skipping lighting, tone mapping and fog while keeping alpha masking and output encoding.

perceivable

Something perceivers can see and hear. ScenePerceivable.

Field	Type	Default	What it does
faction	string	required	Its faction. Must not be blank.
visible	boolean	true	Whether it can be seen; it can always be heard.
height	number	1	How far above its position a viewer aims at it.

perceiver

An entity that sees, hears and remembers. ScenePerceiver. A played project runs perception for it before its tree or machine, writing what it perceives to their blackboard.

Field	Type	Default	What it does
faction	string	required	Its faction, which decides how it regards what it perceives. Must not be blank.
settings	object	Core's	How it perceives: sight (focusRange 15, focusAngle 60, peripheralRange 5, peripheralAngle 180, eyeHeight 1.6, lineOfSight true), hearing (range 10, muffledBy 0.5), forgetAfter 10, updateInterval 0.2, and the blackboard keys it writes.

physics_body

A collider or rigid body. ScenePhysicsBody.

Field	Type	Default	What it does
shape	collision shape	box, half extents 0.5	Collision shape. Sizes above 0.
motion	STATIC · KINEMATIC · DYNAMIC	STATIC	How the body moves.
layer	integer	none	Collision layer index. None uses the default for motion. Not negative.
sensor	boolean	false	Detects what passes through instead of blocking it.
degreesOfFreedom	ALL · PLANE_2D	ALL	Allowed motion in world axes. PLANE_2D locks Z translation and X/Y rotation.

degreesOfFreedom applies to primitive and model colliders and survives saving and body rebuilds. Shapes retain their Z thickness; see Physics in 2D.

Collision shape

The value of shape, named by its type key.

type	Fields	Defaults
box	halfExtents (vector)	{x: 0.5, y: 0.5, z: 0.5}
sphere	radius (number)	0.5
capsule	halfHeight (number), radius (number)	0.5, 0.5
mesh	mesh (string), primitive (integer)	required, none
convex_hull	mesh (string), primitive (integer)	required, none

mesh collides with the triangles of the .glb or .gltf model at the project path mesh: primitive picks one primitive, counted in node order, and none merges them all. The node's scale is baked into the triangles. Only STATIC bodies that are not sensors can use it, and it needs MeshColliderSystem to build the body; see Collide with a model.

convex_hull shrink-wraps the model's vertices into a convex volume with node scale baked in. Because it encloses volume, it supports any motion (STATIC, KINEMATIC, or DYNAMIC) and can be a sensor. Like mesh, it uses MeshColliderSystem to build the body from models loaded through loadCollisionMeshes.

post_processing

Configures the post-processing effects chain applied to the camera's rendered view. ScenePostProcessing.

Field	Type	Default	What it does
enabled	boolean	true	Whether post-processing is enabled for this camera.
effects	array	[]	Ordered list of post-processing effect specifications.

Each effect is an object whose type names it. The camera's colour is already tone mapped and encoded by the lit shaders, so a tone_mapping_grade must use "mode": "Passthrough": a scene with an enabled PbrNeutral one, or with two enabled tone_mapping_grade effects, fails validation. The Lights and shadows guide lists the valid combinations.

tone_mapping_grade, one grading pass:

Field	Type	Default	What it does
enabled	boolean	true	Whether the pass runs.
mode	PbrNeutral · Passthrough	PbrNeutral	Passthrough grades only. PbrNeutral then applies the PBR Neutral curve and the gamma 2.2 encode, which a scene camera's colour already has, so a scene refuses it.
exposure	number	1	Multiplies the colour before grading. Finite and above 0.
contrast	number	1	Contrast around mid-grey 0.18. Finite and at least 0.
saturation	number	1	0 is grey, 1 as drawn. Finite and at least 0.
whiteBalanceTemperature	number	0	Cool (-1) to warm (1).
whiteBalanceTint	number	0	Green (-1) to magenta (1).
lift	array	[0, 0, 0]	Added to the shadows, per channel.
gamma	array	[1, 1, 1]	Midtone exponent, per channel.
gain	array	[1, 1, 1]	Highlight multiplier, per channel.

bloom: enabled, intensity (0.5), threshold (1), knee (0.5, 0 to 1) and radius (8, in pixels). fxaa: enabled and quality (Off · Low · Medium · High, default High). custom: enabled, shaderId (a registered image-pass shader) and parameters (its floats).

prefab_link

Places a prefab file at this node. SceneDocument.withPrefabs (which loadProject runs) puts the prefab's root under the node, so the node's transform places it and its own components add to it. The node holds no children of its own. Exporting the world writes the link, not the prefab's nodes. A prefab file is a ScenePrefab as JSON: guid, optional name, and a root node. ScenePrefabLink.

Field	Type	Default	What it does
path	string	required	The prefab file, relative to the project root. Must not be blank.

shader_effect

A shader the project ships as data, drawn at this node: a sky behind the scene, an overlay in front of it, or a plane placed by the node's transform, as the document's surface says. The document is a *.shader.json file in the project; loadProject reads, checks and compiles it once, and ShaderEffectSystem draws it, advancing its clock each frame. An effect whose parameters or textures do not match its document is logged with the node and not drawn, and the scene plays on without it. The document's format is in the shader document reference. SceneShaderEffect.

Field	Type	Default	What it does
shader	string	required	Project path of the shader document.
parameters	object of number lists	{}	Parameter name to its numbers: 1 for a float, 2 to 4 for a vector, 4 for a color. A parameter left out takes the document's default.
textures	object of strings	{}	Texture name, as the document declares it, to the project path of its image. Every declared texture needs one.
enabled	boolean	true	Whether the effect draws. Its clock runs either way.

skybox

The background drawn behind the scene. SceneSkybox.

Field	Type	Default	What it does
enabled	boolean	true	Whether the sky is drawn.
type	string: Procedural · SolidColor · Cubemap	"Procedural"	Sky mode, case-insensitive. Any other value is Procedural.
horizonColor	color	{r: 0.72, g: 0.80, b: 0.88}	Horizon color, and the color of SolidColor.
zenithColor	color	{r: 0.20, g: 0.38, b: 0.68}	Color straight up.
horizonColorR	number	none	Legacy channel. When all three horizonColor* channels are set, they replace horizonColor.
horizonColorG	number	none	Legacy channel.
horizonColorB	number	none	Legacy channel.
zenithColorR	number	none	Legacy channel. When all three zenithColor* channels are set, they replace zenithColor.
zenithColorG	number	none	Legacy channel.
zenithColorB	number	none	Legacy channel.
cubemapPath	string	none	Cubemap asset path, for Cubemap.
exposure	number	1	Cubemap brightness, for Cubemap.

spin_control

Rotates the entity around Y. SceneSpinControl.

Field	Type	Default	What it does
radians	number	0	Starting angle in radians.
speed	number	1	Rotation speed multiplier. Not negative.

sprite

A flat image drawn at the node's Transform, with no lighting: one cell of a frame sheet. Its size is the cell's pixel size divided by pixelsPerUnit, so under an orthographic camera it keeps its size however the image is scaled. SceneSprite.

A project played with runProject reads the image from the project's files the first time the sprite is drawn. Until it has loaded, the sprite is not drawn; an image that can't be read draws nothing and is logged once. An image whose size doesn't divide into columns by rows whole-pixel cells is not drawn either, and is logged once. A host that changes the file has the scene's asset library forgetTexture it (or requestForgetTexture it from another thread), and the next frame reads it again.

Field	Type	Default	What it does
texture	string	required	A project image file the sprite shows. Not blank.
columns	integer	1	Frame-sheet columns. At least 1.
rows	integer	1	Frame-sheet rows. At least 1.
frame	integer	0	The cell shown, counted from 0 in reading order from the top left. Within the sheet.
pixelsPerUnit	number	100	Image pixels that make one scene unit. Finite and above 0.
flipX	boolean	false	Mirrors the sprite left to right.
flipY	boolean	false	Mirrors the sprite top to bottom.
tint	color	white	Multiplied into the image's colour and alpha.
sortOrder	integer	0	Within its sortingLayer, a higher order draws over a lower one; a tie draws by depth from the camera.
pivot	object (x, y)	{"x": 0.5, "y": 0.5}	The point of the frame placed at the node, which the sprite turns and scales about, as a fraction of the frame from its bottom left: the default is its centre, {"x": 0.5, "y": 0} the middle of its bottom edge. It holds for every frame, and a flipped sprite mirrors about it. Finite; outside 0 to 1 places it outside the frame.
sortingLayer	string	"Default"	The project's sorting layer it draws on: a later layer in the manifest's sortingLayers draws over an earlier one whatever their sortOrder. A name the list leaves out draws on Default, and is a warning when the project loads. Not blank.
## state_machine

Runs the state machine in a definition file. SceneStateMachine. A played project reads and checks the file when it loads, and gives the entity an AiStateMachineComponent built from it.

Field	Type	Default	What it does
asset	string	required	Path of the definition, a StateMachineDefinition as JSON. Must not be blank.
seed	integer or none	none	Seeds the machine's random nodes. None gives each entity its own.
enabled	boolean	true	Whether the machine runs.

tilemap

A finite orthogonal atlas layer. The node's origin is its top left, with +X right and -Y down. The runtime uploads one mesh per non-empty chunk, draws visible chunks through the sprite pipeline, and rebuilds only edited chunks. Its atlas image loads as a sprite's does. SceneTilemap.

Field	Type	Default	What it does
texture	string	required	Named atlas image; must not be blank.
width	integer	required	Map columns. At least 1.
height	integer	required	Map rows. At least 1.
tiles	list of integers	required	Exactly width times height frames in row order; -1 is empty.
columns	integer	1	Atlas columns. At least 1.
rows	integer	1	Atlas rows. At least 1.
pixelsPerUnit	number	100	Pixels per local world unit. Finite and above 0.
chunkSize	integer	16	Cells per chunk edge. At least 1; edge chunks may be smaller.
tint	color	white	Whole-layer straight-alpha multiplier.
sortOrder	integer	0	Within its sortingLayer, higher order draws after lower-order tilemaps and sprites.
sortingLayer	string	"Default"	The project's sorting layer it draws on, shared with sprites. Not blank.

sprite_clips

Named animation runs for the sprite on the same node. Sheet dimensions come from that sprite; every run must fit its atlas. SceneSpriteClips.

The standard scene runtime advances SpriteClipSystem before rendering, and sceneSystemsFor includes it for a scene with sprite_clips, so an editor's Play advances them. A custom host runs it once per simulation frame. SpriteClips.play("hit") changes the run; repeated requests preserve time unless restart = true. speed = 0 pauses this entity, and isFinished reports one-shot completion. An empty library leaves the sprite's manually selected frame alone. Export saves the selected clip name, while playback time and speed remain transient runtime state.

Field	Type	Default	What it does
clips	object of runs	{}	Runs by name. Names must not be empty.
clip	string	the first listed	Initial run; must name a run in clips.

Sprite run

Each entry in clips is a SceneSpriteClip:

Field	Type	Default	What it does
firstFrame	integer	0	First cell, counted from the top left across rows. Not negative.
frameCount	integer	1	Cells in the run; at least one and the whole run must fit the sprite.
framesPerSecond	number	0	Authored playback rate. Finite and not negative; zero holds the first cell.
loop	boolean	true	Repeat the run. False plays once and holds its last cell.

Importing sprite-sheet metadata

SpriteGenManifest.decode(manifestText) from com.awakekt.awake.asset:sprite imports a sprite-gen component-row manifest. It returns the image reference, regular grid and named clips. Resolve the image through your asset loader and verify its decoded size with sheet.requireImageSize(width, height).

Before instantiation, call authored.withSpriteSheets(mapOf("hero" to sheet)), importing the extension from com.awakekt.awake.scene.scene2d. Keys match each sprite's authored texture. This fills in atlas dimensions and runs on nested matching nodes, retains clip selection and styling, and lets local runs override imported names. The result saves as ordinary scene components.

Runs must contain contiguous, untrimmed cells on one row. Uniform durations_ms overrides fps; without durations, fps is required. Packed atlases, reordered cells and variable frame durations are unsupported and rejected with IllegalArgumentException.

static_transform

Marks a node that never moves, such as a placed prop. SceneStaticTransform, no fields.

TransformSystem builds the node's world matrix once and then skips it, so a level of thousands of props costs almost nothing per frame. The node's parent must not move either: a static node does not follow a parent that moves. An editor that moves static nodes uses TransformSystem(skipsStatic = false).

{ "component": "static_transform" }

tag

What the entity is to gameplay, by role, such as enemy or pickup. It becomes the entity's Tags (awake:ecs), which code finds with world.withTag("enemy") and tests with world.hasTag(entity, "enemy"). A prefab's tags ride on its root entity; tags on the node that links the prefab tag that node. SceneTag.

Field	Type	Default	What it does
tags	array of strings	[]	The node's tags, any number of them. Each is letters, digits, _, . and -, starting with a letter, digit or _. A project can list its tags in the manifest's tags; a scene tag the list leaves out is a warning when the project loads.

terrain

A heightmap terrain. At most one per node. SceneTerrain.

Field	Type	Default	What it does
width	integer	required	Samples along X. At least 2.
depth	integer	required	Samples along Z. At least 2.
scaleX	number	1	Spacing between samples along X. Finite and above 0.
scaleY	number	1	Height multiplier. Finite and above 0.
scaleZ	number	1	Spacing between samples along Z. Finite and above 0.
samples	array of number	required	Heights, width × depth finite values.
tilingScale	number	16	Texture tiling across the terrain.
isVisible	boolean	true	Whether the terrain is drawn.
surface	terrain surface	none	Surface model, read by a terrain surface provider.
collider	boolean	false	Whether the terrain is solid ground when physics runs, as a static heightfield. Needs a square terrain of at least 4 samples a side.

Terrain surface

SceneTerrainSurface, the value of surface.

Field	Type	Default	What it does
provider	string	required	Id of the surface provider.
version	integer	1	Version of the provider's payload.
payload	any JSON	{}	The provider's data. Kept unchanged when no provider is installed.

texture_animation

Plays the entity's texture as a frame sheet and scrolls it. The textured shader applies it to every texture of the entity's material; with no pbr_material it plays with glTF's default factors. SceneTextureAnimation.

Field	Type	Default	What it does
columns	integer	1	Frame-sheet columns. At least 1.
rows	integer	1	Frame-sheet rows. At least 1.
frameCount	integer	0	Frames played from firstFrame. 0 plays every cell from firstFrame on.
framesPerSecond	number	0	Playback rate. 0 holds the first frame of the run. Not negative.
scrollU	number	0	UV units per second along U.
scrollV	number	0	UV units per second along V, toward the bottom of the image.
firstFrame	integer	0	The cell the run starts at, counted from 0 in reading order. Within the sheet, and firstFrame + frameCount at most columns * rows.

texture_clips

A frame sheet with named clips cut out of it, one of which plays on the entity. texture_animation loops one run on the GPU's clock; these are stepped on the CPU by TextureClipSystem from the scene's clock, so a game can switch clip by name (TextureClips.play), see when a one-shot clip has finished, and a paused game holds still. The system gives the entity a TextureAnimation that holds the cell now showing, so an entity should not also carry a texture_animation. SceneTextureClips.

Field	Type	Default	What it does
columns	integer	1	Frame-sheet columns. At least 1.
rows	integer	1	Frame-sheet rows. At least 1.
clips	object of clips	{}	The sheet's runs by name; each is described below.
clip	string	the first listed	The clip that plays when the scene loads. One of clips.

Each clip in clips is a SceneTextureClip:

Field	Type	Default	What it does
firstFrame	integer	0	The clip's first cell, counted from 0 in reading order from the top left.
frameCount	integer	1	Cells in the clip. At least 1, and firstFrame + frameCount at most columns * rows.
framesPerSecond	number	12	Playback rate. 0 holds the first cell.
loop	boolean	true	Whether the clip starts over when it ends. false holds its last cell.

tone_mapping

How bright the lit scene is shown. At most one per node; the first found applies. SceneToneMapping.

Field	Type	Default	What it does
exposure	number	1	Multiplies the lit scene before tone mapping. 2 is one stop brighter. Finite and above 0.

trail_renderer

A trail drawn at its node: a swing's ribbon, a projectile's streak, a tyre mark. A strip of point pairs drawn unlit in the transparent pass, through the node's world matrix, from one GPU buffer sized once at capacity. The document says how it is drawn; a game's systems write its pairs, how many show and their colours every frame. SceneTrailRenderer.

Field	Type	Default	What it does
capacity	integer	64	The most point pairs it holds, 2 to 65536.
blend	Additive · Alpha	Additive	Additive adds to what is behind it; Alpha covers it by its alpha.
tint	color	white	Multiplied into every vertex's own colour.

world_text

Text placed in the scene at its node: a sign, a label on an object, a number seen in perspective. It is laid out once and drawn from the built-in face's distance field in the scene pass, with its edge width taken from screen-space derivatives, so it stays sharp close up, far away and at a grazing angle. It is depth tested, so what stands in front of it hides it, and it sorts with the scene's other transparent draws. SceneWorldText.

Field	Type	Default	What it does
text	string	""	What it says. Each \n starts a line.
size	number	0.25	The em size in world units, before the node's scale. Above 0.
color	color	white	Its colour, straight alpha.
weight	integer	400	The face's weight, 100 to 900: 400 regular, 700 bold.
align	Start · Center · End	Center	How each line lines up across the text's width. The block of lines is centred on the node vertically.
lineSpacing	number	1	One line's top to the next, as a multiple of the face's line height. Above 0.
billboard	boolean	false	Turn to face the camera every frame, keeping the node's place and scale. Off, it lies in the node's XY plane facing its +Z.

See also

• Scene document schema
• Component map