Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
TIC-80 tiny computer
TIC-80 is a tiny computer which you can use to make, play, and share tiny games. There are built-in tools for development: code, sprites, maps, sound editors and the command line, which is enough to create a mini retro game. When you are finished, you can export a cartridge file, which can be stored and uploaded to the website. Also, the game can be packed into a game player that works on all popular platforms and which you can distribute as you wish. To make a retro styled game, the whole process of creation takes place under some technical limitations: 240x136 pixels display, a 16 color palette, 256 8x8 color sprites, 4 channel sound, etc.
- Code Editor
- Sprite Editor
- Map Editor
- SFX Editor
- Music Editor
- Command Line Arguments
- Supported Platforms
Display 240x136 pixels, 16-color palette Input 4 gamepads with 8 buttons / mouse / keyboard Sprites 256 8x8 foreground sprites and 256 8x8 background tiles Map 240x136 cells, 1920x1088 pixels (240*8 x 136*8) Sound 4 channels (with editable waveform envelopes) Code 64KB (or 512KB in PRO bankswitching) Bankswitching Up to 8 banks in cart (PRO version only)
.-----------------------------------. | 80K RAM LAYOUT | |-----------------------------------| | ADDR | INFO | SIZE | |-------+-------------------+-------| | 00000 | SCREEN | 16320 | 240x136 4-bit screen | 03FC0 | PALETTE | 48 | 16 24-bit RGB colors | 03FF0 | PALETTE MAP | 8 | 16 4-bit colors assignment | 03FF8 | BORDER | 1 | 4-bit border color | 03FF9 | SCREEN OFFSET | 2 | Horizontal and vertical offsets | 03FFB | MOUSE CURSOR | 1 | Set mode of mouse cursor | 03FFC | ... | 4 | | 04000 | TILES | 8192 | 256 8x8 BG tiles | 06000 | SPRITES | 8192 | 256 8x8 FG tiles | 08000 | MAP | 32640 | 240x136 world from BG tiles | 0FF80 | GAMEPADS | 4 | 4 gamepads x 8 buttons (Up Down Left Right A B X Y) | 0FF84 | MOUSE | 4 | Mouse cursor X/Y and mouse buttons | 0FF88 | KEYBOARD | 4 | 4 simultaneous keyboard indexes | 0FF8C | ... | 16 | | 0FF9C | SOUND REGISTERS | 72 | 18 bytes x 4 channels | 0FFE4 | WAVEFORMS | 256 | 16 32x4-bit waveforms | 100E4 | SFX | 4224 | 64 x 30 samples | 11164 | MUSIC PATTERNS | 11520 | 60 x 64 rows | 13E64 | MUSIC TRACKS | 408 | 8 x 16 patterns x 4 channels | 13FFC | MUSIC POS | 4 | | 14000 | ... | 0 | '-----------------------------------'
help- Show available commands
ram- Show 80K RAM layout
exit- Exit the application
edit- Show editors
new [lua | moon | js | wren | fennel]- Create new Hello World cartridge
load <cart> [sprites | map | cover | code | sfx | music | palette]- Load cartridge from the local filesystem (you can type cart name without .tic extension), also you can load only data section (sprites, map...) from other cart
save <cart>- Save cartridge to the local filesystem, use
.lua / .js / .mooncart extension to save it in text format [PRO version]
run- Run current project
resume- Resume last loaded project
dir- Show list of local files
cd- Change directory
mkdir- Make directory
folder- Open working directory in OS (Windows, Linux, MacOSX)
add- Show file open dialog to add file to TIC
del <file>- Delete from the filesystem
get <file>- Show file save dialog to download file
export [html | native | sprites | cover | map]- Export HTML, NATIVE build of game or sprites and cover as .gif
import [sprites | cover | map]- Import sprites or cover from .gif
cls- Clear screen
demo- Install demo carts
version- Show the current version (0.60.3)
config [save | default]- Show config.tic file editor, use save param to save current configuration, use default to edit default cart template
keymap- Configure keyboard buttons mapping (got removed in later versions)
surf- Open carts browser
dofile("example.lua") -- Can be used for saving a standalone Lua file in the TIC executable's directory. -- title: game title -- Briefly shows the name of the cart. -- author: game developer -- Briefly shows who made the cart. -- desc: short description -- Optional description of game, isn't necessary. -- script: lua (or moon/wren/js/fennel) -- Selects language. The default and most popular is Lua. -- input: gamepad (or mouse or keyboard) -- Selects either gamepad or mouse or keyboard input usage. All the input types enabled by default. -- saveid: MyAwesomeGame -- Allows save data to be shared within multiple games on a copy of TIC.
- The title and author tags and a cover image are required for uploading to the official website.
- dofile must be placed in the first line of the game source code.
It's a good practice to declare all these tags on top of source code.
If you want to enable Moonscript support add
-- script: moon tag
// script: js tag
If you want to enable Fennel support add
;; script: fennel tag
If you want to enable Wren support add
// script: wren tag
To enable mouse input only (and disable gamepad/keyboard) add
-- input: mouse tag
Using a unique saveid for your game will keep pmem instead of relying on MD5 hash.
- TIC - Main function called at 60 fps
- SCN - Called on every line render, has one parameter
- OVR - Called on every frame. You can draw things like HUD on a separate layer (with own palette)
- print - Print string with system font
- font - Print string with font defined in foreground sprites
- clip - Set screen clipping region
- cls - Clear the screen
- pix - Set/Get pixel color on the screen
- line - Draw line
- rect - Draw filled rectangle
- rectb - Draw rectangle border
- circ - Draw filled circle
- circb - Draw circle border
- spr - Draw sprite by ID, can rotate or flip
- btn - Get gamepad button state in current frame
- btnp - Get gamepad button state according to previous frame
- sfx - Play SFX by ID on specific channel
- key - Get keybaord button state in current frame
- keyp - Get keyboard button state according to previous frame
- map - Draw map region on the screen
- mget - Get map tile index
- mset - Set map tile index
- music - Play music track by ID
- peek - Read a byte value from RAM
- poke - Write a byte value to RAM
- peek4 - Read a half byte value from RAM
- poke4 - Write a half byte value to RAM
- reset - Reset game to initial state (0.60)
- memcpy - Copy bytes in RAM
- memset - Set byte values in RAM
- pmem - Save integer value to persistent memory
- trace - Trace string to the Console
- time - Returns how many milliseconds passed since game started
- mouse - Get XY and press state of mouse/touch
- sync - Copy modified sprites/map to the cartridge
- tri - Draw filled triangle
- textri - Draw triangle filled with texture
- exit - Interrupt program and return to console
Using external code editors
There are two methods with which you can edit code in an external editor:
dofile('game.lua')to the first line and place
game.luaby your current working directory.
- Windows: in the same folder as your your executable.
- Unix/Linux: in the current working directory that you started the
- Android: use the full path to your LUA file. For example,
- or use
tic cart.tic -code game.luacommand line parameters to inject your code to the cartridge
Visual Studio Code settings for TIC-80 game developers - settings, user snippets, docs. Made by @AlRado
You can define two 128x128 sprite sheets in the game. One is for foreground objects and the other for backgrounds.
At the top right, you'll see a slider for editing a 8x8, 16x16, 32x32, or 64x64 segment of a sprite sheet. There's also two tabs for selecting the foreground (FG) or background (BG) sheets. A new cart will initialize 2 frames of Ticsy's animation in the background set of sprites.
On the left is a sprite-drawing portion, and the right is a view of the selected sprite sheet.
A number at the top left shows the selected sprite index. Below it is a space for editing the selected sprite index. On the far left is a brush size selector, ranging from 1 pixel to 4 pixels squared. On the bottom of the tile editor is a basic drawing tool set.
- Brush draws on the selected tile.
- Color Picker chooses the color based on the pixel clicked.
- Select allows you to move around a certain part of a portion of a tile and move it around.
- Fill is a basic paint bucket tool. It allows you to fill in a mono-colored shape of the tile with a color.
- Flip Horz and Flip Vert allows the tile to be flipped in either axis.
- Rotate allows you to rotate a tile 90 degrees clockwise.
- Erase clears out the entire tile.
Below the tool set is a color selector with 16 colors. The system and a new cart initialize the palette to the default DB16. On the right is an RGB editor button for the palette colors.
You can define 64 sound effects which also can be used in the Music Editor as instruments.
Once in the editor you will see two inputs up top, Index (IDX) and Speed (SPD). Index controls what sound effect you are editing (from 00 to 63) and Speed controls how fast that sound effect plays (from -4 to 03). Next, there are 4 ways to affect how your instrument sounds, on the left. These are:
- Wave For changing the type of waveform your instrument uses. The options are a set of waveforms defined in the waverform tab of the editor. A new cartridge will already have waveforms setup for Square, Triangle, Saw wave or Noise (Mainly used for percussion and explosions)
- Volume How loud your instrument is. If you want your SFX to fade in or out, this is the way to do it.
- Arpeggio Changing note, relative to the base note played. This can be used to play through chords.
- Pitch Change the base note.
The Octave (OCT) option at the bottom changes the octave your keyboard plays in. You can play notes with the
M keys. The keys are mapped as if the bottom row on a standard qwerty keyboard are one octave of a piano, with sharps and flats on the row above. Pressing
SPACE will play your last played key.
The Loop function lets you repeat parts of your SFX. The first number controls the length of the loops (From 0-15) and the second number controls its position (Also 0-15). This will loop the current pattern for the selected option on the left. You can control the loops for all the options separately and they do not affect each other.
sfx(id) to run your sound effect
You can store up to 8 tracks (0 to 7) that act like separate pieces of music. The tempo is how fast the music will go in BPM (Beats Per Minute). Rows controls how many beats are in track.
To enter a note, click on a cell (or move to it using the arrow keys) and press a key on the bottom row of the keyboard in the same way you do in the SFX Editor. You can also enter notes from the next octave apart. Once you have entered a note it will carry on as long as there are no different notes or breaks. A break can be made by pressing
SPACE. A Note on the track has four components.
The first component is a letter from A to G which is the note (It can also have a # after to show that the note is sharp). The number next to it is the octave that note will be played in. Next to that there is an orange number from 00 to 63. This is the index of the SFX voice that note will use. Finally there is a single blue hexadecimal number. This is the volume of that note. F is 100% volume and 0 is 0%. Effects for notes and Piano Mode are in development.
You can press
SPACE to preview the note you're currently on and
ENTER to play the current frame.
ESC switch console/editor ALT+~ show console ALT+1/F1 show code editor ALT+2/F2 show sprite editor ALT+3/F3 show map editor ALT+4/F4 show sfx editor ALT+5/F5 show music editor CTRL+PGUP/PGDOWN switch to previous/next editor mode (0.70.0) F11/ALT+ENTER fullscreen/window mode CTRL+R/ENTER run current project CTRL+X/C/V cut/copy/paste in the editors CTRL+S save cart ARROWS navigate in sprite editor, move map in map editor, navigate music tracker SHIFT show spritesheet in map editor CTRL+Z/Y undo/redo changes CTRL+F find in code editor CTRL+G go to line in code editor CTRL+O show code outline F7 assign cover image F8 take a screenshot F9 start/stop GIF video recording SHIFT+ENTER play pattern from cursor position in the music editor
Command Line Arguments
Native versions of TIC support some arguments when call from console or other programs.
It supports absolute and relative paths. Useful when using external editors.
tic80 . will use current directory as storage tic80 ../path/to/cart.tic will use ../path/to/ as storage and load cart.tic tic80 -code game.lua load and run the code without startup animation tic80 -code-watch game.lua same as -code but also reload it when TIC is focused tic80 game.tic -code game.lua load cartridge, inject the code and run without startup animation tic80 > log.txt all trace output is redirect to file log.txt tic80 | Out-File log.txt same as upper one but in case of PowerShell tic80 cart.tic -sprites blahblah.gif inject sprites to cart.tic tic80 -surf to start in SURF mode tic80 -nosound to start in silent mode tic80 -fullscreen to start in fullscreen mode tic80 -skip to skip startup animation (0.60.0)
TIC is developed with pure C language and with SDL, LUA libraries. That's why all have to work on all popular platforms without problems:
HTML5 done Windows done Windows 10 UWP done Linux 32/64bit done Android done Mac OS X done Raspberry Pi done Pocket CHIP done iOS done (courtesy of CliffsDover and Bruno Philipe) libretro done
You can find iOS/tvOS version here
There is a fork of TIC-80 that supports game scripting with Brainfuck language. See https://github.com/lolbot-iichan/TIC-80/wiki for details and samples.
There is a fork of TIC-80 that supports exercises within Lua (with multiple unit tests, progress save, and other features) to help with programming teaching, more specifically game development. This fork was renamed to FEUP-8, due to it being a university project and it can be found here afonsojramos/feup-8.
French translation (WIP) : GitHub @Red-Rapious
Filippo Rivato - Twitter @HomineLudens
Fred Bednarski - Twitter @FredBednarski
Al Rado - Twitter @alrado2
Trevor Martin - Twitter @trelemar
MonstersGoBoom - Twitter @MonstersGoBoom
Matheus Lessa - Twitter @matheuslrod
CliffsDover - Twitter @DancingBottle
Frantisek Jahoda - GitHub @jahodfra
Guilherme Medeiros - GitHub @frenetic
Andrei Rudenko - GitHub @RudenkoArts
Phil Hagelberg - @technomancy
Rob Loach - Twitter @RobLoach GitHub @RobLoach