Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Sprites

DISABLE SPRITE · EMITPARTICLE · ENABLE SPRITE · HIDE SPRITE · MOVE SPRITE · RESERVE SPRITE · SET SPRITE · SHOW SPRITE · SPRITE RESET · collisions · framecount · getspritemeta · imagebbox · nextfreesprite · spritebbox · spritecollisionid · spritecount · spritedirection · spritedist · spriteelevation · spriteenabled · spriteheight · sprites · spritetag · spritevisible · spritewidth · spritex · spritey

DISABLE SPRITE

Disable a sprite slot: it stops drawing and colliding.

DISABLE SPRITE id
disable_sprite(id)

Parameters

  • id AS NUMBER - Sprite number.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0) tag("coin")
SHOW SPRITE 0
PRINT spritecount("coin")
DISABLE SPRITE 0
// A disabled slot is free again
PRINT spritecount("coin"), nextfreesprite()

Notes

It’s also the function disable_sprite, for when you want what it gives back.

EMITPARTICLE

Emit a particle: an image, or a copy of a shape, driven by a behavior or pattern and gone after ticks ticks.

EMITPARTICLE at, source, tag, motion, ticks
emitparticle(at, source, tag, motion, ticks)

Also documents: alpha, bbox, behavior, behavior_params, clear_behaviors, clear_max_acceleration, clear_max_velocity, clear_pattern, clear_shader, color, fill, flip_x, flip_y, frame, layer, max_acceleration, max_velocity, one_way, origin, params, pattern, pattern_params, remove_behavior, rotate, rotate_origin, scale, scale_to, shader, shader_params, solid, sprites, texture, uv, velocity, z_order

Parameters

  • at AS COORDINATE - Where it starts: (x, y).
  • source - An image name, or a MUTATION whose copy the particle is.
  • tag AS STRING - Its tag.
  • motion AS STRING - The behavior or pattern that drives it.
  • ticks AS NUMBER - How many ticks it lives.

After !!

  • alpha(value AS NUMBER) - Opacity, 0-1.
  • bbox(value AS VECTOR) - Collision box, from its top-left to its bottom-right, 0-1 across the shape, so (0, 0) to (1, 1) is the whole shape.
  • behavior(value AS STRING) - Attach a behavior.
  • behavior_params(value) - Values for the behavior’s @parameters, by name.
  • clear_behaviors(on = TRUE) - Remove every behavior.
  • clear_max_acceleration(on = TRUE) - Remove its acceleration cap.
  • clear_max_velocity(on = TRUE) - Remove its speed cap.
  • clear_pattern(on = TRUE) - Stop its pattern.
  • clear_shader(on = TRUE) - Remove its shader.
  • color(value AS NUMBER) - Outline palette index (or colour).
  • fill(value AS NUMBER) - Fill palette index (or colour).
  • flip_x(on = TRUE) - Mirror horizontally.
  • flip_y(on = TRUE) - Mirror vertically.
  • frame(value AS NUMBER) - Spritesheet frame (an image particle only; a shape has no frames).
  • layer(value AS NUMBER) - The layer it draws above.
  • max_acceleration(value AS COORDINATE) - Cap its acceleration per axis: (x, y).
  • max_velocity(value AS COORDINATE) - Cap its speed per axis: (x, y).
  • one_way(value) - Solid from one side only: “top”, “bottom”, “left” or “right”; off for ONEWAY OFF.
  • origin(value AS COORDINATE) - The anchor it is placed by, 0-1 across its extent.
  • params(value) - Values for the pattern’s or behavior’s @parameters, by name.
  • pattern(value AS STRING) - Run a pattern.
  • pattern_params(value) - Values for the pattern’s @parameters, by name.
  • remove_behavior(value) - Remove a behavior, or a list of them. Removed before behavior= is added.
  • rotate(value AS NUMBER) - Turn it to this many degrees (a pose).
  • rotate_origin(value AS COORDINATE) - The point it turns about, 0-1 across its extent.
  • scale(value) - Scale it: (sx, sy) (1 is actual size).
  • scale_to(value AS COORDINATE) - Scale it to (width, height) pixels.
  • shader(value AS STRING) - Run a shader over it.
  • shader_params(value) - Values for the shader’s @parameters, by name: a number for a USE NUMBER, three or four numbers from 0 to 1 for a USE COLOR, a picture’s name for a USE IMAGE. A name the shader doesn’t have is an error.
  • solid(value) - Give it a collider: on (a circle), or “circle”, “box” or “poly” (its real outline).
  • sprites(value AS ARRAY) - Tags it collides with, as SOLID SPRITES(...); [] clears them.
  • texture(value AS STRING) - An image to texture the shape with.
  • uv(value AS ARRAY) - A shape whose points are per-vertex texture coordinates (0-1).
  • velocity(value AS COORDINATE) - Set its velocity: (vx, vy).
  • z_order(value AS NUMBER) - Draw order within the layer.

Examples

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
BEHAVIOR "fade_out"
    ALPHA 1, 0, 60
END BEHAVIOR
// A spark that fades out over a second and is gone
EMITPARTICLE (100, 100), "hero", "spark", "fade_out", 60 !! frame(1)
PRINT spritecount("spark")

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
BEHAVIOR "burst"
    IMPULSE PARAM("vx", 0), PARAM("vy", 0)
    FRICTION 0.05, 0.05
END BEHAVIOR
// An explosion: twenty particles, each thrown its own way
FOR i = 0 ... 19
    angle = i * 2 * PI / 20
    EMITPARTICLE (160, 120), "hero", "debris", "burst", 45 !! params({vx: COS(angle) * 4, vy: SIN(angle) * 4}) scale((0.5, 0.5)) alpha(0.8)
END FOR
PRINT spritecount("debris")

Notes

It’s also the function emitparticle, for when you want what it gives back.

See also: BEHAVIOR, param

ENABLE SPRITE

Enable a sprite slot.

ENABLE SPRITE id
enable_sprite(id)

Parameters

  • id AS NUMBER - Sprite number.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(160) y(120) image("hero") frame(0)
SHOW SPRITE 0
PRINT spriteenabled(0), spriteenabled(1)

Notes

It’s also the function enable_sprite, for when you want what it gives back.

HIDE SPRITE

Hide a sprite.

HIDE SPRITE id
hide_sprite(id)

Parameters

  • id AS NUMBER - Sprite number.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
SHOW SPRITE 0
HIDE SPRITE 0
// Hidden, but still enabled: it keeps its place and its slot
PRINT spritevisible(0), spriteenabled(0)

Notes

It’s also the function hide_sprite, for when you want what it gives back.

MOVE SPRITE

Move a sprite to (x, y).

MOVE SPRITE id, at
move_sprite(id, at)

Parameters

  • id AS NUMBER - Sprite number.
  • at AS COORDINATE - Where: (x, y).

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(10) y(10) image("hero") frame(0)
SHOW SPRITE 0
MOVE SPRITE 0, (150, 80)
PRINT spritex(0), spritey(0)

Notes

It’s also the function move_sprite, for when you want what it gives back.

RESERVE SPRITE

Claim the next free sprite slot and return its number (-1 when none is free).

RESERVE SPRITE
reserve_sprite()

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
id = reserve_sprite()
SET SPRITE id !! x(50) y(50) image("hero") frame(0)
// The slot is taken now, so the next one is another
other = reserve_sprite()
PRINT id, other, id <> other

Notes

It’s also the function reserve_sprite, for when you want what it gives back.

SET SPRITE

Place a sprite with an image (id, x, y, image), or change one already enabled or placed: any of x, y and image on its own (an enabled sprite still needs its image), and any modifiers.

SET SPRITE id
set_sprite(id)

Also documents: alpha, bbox, behavior, behavior_params, clear_behaviors, clear_ik, clear_limit, clear_max_acceleration, clear_max_velocity, clear_parent, clear_pattern, clear_pin, clear_shader, elevation, flip_x, flip_y, frame, ghost, ik_bend, ik_iterations, ik_length, ik_mix, ik_target, image, layer, limit_axis, limit_x, limit_y, location, max_acceleration, max_velocity, meta, meta_key, one_way, origin, parent, parent_polygon, pattern, pattern_params, pin_mix, pin_target, remove_behavior, reset, rigid, rotate, rotate_origin, scale, scale_to, shader, shader_params, solid, sprites, sync, sync_room, tag, velocity, x, y, z_order

Parameters

  • id AS NUMBER - Sprite number.

After !!

  • alpha(value AS NUMBER) - Opacity, 0-1.
  • bbox(value AS VECTOR) - Collision box, from its top-left to its bottom-right, 0-1 across the sprite, so (0, 0) to (1, 1) is the whole sprite.
  • behavior(value AS STRING) - Attach a behavior.
  • behavior_params(value) - Values for the behavior’s @parameters, by name.
  • clear_behaviors(on = TRUE) - Remove every behavior.
  • clear_ik(on = TRUE) - Remove its IK constraint.
  • clear_limit(on = TRUE) - Remove its limit.
  • clear_max_acceleration(on = TRUE) - Remove its acceleration cap.
  • clear_max_velocity(on = TRUE) - Remove its speed cap.
  • clear_parent(on = TRUE) - Detach from the parent.
  • clear_pattern(on = TRUE) - Stop its pattern.
  • clear_pin(on = TRUE) - Remove its pin.
  • clear_shader(on = TRUE) - Remove its shader.
  • elevation(value AS NUMBER) - Height above a plane layer, in world units.
  • flip_x(on = TRUE) - Mirror horizontally.
  • flip_y(on = TRUE) - Mirror vertically.
  • frame(value AS NUMBER) - Spritesheet frame.
  • ghost(on = TRUE) - Drop its collider.
  • ik_bend(value AS STRING) - Which way its joints bend: “cw” or “ccw”.
  • ik_iterations(value AS NUMBER) - Solver passes per tick.
  • ik_length(value AS NUMBER) - How many parents the IK chain bends.
  • ik_mix(value AS NUMBER) - Blend, 0-1, between the posed and the solved chain.
  • ik_target(value AS COORDINATE) - Inverse kinematics: reach the chain ending at this sprite toward (x, y).
  • image(value AS STRING) - The image it shows.
  • layer(value AS NUMBER) - The layer it draws on.
  • limit_axis(value AS STRING) - Lock it to sliding along “x” or “y”.
  • limit_x(value AS RANGE) - Clamp its x to min ... max.
  • limit_y(value AS RANGE) - Clamp its y to min ... max.
  • location(value AS COORDINATE) - Place it: (x, y) is where its ORIGIN goes.
  • max_acceleration(value AS COORDINATE) - Cap its acceleration per axis: (x, y).
  • max_velocity(value AS COORDINATE) - Cap its speed per axis: (x, y).
  • meta(value) - Attach data to it, or one key’s value with meta_key.
  • meta_key(value AS STRING) - The key meta sets.
  • one_way(value) - Solid from one side only: “top”, “bottom”, “left” or “right”; off for ONEWAY OFF.
  • origin(value AS COORDINATE) - The anchor it is placed by, 0-1 across its extent.
  • parent(value AS NUMBER) - Attach to a sprite.
  • parent_polygon(value AS NUMBER) - Attach to a bound polygon.
  • pattern(value AS STRING) - Run a pattern.
  • pattern_params(value) - Values for the pattern’s @parameters, by name.
  • pin_mix(value AS NUMBER) - How strongly, 0-1.
  • pin_target(value AS COORDINATE) - Pull its position toward (x, y) each tick.
  • remove_behavior(value) - Remove a behavior, or a list of them. Removed before behavior= is added.
  • reset(on = TRUE) - Clear velocity, acceleration, pose, behaviors and pattern.
  • rigid(on = TRUE) - Orbit and turn with the parent, not just follow it.
  • rotate(value AS NUMBER) - Rotation in degrees.
  • rotate_origin(value AS COORDINATE) - The point it turns about, 0-1 across its extent.
  • scale(value) - Scale: (sx, sy) (1 is actual size).
  • scale_to(value AS COORDINATE) - Scale to (width, height) pixels.
  • shader(value AS STRING) - Run a shader over it.
  • shader_params(value) - Values for the shader’s @parameters, by name: a number for a USE NUMBER, three or four numbers from 0 to 1 for a USE COLOR, a picture’s name for a USE IMAGE. A name the shader doesn’t have is an error.
  • solid(on = TRUE) - Collide with boundaries.
  • sprites(value AS ARRAY) - Tags it also collides with; [] clears them.
  • sync(on = TRUE) - Multiplayer: broadcast it to every player when on, or stop when off.
  • sync_room(value AS STRING) - Multiplayer: broadcast it only within this room.
  • tag(value AS STRING) - A name for the kind of thing it is (“wall”, “coin”), shared by as many sprites as you like: another sprite collides with it by listing this tag in its sprites, and collision handlers, spritetag, spritecollision and spritetouching give or match it.
  • velocity(value AS COORDINATE) - Set its velocity: (vx, vy).
  • x(value AS NUMBER) - X position.
  • y(value AS NUMBER) - Y position.
  • z_order(value AS NUMBER) - Draw order within the layer.

Examples

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(160) y(120) image("hero") frame(0) origin((0.5, 0.5)) scale((2, 2)) tag("hero")
SHOW SPRITE 0
// Later: change only what changes
SET SPRITE 0 !! flip_x alpha(0.8)
SET SPRITE 0 !! location((200, 120)) rotate(45)
PRINT spritetag(0), spritewidth(0), spriteheight(0)

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
// A sword that follows the hero, orbiting and turning with it
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0) origin((0.5, 0.5))
SHOW SPRITE 0
ENABLE SPRITE 1
SET SPRITE 1 !! x(112) y(100) image("hero") frame(1) origin((0, 0.5)) parent(0) rigid
SHOW SPRITE 1
SET SPRITE 0 !! rotate(30)
PRINT "sword attached"

Notes

It’s also the function set_sprite, for when you want what it gives back.

See also: BEHAVIOR, param, PATTERN

SHOW SPRITE

Show a sprite.

SHOW SPRITE id
show_sprite(id)

Parameters

  • id AS NUMBER - Sprite number.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
HIDE SPRITE 0
PRINT spritevisible(0)
SHOW SPRITE 0
PRINT spritevisible(0)

Notes

It’s also the function show_sprite, for when you want what it gives back.

SPRITE RESET

Reset a sprite’s motion, pose, behaviors and pattern, keeping where it is and what it shows.

SPRITE RESET id
sprite_reset(id)

Parameters

  • id AS NUMBER - Sprite number.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
BEHAVIOR "spin"
    ROTATE 360, 30
END BEHAVIOR
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0) behavior("spin") velocity((2, 0))
SHOW SPRITE 0
PRINT hasbehavior(0, "spin")
SPRITE RESET 0
// Still there, still the hero, but no longer moving or spinning
PRINT hasbehavior(0, "spin"), spriteenabled(0)

Notes

It’s also the function sprite_reset, for when you want what it gives back.

collisions

Every pair of sprites touching now, each with a and b. With boundaries, a pair also has the boundary’s tag and the edge that was hit.

collisions
collisions(boundaries = FALSE)

Also documents: boundaries

Parameters

  • boundaries = FALSE

After !!

  • boundaries(on = TRUE) - Look at boundaries too: each pair then has the boundary’s tag and the edge that was hit.

Example

SCREEN 320, 240
BOUNDARY ADD "wall", (0, 0) -> (320, 240) !! solid
touching = COLLISIONS() !! boundaries
FOR hit = touching
    PRINT hit.a, hit.b, hit.tag, hit.edge
END FOR
PRINT "checked"

framecount

Returns the number of frames in a sprite sheet loaded with LOADIMG AS SPRITESHEET.

framecount(image_name)

Parameters

  • image_name - Name of sprite sheet image resource

Examples

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
PRINT framecount("hero")

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
SHOW SPRITE 0
// Step to the next frame, wrapping round at the end of the sheet
f = 0
FOR i = 1 ... 8
    f = (f + 1) MOD framecount("hero")
    SET SPRITE 0 !! x(100) y(100) image("hero") frame(f)
    PRINT f
END FOR

getspritemeta

Retrieves metadata previously stored on a sprite using SET SPRITE META. Supports both single-value and key-value retrieval. Returns the stored value (number, string, or object), or 0 if no metadata has been set for that key. Crash BASIC has no null: a missing key and a stored 0 are indistinguishable, so if 0 is a meaningful value for your metadata, store a sentinel (-1) or a separate “has” key rather than testing the value itself. It can be written getspritemeta(sprite_num) or getspritemeta(sprite_num, key).

getspritemeta(sprite_num, key = NULL)

Parameters

  • sprite_num - Sprite slot number (0-99,999)
  • key = NULL - Optional string key to retrieve specific value (e.g., “health”, “lives”)

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
SHOW SPRITE 0
SET SPRITE 0 !! meta(100) meta_key("health")
PRINT getspritemeta(0, "health")
// Nothing stored under "lives"
PRINT getspritemeta(0, "lives")

imagebbox

Returns a named Aseprite slice’s bounding box on a given frame of a loaded .ase image, as a Range (x1,y1)-(x2,y2) in RELATIVE 0-1 coordinates. There’s no sprite context, so no world position — combine the relative box with a position yourself, feed it straight into SET SPRITE id BBOX <range>, or use SPRITEBBOX when you want world coordinates for a placed sprite.

imagebbox(image, slice_name, frame)

Parameters

  • image - Name an .ase image was loaded under with LOADIMG (case-insensitive)
  • slice_name - Aseprite slice name (case-insensitive)
  • frame - Absolute frame index (0-based)

Example

SCREEN 320, 240
// knight.ase: one 16x16 frame with a slice called "hitbox" at (4, 2), 8x12
LOADIMG "knight.ase", "knight"
box = imagebbox("knight", "hitbox", 0)
PRINT box

nextfreesprite

Returns the index of the next available (not enabled) sprite slot. Use this function to get a free sprite from the pool without manually tracking which sprites are in use. When a sprite is disabled, its slot becomes available again and can be returned by this function.

nextfreesprite

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
FOR i = 1 ... 3
    id = nextfreesprite()
    ENABLE SPRITE id
    SET SPRITE id !! x(i * 40) y(100) image("hero") frame(0) tag("enemy")
    SHOW SPRITE id
END FOR
PRINT spritecount("enemy"), "enemies, next free slot", nextfreesprite()

spritebbox

Returns a sprite’s bounding box in WORLD pixels as a Range (x1,y1)-(x2,y2), ready for manual hit-detection. With no slice name it returns the sprite’s active collision box — its custom BBOX, or the full frame if none is set. With a slice name it returns that Aseprite slice’s box at the sprite’s CURRENT animation frame. World coordinates account for the sprite’s position (including any parent), its scale and its ORIGIN. A bbox is relative to the IMAGE and ORIGIN does not reshape it — but ORIGIN moves the image, and the box travels with it, so the rectangle returned here is exactly the one collision tests.

spritebbox(id, slice_name = NULL)

Parameters

  • id - Sprite id
  • slice_name = NULL - Optional Aseprite slice name (case-insensitive). Omit for the sprite’s active collision box.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(10) y(20) image("hero") frame(0) origin((0.5, 0.5))
SHOW SPRITE 0
// Its collision box in world pixels, ORIGIN taken into account
PRINT spritebbox(0)

spritecollisionid

Returns the sprite ID of the first sprite tagged tag that spriteNum is colliding with, or -1 if it is colliding with none.

spritecollisionid(sprite_num, tag)

Parameters

  • sprite_num - Sprite slot number to test
  • tag - Tag to match against. Matched case-insensitively.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
SHOW SPRITE 0
ENABLE SPRITE 7
SET SPRITE 7 !! x(108) y(100) image("hero") frame(0) tag("coin")
SHOW SPRITE 7
hit = spritecollisionid(0, "coin")
// 0 is a real sprite, so test against -1
IF hit <> -1 THEN DISABLE SPRITE hit
PRINT hit

spritecount

Returns the number of currently enabled sprites that have the specified tag. This is useful for checking how many enemies remain, counting collectibles, or managing spawn limits. Only enabled sprites are counted.

spritecount(tag_name)

Parameters

  • tag_name - String expression for the tag to count (case-sensitive: a sprite tagged “Hero” is not counted by SPRITECOUNT(“hero”))

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
FOR id = 0 ... 4
    ENABLE SPRITE id
    SET SPRITE id !! x(id * 30) y(50) image("hero") frame(0) tag("enemy")
    SHOW SPRITE id
END FOR
DISABLE SPRITE 2
PRINT spritecount("enemy"), "enemies left"

spritedirection

Returns the last movement direction of a sprite in degrees. 0 = right, 90 = down, 180 = left, 270 = up. Direction is updated whenever the sprite moves via behaviors. Returns 0 if sprite has not moved.

spritedirection(sprite_num)

Parameters

  • sprite_num - Sprite slot number (0-99,999)

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
BEHAVIOR "down"
    VELOCITY 0, 2
END BEHAVIOR
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(20) image("hero") frame(0) behavior("down")
SHOW SPRITE 0
FOR i = 1 ... 10
    YIELD
END FOR
// 90 is down
PRINT spritedirection(0)

spritedist

Returns the straight-line distance in pixels between two sprites’ positions, as a Float.

spritedist(sprite_a, sprite_b)

Parameters

  • sprite_a - First sprite slot number
  • sprite_b - Second sprite slot number

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(0) y(0) image("hero") frame(0)
SHOW SPRITE 0
ENABLE SPRITE 1
SET SPRITE 1 !! x(30) y(40) image("hero") frame(0)
SHOW SPRITE 1
PRINT spritedist(0, 1)

spriteelevation

Returns a sprite’s current ELEVATION — its height above the plane layer it sits on (AFFINE/PERSPECTIVE), in world units; 0 means on the floor. Useful in behavior/pattern WHEN conditions, e.g. landing detection. Elevation is set with SET SPRITE id ELEVATION(z) or animated with the ELEVATE behavior.

spriteelevation(sprite_num)

Parameters

  • sprite_num - Sprite slot number (0-99,999)

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
SHOW SPRITE 0
// 0 is on the floor
PRINT spriteelevation(0)

spriteenabled

Returns 1 if the sprite slot is enabled, 0 otherwise. An enabled sprite can be configured and rendered. Use this to check sprite slot availability.

spriteenabled(sprite_num)

Parameters

  • sprite_num - Sprite slot number (0-99,999)

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 3
SET SPRITE 3 !! x(100) y(100) image("hero") frame(0)
SHOW SPRITE 3
FOR id = 0 ... 4
    IF spriteenabled(id) THEN PRINT "slot", id, "is in use"
END FOR

spriteheight

Returns the current height of a hardware sprite in pixels. The returned value accounts for scaling (base texture height multiplied by the sprite’s Y scale factor). Returns 0 if the sprite does not exist.

spriteheight(sprite_num)

Parameters

  • sprite_num - Sprite slot number (0-99,999)

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
SHOW SPRITE 0
PRINT spriteheight(0)
SET SPRITE 0 !! scale((1, 3))
PRINT spriteheight(0)

sprites

The sprites that have a tag, as a list of their numbers.

sprites(tag AS STRING)

Parameters

  • tag AS STRING

Example

SCREEN 320, 240
FOR id = 0 ... 2
    ENABLE SPRITE id
    SET SPRITE id !! tag("enemy")
    SHOW SPRITE id
END FOR
FOR s = SPRITES("enemy")
    PRINT "enemy", s
END FOR

spritetag

Returns the tag string associated with the specified sprite. Returns an empty string if no tag has been set.

spritetag(sprite_num)

Parameters

  • sprite_num - Sprite slot number (0-99,999)

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0) tag("player")
SHOW SPRITE 0
ENABLE SPRITE 1
SET SPRITE 1 !! x(140) y(100) image("hero") frame(0)
SHOW SPRITE 1
PRINT spritetag(0)
PRINT spritetag(1) = ""

spritevisible

Returns 1 if the sprite is both enabled AND visible, 0 otherwise. A sprite is not visible if it has been hidden with HIDE SPRITE or if it is not enabled.

spritevisible(sprite_num)

Parameters

  • sprite_num - Sprite slot number (0-99,999)

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
// Placed, but not shown yet
PRINT spritevisible(0)
SHOW SPRITE 0
PRINT spritevisible(0)
HIDE SPRITE 0
PRINT spritevisible(0)

spritewidth

Returns the current width of a hardware sprite in pixels. The returned value accounts for scaling (base texture width multiplied by the sprite’s X scale factor). Returns 0 if the sprite does not exist.

spritewidth(sprite_num)

Parameters

  • sprite_num - Sprite slot number (0-99,999)

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(100) image("hero") frame(0)
SHOW SPRITE 0
PRINT spritewidth(0)
SET SPRITE 0 !! scale((2, 1))
PRINT spritewidth(0)

spritex

Returns the X position of a hardware sprite’s drawn rectangle: by default its left edge, whatever its ORIGIN. When relativeX is provided (0-1 range), returns the coordinate at that relative position across the sprite’s width: 0.5 is the centre, and passing the sprite’s own origin — SPRITEX(n, ox) for ORIGIN(ox, oy) — gives its anchor, the point LOCATION places. So with an ORIGIN other than (0, 0), LOCATION(SPRITEX(n), SPRITEY(n)) moves the sprite: pass the origin to read the anchor back.

spritex(sprite_num, relative_x = NULL)

Parameters

  • sprite_num - Sprite slot number (0-999 for user sprites; emitted particles use 100,000+)
  • relative_x = NULL - Optional. Relative position (0-1) across sprite width. 0 = left edge (default), 0.5 = center, 1 = right edge

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(50) image("hero") frame(0)
SHOW SPRITE 0
// Left edge, centre and right edge
PRINT spritex(0), spritex(0, 0.5), spritex(0, 1)
// Exact, not rounded: a sprite between pixels reads between them
SET SPRITE 0 !! x(100.5)
PRINT spritex(0), round(spritex(0))

spritey

Returns the Y position of a hardware sprite’s drawn rectangle: by default its top edge, whatever its ORIGIN. When relativeY is provided (0-1 range), returns the coordinate at that relative position across the sprite’s height: 0.5 is the centre, and passing the sprite’s own origin — SPRITEY(n, ox) for ORIGIN(ox, oy) — gives its anchor, the point LOCATION places. So with an ORIGIN other than (0, 0), LOCATION(SPRITEX(n), SPRITEY(n)) moves the sprite: pass the origin to read the anchor back.

spritey(sprite_num, relative_y = NULL)

Parameters

  • sprite_num - Sprite slot number (0-99,999)
  • relative_y = NULL - Optional. Relative position (0-1) across sprite height. 0 = top edge (default), 0.5 = center, 1 = bottom edge

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(50) image("hero") frame(0)
SHOW SPRITE 0
// Top edge, centre and bottom edge
PRINT spritey(0), spritey(0, 0.5), spritey(0, 1)
// Exact, not rounded: a sprite between pixels reads between them
SET SPRITE 0 !! y(50.25)
PRINT spritey(0), round(spritey(0))