Skip to content

API.md

Latest commit

 

History

History
1014 lines (706 loc) · 25.5 KB

API.md

File metadata and controls

1014 lines (706 loc) · 25.5 KB

Fantasy Console 0 - API Reference

A complete reference for all functions available in Fantasy Console 0 cart code.

Table of Contents

Overview

Fantasy Console 0 is a PICO-8-inspired fantasy console that uses JavaScript as its scripting language. All API functions are available in the global scope within cart code.

Screen Specifications

  • Resolution: 128x128 pixels
  • Colors: 16 colors (PICO-8 palette)
  • Sprites: 256 sprites (16x16 grid of 8x8 pixel sprites)
  • Map: 128x64 tiles

Game Loop Functions

Define these functions in your cart code:

function _init() {
  // Called once at startup
}

function _update() {
  // Called every frame (60fps) - put game logic here
}

function _draw() {
  // Called every frame after _update - put rendering here
}

Drawing Functions

cls(col?)

Clear the screen with a color.

Parameter Type Description
col number (optional) Color index (0-15). Defaults to 0 (black). 
cls() // Clear to black
cls(1) // Clear to dark blue

pset(x, y, col?)

Set a pixel at position (x, y).

Parameter Type Description
x number X coordinate
y number Y coordinate
col number (optional) Color index (0-15). Uses current color if omitted. 
pset(64, 64, 7) // Draw white pixel at center
pset(10, 10) // Draw with current color

pget(x, y)

Get the color of a pixel at position (x, y).

Parameter Type Description
x number X coordinate
y number Y coordinate

Returns: number - Color index (0-15) at the position.

let c = pget(64, 64)

rect(x, y, w, h, col?)

Draw a rectangle outline.

Parameter Type Description
x number Left x coordinate
y number Top y coordinate
w number Width in pixels
h number Height in pixels
col number (optional) Color index (0-15) 
rect(10, 10, 40, 40, 8) // Red rectangle outline

rectfill(x, y, w, h, col?)

Draw a filled rectangle.

Parameter Type Description
x number Left x coordinate
y number Top y coordinate
w number Width in pixels
h number Height in pixels
col number (optional) Color index (0-15) 
rectfill(10, 10, 40, 40, 12) // Blue filled rectangle

circ(cx, cy, r, col?)

Draw a circle outline.

Parameter Type Description
cx number Center x coordinate
cy number Center y coordinate
r number Radius
col number (optional) Color index (0-15) 
circ(64, 64, 20, 7) // White circle outline

circfill(cx, cy, r, col?)

Draw a filled circle.

Parameter Type Description
cx number Center x coordinate
cy number Center y coordinate
r number Radius
col number (optional) Color index (0-15) 
circfill(64, 64, 20, 11) // Green filled circle

oval(x, y, w, h, col?)

Draw an oval (ellipse) outline.

Parameter Type Description
x number Left x position
y number Top y position
w number Width in pixels
h number Height in pixels
col number (optional) Color index (0-15) 
oval(10, 30, 40, 30, 9) // Orange oval outline

ovalfill(x, y, w, h, col?)

Draw a filled oval (ellipse).

Parameter Type Description
x number Left x position
y number Top y position
w number Width in pixels
h number Height in pixels
col number (optional) Color index (0-15) 
ovalfill(10, 30, 40, 30, 14) // Pink filled oval

line(x0, y0, x1, y1, col?)

Draw a line from (x0, y0) to (x1, y1).

Parameter Type Description
x0 number Start x coordinate
y0 number Start y coordinate
x1 number End x coordinate
y1 number End y coordinate
col number (optional) Color index (0-15) 
line(0, 0, 127, 127, 7) // White diagonal line

print(str, x?, y?, col?)

Print text at position using the 3x5 pixel font.

Parameter Type Description
str string Text to print
x number (optional) X coordinate. Defaults to 0.
y number (optional) Y coordinate. Defaults to 0.
col number (optional) Color index (0-15)

Text is rendered in uppercase using a 3x5 pixel font with 1 pixel spacing between characters. Supports letters, numbers, and common punctuation.

print('HELLO WORLD', 20, 60, 7)
print('SCORE: ' + score, 0, 0, 11)

printXL(str, x?, y?, col?)

Print text at position using the larger 4x6 pixel font.

Parameter Type Description
str string Text to print
x number (optional) X coordinate. Defaults to 0.
y number (optional) Y coordinate. Defaults to 0.
col number (optional) Color index (0-15)

Same as print() but uses a larger 4x6 pixel font. Good for titles and headings.

printXL('GAME OVER', 30, 55, 8)
printXL('SCORE: ' + score, 20, 70, 7)

color(col)

Set the default drawing color for subsequent operations.

Parameter Type Description
col number Color index (0-15) 
color(8)
rect(10, 10, 20, 20) // Uses red (color 8)
circ(50, 50, 10) // Also uses red

Sprite Functions

spr(n, x, y, w?, h?, flipX?, flipY?)

Draw a sprite from the sprite sheet.

Parameter Type Description
n number Sprite number (0-255)
x number X position to draw at
y number Y position to draw at
w number (optional) Width in sprites (default 1)
h number (optional) Height in sprites (default 1)
flipX boolean (optional) Flip horizontally
flipY boolean (optional) Flip vertically 
spr(0, 60, 60) // Draw sprite 0 at (60,60)
spr(1, 20, 20, 2, 2) // Draw 2x2 sprite area
spr(0, 40, 40, 1, 1, true) // Draw flipped horizontally

sspr(sx, sy, sw, sh, dx, dy, dw?, dh?, flipX?, flipY?)

Draw a region of the sprite sheet with optional scaling.

Parameter Type Description
sx number Source x in sprite sheet
sy number Source y in sprite sheet
sw number Source width in pixels
sh number Source height in pixels
dx number Destination x
dy number Destination y
dw number (optional) Destination width (for scaling)
dh number (optional) Destination height (for scaling)
flipX boolean (optional) Flip horizontally
flipY boolean (optional) Flip vertically 
sspr(0, 0, 16, 16, 50, 50, 32, 32) // Draw 16x16 area scaled to 32x32

pal(c0?, c1?, p?)

Set palette color mapping or reset palette.

Parameter Type Description
c0 number (optional) Source color
c1 number (optional) Destination color
p number (optional) Palette type: 0=draw palette, 1=screen palette 
pal() // Reset both palettes
pal(7, 8) // Map white to red in draw palette
pal(7, 8, 1) // Map white to red in screen palette

palt(col?, t?)

Set color transparency for sprite drawing.

Parameter Type Description
col number (optional) Color index (0-15)
t boolean (optional) True = transparent, False = opaque 
palt() // Reset (only color 0 is transparent)
palt(0, false) // Make black opaque
palt(7, true) // Make white transparent

Map Functions

map(celX, celY, sx, sy, celW, celH, layer?)

Draw a region of the map.

Parameter Type Description
celX number Map cell x start
celY number Map cell y start
sx number Screen x position
sy number Screen y position
celW number Width in cells
celH number Height in cells
layer number (optional) Layer bitmask for flag-based filtering 
map(0, 0, 0, 0, 16, 16) // Draw 16x16 tile region

mget(x, y)

Get the sprite number at a map cell.

Parameter Type Description
x number Map cell x
y number Map cell y

Returns: number - Sprite number (0-255) at the cell.

let tile = mget(5, 3)
if (tile == 1) {
  // Solid tile
}

mset(x, y, val)

Set the sprite number at a map cell.

Parameter Type Description
x number Map cell x
y number Map cell y
val number Sprite number (0-255) 
mset(5, 3, 0) // Clear tile at (5,3)

Camera & Screen

camera(x?, y?)

Set camera offset for drawing operations.

Parameter Type Description
x number (optional) Camera x offset. Defaults to 0.
y number (optional) Camera y offset. Defaults to 0. 
camera(playerX - 64, playerY - 64) // Center on player
camera() // Reset camera

clip(x?, y?, w?, h?)

Set the clipping region for drawing operations.

Parameter Type Description
x number (optional) Clip region x
y number (optional) Clip region y
w number (optional) Clip region width
h number (optional) Clip region height 
clip(10, 10, 108, 108) // Draw only within this rectangle
clip() // Reset to full screen

Input Functions

btn(buttonId)

Check if a button is currently held down.

Parameter Type Description
buttonId number Button ID (0-7)

Returns: boolean - True if button is held.

Button ID Primary Key Alternate Key Description
0 Arrow Left A Left
1 Arrow Right D Right
2 Arrow Up W Up
3 Arrow Down S Down
4 Z J B button
5 X K A button
6 Enter Space Start
7 Shift (left or right) Select 
if (btn(0)) {
  x -= 1 // Move left while held
}

btnp(buttonId)

Check if a button was just pressed this frame.

Parameter Type Description
buttonId number Button ID (0-7)

Returns: boolean - True if button was just pressed.

if (btnp(5)) {
  jump() // Jump on press, not every frame
}

Math Functions

abs(x)

Absolute value of x.

Parameter Type Description
x number Input value

Returns: number - Absolute value.

abs(-5) // Returns 5
abs(3) // Returns 3

sgn(x)

Sign of x.

Parameter Type Description
x number Input value

Returns: number - Returns -1 if x < 0, 0 if x == 0, 1 if x > 0.

sgn(-5) // Returns -1
sgn(0) // Returns 0
sgn(3) // Returns 1

min(x, y)

Returns the smaller of x and y.

Parameter Type Description
x number First value
y number Second value

Returns: number - Smaller value.

min(5, 3) // Returns 3

max(x, y)

Returns the larger of x and y.

Parameter Type Description
x number First value
y number Second value

Returns: number - Larger value.

max(5, 3) // Returns 5

mid(x, y, z)

Returns the middle value of three numbers.

Parameter Type Description
x number First value
y number Second value
z number Third value

Returns: number - Middle value.

mid(1, 5, 3) // Returns 3
mid(10, 5, 8) // Returns 8

Tip: Use mid for clamping values:

x = mid(0, x, 127) // Clamp x between 0 and 127

flr(x)

Floor function - round down to integer.

Parameter Type Description
x number Input value

Returns: number - Floored value.

flr(3.7) // Returns 3
flr(-1.5) // Returns -2

ceil(x)

Ceiling function - round up to integer.

Parameter Type Description
x number Input value

Returns: number - Ceiling value.

ceil(3.2) // Returns 4
ceil(-1.5) // Returns -1

sqrt(x)

Square root of x.

Parameter Type Description
x number Input value (non-negative)

Returns: number - Square root. Returns 0 for negative inputs.

sqrt(16) // Returns 4
sqrt(2) // Returns 1.414...

sin(x)

Sine function using 0-1 angle range (not radians).

Parameter Type Description
x number Angle in 0-1 range

Returns: number - Sine value in range [-1, 1].

Angle (x) Degrees sin(x)
0 0° 0
0.25 90° 1
0.5 180° 0
0.75 270° -1
1.0 360° 0 
let y = sin(t) * 20 // Oscillate y by 20 pixels

cos(x)

Cosine function using 0-1 angle range (not radians).

Parameter Type Description
x number Angle in 0-1 range

Returns: number - Cosine value in range [-1, 1].

Angle (x) Degrees cos(x)
0 0° 1
0.25 90° 0
0.5 180° -1
0.75 270° 0
1.0 360° 1 
// Circular motion
let x = 64 + cos(t) * 30
let y = 64 + sin(t) * 30

atan2(dx, dy)

Arctangent of dy/dx, returns angle in 0-1 range.

Parameter Type Description
dx number X component
dy number Y component

Returns: number - Angle in range [0, 1).

Direction atan2 result
Right (+x) 0.25
Down (+y) 0.5
Left (-x) 0.75
Up (-y) 0 
let angle = atan2(targetX - x, targetY - y)
// Move toward target
x += cos(angle) * speed
y += sin(angle) * speed

Random Functions

rnd(x?)

Generate a random number.

Parameter Type Description
x number (optional) Upper bound (exclusive)

Returns: number - Random number in range [0, x) if x provided, otherwise [0, 1).

rnd() // Random float 0-1
rnd(10) // Random float 0-9.999...
flr(rnd(6)) // Random integer 0-5 (like a die roll)

srand(seed)

Set the random seed for reproducible sequences.

Parameter Type Description
seed number Seed value (integer) 
srand(12345)
let a = rnd() // Always same value with this seed
let b = rnd() // Always same value with this seed

String Functions

sub(str, pos, len?)

Extract a substring. Uses 0-based indexing.

Parameter Type Description
str string Source string
pos number Start position (0-indexed). Negative counts from end.
len number (optional) Length to extract. If omitted, extract to end.

Returns: string - Extracted substring.

sub('HELLO', 1, 3) // Returns "ELL"
sub('HELLO', 1) // Returns "ELLO"
sub('HELLO', -2) // Returns "LO" (last 2 chars)

chr(val)

Convert character code to string.

Parameter Type Description
val number Character code

Returns: string - Single-character string.

chr(65) // Returns "A"
chr(48) // Returns "0"

ord(str, pos?)

Get character code at position. Uses 0-based indexing.

Parameter Type Description
str string Source string
pos number (optional) Position (0-indexed, default 0)

Returns: number | undefined - Character code, or undefined if out of bounds.

ord('ABC') // Returns 65 (code for 'A')
ord('ABC', 1) // Returns 66 (code for 'B')

Array Functions

These functions work with JavaScript arrays and provide PICO-8-style array manipulation.

add(arr, val, index?)

Add a value to an array (in place).

Parameter Type Description
arr array Array to modify
val any Value to add
index number (optional) Position to insert (0-indexed)

Returns: The added value.

let enemies = []
add(enemies, { x: 50, y: 50 }) // Add to end
add(enemies, { x: 10, y: 10 }, 0) // Insert at beginning

del(arr, val)

Remove first occurrence of a value from array (in place).

Parameter Type Description
arr array Array to modify
val any Value to remove

Returns: The removed value, or undefined if not found.

let items = [1, 2, 3, 2]
del(items, 2) // items is now [1, 3, 2]

count(arr)

Count elements in an array or object.

Parameter Type Description
arr array or object Container to count

Returns: number - Count of non-undefined elements.

let arr = [1, 2, 3]
count(arr) // Returns 3

all(arr)

Return the array for iteration.

Parameter Type Description
arr array Array to iterate

Returns: The input array.

for (let enemy of all(enemies)) {
  enemy.x += enemy.vx
}

foreach(arr, fn)

Call a function for each element.

Parameter Type Description
arr array Array to iterate
fn function Function to call for each element 
foreach(particles, function (p) {
  p.y += p.vy
})

Audio Functions

sfx(n, channel?, offset?)

Play, stop, or control sound effects.

Parameter Type Description
n number SFX number (0-63), or -1 to stop, or -2 to stop looping
channel number (optional) Channel to play on (0-3). Auto-selected if omitted.
offset number (optional) Starting note position (0-31). Defaults to 0.

FC0 has 4 simultaneous audio channels (0-3). Each channel can play one SFX at a time.

Special values for n:

  • n = -1: Stop the specified channel, or stop all channels if no channel is given
  • n = -2: Stop looping on the specified channel (plays to end), or all channels if no channel is given

Channel auto-selection: When no channel is specified, a free channel is chosen automatically. If all channels are busy, channel 0 is overridden.

// Play SFX 0 on auto-selected channel
sfx(0)

// Play SFX 5 on channel 2
sfx(5, 2)

// Play SFX 10 starting from note 8
sfx(10, 0, 8)

// Stop channel 1
sfx(-1, 1)

// Stop all channels
sfx(-1)

// Stop looping on channel 3 (plays to end)
sfx(-2, 3)

SFX are created using the Sound Editor tab. See the Sound Editor Guide for details.

Debug Functions

printh(str)

Print a debug message to the host console.

Parameter Type Description
str string Message to print

Messages are sent to the host application via the LOG message. In the test page, they appear in the Console Output panel. In the browser, they appear in the developer console.

printh('Player position: ' + x + ', ' + y)
printh('Debug: entered state ' + state)

Note: console.log, console.warn, and console.error also work and are intercepted and sent to the host.

console.log('This also works!')
console.warn('Warning message')
console.error('Error message')

Color Palette

Fantasy Console 0 uses the PICO-8 16-color palette:

Index Color Hex
0 Black #000000
1 Dark Blue #1D2B53
2 Dark Purple #7E2553
3 Dark Green #008751
4 Brown #AB5236
5 Dark Grey #5F574F
6 Light Grey #C2C3C7
7 White #FFF1E8
8 Red #FF004D
9 Orange #FFA300
10 Yellow #FFEC27
11 Green #00E436
12 Blue #29ADFF
13 Lavender #83769C
14 Pink #FF77A8
15 Peach #FFCCAA