TIC80

HOW TO SAVE YOUR WORK

1. From the TIC-80 shell
https://hub.xpub.nl/sandbot/PrototypingTimes/tic80/tic80.html
save "YOURGAMENAME"
then goto https://hub.xpub.nl/sandbot/PrototypingTimes/tic80/save.html
and right click the YOURGAMENAME.tic file and choose save link as... (downloads to your computer)

2. In your sandbot jupyter lab, navigate to shared/html/PrototypingTimes/tic80/2021-01-18/
Copy + paste maze.html and rename to YOURGAMENAME.html
Drag + Drop your tic file
Right-click the HTML page and choose Open in Editor.
Change "maze.tic" to "YOURGAMENAME.tic"

3. Test if it works:
https://hub.xpub.nl/sandbot/PrototypingTimes/tic80/2021-01-18/

What is what

• From TIC-80 The Missing Manual

API

Main functions / Callbacks

TIC

TIC is the ‘main’ function and must be present in every program. It takes no parameters and is called sixty times per second (60fps).

-- script: lua
function TIC()
  -- Put your stuff here
end

SCN

SCN allows you to execute code between the drawing of each scan line, for example, to manipulate the palette.

Parameters

• scanLine: The next scan line to be drawn (0..135)

function SCN(line)
 -- your code here
end

Examples

OVR

OVR is called on every frame. It draws on a separate layer and can be used together with SCN() to create separate background or foreground layers and other visual effects.

function OVR()
 -- Draw foreground
end

Input

btn

btn [id: 0..31] -> pressed
Parameters:

id : the id of the key we want to interrogate, see the key map for reference

keyp

keyp code hold period
Parameters

code : the key code we want to check (see codes here)
hold : time in ticks before autorepeat
period : time in ticks for autorepeat interval

Description

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

mouse

mouse -> x y left middle right scrollx scrolly

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.

Drawing

clip

clip [x y w h]

This function limits drawing to a clipping region or ‘viewport’ defined by x,y,w,h. Things drawn outside of this area will not be visible.

Calling clip() with no parameters will reset the drawing area to the entire screen.

Parameters

• x : x coordinate of the top left of the clipping region
• y : y coordinate of the top left of the clipping region
• w : width of the drawing area in pixels
• h : height of the drawing area in pixels

cls

cls [color]

This function clears the entire screen using the color argument. If no parameter is passed, index 0 of the palette is used. The function is usually called inside TIC(), but isn’t mandatory. If you’re drawing to the entire screen, for example with sprites, the map or primitive shapes, there’s no need to clear the screen with cls() beforehand. Tip: You can create some interesting effects by not calling cls() or calling it repeatedly it to “flash” the screen when some special event occurs. You can also supply a color index above 15 to see some interesting fill patterns!

Paramenters

• color : the index (0 to 15) of the color in the current palette.

Example

-- cls demo
c=0
function TIC()
	--Use Up/Down to change color
	if btnp(0) then c=c+1 end
	if btnp(1) then c=c-1 end

	--Clear with the color 
	cls(c)
	
	--Make a background for the text 
	rect(0,0,240,8,0)
	--Ouput a text with function call
	print('cls('..c..')  --Use Up/Down to change color')
end

circ

circ x y radius color
This function draws a filled circle of the desired radius and color with its center at x, y. It uses the Bresenham algorithm.
Parameters:

x : the x coordinate of the circle center
y : the y coordinate of the circle center
r : the radius of the circle in pixels
color: the index of the desired color in the current palette

circb

circ x y radius color

Draws the circumference of a circle with its center at x, y using the radius and color requested.
Parameters

x : the x coordinate of the circle’s center y : the y coordinate of the circle’s center
r : the radius of the circle in pixels
color: the index of the desired color in the current palette

line

line x0 y0 x1 y1 color
Parameters

x0 : the x coordinate where the line starts
y0 : the y coordinate where the line starts
x1 : the x coordinate where the line ends
y1 : the y coordinate where the line ends
color: the index of the color in the current palette

Draws a straight line from point (x0,y0) to point (x1,y1) in the specified color.

pix

Syntax

pix x y [color] -> color

This function can read or write pixel color values. When called with a color parameter, the pixel at the specified coordinates is set to that color. Calling the function without a color parameter returns the color of the pixel at the specified position.

x : x coordinate of the pixel to write
y : y coordinate of the pixel to write
color : the index of the color in the palette to apply at the desired coordinates

rect

Syntax

rect x y w h color
description

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 (if not filled) see rectb
parameters

x : x coordinate of the top left corner of the rectangle
y : y coordinate of the top left corner of the rectangle
w : the width the rectangle in pixels
h : the height of the rectangle in pixels
color : the index of the color in the palette that will be used to fill the rectangle

rectb

Syntax

• rectb x y w h color
  

description

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.
parameters

x : x coordinate of the top left corner of the rectangle
y : y coordinate of the top left corner of the rectangle
w : the rectangle’s width in pixels
h : the rectangle’s height in pixels
color : the index of the color in the palette that will be used to color the rectangle’s border.

tri

• tri x1 y1 x2 y2 x3 y3 color
  

This function draws a triangle filled with * color *, using the supplied vertices.

x1 : the x coordinate of the first triangle corner
y1 : the y coordinate of the first triangle corner
x2 : the x coordinate of the second triangle corner
y2 : the y coordinate of the second triangle corner
x3 : the x coordinate of the third triangle corner
y3 : the y coordinate of the third triangle corner
color: the index of the desired color in the current palette

textri

• textri x1 y1 x2 y2 x3 y3 u1 v1 u2 v2 u3 v3 [use_map=false] [colorkey=-1]
  

It renders a triangle filled with texture from image ram or map ram

x1 : the x coordinate of the first triangle corner
y1 : the y coordinate of the first triangle corner
x2 : the x coordinate of the second triangle corner
y2 : the y coordinate of the second triangle corner
x3 : the x coordinate of the third triangle corner
y3 : the y coordinate of the third triangle corner

Program / Interrupts

exit

Interrupts program execution and returns to the console when the TIC function ends.

reset

Reset game to initial state (0.60) Resets the cartridge. To return to the console, see the exit function.
time

• • Milliseconds ** elapsed since game start.
    

This function returns the number of ** milliseconds ** elapsed since the cartridge began execution. * Useful for keeping track of time, animating items and triggering events. *

tstamp

The current unix timestamp in ** seconds. **

This function returns the number of ** seconds ** elapsed since January 1st, 1970. * Useful for creating persistent games which evolve over time between plays. *

trace

• trace msg [color]
  

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 * concatenator for strings is .. (two points) * Use console * cls * command to clear the output from trace
    

msg : the message to print in the * console *. Can be a ‘string’ or variable.
color : color for the ** msg ** text

Program / Interrupts

exit

Interrupts program execution and returns to the console when the TIC function ends.
reset

Reset game to initial state (0.60) Resets the cartridge. To return to the console, see the exit function.

time

• • Milliseconds ** elapsed since game start.
    

This function returns the number of ** milliseconds ** elapsed since the cartridge began execution. * Useful for keeping track of time, animating items and triggering events. *
tstamp

The current unix timestamp in ** seconds. **

This function returns the number of ** seconds ** elapsed since January 1st, 1970. * Useful for creating persistent games which evolve over time between plays. *

trace

• trace msg [color]
  

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 * concatenator for strings is .. (two points) * Use console * cls * command to clear the output from trace
    

msg : the message to print in the * console *. Can be a ‘string’ or variable.
color : color for the ** msg ** text

Sprite / Map

fget

Returns true if the specified flag of the sprite is set.

fget index flag
Parameters

index : sprite index flag : flag index (0-7) to check

fset

fset index flag bool
Parameters

index : sprite index flag : index of flag (0-7) *bool : What state to set the flag, true or false
Description

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 flag should be draw scaled etc.

map

map [x=0 y=0] [w=30 h=17] [sx=0 sy=0] [colorkey=-1] [scale=1] [remap=nil]

The map consists of cells of 8x8 pixels, each of which can be filled with a 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).
parameters

x : The leftmost map cell to be drawn.
y : The uppermost map cell to be drawn.
w : The number of cells to draw horizontally.
h : The number of cells to draw vertically.
sx : The screen x coordinate where drawing of the map section will start.
sy : The screen y coordinate where drawing of the map section will start.
colorkey : index (or array of indexes 0.80.0) of the color that will be used as transparent color. Not setting this parameter will make the map opaque.
scale : Map scaling.
remap: An optional function called before every tile is drawn. Using this callback function you can show or hide tiles, create tile animations or flip/rotate tiles during the map rendering stage: callback [tile [x y] ] -> [tile [flip [rotate] ] ]

mget

mget x y -> id
parameters

x : x coordinate on the map
y : y coordinate on the map

returns the sprite id at the given x and y map coordinate

mset

mset x y id

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, see sync.
Parameters:

x : x coordinate on the map
y : y coordinate on the map
id : The background tile (0-255) to place in map at specified coordinates.

spr

spr id x y [colorkey=-1] [scale=1] [flip=0] [rotate=0] [w=1 h=1]

Draw sprite by ID, can be rotated or flipped

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).

id : index of the sprite
x : x coordinate where the sprite will be drawn, starting from top left corner.
y : y coordinate where the sprite will be drawn, starting from top left corner.
colorkey : index (or array of indexes) of the color in the sprite that will be used as transparent color. Use -1 if you want an opaque sprite.
scale : scale factor applied to sprite. *flip : flip the sprite vertically or horizontally or both.
rotate : rotate the sprite by 0, 90, 180 or 270 degrees.
w : width of composite sprite
h : height of composite sprite

text

font

This function will draw text to the screen using sprites from the foreground sprite-sheet for the font. More specifically, sprite ID#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 ID#321 (256+65). See the example below or check out the In-Browser Demo

To simply print text to the screen using the default font, see print. To print to the console, refer to trace
Parameters

text : any string to be printed to the screen x : x coordinate where to print the text y : y coordinate where to print the text colorkey : the colorkey to use as transparency. char width : Width of characters to use for spacing, in pixels char height : Height of characters to use for multiple line spacing, in pixels. fixed : a flag indicating whether to fix the width of the characters, by default is not fixed scale : font scaling

print

Syntax

   print text [x=0 y=0] [color=15] [fixed=false] [scale=1] [smallfont=false] -> width

Description

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.

parameters

• text : any string to be printed to the screen
• x : x coordinate where to print the text
• y : y coordinate where to print the text
• color : the color to use to draw the text to the screen
• fixed : a flag indicating whether fixed width printing is required
• scale : font scaling
• smallfont : use small font if true

Memory

memcpy

memcpy toaddr fromaddr len

This function allows you to copy a continuous block of TIC’s 64k RAM from one address to another. Addresses are specified are in hexadecimal format, values are decimal.

1. 1. 1. parameters * toaddr : the address you want to write to * fromaddr : the address you want to copy from * len : the length of the memory block you want to copyDescription:
         

memset

memset addr val len

This function allows you to set a continuous block of any part of TIC’s RAM to the same value. The address is specified in hexadecimal format, the value in decimal.

addr : the address of the first byte of 64k RAM you want to write to
val : the value you want to write
len : the length of the memory block you want to setDescription:

peek

peek addr -> val (byte)

This function allows to read the memory from TIC. It’s useful to access resources created with the integrated tools like sprite, maps, sounds, cartridges data? Never dream to sound a sprite? Address are in hexadecimal format but values are decimal. To write to a memory address, use poke.
Parameters:

addr : any address of the 80k RAM byte you want to read

Output: * val : the value read from the addr parameter. Each address stores a byte, so the value will be an integer from 0 to 255.

peek4

Syntax

peek4 addr4 -> val4
This function enables you to read values from TIC’s RAM. The address should be specified in hexadecimal format. addr4 : any address of the 80K RAM byte you want to read, divided in groups of 4 bits (nibbles). Therefore, to address the high nibble of position 0x2000 you should pass 0x4000 as addr4, and to access the low nibble (rightmost 4 bits) you would pass 0x4001. val4 : the 4-bit value (0-15) read from the specified address.

pmem

Syntax

pmem index:0..255 [val] -> val

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. The data is stored as unsigned 32-bit integers (from 0 to 4294967295).

index : the index of the value you want to save/read in the persistent memory
val : the value you want to store in the memory. Omit this parameter if you want to read the memory.

poke

Syntax

poke addr val

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.

addr : the address in RAM
val : the value to write

poke4

Syntax

poke4 addr4 val
description

This function allows you to write to the virtual RAM of TIC. It differs from poke in that it divides memory in groups of 4 bits. Therefore, to address the high nibble of position 0x4000 you should pass 0x8000 as addr4, and to access the low nibble (rightmost 4 bits) you would pass 0x8001. The address should be specified in hexadecimal format, and values should be given in decimal.
parameters

addr4 : the nibble (4 bits) address in RAM to which to write
val : the 4-bit value (0-15) to write to the specified address

sync

Copy modified sprites/map to the cartridge

• sync [mask=0] [bank=0] [tocart=false]
  

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.

mask : mask of sections you want to switch: 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 0 - will switch all the sections 1 | 2 | 4 - will switch tiles, sprites and map sections, for example
bank : memory bank, can be 0…7.
toCart : true - save sprites/map/sound from runtime to bank, false - load data from bank to runtime. 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 runtime memory to the contents of bank 0. Note that sync is not used to load code from banks; this is done automatically.

Sound

music

music [track=-1] [frame=-1] [row=-1] [loop=true] [sustain=false]
This function starts playing a track created in the Music Editor. Call without arguments to stop the music.
Parameters:

track : the id of the track to play from (0..7)
frame : the index of the frame to play from (0..15)
row : the index of the row to play from (0..63)
loop : loop music or play it once (true/false)
sustain : sustain notes after the end of each frame or stop them (true/false)

sfx

sfx id [note] [duration=-1] [channel=0] [volume=15] [speed=0]

This function will play the sound with id created in the sfx editor. Calling the function with id set to -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.

id : The sfx id, from 0 to 63
note : The note number or name
duration : Duration (-1 by default)
channel : Which channel to use, 0..3
volume : Volume (15 by default)
speed : Speed (0 by default)

Console

https://github.com/nesbox/TIC-80/wiki/Console

load / save

load <cart> [sprites | map | cover | code | sfx | music | palette]

Load cartridge from the local filesystem (there's no need to type the .tic extension).

You can also load just the data (sprites, map etc) from another cart

Save "lua" files with all resources in a text file

 save mycart.lua

get : Download a file

Downloads a file (that exists) from the TIC80 to your local disk. Use with export & save.

 get mygame.tic

 get myfile.lua

 get myexportedsprites.gif

add : Upload a file

UPLOAD a file into the TIC80

 add

If the file already exists, be sure to del it first in the TIC console...

 del myfile.lua
 add

Importing / exporting sprites

NB: works with the "internal file system" ... use with add/get to upload/download files.

Export and download sprites...

 export sprites mysprites.gif
 get mysprites.gif

Once you have edited mysprites.gif outside of TIC, you can import the file into your game

First you need to delete the (old) "internal" file, otherwise add will complain when you try to reupload the same named file).

 del mysprites.gif

Press ENTER to confirm the delete. Now...

 add

And pick the local "mysprites.gif" file.

Finally

 import sprites mysprites.gif

Importing code from an outside file into TIC80 (keeping sprites etc)

You can use the add command to upload a lua file to the TIC then load it...

 add
 load yourfile.lua

To preserve the default sprites etc, or to mix with the graphics of another tic file, save the default/other as a lua file. Then use get to download it. You can then copy and paste the tiles, etc and re-upload the resulting file as above.

In TIC80:

 new
 save new.lua
 get new.lua

Inside the new.lua file is the tiles etc data as pseudo-html blocks (hex encoded binary data actually). This can be cut & paste into your own code and reuploaded.

-- <TILES>
-- 001:eccccccccc888888caaaaaaaca888888cacccccccacc0ccccacc0ccccacc0ccc
-- 002:ccccceee8888cceeaaaa0cee888a0ceeccca0ccc0cca0c0c0cca0c0c0cca0c0c
-- 003:eccccccccc888888caaaaaaaca888888cacccccccacccccccacc0ccccacc0ccc
-- 004:ccccceee8888cceeaaaa0cee888a0ceeccca0cccccca0c0c0cca0c0c0cca0c0c
-- 017:cacccccccaaaaaaacaaacaaacaaaaccccaaaaaaac8888888cc000cccecccccec
-- 018:ccca00ccaaaa0ccecaaa0ceeaaaa0ceeaaaa0cee8888ccee000cceeecccceeee
-- 019:cacccccccaaaaaaacaaacaaacaaaaccccaaaaaaac8888888cc000cccecccccec
-- 020:ccca00ccaaaa0ccecaaa0ceeaaaa0ceeaaaa0cee8888ccee000cceeecccceeee
-- </TILES>

-- <WAVES>
-- 000:00000000ffffffff00000000ffffffff
-- 001:0123456789abcdeffedcba9876543210
-- 002:0123456789abcdef0123456789abcdef
-- </WAVES>

-- <SFX>
-- 000:000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000304000000000
-- </SFX>

-- <PALETTE>
-- 000:1a1c2c5d275db13e53ef7d57ffcd75a7f07038b76425717929366f3b5dc941a6f673eff7f4f4f494b0c2566c86333c57
-- </PALETTE>

Remember to del any previous file with the same name.

 del oldfile.lua
 add