ReferenceScripting APIMotionScene
MotionScene
interfaceThe scene: everything a script can do.
| Name | MotionScene |
|---|---|
| Kind | interface |
| Script reaches it as | scene (a global), or import scene from "motion" |
| Since | 0.3 |
Syntax
interface MotionScene { … }declare const scene: MotionScene;Sound
Properties
| Name | Type | Description |
|---|---|---|
audioproperty | readonly MotionAudio | What's playing, 0 to 1 each, when the computer listens. |
beatproperty | readonly MotionBeat | The beat of what's playing. |
spectrumproperty | readonly number[] | The sound's 64 bands, low to high (35 Hz to 10 kHz), 0 to 1 each. |
waveformproperty | readonly number[] | The sound's shape: 64 samples, -1 to 1. |
Methods
| Signature | Description |
|---|---|
loadSound(file: string, options?: { bus?: string }): MotionSoundmethod | Loads a sound file of the scene's folder, decoded as the scene opens. |
sound(name: string): MotionSoundLayermethod | A Sound layer, by its name or id. |
band(lowHz: number, highHz: number): numbermethod | How loud a band of pitches is, from the spectrum. |
Web
Methods
| Signature | Description |
|---|---|
sendToPage(layer: string, data: unknown): voidmethod | Sends something to a web project's page (its motion.on("message")). |
fetch(url: string, options?: { method?: "GET" | "POST" | "HEAD"; headers?: Record<string, string>; body?: unknown }): Promise<MotionFetched>method | Reads a web address on one of the sites the scene may read (Websites it may read, on the Scene's Script card), when the person allows it. |
prop<T>(id: string): Tmethod | One of the wallpaper's own settings. |
Layers
Properties
| Name | Type | Description |
|---|---|---|
layersproperty | readonly MotionLayerInfo[] | All of the scene's layers, bottom first: each one's id, name, kind and folder. |
foldersproperty | readonly ({ id: string; name: string; layers: string[] })[] | The scene's folders: each its id, name and the layers in it. |
widthproperty | readonly number | The scene's width, pixels. |
heightproperty | readonly number | The scene's height, pixels. |
Methods
| Signature | Description |
|---|---|
set(layer: string, setting: string, value: SettingValue): voidmethod | Changes one of a layer's settings at once. The value is kept in the setting's range. |
animate(layer: string, setting: string, value: string | number, seconds: number, options?: MotionAnimateOptions): Promise<boolean>method | Moves a number or a colour setting to a new value smoothly, over some seconds. |
stopAnimating(layer: string, setting?: string): voidmethod | Stops a layer's moves where they are now. |
get(layer: string, setting: string): SettingValue | undefinedmethod | A setting's value: what the script last set, or else what the scene started with. Not what keyframes, the sound or a move make it: see read. |
read(layer: string, setting: string): SettingValue | undefinedmethod | A setting as it was last drawn: its keyframes, the sound and moves in. |
show(layer: string, visible: boolean): voidmethod | Shows or hides a layer. |
hide(layer: string): voidmethod | Hides a layer. |
layer(name: string): MotionLayermethod | One layer, to change without naming it each time. |
layersNamed(name: string): MotionLayerInfo[]method | Every layer with a name, bottom first (a name can be shared; ids can't). |
layerAt(x: number, y: number): MotionLayerInfo | nullmethod | The top layer drawn at a point. |
bringToFront(layer: string): voidmethod | Moves a layer above the others beside it. |
sendToBack(layer: string): voidmethod | Moves a layer below the others beside it. |
clone(layer: string, name?: string): MotionLayermethod | A copy of a layer, just above it, while the scene plays. |
remove(layer: string): voidmethod | Takes a layer out of the scene while it plays (the scene's file is as it was). |
Text
Methods
Particles
Methods
| Signature | Description |
|---|---|
particles(layer: string): MotionParticlesmethod | A particle layer's system: bursts, rates, pausing. |
Video
Methods
| Signature | Description |
|---|---|
video(layer: string): MotionVideomethod | A Video layer's film: play, hold, seek and speed it. |
3D
Methods
| Signature | Description |
|---|---|
camera(layer: string): MotionCameramethod | A 3D layer's camera. |
pickItem(layer: string, x: number, y: number): Promise<{ item: number; mote: Mote | null } | null>method | Which of a 3D layer's items is under a point, as last drawn. |
Time
Properties
| Name | Type | Description |
|---|---|---|
timeproperty | readonly number | How long the scene has been playing, seconds. |
pausedproperty | readonly boolean | Whether the wallpaper is paused just now (covered by a window, on battery, or by hand). |
qualityproperty | readonly number | How finely the wallpaper is drawn, 0 to 1: lower on battery or a slow computer. |
tickRateproperty | number | Ticks a second the script hears (scene.on("tick"), timers); 0, the default, is every frame. Set it to tick less often. |
clockproperty | readonly MotionClock | The clock where the desktop is. |
Methods
| Signature | Description |
|---|---|
every(seconds: number, fn: () => void): numbermethod | Runs a function again and again, every so many seconds. |
after(seconds: number, fn: () => void): numbermethod | Runs a function once, after some seconds. |
cancel(id: number): voidmethod | Stops something scene.every or scene.after would run. |
Events
Methods
| Signature | Description |
|---|---|
on<E extends keyof MotionEvents>(event: E, fn: MotionEvents[E], options?: MotionEventOptions): () => voidmethod | Listens for something happening. |
off<E extends keyof MotionEvents>(event: E, fn: MotionEvents[E]): voidmethod | Stops listening. |
Sensors
Methods
| Signature | Description |
|---|---|
sensor(name: string): { value: any; at: number } | nullmethod | The latest reading of one of the scene's sensors (those its Sensors tab lists). |
onSensor<T>(name: string, fn: (value: T, at: number) => void): () => voidmethod | Listens for one of the scene's sensors' readings. |
sensorAge(name: string): number | nullmethod | How long since one of the scene's sensors' last reading. |
sensors(): ({ sensor: string; share: string })[]method | The sensors the scene listens to, as its Sensors tab lists them. |
Numbers and colours
Properties
| Name | Type | Description |
|---|---|---|
mathsproperty | readonly MotionMaths | Maths for code: noise, easing, smooth steps, ranges. |
colourproperty | readonly MotionColour | Colour for code: lighter, more colourful, opposite, from a temperature. |
Methods
| Signature | Description |
|---|---|
random(min?: number, max?: number): numbermethod | A random number: 0 to 1, 0 to max, or min to max. |
seed(n: number): voidmethod | Makes random numbers repeat: the same seed, the same numbers. |
pick<T>(list: readonly T[]): T | undefinedmethod | A random one of a list. |
lerp(a: number, b: number, t: number): numbermethod | Between a and b, t of the way. |
clamp(v: number, lo: number, hi: number): numbermethod | A number kept within lo and hi. |
mix(a: string, b: string, t: number): stringmethod | Between two colours, t of the way. |
hsv(h: number, s: number, v: number): stringmethod | A colour from its hue, saturation and value. |
Memory
Properties
| Name | Type | Description |
|---|---|---|
storeproperty | readonly MotionStore | What the script keeps between runs (the scene's own). |
Methods
| Signature | Description |
|---|---|
storeFor(scope: "scene" | "screen"): MotionStoremethod | A store of a scope: the scene's own ("scene"), or this screen's ("screen": each screen of several keeps its own). |
The console
Methods
Environment
Properties
| Name | Type | Description |
|---|---|---|
fpsproperty | readonly number | Frames a second the wallpaper is drawn at now (smoothed): lower on battery, or when it's busy. |
isPreviewproperty | readonly boolean | Whether it's playing in Studio's preview rather than on the desktop. |
platformproperty | readonly "windows" | "linux" | "android" | What it runs on: "windows", "linux" or "android". |
localeproperty | readonly string | The person's language, as a tag: "en-GB", "de-DE"... |
screenproperty | readonly { index: number; count: number; dpr: number } | Which screen this is (0 the first), of how many, and its pixels to a point. |
Pointer
Properties
| Name | Type | Description |
|---|---|---|
capturedproperty | readonly boolean | Whether the scene has the keyboard and pointer (the person gave them: requestInput). |
pointerproperty | readonly MotionPointer | The pointer over the wallpaper. |
Methods
| Signature | Description |
|---|---|
requestInput(): voidmethod | Asks for the keyboard and pointer, as a game layer does: the person gives them with a click on the scene's Play, and key and pad are heard while it has them. |
releaseInput(): voidmethod | Gives the keyboard and pointer back. |
World
Properties
| Name | Type | Description |
|---|---|---|
weatherproperty | readonly MotionWeather | null | The desktop's weather, or null until it says. |
mediaproperty | readonly MotionMedia | null | What's playing on the desktop: the track, its artist and album, its cover, where it is. |
calendarproperty | readonly { events: MotionEvent[] } | null | The next days' calendar events (the desktop's own calendar, or the folder of .ics files picked in Motion's settings). |
systemproperty | readonly MotionSystem | null | The computer's load: processor, memory, disk, temperature, network, battery. |
Methods
| Signature | Description |
|---|---|
weatherAt(place: string | MotionPlace): MotionWeather | nullmethod | The weather at a place the scene names itself: a Weather layer's Place, or a setting that follows the weather at a place of its own. |
mediaPosition(): numbermethod | Where what's playing is now, seconds: from what the desktop last said, on since while it plays. |
Timeline
Properties
| Name | Type | Description |
|---|---|---|
timelineproperty | readonly MotionTimeline | The keyframes' clock: play, hold, seek and speed them. |
See also
MotionSound · MotionSoundLayer · SettingValue · MotionLayer · MotionLayerInfo · MotionParticles · MotionVideo · MotionCamera
Notes from the community
Written by creators and checked by the docs' editors. Not part of Motion's official reference.