Home

SergioFLS edited this page Jun 9, 2018 · 140 revisions

Logo

TIC-80 tiny computer

https://tic.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.

Manual

  1. Specification
  2. Console
  3. Code Editor
  4. Sprite Editor
  5. Map Editor
  6. SFX Editor
  7. Music Editor
  8. Hotkeys
  9. Command Line Arguments
  10. Supported Platforms
  11. Mods
  12. Credits

Specification

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     |
+-------+-------------------+-------+

Full memory layout specification

Console

Console Demo

Available Commands

  • 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 / .moon cart 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

Code Editor

Code Editor Demo

Cartridge Metadata

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.

WARNINGS:

  • 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
If you want to enable Javascript support add // 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.

Special Functions

  • TIC - Main function called at 60 fps
  • scanline - Called on every line render, has one parameter
  • init

Functions

  • 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 ticks passed from 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:

  • add dofile('game.lua') to the first line and place game.lua by your current working directory.
    • Windows: in the same folder as your your executable.
    • Unix/Linux: in the current working directory that you started the tic binary from.
  • or use tic cart.tic -code game.lua command line parameters to inject your code to the cartridge

Visual Studio Code extension for TIC-80 made by @Gi972

API user snippets for Visual Studio Code made by @Viza74

Visual Studio Code settings for TIC-80 game developers - settings, user snippets, docs. Made by @AlRado

Sublime Text 3 package - Syntax highlighting and auto-complete TIC-80 functions in Sublime Text. By @AlRado

Sprite Editor

Sprite Editor Demo

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.

Map Editor

Map Editor Demo

SFX Editor

SFX Editor Screen Capture

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 Z S X D C V G B H N J 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.

Call sfx(id) to run your sound effect

Music Editor

Music Editor Screen Capture

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 A or SPACE. A Note on the track has four components.

Note on a track

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.

Hotkeys

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)

Supported Platforms

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)

You can find iOS/tvOS version here

Mods

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.

Credits

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