API - nesbox/TIC-80 GitHub Wiki

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
⚠️ **GitHub.com Fallback** ⚠️