API

You can download a quick API reference sheet suitable for viewing or printing here: PDF (OUTDATED). The Wiki also includes a Cheatsheet for fast reference. And you can use export help <file> to export all help information into a markdown file.

Callbacks

Callbacks are functions that your game defines and that TIC-80 calls automatically. Every game at a minimum must define a TIC function.

• TIC - Called 60 times per second (60 FPS); the main update/draw callback. Required.
• BOOT - Called once when yout cartridge is first booted
• SCN(n) - (deprecated as of 0.90, use BDR(n) now instead)
• BDR(n) - Called prior to each scanline/borderline render (allowing for palette swaps, etc).
• OVR - Called last and draws to a separate layer (using a separate palette).
• MENU - Used to handle custom items in the Game Menu (introduced in 1.0)

Sequencing

-- cartridge is booted
   BOOT()

-- frame begins (at 60 frames per second)

   TIC()
   OVR()
   BDR(0..143)

-- frame ends

SCN callsbacks are not included in the above table because SCN has been deprecated. You should now use BDR instead of SCN.

Functions

Drawing

• circ - Draw a filled circle
• circb - Draw a circle border
• elli - Draw a filled ellipse (0.90)
• ellib - Draw an ellipse border (0.90)
• clip - Set the screen clipping region
• cls - Clear the screen
• font - Print a string using foreground sprite data as the font
• line - Draw a straight line
• map - Draw a map region
• pix - Get or set the color of a single pixel
• print - Print a string using the system font
• rect - Draw a filled rectangle
• rectb - Draw a rectangle border
• spr - Draw a sprite or composite sprite
• tri - Draw a filled triangle
• trib - Draw a triangle border (0.90)
• textri - (deprecated as of 1.0, use ttri now instead)
• ttri - Draw a triangle filled with texture

Input

• btn - Get gamepad button state in current frame
• btnp - Get gamepad button state according to previous frame
• key - Get keyboard button state in current frame
• keyp - Get keyboard button state relative to previous frame
• mouse - Get XY and press state of mouse/touch

Sound

• music - Play or stop playing music
• sfx - Play or stop playing a given sound

Memory

• memcpy - Copy bytes from one location in RAM to another
• memset - Set sequential bytes in RAM to a given value
• pmem - Access or update the persistent memory
• peek - Read a byte from an address in RAM
• peek1 - Read a single bit from an address in RAM (1.0)
• peek2 - Read two bit value from an address in RAM (1.0)
• peek4 - Read a nibble (4bit) value from an address RAM
• poke - Write a byte value to an address in RAM
• poke1 - Write a single bit to an address in RAM (1.0)
• poke2 - Write a two bit value to an address in RAM (1.0)
• poke4 - Write a nibble (4bit) value to an address in RAM
• sync - Copy banks of RAM (sprites, map, etc) to and from the cartridge
• vbank - Switch the 16kb of banked video RAM

Utilities

• fget - Retrieve a sprite flag (0.80)
• fset - Update a sprite flag (0.80)
• mget - Retrieve a map tile at given coordinates
• mset - Update a map tile at given coordinates

System

• exit - Interrupt program and return to console
• reset - Reset game to initial state (0.60)
• time - Returns how many milliseconds have passed since game started
• tstamp - Returns the current Unix timestamp in seconds (0.80)
• trace - Print a string to the Console