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_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_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_scaler	CanvasScaler	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
particle_emitter	ParticleEmitterSource	com.awakekt.awake.scene:particles	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

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_controls, canvas_element, canvas_follow_limit, canvas_follow_occlusion, canvas_scaler, day_cycle, fog, keyframe_animation, light, locomotion_animation, mesh_renderer, particle_emitter, pbr_material, shader_effect, skybox, spin_control, static_transform, tag, terrain, tone_mapping. 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
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, 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.

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; 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

Screen-space UI drawn over the game. 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, end, horizontal), image, fillImage, fillImageMode, cornerRadius, borderWidth, borderColor, shadow (color, offsetX, offsetY, blur, spread), textColor, textShadow (color, offsetX, offsetY), textOutline (color, width), alpha, rotation, linkColor, and hovered, pressed and disabled states for a Button. 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.
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.
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_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 works its scale out from the screen's size, so a HUD designed at one resolution fits every screen. A scene has one, on any node; without one the canvas draws at the scale its host passes. Every canvas_element size, offset, font and image is multiplied by the scale. SceneCanvasScaler, saved from the live CanvasScaler.

Field	Type	Default	What it does
mode	ScaleWithScreenSize · ConstantPixelSize · ConstantPhysicalSize	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.
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. 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. 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.

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 and jumping. SceneLocomotionAnimation.

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. 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.

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.

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).

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 and, with inheritOrientation, turns the spawn ring and velocity. 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.

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.

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.

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.

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.

See also

• Scene document schema
• Component map