Types
AudioChannel = range[0 .. 3]
- The channel of sfx
AudioNote = range[-1 .. 95]
-
All possible notes
The -1 is for stop playing in sfx
AudioSfx = range[-1 .. 63]
-
All possible sfx
The -1 is for stop playing in sfx
AudioSpeed = range[-4 .. 3]
- The speed of sfx
AudioVolume = range[0 .. 15]
- The volume of sfx
Button = range[0 .. 31]
- All buttons
Buttons = enum BtnUp, BtnDown, BtnLeft, BtnRight, BtnA, BtnB, BtnX, BtnY
-
Buttons by name
Byte4 = range[0 .. 15]
- 4 bits value
Color = range[-1 .. 15]
-
All available colors-1 is for no color
DefaultPallete {.pure.} = enum black = 0, purple, red, orange, yellow, lightGreen, green, darkGreen, darkBlue, blue, lightBlue, cyan, white, lightGrey, grey, darkGrey
-
Colors by name
DisplaySize = object width: range[0 .. 239] height: range[0 .. 135]
Key = range[1 .. 65]
- All keys of keyboard
Keys {.pure.} = enum a = 1, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, zero, one, two, three, four, five, six, seven, eight, nine, minus, equals, leftbracket, rightbracket, backslash, semicolon, apostrophe, grave, comma, period, slash, space, tab, `return`, backspace, delete, insert, pageup, pagedown, home, `end`, up, down, left, right, capslock, ctrl, shift, alt
- All keyboard keys by name
MapTile = byte
- The id of tile in map
MemoryBank = range[0 .. 7]
- All memory banks available on PRO version
MusicFrame = range[-1 .. 15]
- The frame of music track
MusicRow = range[-1 .. 63]
- The row of frame of the music track
MusicSpeed = range[-1 .. 90]
- Music speed
MusicTempo = range[-1 .. 90]
- Music tempo
MusicTrack = range[0 .. 7]
- The music track
Sprite = range[0 .. 2047]
- All possible sprites (even with 1 BPP)
SpriteFlag = range[0 .. 7]
- All sprite flags
SpriteWithFlag = range[0 .. 511]
- All the sprites using 4 BPP
TransformFlip = range[0 .. 3]
- 0 = No Flip 1 = Flip horizontally 2 = Flip vertically 3 = Flip both vertically and horizontally
TransformRotate = range[0 .. 3]
-
When you rotate the sprite, it's rotated clockwise in 90° steps:
0 = No rotation 1 = 90° rotation 2 = 180° rotation 3 = 270° rotation
Procs
proc btnp(id: Buttons; hold, period: int): bool {.importc.}
-
returns true if pressed in the current but wasn't pressed in the previous frame
proc circ(x, y, radius: int; color: Color) {.importc.}
-
This function draws a filled circle of the desired radius and color with its center at x, y. It uses the Bresenham algorithm.
proc circb(x, y, radius: int; color: Color) {.importc.}
-
Draws the circumference of a circle with its center at x, y using the radius and color requested. It uses the Bresenham algorithm.
proc circb(x, y, radiusH, radiusW: int; color: Color) {.importc.}
-
This function draws a filled ellipse of the desired radiuses a b and color with its center at x, y. It uses the Bresenham algorithm.
proc clip() {.importc.}
-
Calling clip() with no parameters will reset the drawing area to the entire screen.
proc clip(x, y, width, height: int) {.importc.}
-
This function limits drawing to a clipping region or 'viewport' defined by x,y, width, and height. Any pixels falling outside of this area will not be drawn.
proc cls(color: Color = 0) {.importc.}
-
Calling clip() with no parameters will reset the drawing area to the entire screen.
proc exit() {.importc.}
-
This function causes program execution to be interrupted after the current TIC function ends. All code in the TIC function for the current frame will be executed - including any code that follows exit(). See the example below for a demo of this behavior.
Once execution is interrupted you are returned to the console.
proc fget(spriteId: SpriteWithFlag; flag: SpriteFlag): bool {.importc.}
-
Returns true if the specified flag of the sprite is set.
proc font(text: cstring; x, y: int; transparentColor: Color; charWidth, charHeight: int; fixed = false; scale = 1) {.importc.}
-
This function will draw text to the screen using the foreground spritesheet as the font. Sprite #256 is used for ASCII code 0, #257 for code 1 and so on. The character 'A' has the ASCII code 65 so will be drawn using the sprite with sprite #321 (256+65). See the example below or check out the In-Browser Demo (http://tic.computer/play?cart=20)
To simply print text to the screen using the system font, please see print
To print to the console, please see trace
proc fset(spriteId: SpriteWithFlag; flag: SpriteFlag; state: bool) {.importc.}
-
Each sprite has eight flags which can be used to store information or signal different conditions. For example, flag 0 might be used to indicate that the sprite is invisible, flag 6 might indicate that the sprite should be draw scaled etc.
To check these flags, see fget.
proc keyp(code: Key; hold, pediod: int) {.importc.}
-
This function returns true if the given key is pressed but wasn't pressed in the previous frame. Refer to btnp for an explanation of the optional hold and period parameters
proc line(x0, y0, x1, y1: int; color: Color) {.importc.}
-
Draws a straight line from point (x0,y0) to point (x1,y1) in the specified color.
proc map(x, y: int; w = 30; h = 17; sx = 0; sy = 0; colorkey: Color = noColor; scale = 1; remap = proc (tileId, x, y: int): array[3, int]) {.importc.}
-
The map consists of cells of 8x8 pixels, each of which can be filled with a tile (sprite) using the map editor. The map can be up to 240 cells wide by 136 deep. This function will draw the desired area of the map to a specified screen position. For example, map(5,5,12,10,0,0) will draw a 12x10 section of the map, starting from map co-ordinates (5,5) to screen position (0,0). Calling map() without parameters will draw 30x17 tiles to screen position (0,0).
The map function’s last parameter is a powerful callback function for changing how map cells are drawn when map() is called. It can be used to rotate, flip and replace sprites while the game is running. Unlike mset, which saves changes to the map, this special function can be used to create animated tiles or replace them completely. Some examples include changing sprites to open doorways, hiding sprites used to spawn objects in your game and even to emit the objects themselves.
The tilemap is laid out sequentially in RAM - writing 1 to 0x08000 will cause tile(sprite) #1 to appear at top left when map() is called. To set the tile immediately below this we need to write to 0x08000 + 240, ie 0x080F0
proc memcpy(toAddr, fromAddr, length: int) {.importc.}
-
This function copies a continuous block of RAM from one address to another. Addresses are specified are in hexadecimal format, values are decimal.
proc memset(memAddr: int; value: byte; length: int) {.importc.}
-
This function sets a continuous block of RAM to the same value. The address is specified in hexadecimal format, the value in decimal.
proc mget(x, y: int): MapTile {.importc.}
-
This function returns the tile at the specified map coordinates, the top left cell of the map being (0, 0).
proc mouse(): array[7, int] {.importc.}
-
This function returns the mouse coordinates and a boolean value for the state of each mouse button, with true indicating that a button is pressed.
Note: The values of index: 2, 3 and 4 are boolean
proc mset(x, y: int; tile: MapTile) {.importc.}
-
This function will change the tile at the specified MAP coordinates. By default, changes made are only kept while the current game is running. To make permanent changes to the map (persisting them back to the cartridge), see sync.
proc music() {.importc.}
-
Stops the music
proc music(track: MusicTrack; frame: MusicFrame = -1; row: MusicRow = -1; loop = true; sustain = false; tempo: MusicTempo = -1; speed: MusicSpeed = -1) {.importc.}
-
This function starts playing a track created in the Music Editor (https://github.com/nesbox/TIC-80/wiki#music-editor).
The music function needs to be called outside of the tic() function. If you would like to call the music function inside of the tic function you can try the following.
proc peek(ramAddr: int): byte {.importc.}
-
This function allows you to read from TIC's RAM. It can be used to access resources created with the integrated tools, such as the sprite, map and sound editors, as well as cartridge data. The address is specified in hexadecimal format.
To write to a memory address, use poke.
proc peek4(ramAddr4: int): Byte4 {.importc.}
-
This function enables you to read values from TIC's RAM. The address should be specified in hexadecimal format.
See also: poke4
proc pix(x, y: int): Color {.importc.}
-
This function can read or write individual pixel color values. When called with color, the pixel at the specified coordinates is set to that color. When called with only x and y values, the color of the pixel at the specified position is returned.
Reading
proc pix(x, y: int; color: Color) {.importc.}
-
This function can read or write individual pixel color values. When called with color, the pixel at the specified coordinates is set to that color. When called with only x and y values, the color of the pixel at the specified position is returned.
Writing
proc pmem(index: byte): uint32 {.importc.}
-
This function allows you to save and retrieve data in one of the 256 individual 32-bit slots available in the cartridge's persistent memory. This is useful for saving high-scores, level advancement or achievements. Data is stored as unsigned 32-bit integers (from 0 to 4294967295).
- Tips:
- -pmem depends on the cartridge hash (md5), so don't change your lua script if you want to keep the data.-Use saveid: with a personalized string in the header metadata to override the default MD5 calculation. This allows the user to update a cart without losing their saved data.
Reading
proc pmem(index: byte; value: uint32) {.importc.}
-
This function allows you to save and retrieve data in one of the 256 individual 32-bit slots available in the cartridge's persistent memory. This is useful for saving high-scores, level advancement or achievements. Data is stored as unsigned 32-bit integers (from 0 to 4294967295).
- Tips:
- pmem depends on the cartridge hash (md5), so don't change your lua script if you want to keep the data.
- Use saveid: with a personalized string in the header metadata to override the default MD5 calculation. This allows the user to update a cart without losing their saved data.
Saving
proc poke(ramAddr: int; val: byte) {.importc.}
-
This function allows you to write a single byte to any address in TIC's RAM. The address should be specified in hexadecimal format, the value in decimal.
proc poke4(ramAddr: int; val: Byte4) {.importc.}
-
This function allows you to write a single byte to any address in TIC's RAM. The address should be specified in hexadecimal format, the value in decimal.
proc print(text: cstring; x = 0; y = 0; color: Color = DefaultPallete.white; fixed = false; scale = 1; smallfont = false) {.importc.}
-
This will simply print text to the screen using the font defined in config. When set to true, the fixed width option ensures that each character will be printed in a 'box' of the same size, so the character 'i' will occupy the same width as the character 'w' for example. When fixed width is false, there will be a single space between each character. Refer to the example for an illustration.
To use a custom rastered font, check out font.
To print to the console, check out trace.
proc rect(x, y, w, h: int; color: Color) {.importc.}
-
This function draws a filled rectangle of the desired size and color at the specified position. If you only need to draw the border or outline of a rectangle (ie not filled) see rectb
proc rectb(x, y, w, h: int; color: Color) {.importc.}
-
This function draws a one pixel thick rectangle border at the position requested. If you need to fill the rectangle with a color, see rect instead.
proc reset() {.importc.}
-
Resets and immediately restarts the cartridge.
To simply return to the console, please use exit.
This API was added in version 0.60.
proc sfx(id: AudioSfx; note: AudioNote = -1; duration = -1; channel: AudioChannel = 0; volume: AudioVolume = 15; speed: AudioSpeed = 0) {.importc.}
-
This function will play the sound with id created in the sfx editor. Calling the function with an id of -1 will stop playing the channel.
The note can be supplied as an integer between 0 and 95 (representing 8 octaves of 12 notes each) or as a string giving the note name and octave. For example, a note value of '14' will play the note 'D' in the second octave. The same note could be specified by the string 'D-2'. Note names consist of two characters, the note itself (in upper case) followed by '-' to represent the natural note or '#' to represent a sharp. There is no option to indicate flat values. The available note names are therefore: C-, C#, D-, D#, E-, F-, F#, G-, G#, A-, A#, B-. The octave is specified using a single digit in the range 0 to 8.
The duration specifies how many ticks to play the sound for; since TIC-80 runs at 60 frames per second, a value of 30 represents half a second. A value of -1 will play the sound continuously.
The channel parameter indicates which of the four channels to use. Allowed values are 0 to 3.
Volume can be between 0 and 15.
Speed in the range -4 to 3 can be specified and means how many 'ticks+1' to play each step, so speed==0 means 1 tick per step.
proc spr(id: Sprite; x, y: int; transparentColor: Color = noColor; scale = 1; flip: TransformFlip = 0; rotate: TransformRotate = 0; w = 1; h = 1) {. importc.}
-
Draws the sprite number index at the x and y coordinate.
You can specify a colorkey in the palette which will be used as the transparent color or use a value of -1 for an opaque sprite.
The sprite can be scaled up by a desired factor. For example, a scale factor of 2 means an 8x8 pixel sprite is drawn to a 16x16 area of the screen.
You can flip the sprite where:
- 0 = No Flip
- 1 = Flip horizontally
- 2 = Flip vertically
- 3 = Flip both vertically and horizontally
When you rotate the sprite, it's rotated clockwise in 90° steps:
- 0 = No rotation
- 1 = 90° rotation
- 2 = 180° rotation
- 3 = 270° rotation
You can draw a composite sprite (consisting of a rectangular region of sprites from the sprite sheet) by specifying the w and h parameters (which default to 1).
proc sync(mask = 0; bank: MemoryBank = 0; toCart = false) {.importc.}
-
The PRO version of TIC-80 contains 8 memory banks. To switch between these banks, sync can be used to either load contents from a memory bank to runtime, or save contents from the active runtime to a bank. The function can only be called once per frame.
- tiles = 1<<0 -- 1
- sprites = 1<<1 -- 2
- map = 1<<2 -- 4
- sfx = 1<<3 -- 8
- music = 1<<4 -- 16
- palette = 1<<5 -- 32
- flags = 1<<6 -- 64
screen = 1<<7 -- 128 (as of 0.90)
Use sync() to save data you modify during runtime and would like to persist, or to restore runtime data from the cartridge. For example, if you have manipulated the runtime memory (e.g. by using mset), you can reset the active state by calling sync(0,0,false). This resets the whole of runtime memory to the contents of bank 0.
Note that sync is never used to load code from banks; this is done automatically. All data is restored from cartridge on every startup.
Note: In older versions of TIC-80, calling sync was not required to save runtime map and sprite data. Sync should be called any time changes to the sprites and map are made during runtime if you'd like the changes to be applied.
proc textri(x1, y1, x2, y2, x3, y3, u1, v1, u2, v2, u3, v3: int; use_map = false; trans: seq[Color] = @[]) {.importc.}
-
This function draws a triangle border with color, using the supplied vertices.
proc ticHeader(title, author, desc: string; saveId = ""): string {....raises: [], tags: [].}
- Generates the game header
proc time(): uint64 {.importc.}
-
This function returns the number of milliseconds elapsed since the cartridge began execution. Useful for keeping track of time, animating items and triggering events.
proc trace(message: cstring; color: Color = DefaultPallete.black) {.importc.}
-
This is a service function, useful for debugging your code. It prints the message parameter to the console in the (optional) color specified.
- Tips:
- The Lua concatenation operator is .. (two periods)
- Use the console cls command to clear the output from trace
proc tri(x1, y1, x2, y2, x3, y3: int; color: Color) {.importc.}
-
This function draws a triangle filled with color, using the supplied vertices.
proc trib(x1, y1, x2, y2, x3, y3: int; color: Color) {.importc.}
-
This function draws a triangle border with color, using the supplied vertices.
proc tstamp(): uint64 {.importc.}
-
This function returns the number of seconds elapsed since January 1st, 1970. This can be quite useful for creating persistent games which evolve over time between plays.