ReferenceScripting API

Scripting API

Everything a scene's script can use, in Motion 0.4: the types Studio checks your scripts against (motion.d.ts). Each type has its own page, named as TypeScript names it (MotionScene); the objects a script calls are the globals below (scene is a MotionScene). For a gentler start, read Logic as code.

Globals

Name	Type	Description
`scene`	`MotionScene`	The scene: everything a script can do.
`callable`	`(options?: MotionCallableOptions) => Decorator & { pure: }`	Makes a method a node in the logic graph. callable.pure makes one without flow pins (the arrow-shaped ones), which only works out values. `import { callable } from "motion"`
`classes`	`Map<string, Function>`	Your scene's mote classes, by name. `import { classes } from "motion"`
`maths`	`MotionMaths`	Maths for code: noise, easing, smooth steps, ranges (the same as scene.maths). `import { maths } from "motion"`
`colour`	`MotionColour`	Colour for code (the same as scene.colour). `import { colour } from "motion"`
`stage`	`MotionStageApi`	The scene's motes. `import { stage } from "motion"`

Layers

Type	Kind	Description
`MotionEffect`	interface	One of a layer's effects (layer.effect).
`MotionLayer`	interface	One layer, to change without naming it each time (scene.layer).
`MotionScene`	interface	The scene: everything a script can do.

Time

Type	Kind	Description
`MotionClock`	interface	The clock where the desktop is.

Events

Type	Kind	Description
`MotionEvents`	interface	The events scene.on hears, and what each hands its function.

Sound

Type	Kind	Description
`MotionAudio`	interface	What's playing, heard through the computer, 0 to 1 each.
`MotionBeat`	interface	The beat of what's playing.
`MotionSound`	interface	A sound of the script's own (scene.loadSound): played as many times as asked, each a voice.
`MotionSoundLayer`	interface	A Sound layer, by its name or id (scene.sound).
`MotionVoice`	interface	One playing of a sound: turned, panned, sped, moved, stopped, or crossed over to another sound. Read it with its properties, change it with its methods.

Video

Type	Kind	Description
`MotionVideo`	interface	A Video layer's film (scene.video).
`VideoComponent`	class	A Video layer of a mote.

Particles

Type	Kind	Description
`MotionParticles`	interface	A particle layer's system (scene.particles): bursts, rates, pausing and clearing.
`ParticleComponent`	class	A particle layer of a mote.

3D

Type	Kind	Description
`CameraComponent`	class	A 3D layer's camera, as a mote's component (its layer the 3D layer).
`MeshComponent`	class	One item of a 3D layer: its settings are the item's own; a model's clips play here.
`MotionCamera`	interface	A 3D layer's camera (scene.camera).

Timeline

Type	Kind	Description
`MotionTimeline`	interface	The clock the scene's keyframes go by (scene.timeline): the scene's own time until a script plays, holds, seeks or speeds it.

Pointer

Type	Kind	Description
`DragComponent`	class	Lets the pointer drag its mote: pressed on it, the mote follows the pointer until let go.
`MotionPointer`	interface	The pointer over the wallpaper.

World

Type	Kind	Description
`MotionMedia`	interface	What's playing on the desktop (scene.media), as its media session says.
`MotionSystem`	interface	The computer's load (scene.system).
`MotionWeather`	interface	The weather where the desktop is (scene.weather), as a Weather layer shows it.

Web

Type	Kind	Description
`MotionFetched`	interface	What scene.fetch gives back.

Numbers and colours

Type	Kind	Description
`MotionColour`	interface	Colour for code (scene.colour, or import { colour } from "motion"): colours are "#rrggbb".
`MotionMaths`	interface	Maths for code, as the logic graph's nodes have it (scene.maths, or import { maths } from "motion").

Memory

Type	Kind	Description
`MotionStore`	interface	What a script keeps between runs (256 KB as JSON, 64 keys).

Motes

Type	Kind	Description
`Component`	class	A part of a mote, bound to one of its layers (or a 3D layer's item).
`Mote`	class	A thing in the scene with a place, made of components bound to its layers.
`MotionStageApi`	interface	The scene's motes: found, spawned and destroyed, and their physics.
`Signal`	class	An event others can bind to: sent by one, heard by any number.
`Stage`	class	The scene's own: one is made, to hear the scene; it has all of the stage's.
`Vector2`	class	A point or direction in 2D.
`Vector3`	class	A point or direction in 3D (a 2D mote's z is its depth).

Physics

Type	Kind	Description
`BodyComponent`	class	A mote's body, which Motion's physics moves.
`JointComponent`	class	Joins its mote's body to another's (stage.join), from connect() until disconnect().

The Stage

Type	Kind	Description
`AudioComponent`	class	Not in Motion yet: one does nothing for now.
`CharacterComponent`	class	Not in Motion yet: one does nothing for now.
`ColliderComponent`	class	Not in Motion yet: one does nothing for now (a body's collider is the body's own shape).
`DriveComponent`	class	Not in Motion yet: one does nothing for now.
`EffectComponent`	class	An effect layer of a mote.
`FollowComponent`	class	Not in Motion yet: one does nothing for now.
`ImageComponent`	class	An Image layer of a mote.
`LayerComponent`	class	A layer of a mote.
`LightComponent`	class	A light of a 3D layer.
`MotionHit`	interface	Where a mote was clicked: in the scene's pixels (location) and 0 to 1 (x, y), and with which button.
`MotionJointSpec`	interface	How two motes' bodies are joined (stage.join).
`MotionRayHit`	interface	What a ray met.
`MotionTicking`	interface	How often a mote ticks.
`MovementComponent`	class	Not in Motion yet: one does nothing for now.
`NestedSceneComponent`	class	A scene layer of a mote.
`PathComponent`	class	Not in Motion yet: one does nothing for now.
`RotatingComponent`	class	Not in Motion yet: one does nothing for now.
`Rotator`	interface	Pitch, yaw and roll, in degrees.
`ShaderComponent`	class	A Shader layer of a mote.
`ShapeComponent`	class	A Shape layer of a mote.
`SpriteComponent`	class	A Sprite layer of a mote.
`TextComponent`	class	A Text layer of a mote.
`TimelineComponent`	class	Not in Motion yet: one does nothing for now.
`TransformComponent`	class	A mote's place (its own).
`WanderComponent`	class	Not in Motion yet: one does nothing for now.
`WebComponent`	class	A web layer of a mote.

Types

Type	Kind	Description
`Easing`	type	How a move eases: one of the names, a cubic Bézier's control points [x1, y1, x2, y2] (as CSS has them), or a curve drawn as values evenly along it ({ curve: [y0, y1, ...] }).
`MotionAnimateOptions`	interface	How scene.animate moves: its easing ("easeInOut" unless given), a delay before it starts (seconds), and whether it loops (true round and round, "pingpong" there and back).
`MotionBounds`	interface	Where a layer is on the scene, 0 to 1 of it: the box round it, and its turn in degrees.
`MotionCallableOptions`	interface	What the callable decorator takes: the node's title, where the palette shows it, and how it's drawn.
`MotionEvent`	interface	One of the calendar's events: its title, start and end (ms since 1970, local time), and whether it lasts all day.
`MotionEventOptions`	interface	What scene.on's handler for loud or quiet listens for.
`MotionLayerInfo`	interface	A layer as scene.layers lists it.
`MotionPlace`	interface	A place for the weather, as a Weather layer's place names it: where it is, to a tenth of a degree, and its name.
`MotionPlaceableOptions`	interface	What the placeable and component decorators take: where Studio's palette shows the class, and the words it finds it by.
`MotionPlayOptions`	interface	How a sound plays: its volume (0 to 2), pan (-1 left to 1 right), speed (0.25 to 4, faster is higher), whether it loops, its fade in and where it starts (seconds).
`MotionPropertyOptions`	interface	What the property decorator takes: its range, unit and label in Studio's Details, and whether it's shown, exposed and kept.
`SettingValue`	type	A layer's setting's value: a number, words, true or false, a colour ("#rrggbb") or a list.

The labels for plain numbers and words that give a node's input its unit or a slider in Studio (Seconds, Metres, Int, Ranged<0, 1>…) are on Units and values.

Older scripts may use the names these types had before, which still work: AnimateOptions is MotionAnimateOptions, CallableOptions is MotionCallableOptions, Hit is MotionHit, JointSpec is MotionJointSpec, PlaceableOptions is MotionPlaceableOptions, PropertyOptions is MotionPropertyOptions, RayHit is MotionRayHit, StageApi is MotionStageApi, Ticking is MotionTicking.

The "motion" module

Type	Kind	Description
`motion`	module	What a script imports from "motion": the Stage's helpers, the decorators that make a class's members show in Studio, and the shared objects.