Stage

The play area and backdrop behind the sprites. It behaves like a special sprite that cannot move or be cloned, but holds the backdrops and can run its own stage-wide scripts (for example, when the backdrop changes).

The Stage engine class. Most members are available as free functions; this page documents the underlying API for advanced use.

answer

Stage.answer: string | null

The most recent answer the player typed in response to a question.

Since 1.0.0

arrayIncludes

Stage.arrayIncludes(array: T[], value: T): boolean

Checks whether a list contains a given value.

Since 1.0.0

askAndWait

Stage.askAndWait(question: string): Yielding<void>

Asks the player a question and pauses the script until they type an answer. In engine code this generator is awaited with yield*; in sprite code the free-function wrapper handles it.

Pauses the script (a generator). In sprite code the free-function wrapper awaits it for you.

Since 1.0.0

audioEffects

Stage.audioEffects: AudioEffectMap

The sound effects (like pitch or pan) currently applied to this sprite or stage’s sounds.

Since 1.0.0

broadcast

Stage.broadcast(name: string): Promise<void>

Sends a broadcast message and continues without waiting for the receiving scripts to finish.

Since 1.0.0

broadcastAndWait

Stage.broadcastAndWait(name: string): Yielding<void>

Sends a broadcast message and pauses the script until every receiving script has finished. In engine code this generator is awaited with yield*; in sprite code the free-function wrapper handles it.

Pauses the script (a generator). In sprite code the free-function wrapper awaits it for you.

Since 1.0.0

clearPen

Stage.clearPen(): void

Erases everything that has been drawn on the stage with the pen.

Since 1.0.0

compare

Stage.compare(v1: unknown, v2: unknown): number

Compares two values the way Scratch does, returning a negative, zero, or positive number.

Since 1.0.0

costume

Stage.costume: Costume

The Costume object currently being shown.

Since 1.0.0

costumeNumber

Stage.costumeNumber: number

The number of the backdrop currently being shown (1 is the first backdrop).

Since 1.0.0

degToRad

Stage.degToRad(deg: number): number

Converts an angle in degrees to radians.

Since 1.0.0

degToScratch

Stage.degToScratch(deg: number): number

Converts a standard angle in degrees to Scratch’s direction system.

Since 1.0.0

effects

Stage.effects: _EffectMap

The graphic effects (like color, ghost, or fisheye) currently applied to this sprite or stage.

Since 1.0.0

fence

Stage.fence: {
    left: number
    right: number
    top: number
    bottom: number
  }

The boundaries of the stage that keep sprites from wandering too far off screen.

Since 1.0.0

fireBackdropChanged

Stage.fireBackdropChanged(): Promise<void>

Fires the “when backdrop switches to” triggers for the current backdrop.

Since 1.0.0

getSound

Stage.getSound(soundName: string): Sound | undefined

Finds one of this sprite’s sounds by its name or number.

Since 1.0.0

height

Stage.height: number

The height of the stage in pixels.

Since 1.0.0

id

Stage.id: UID

A unique identifier for this sprite or stage.

Since 1.0.0

indexInArray

Stage.indexInArray(array: T[], value: T): number

Finds the position of a value within a list.

Since 1.0.0

itemOf

Stage.itemOf(array: T[], index: number): T | ""

Gets an item from a list by its position.

Since 1.0.0

keyPressed

Stage.keyPressed(name: string): boolean

Checks whether the given key is currently being pressed.

Since 1.0.0

letterOf

Stage.letterOf(string: string, index: number): string

Gets a single letter from text by its position.

Since 1.0.0

loudness

Stage.loudness: number

How loud the microphone input is, from 0 to 100.

Since 1.0.0

mouse

Stage.mouse: Mouse

The mouse, used to read the pointer’s position and whether it’s pressed.

Since 1.0.0

normalizeDeg

Stage.normalizeDeg(deg: number): number

Wraps an angle so it stays within the range of -180 to 180 degrees.

Since 1.0.0

playSoundUntilDone

Stage.playSoundUntilDone(soundName: string): Yielding<void>

Plays a sound and pauses the script until that sound finishes. In engine code this generator is awaited with yield*; in sprite code the free-function wrapper handles it.

Pauses the script (a generator). In sprite code the free-function wrapper awaits it for you.

Since 1.0.0

Example

yield* this.playSoundUntilDone("Meow")

radToDeg

Stage.radToDeg(rad: number): number

Converts an angle in radians to degrees.

Since 1.0.0

radToScratch

Stage.radToScratch(rad: number): number

Converts an angle in radians to a Scratch direction.

Since 1.0.0

random

Stage.random(a: number, b: number): number

Picks a random number between two values (whole numbers if both ends are whole).

Since 1.0.0

restartTimer

Stage.restartTimer(): void

Resets the timer back to zero.

Since 1.0.0

scratchTan

Stage.scratchTan(angle: number): number

Calculates the tangent of an angle in degrees, matching Scratch’s behavior at special angles.

Since 1.0.0

scratchToDeg

Stage.scratchToDeg(scratchDir: number): number

Converts a Scratch direction to a standard angle in degrees.

Since 1.0.0

scratchToRad

Stage.scratchToRad(scratchDir: number): number

Converts a Scratch direction to an angle in radians.

Since 1.0.0

sprites

Stage.sprites: Partial<Record<string, Sprite>>

All of the sprites in the project, keyed by name.

Since 1.0.0

stage

Stage.stage: Stage

The stage of the project, which all sprites share.

Since 1.0.0

startSound

Stage.startSound(soundName: string): Yielding<void>

Starts playing a sound and continues the script right away without waiting for it to finish. In engine code this generator is awaited with yield*; in sprite code the free-function wrapper handles it.

Pauses the script (a generator). In sprite code the free-function wrapper awaits it for you.

Since 1.0.0

stop

Stage.stop(option: StopOption): void

Stops running scripts based on the given option (for example, all scripts or just this one).

Since 1.0.0

stopAllOfMySounds

Stage.stopAllOfMySounds(): void

Stops only the sounds that this sprite or stage is playing.

Since 1.0.0

stopAllSounds

Stage.stopAllSounds(): void

Stops every sound playing in the whole project.

Since 1.0.0

stringIncludes

Stage.stringIncludes(string: string, substring: string): boolean

Checks whether one piece of text contains another, ignoring upper/lower case.

Since 1.0.0

timer

Stage.timer: number

The number of seconds since the timer was last started or reset.

Since 1.0.0

toBoolean

Stage.toBoolean(value: unknown): boolean

Converts a value into true or false, following Scratch’s rules.

Since 1.0.0

toNumber

Stage.toNumber(value: unknown): number

Converts a value into a number, treating invalid values as 0.

Since 1.0.0

toString

Stage.toString(value: unknown): string

Converts a value into text.

Since 1.0.0

triggers

Stage.triggers: Trigger[]

The list of event triggers (like “when green flag clicked”) attached to this sprite or stage.

Since 1.0.0

vars

Stage.vars: object

The variables belonging to this sprite or stage.

Since 1.0.0

wait

Stage.wait(secs: number): Yielding<void>

Pauses the running script for the given number of seconds. In engine code this generator is awaited with yield*; in sprite code the free-function wrapper handles it.

Pauses the script (a generator). In sprite code the free-function wrapper awaits it for you.

Since 1.0.0

warp

Stage.warp(procedure: GeneratorFunction): (...args: unknown[]) => void

Runs a script all at once without pausing, so it finishes in a single frame.

Since 1.0.0

watchers

Stage.watchers: Partial<Record<string, Watcher>>

The variable watchers shown on the stage for this sprite or stage, keyed by name.

Since 1.0.0

width

Stage.width: number

The width of the stage in pixels.

Since 1.0.0

wrapClamp

Stage.wrapClamp(n: number, min: number, max: number): number

Keeps a number within a range, wrapping any extra around to the other end.

Since 1.0.0