Sprite

A character on the stage: it has a position, a direction, costumes, and the motion, looks, sound, and sensing abilities that game scripts control. Most of the code learners write lives on a sprite.

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

Edge

Sprite.Edge: Readonly<{ BOTTOM: symbol; LEFT: symbol; RIGHT: symbol; TOP: symbol; }>

The names of the stage’s edges (top, bottom, left, and right).

Since 1.0.0

RotationStyle

Sprite.RotationStyle: Readonly<{ ALL_AROUND: symbol; LEFT_RIGHT: symbol; DONT_ROTATE: symbol; }>

The available rotation styles a sprite can use (all around, left-right, or don’t rotate).

Since 1.0.0

andClones

Sprite.andClones(): this[]

Returns this sprite together with all of its clones as one list.

Since 1.0.0

answer

Sprite.answer: string | null

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

Since 1.0.0

arrayIncludes

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

Checks whether a list contains a given value.

Since 1.0.0

askAndWait

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

Asks the player a question and pauses until they answer, hiding any speech bubble first. 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

Sprite.audioEffects: AudioEffectMap

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

Since 1.0.0

broadcast

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

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

Since 1.0.0

broadcastAndWait

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

Sprite.clearPen(): void

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

Since 1.0.0

clones

Sprite.clones: this[]

The list of clones made from this sprite.

Since 1.0.0

colorTouching

Sprite.colorTouching(color: Color | string, target: Sprite | Stage): boolean

Checks whether a color on this sprite is touching a color or another sprite.

Since 1.0.0

compare

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

Sprite.costume: Costume

The Costume object currently being shown.

Since 1.0.0

costumeNumber

Sprite.costumeNumber: number

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

Since 1.0.0

createClone

Sprite.createClone(data?: unknown): void

Makes a copy of this sprite that starts running its “when I start as a clone” scripts.

Since 1.0.0

degToRad

Sprite.degToRad(deg: number): number

Converts an angle in degrees to radians.

Since 1.0.0

degToScratch

Sprite.degToScratch(deg: number): number

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

Since 1.0.0

deleteThisClone

Sprite.deleteThisClone(): void

Deletes this clone and stops its scripts (does nothing on the original sprite).

Since 1.0.0

direction

Sprite.direction: number

The direction the sprite is pointing, in degrees (90 is to the right).

Since 1.0.0

effects

Sprite.effects: _EffectMap

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

Since 1.0.0

getSound

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

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

Since 1.0.0

glide

Sprite.glide(seconds: number, x: number, y: number): Yielding<void>

Smoothly slides the sprite to a new position over 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

Example

yield* this.glide(1, 100, 50)

goto

Sprite.goto(x: number, y: number): void

Moves the sprite instantly to the given x and y position, drawing a pen line if the pen is down.

Since 1.0.0

Example

this.goto(0, 0)

id

Sprite.id: UID

A unique identifier for this sprite or stage.

Since 1.0.0

ifOnEdgeBounce

Sprite.ifOnEdgeBounce(): void

Makes the sprite turn around when it reaches the edge of the stage.

Since 1.0.0

indexInArray

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

Finds the position of a value within a list.

Since 1.0.0

itemOf

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

Gets an item from a list by its position.

Since 1.0.0

keyPressed

Sprite.keyPressed(name: string): boolean

Checks whether the given key is currently being pressed.

Since 1.0.0

letterOf

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

Gets a single letter from text by its position.

Since 1.0.0

loudness

Sprite.loudness: number

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

Since 1.0.0

mouse

Sprite.mouse: Mouse

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

Since 1.0.0

move

Sprite.move(dist: number): void

Moves the sprite forward in the direction it is facing by the given number of steps.

Since 1.0.0

Example

this.move(10)

moveAhead

Sprite.moveAhead(value?: number | Sprite): void

Moves the sprite forward in the layers, either by a number of layers or in front of another sprite.

Since 1.0.0

moveBehind

Sprite.moveBehind(value?: number | Sprite): void

Moves the sprite backward in the layers, either by a number of layers or behind another sprite.

Since 1.0.0

nearestEdge

Sprite.nearestEdge(): symbol | null

Finds which edge of the stage the sprite is touching, or null if it isn’t touching one.

Since 1.0.0

normalizeDeg

Sprite.normalizeDeg(deg: number): number

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

Since 1.0.0

penColor

Sprite.penColor: Color

The color the pen draws with.

Since 1.0.0

penDown

Sprite.penDown: boolean

Whether the pen is down, so the sprite draws a line as it moves.

Since 1.0.0

penSize

Sprite.penSize: number

The thickness of the line the pen draws.

Since 1.0.0

playSoundUntilDone

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

positionInFence

Sprite.positionInFence(): void

Nudges the sprite back so it stays at least partly inside the stage’s edges.

Since 1.0.0

radToDeg

Sprite.radToDeg(rad: number): number

Converts an angle in radians to degrees.

Since 1.0.0

radToScratch

Sprite.radToScratch(rad: number): number

Converts an angle in radians to a Scratch direction.

Since 1.0.0

random

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

Sprite.restartTimer(): void

Resets the timer back to zero.

Since 1.0.0

rotationStyle

Sprite.rotationStyle: RotationStyle

How the sprite turns when its direction changes (all around, left-right, or not at all).

Since 1.0.0

say

Sprite.say(text: string): void

Shows a speech bubble with the given text above the sprite.

Since 1.0.0

Example

this.say("Hello!")

sayAndWait

Sprite.sayAndWait(text: string, seconds: number): Yielding<void>

Shows a speech bubble for the given number of seconds, pausing the script until it’s done. 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

scratchTan

Sprite.scratchTan(angle: number): number

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

Since 1.0.0

scratchToDeg

Sprite.scratchToDeg(scratchDir: number): number

Converts a Scratch direction to a standard angle in degrees.

Since 1.0.0

scratchToRad

Sprite.scratchToRad(scratchDir: number): number

Converts a Scratch direction to an angle in radians.

Since 1.0.0

size

Sprite.size: number

The sprite’s size as a percentage, where 100 is its normal size.

Since 1.0.0

sprites

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

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

Since 1.0.0

stage

Sprite.stage: Stage

The stage of the project, which all sprites share.

Since 1.0.0

stamp

Sprite.stamp(): void

Stamps a copy of the sprite’s current look onto the stage with the pen.

Since 1.0.0

startSound

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

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

Sprite.stopAllOfMySounds(): void

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

Since 1.0.0

stopAllSounds

Sprite.stopAllSounds(): void

Stops every sound playing in the whole project.

Since 1.0.0

stringIncludes

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

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

Since 1.0.0

think

Sprite.think(text: string): void

Shows a thought bubble with the given text above the sprite.

Since 1.0.0

thinkAndWait

Sprite.thinkAndWait(text: string, seconds: number): Yielding<void>

Shows a thought bubble for the given number of seconds, pausing the script until it’s done. 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

timer

Sprite.timer: number

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

Since 1.0.0

toBoolean

Sprite.toBoolean(value: unknown): boolean

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

Since 1.0.0

toNumber

Sprite.toNumber(value: unknown): number

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

Since 1.0.0

toString

Sprite.toString(value: unknown): string

Converts a value into text.

Since 1.0.0

touching

Sprite.touching(target: "mouse" | "edge" | Sprite | Stage, fast?: boolean): boolean

Checks whether the sprite is touching the mouse pointer, the edge, or another sprite.

Since 1.0.0

triggers

Sprite.triggers: Trigger[]

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

Since 1.0.0

vars

Sprite.vars: object

The variables belonging to this sprite or stage.

Since 1.0.0

visible

Sprite.visible: boolean

Whether the sprite is currently shown on the stage.

Since 1.0.0

wait

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

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

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

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

Since 1.0.0

wrapClamp

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

x

Sprite.x: number

The sprite’s x position (left-right) on the stage.

Since 1.0.0

y

Sprite.y: number

The sprite’s y position (up-down) on the stage.

Since 1.0.0