Tips for newcomers - nesbox/TIC-80 GitHub Wiki

People learn in different ways, and some enjoy finding things out on their own. This page aims to have the most important information everyone needs to begin well, a few tips that are easy to miss, not more.
If you are new to programming, have a look at the beginners tutorials instead.

Display

TIC-80 has a native screen resolution of 240 pixels wide by 136 pixels tall. The screen origin is at top-left, with x coordinates running left to right and y coordinates from top to bottom.

Console Commands

Here are some essential console commands:

`new lua`           Create a new cart using Lua (works with lua, python, ruby, js, moon, fennel, scheme, squirrel, wren, wasm, janet).
`save mycart`       Save and name the cart as "mycart" (Hotkey: CTRL+S).
`run`               Run the cart (Hotkey: CTRL+R/ENTER).
`folder`            Open the working directory in OS, where TIC files are saved.
`surf`              Open carts browser.
`eval`              Execute provided code.

Find more console commands here.

Example of eval Usage

To log the results use trace:

>eval trace("Floor division of 32 by 10 is "..32//10)
Floor division of 32 by 10 is 3

Note: Run a cart first to launch the virtual machine; otherwise, eval will output an empty string no matter what you do.

Code

It is good practice to start cartridges by the metadata tags. In particular, the script tag is required when another language than Lua is used for the virtual machine to know.

At the core of every game is a loop that updates the game and renders new frames. In TIC-80, this is managed by the TIC() function:

-- # Metadata Tags:
-- title:   game title
-- author:  game developer, email, etc.
-- script:  lua --required to run cart

-- # Code outside TIC() runs once at program start.
-- Declare variables, functions, initialize

function TIC()
    -- # Code inside TIC() runs ~60 times per second.
    -- Handle inputs, update game state

    cls() -- Clear the screen
    -- Render graphics, characters, objects, backgrounds, etc.
end

Note: Not clearing the screen at every frame can result in annoying artifacts.

Debugging

Use trace in your code for debugging:

trace("x = "..x) -- Prints the value of x to the console

Hotkeys

Useful hotkeys:

ESC                 Switch between console/editor or open menu while in-game.
ESC+F1              Switch to editor while in-game.
F1/F2/F3/F4/F5      Show code/sprite/map/sfx/music editor.
CTRL+R/ENTER        Run cart.
CTRL+S              Save cart.
CTRL+O              In code editor: show and navigate outline of code. One of the best ways to navigate through code in TIC-80.

Find more hotkeys here.

Resources

Explore TIC-80 on the wiki, along with several tutorials. Additionally, you can use the help command in the console.

You can start by learning about print, spr, and btn to understand the Hello World cartridge.

If you struggle to find something on the wiki use github search bar with "Wikis" filter.

Questions

If you have specific questions, you can find assistance on the discord, which is an active community, or on telegram, itch.io and github.

Lua

To quickly grasp the basics of Lua, this tutorial serves as an excellent introduction, if you already know programming.
Note: % is modulo and // floor division.

Cheatsheet

Here is a cheatsheet by Skye Waddell.