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

Collisions

BOUNDARY ADD · BOUNDARY ADD FROM · BOUNDARY ADD FROM LAYER · BOUNDARY CLEAR · BOUNDARY DELETE · box_collision · circle_collision · point_in_box · spritecollision · spritetouching · spritetouchingx · spritetouchingy

BOUNDARY ADD

Add a collision boundary: a rectangle solid things collide with — or, with enclosure, a wall they collide with when they try to LEAVE it.

BOUNDARY ADD tag, area
boundary_add(tag, area)

Also documents: enclosure, face_entry, layer, one_way, slope, solid

Parameters

  • tag AS STRING - Its tag, as collisions report it.
  • area AS VECTOR - From one corner to the other: (x1, y1) -> (x2, y2).

After !!

  • enclosure(on = TRUE) - Collide on leaving rather than entering.
  • face_entry(on = TRUE) - Opt-in for a one-way slope: new contacts must approach its selected face; existing diagonal support is preserved. Omit to allow normal uphill entry.
  • layer(value AS NUMBER) - The layer it belongs to.
  • one_way(value AS STRING) - Solid from one side only (with slope, its diagonal from the empty half): “top”, “bottom”, “left” or “right”.
  • slope(value AS STRING) - A triangle instead of a box, solid in one corner: “ne”, “nw”, “se” or “sw” (or spelled out, “northeast” …).
  • solid(on = TRUE) - Solid things are stopped by it.

Examples

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
// A floor, a ledge you can jump up through, and a hill climbed walking right.
BOUNDARY ADD "floor", (0, 230) -> (320, 240) !! solid
BOUNDARY ADD "ledge", (160, 160) -> (240, 164) !! solid one_way("top")
BOUNDARY ADD "hill", (200, 200) -> (264, 230) !! solid slope("se")
BEHAVIOR "fall"
    ACCELERATION 0, 0.5
END BEHAVIOR
ENABLE SPRITE 0
SET SPRITE 0 !! x(40) y(150) image("hero") frame(0) solid behavior("fall")
SHOW SPRITE 0
FOR i = 1 ... 120
    IF spritetouching(0, "TOP") <> "" THEN BREAK
    YIELD
END FOR
PRINT "standing on", spritetouching(0, "TOP")

SCREEN 320, 240
// Keep everything on screen: an enclosure is hit on the way out.
BOUNDARY ADD "edge", (0, 0) -> (320, 240) !! solid enclosure
PRINT "the screen is walled in"

Notes

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

BOUNDARY ADD FROM

Add every boundary a JSON file describes.

BOUNDARY ADD FROM file
boundary_add_from(file)

Parameters

  • file AS STRING - The JSON file, in the game folder.

Example

SCREEN 320, 240
// Every boundary drawn in the map editor, as boundary_add would add each.
BOUNDARY ADD FROM "boundaries.json"
PRINT "boundaries loaded"

Notes

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

BOUNDARY ADD FROM LAYER

Add boundaries traced from a layer’s pixels: each opaque cell becomes solid ground.

BOUNDARY ADD FROM LAYER tag, layer
boundary_add_from_layer(tag, layer)

Also documents: cell, solid

Parameters

  • tag AS STRING - Their tag, as collisions report it.
  • layer AS NUMBER - The layer to trace.

After !!

  • cell(value AS NUMBER) - The size of a traced cell, in pixels.
  • solid(on = TRUE) - Solid things are stopped by them.

Example

SCREEN 320, 240
CREATE LAYER 1, 320, 240
SET LAYER 1
LINE (0, 220) -> (319, 239), 7 !! box fill
// The floor just drawn becomes a solid boundary tagged "ground".
BOUNDARY ADD FROM LAYER "ground", 1 !! solid
PRINT "the drawn floor is solid"

Notes

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

BOUNDARY CLEAR

Remove every boundary.

BOUNDARY CLEAR
boundary_clear()

Example

SCREEN 320, 240
BOUNDARY ADD "floor", (0, 230) -> (320, 240) !! solid
BOUNDARY ADD "wall", (300, 0) -> (320, 240) !! solid
// A new level: start again from nothing.
BOUNDARY CLEAR
PRINT "no boundaries left"

Notes

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

BOUNDARY DELETE

Remove the boundaries with this tag.

BOUNDARY DELETE tag
boundary_delete(tag)

Parameters

  • tag AS STRING - Their tag.

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
BOUNDARY ADD "door", (100, 0) -> (120, 240) !! solid
// The door opens: the runner is no longer stopped by it.
BOUNDARY DELETE "door"
BEHAVIOR "run"
    VELOCITY 4, 0
END BEHAVIOR
ENABLE SPRITE 0
SET SPRITE 0 !! x(90) y(100) image("hero") frame(0) solid behavior("run")
SHOW SPRITE 0
DELAY 300
PRINT "through the door:", spritex(0) > 120

Notes

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

box_collision

Whether two rectangles overlap, each given by its corner, width and height.

box_collision(x1 AS NUMBER, y1 AS NUMBER, w1 AS NUMBER, h1 AS NUMBER, x2 AS NUMBER, y2 AS NUMBER, w2 AS NUMBER, h2 AS NUMBER)

Parameters

  • x1 AS NUMBER
  • y1 AS NUMBER
  • w1 AS NUMBER
  • h1 AS NUMBER
  • x2 AS NUMBER
  • y2 AS NUMBER
  • w2 AS NUMBER
  • h2 AS NUMBER

Example

SCREEN 320, 240
player = (10, 10)
enemy = (30, 20)
IF BOX_COLLISION(player.x, player.y, 32, 32, enemy.x, enemy.y, 24, 24) THEN PRINT "hit"

circle_collision

Whether two circles overlap, each given by its center and radius.

circle_collision(cx1 AS NUMBER, cy1 AS NUMBER, r1 AS NUMBER, cx2 AS NUMBER, cy2 AS NUMBER, r2 AS NUMBER)

Parameters

  • cx1 AS NUMBER
  • cy1 AS NUMBER
  • r1 AS NUMBER
  • cx2 AS NUMBER
  • cy2 AS NUMBER
  • r2 AS NUMBER

Example

SCREEN 320, 240
IF CIRCLE_COLLISION(0, 0, 8, 12, 0, 10) THEN PRINT "the balls touch"

point_in_box

Whether a point is inside a rectangle, given by its corner, width and height.

point_in_box(px AS NUMBER, py AS NUMBER, rx AS NUMBER, ry AS NUMBER, rw AS NUMBER, rh AS NUMBER)

Parameters

  • px AS NUMBER
  • py AS NUMBER
  • rx AS NUMBER
  • ry AS NUMBER
  • rw AS NUMBER
  • rh AS NUMBER

Example

SCREEN 320, 240
button = {x: 100, y: 80, w: 60, h: 20}
IF POINT_IN_BOX(120, 90, button.x, button.y, button.w, button.h) THEN PRINT "clicked"

spritecollision

Checks if a sprite is colliding with another sprite or any sprite with a specific tag. The second parameter can be a sprite index (number) or a tag string. Returns 1 (TRUE) if colliding, 0 (FALSE) if not. Uses custom BBOX if set via SET SPRITE, otherwise uses full sprite bounds. Only enabled sprites are considered for tag-based collision.

spritecollision(sprite, sprite_or_tag)

Parameters

  • sprite - Sprite slot number (0-99,999)
  • sprite_or_tag - Either a sprite index (number) or a tag string to match against

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 1
SET SPRITE 1 !! x(108) y(100) image("hero") frame(0) tag("coin")
SHOW SPRITE 1
ENABLE SPRITE 2
SET SPRITE 2 !! x(200) y(100) image("hero") frame(0) tag("coin")
SHOW SPRITE 2
PRINT spritecollision(0, 1), spritecollision(0, 2), spritecollision(0, "coin")

spritetouching

Returns the tag of the solid boundary or solid sprite that a sprite is touching on the specified edge of THAT boundary or sprite — the face touched, not the side of the sprite: a sprite resting on a floor touches the floor’s “TOP” (its own bottom), and “BOTTOM” answers “”. Checks boundaries first, then sprites registered via SOLID SPRITES(…). Returns an empty string if nothing is touching that edge. Use “ANY” to check all four edges at once. When the optional boundaryTag is provided, only checks boundaries/sprites with that tag. IMPORTANT: The sprite must have a movement behavior (MOVE, VELOCITY, etc.) applied for collision detection to be active.

spritetouching(sprite_id, edge, boundary_tag = NULL)

Parameters

  • sprite_id - The sprite index to check
  • edge - Which edge of the BOUNDARY to check: “TOP”, “BOTTOM”, “LEFT”, “RIGHT”, or “ANY” (checks all edges, returns first match)
  • boundary_tag = NULL - (Optional) Only check the boundary with this tag name

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
BOUNDARY ADD "floor", (0, 200) -> (320, 240) !! solid
BEHAVIOR "fall"
    ACCELERATION 0, 0.5
END BEHAVIOR
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(150) image("hero") frame(0) solid behavior("fall")
SHOW SPRITE 0
FOR i = 1 ... 120
    IF spritetouching(0, "TOP") <> "" THEN BREAK
    YIELD
END FOR
// Standing on the floor touches the floor's TOP.
PRINT spritetouching(0, "TOP")

spritetouchingx

Returns the X coordinate the sprite should be at to align with the boundary it’s touching on the given edge — the boundary’s face, as for spritetouching (a floor the sprite rests on is “TOP”). Useful for snapping sprites to walls. If not touching a boundary, returns the sprite’s current X position. Supports optional boundary tag filter. Requires the sprite to have a movement behavior active for collision detection to work.

spritetouchingx(sprite_id, edge, boundary_tag = NULL)

Parameters

  • sprite_id - The sprite index to check
  • edge - Which edge of the BOUNDARY: “TOP”, “BOTTOM”, “LEFT”, “RIGHT”, or “ANY”
  • boundary_tag = NULL - (Optional) Only check the boundary with this tag

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
BOUNDARY ADD "wall", (300, 0) -> (320, 240) !! solid
BEHAVIOR "run"
    VELOCITY 3, 0
END BEHAVIOR
ENABLE SPRITE 0
SET SPRITE 0 !! x(250) y(100) image("hero") frame(0) solid behavior("run")
SHOW SPRITE 0
// Running right, it meets the wall's LEFT side.
FOR i = 1 ... 120
    IF spritetouching(0, "LEFT", "wall") <> "" THEN BREAK
    YIELD
END FOR
SET SPRITE 0 !! clear_behaviors
PRINT "flush at x =", spritetouchingx(0, "LEFT", "wall")

spritetouchingy

Returns the Y coordinate the sprite should be at to align with the boundary it’s touching on the given edge — the boundary’s face, as for spritetouching (a floor the sprite rests on is “TOP”). Useful for snapping sprites to floors/ceilings and disabling gravity when grounded. If not touching a boundary, returns the sprite’s current Y position. Supports optional boundary tag filter. Requires the sprite to have a movement behavior active for collision detection to work.

spritetouchingy(sprite_id, edge, boundary_tag = NULL)

Parameters

  • sprite_id - The sprite index to check
  • edge - Which edge of the BOUNDARY: “TOP”, “BOTTOM”, “LEFT”, “RIGHT”, or “ANY”
  • boundary_tag = NULL - (Optional) Only check the boundary with this tag

Example

SCREEN 320, 240
LOADIMG "hero_run.png", "hero" !! spritesheet((40, 40))
BOUNDARY ADD "floor", (0, 200) -> (320, 240) !! solid
BEHAVIOR "fall"
    ACCELERATION 0, 0.5
END BEHAVIOR
ENABLE SPRITE 0
SET SPRITE 0 !! x(100) y(150) image("hero") frame(0) solid behavior("fall")
SHOW SPRITE 0
FOR i = 1 ... 120
    IF spritetouching(0, "TOP", "floor") <> "" THEN BREAK
    YIELD
END FOR
// Landed: stop falling and stand exactly on it.
SET SPRITE 0 !! remove_behavior("fall")
PRINT "stand at y =", spritetouchingy(0, "TOP", "floor")