TIC-80 Documentation

TIC-80 is a fantasy computer for making, playing and sharing tiny games.

6,168 stars C C 18 files · ~10,505 tokens #8bit#fantasy-computer#fantasy-console#gamedev#gameengine#retro#tic-80#tic80
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy TIC-80 on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name tic-80 --restart always nesbox/tic-80:latest

Technical Documentation: nesbox/TIC-80

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

TIC-80 TINY COMPUTER — tic80.com

About

TIC-80 is a free and open source fantasy computer for making, playing and sharing tiny games.

With TIC-80 you get built-in tools for development: code, sprites, maps, sound editors and the command line, which is enough to create a mini retro game.

Games are packaged into a cartridge file, which can be easily distributed. TIC-80 works on all popular platforms. This means your cartridge can be played in any device.

To make a retro styled game, the whole process of creation and execution takes place under some technical limitations: 240x136 pixel display, 16 color palette, 256 8x8 color sprites, 4 channel sound, etc.

Features

  • Multiple programming languages: Lua,
    Moonscript,
    Javascript,
    Ruby,
    Wren,
    Fennel,
    Squirrel,
    Janet, and
    Python.
  • Games can have mouse and keyboard as input
  • Games can have up to 4 controllers as input (with up to 8 buttons, each)
  • Built-in editors: for code, sprites, world maps, sound effects and music
  • An additional memory bank: load different assets from your cartridge while your game is executing
  • Moderated community

Binary Downloads

Stable Builds

You can download compiled versions for the major operating systems directly from our Releases page.

Nightly Builds

Can be downloaded from official nightly.link page or from the Github Actions page.

Unofficial Builds

Linux (arm64) builds can be downloaded from aliceisjustplaying nightly.link page. Tested on Raspberry Pi OS (64-bit) (Bookworm), Asahi Linux (Fedora Remix), Ubuntu 22.04 and Fedora 40.

Pro Version

To help support TIC-80 development, we have a PRO Version.

This version has a few additional features and binaries can only be downloaded on our itch.io page.

For users who can't afford the program can easily build the pro version from the source code using cmake .. -DBUILD_PRO=On command.

Pro Features

  • Save/load cartridges in text format, and create your game in any editor you want, also useful for version control systems.
  • Even more memory banks: instead of having only 1 memory bank you have 8.
  • Export your game without editors, and then publish it to app stores.

Community

You can play and share games, tools and music at tic80.com/play.

The community also hangs out and discusses on Telegram or Discord.

Contributing

You can contribute by reporting a bug or requesting a new feature on our Issues page.
Keep in mind when engaging on a discussion to follow our Code of Conduct.

You can also contribute by reviewing or improving our Wiki.
The wiki holds TIC-80 documentation, code snippets and game development tutorials.

Build instructions

Windows

MSVC (Microsoft Visual C++)

Windows XP / Windows 7 32-bit (x86)

The build process has been tested on Windows 11 64-bit (x64); all this should run on Windows 7 SP1 32-bit (x86) as well. This guide assumes you're running an elevated Command Prompt.

  • Install Git, CMake, Visual Studio 2019 Build Tools and Ruby+Devkit 2.7.8 x86

  • Install the neccessary dependencies within VS2019:

    • Launch "Visual Studio Installer"
    • Click "Modify"
    • Check "Desktop Development with C++"
    • Go to "Individual components"
    • Search for "v141"
    • Install:
      • C++ Windows XP Support for VS 2017 (v141) tools [Deprecated]
      • MSVC v141 - VS 2017 C++ x64/x86 build tools (v14.16)
    • Click "Modify"

  • Run ridk install with options 1,3 to set up MSYS2 and development toolchain

  • Add MSYS2's gcc at C:\Ruby27\msys32\mingw32\bin to your $PATH (guide)

  • Open a new elevated Command Prompt and run the following commands:

text
git clone --recursive https://github.com/nesbox/TIC-80 && cd .\TIC-80\build
copy /y .\build\janet\janetconf.h .\vendor\janet\src\conf\janetconf.h
cmake -G "Visual Studio 16 2019" -A Win32 -T v141_xp -DCMAKE_BUILD_TYPE=Release -DBUILD_WITH_ALL=On ..
cmake --build . --parallel

You'll find tic80.exe in TIC-80\build\bin.

Windows 10 / 11 64-bit (x64)

This guide assumes you're running PowerShell with an elevated prompt.

text
winget install Git.Git Kitware.CMake Microsoft.VisualStudio.2019.BuildTools RubyInstallerTeam.RubyWithDevKit.2.7
  • Install the neccessary dependencies within VS2019:
    • Launch "Visual Studio Installer"
    • Click "Modify"
    • Check "Desktop Development with C++"
    • Make sure the following components are installed:
      • Windows 10 SDK (10.0.19041.0)
      • MSVC v142 - VS 2019 C+ + x64/x86 build tools (Latest)
    • Click "Modify"
  • Run ridk install with options 1,3 to set up MSYS2 and development toolchain
  • Add MSYS2's gcc at C:\Ruby27-x64\msys64\mingw64\bin to your $PATH manually or with the following PowerShell command:
text
[Environment]::SetEnvironmentVariable('Path', $env:Path + ';C:\Ruby27-x64\msys64\mingw64\bin', [EnvironmentVariableTarget]::Machine)
  • Open a new elevated prompt and run the following commands:
text
git clone --recursive https://github.com/nesbox/TIC-80 && cd .\TIC-80\build
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_BUILD_TYPE=Release -DBUILD_SDLGPU=On -DBUILD_WITH_ALL=On ..
cmake --build . --parallel

You'll find tic80.exe in TIC-80\build\bin.

MSYS2 / MINGW

Windows 10 / 11 64-bit (x64)

This guide assumes you're running PowerShell with an elevated prompt.

text
winget install Git.Git Kitware.CMake RubyInstallerTeam.RubyWithDevKit.2.7
  • Run ridk install with options 1,3 to set up MSYS2 and development toolchain
  • Add MSYS2's gcc at C:\Ruby27-x64\msys64\mingw64\bin to your $PATH manually or with the following PowerShell command:
text
[Environment]::SetEnvironmentVariable('Path', $env:Path + ';C:\Ruby27-x64\msys64\mingw64\bin', [EnvironmentVariableTarget]::Machine)
  • Open a new elevated prompt and run the following commands:
text
git clone --recursive https://github.com/nesbox/TIC-80 && cd .\TIC-80\build
cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DBUILD_SDLGPU=On -DBUILD_WITH_ALL=On ..
$numCPUs = [Environment]::ProcessorCount
mingw32-make "-j$numCPUs"

You'll find tic80.exe in TIC-80\build\bin.

Linux

Ubuntu

Ubuntu 22.04 (Jammy Jellyfish)

Run the following commands from a terminal:

text
# Install the latest CMake from https://apt.kitware.com
test -f /usr/share/doc/kitware-archive-keyring/copyright ||
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ jammy main' | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null
sudo apt-get update
test -f /usr/share/doc/kitware-archive-keyring/copyright ||
sudo rm /usr/share/keyrings/kitware-archive-keyring.gpg
sudo apt-get install kitware-archive-keyring

sudo apt update && sudo apt -y install build-essential cmake git libpipewire-0.3-dev libwayland-dev libsdl2-dev ruby-dev libglvnd-dev libglu1-mesa-dev freeglut3-dev libcurl4-openssl-dev
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_SDLGPU=On -DBUILD_WITH_ALL=On .. && cmake --build . --parallel

Install with Install Instructions

Ubuntu 24.04 (Noble Numbat)

Run the following commands from a terminal:

text
sudo apt update && sudo apt -y install build-essential cmake git libpipewire-0.3-dev libwayland-dev libsdl2-dev ruby-dev libcurl4-openssl-dev libglvnd-dev libglu1-mesa-dev freeglut3-dev
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_SDLGPU=On -DBUILD_WITH_ALL=On -DBUILD_STATIC=On .. && cmake --build . --parallel

Install with Install Instructions

Arch

run the following commands in the Terminal

text
sudo pacman -S cmake ruby mesa libglvnd glu
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_WITH_ALL=On .. && cmake --build . --parallel

Install with Install Instructions

Fedora

Fedora 36

run the following commands in the Terminal

text
sudo dnf -y groupinstall "Development Tools" "Development Libraries"
sudo dnf -y install ruby rubygem-{tk{,-doc},rake,test-unit} cmake libglvnd-devel libglvnd-gles freeglut-devel clang libXext-devel SDL_sound pipewire-devel pipewire-jack-audio-connection-kit-devel pulseaudio-libs-devel
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DCMAKE_CXX_COMPILER=clang++ -DSDL_ALSA=On -DBUILD_WITH_ALL=On ..

Install with Install Instructions

Fedora 40

Run the following commands from a terminal:

text
sudo dnf -y groupinstall "Development Tools" "Development Libraries"
sudo dnf -y install ruby-devel rubygem-rake cmake clang pipewire-devel SDL2-devel SDL2_sound-devel SDL2_gfx-devel wayland-devel libXext-devel pipewire-jack-audio-connection-kit-devel pipewire-jack-audio-connection-kit-devel pulseaudio-libs-devel rubygems-devel libdecor-devel libdrm-devel mesa-libgbm-devel esound-devel freeglut-devel
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_SDLGPU=On -DBUILD_WITH_ALL=On ..
cmake --build . --parallel

Install with Install Instructions

openSUSE

openSUSE Tumbleweed / Leap 16.0

Run the following commands from a terminal:

text
sudo zypper refresh
sudo zypper install --no-confirm --type pattern devel_basis
sudo zypper install --no-confirm cmake glu-devel libXext-devel pipewire-devel libcurl-devel
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_SDLGPU=On -DBUILD_WITH_ALL=On .. && cmake --build . --parallel

Install with Install Instructions

Raspberry Pi

Raspberry Pi OS (64-Bit) (Bookworm)

Run the following commands from a terminal:

text
sudo apt update && sudo apt -y install cmake libpipewire-0.3-dev libwayland-dev libsdl2-dev ruby-dev libcurl4-openssl-dev
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_SDLGPU=On -DBUILD_WITH_ALL=On .. && cmake --build . --parallel 2

Install with Install Instructions

Raspberry Pi (Retropie)

First, add jessie-backports repo to your /etc/apt/sources.list

deb [check-valid-until=no] http://archive.debian.org/debian jessie-backports main

Then run the following commands in the Terminal

text
# required public keys
gpg --keyserver pgpkeys.mit.edu --recv-key  8B48AD6246925553
gpg -a --export 8B48AD6246925553 | sudo apt-key add -
gpg --keyserver pgpkeys.mit.edu --recv-key 7638D0442B90D010
gpg -a --export 7638D0442B90D010 | sudo apt-key add -

# upgrade system
sudo apt-get update
sudo apt-get dist-upgrade

# install software
sudo apt-get install git build-essential ruby-full libsdl2-dev zlib1g-dev
sudo apt-get install -t jessie-backports liblua5.3-dev
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_WITH_ALL=On ..

# install software ubuntu 22.04.3 LTS
sudo apt-get install git build-essential ruby-full libsdl2-dev zlib1g-dev
sudo apt-get install liblua5.3-dev
sudo apt-get install libcurl4-openssl-dev
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_WITH_ALL=On ..

Install with Install Instructions

Note: If you are using a normal Raspberry Pi image (not Retropie) you may not
have OpenGL drivers enabled. Run sudo raspi-config, then select 7
for "Advanced Options", followed by 6 for "GL Drivers", and enable "GL
(Fake KMS) Desktop Driver". After changing this setting, reboot.

Mac

install Command Line Tools for Xcode and brew package manager

Standard SDL2 Build

run the following commands in the Terminal

text
brew install git cmake
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_WITH_ALL=On -DCMAKE_POLICY_VERSION_MINIMUM=3.5 ..
make -j4

Native Apple Backend (Metal / AppKit / Swift)

TIC-80 also includes an optional native Apple backend built with Metal, AppKit, AVFoundation, GameController, and Swift:

text
brew install git cmake
git clone --recursive https://github.com/nesbox/TIC-80
cmake -G Xcode -B build -DBUILD_APPLE=ON -DBUILD_STATIC=ON -DBUILD_RENDER_CACHE=ON -DBUILD_SDLGPU=OFF -DBUILD_WITH_ALL=ON
cmake --build build --config Release

to create application icon for development version

text
mkdir -p ~/Applications/tic80dev.app/Contents/{MacOS,Resources}
cp -f macosx/tic80.plist ~/Applications/tic80dev.app/Contents/Info.plist
cp -f macosx/tic80.icns ~/Applications/tic80dev.app/Contents/Resources
cat > ~/Applications/tic80dev.app/Contents/MacOS/tic80 <<EOF
#!/bin/sh
exec /Users/nesbox/projects/TIC-80/build/bin/tic80 --skip >/dev/null
EOF
chmod +x ~/Applications/tic80dev.app/Contents/MacOS/tic80

FreeBSD

run the following commands in the Terminal

text
sudo pkg install gcc git cmake ruby libglvnd libglu freeglut mesa-devel mesa-dri alsa-lib
git clone --recursive https://github.com/nesbox/TIC-80 && cd TIC-80/build
cmake -DBUILD_WITH_ALL=On ..
make -j4

Mesa looks for swrast_dri.so from the wrong path, so also symlink it:

text
sudo ln -s /usr/local/lib/dri/swrast_dri.so /usr/local/lib/dri-devel/

Install instructions

Linux

  • To make an executable file ./tic80 without installation run make and locate the output in TIC-80/build/bin.
  • To install system-wide run sudo make install
  • You can append -j4 if you have a modern system, or -j2 for a Raspberry Pi to speed up the process.

TIC-80 can now be run with tic80 (if installed) or ./tic80 (with no installation).

iOS / tvOS

You can find iOS/tvOS version here

Android

You can find the compiled version ready download and install on F-Droid:

Credits

Overview (`patches/README.md`)

Patches

Gravity

gravity-patch.patch

  • gravity_parser.c, gravity_vm.c : Remove ENV and FILE optional libraries.
  • gravity_config.h : Force define bzero if it doesn't exist.
  • gravity_opt_json.c, gravity_vm.c, gravity_json.c : Rename json_parse to prevent a conflict.

Overview (`templates/README.md`)

Compiled Language Templates

This directory contains starter projects (and libs) for the compiled languages we support via script: wasm. Currently this list includes:

  • Zig (low-level)
  • D (low-level)
  • Go (via TinyGo)
  • C
  • Rust
  • Nim

We could easily support these as well, with contributor help:

  • C++
  • Nelua
  • Odin
  • Wat

What is needed? Pull over the example build/template scripts from the WASM-4 project templates. These are typically well done and well maintained so they are a great starting point.

  • Remove wasm4.h.
  • Replace with tic80.h
  • Implement the core API wrapper for your language
  • Implement "nice to haves" to make the API easier to use in your language

If you're interested in helping start by posting on the overarching GitHub topic:

https://github.com/nesbox/TIC-80/issues/1784

Overview (`build/android/readme.md`)

USEFUL ADB COMMANDS

BUILD IN DOCKER

You may need to add exec sdkmanager "ndk;23.2.8568313" just before ./gradlew assembleRelease, the version must match the one shown in app/build.gradle.

text
winpty docker exec -it nice_goldwasser bash -c "cd /tic80/build/android && ./gradlew assembleRelease" && adb install -r app/build/outputs/apk/arm8/release/app-arm8-release.apk && adb shell am start -n com.nesbox.tic/com.nesbox.tic.TIC

INSTALL APP AND RUN

text
release: adb install -r app/build/outputs/apk/arm8/release/app-arm8-release.apk && adb shell am start -n com.nesbox.tic/com.nesbox.tic.TIC

debug: adb install -r app/build/outputs/apk/arm8/debug/app-arm8-debug.apk && adb shell am start -n com.nesbox.tic/com.nesbox.tic.TIC

VIEW APP LOG

text
adb logcat --pid `adb shell pidof com.nesbox.tic`

STOP APP

text
adb shell am force-stop com.nesbox.tic

Overview (`build/baremetalpi/README.md`)

Raspberry PI Baremetal build

The following explains how to build TIC-80 for the Raspberry PI boards in baremetal mode, that is, without an operating system (the board boots directly in TIC-80)

Requirements

You need:

  • A Linux machine
  • gcc ARM toolchain. You can get it here. Successfully tested with version: gcc-arm-none-eabi-8-2018-q4-major
  • A standard building environment (make, cmake, gcc, wget, etc)

Building instructions

Following are all the building steps for building the system.

First, set the path to include the arm toolkit (fix the command with your path):

text
PATH=/home/you/gcc-arm-none-eabi-8-2018-q4-major/bin/:$PATH

Get a fresh copy of TIC-80 repository:

text
git clone --recursive https://github.com/nesbox/TIC-80
cd TIC-80

Now build circle-stdlib (3 is your RPi model, should build with 2 and 4 too but it's untested):

text
cd vendor/circle-stdlib
./configure -r 3
make

Make some addon that are not compiled automatically:

text
cd libs/circle/addon/vc4/sound/
make
cd ../vchiq
make
cd ../../linux
make
cd ../../../../../..

Build tic80studio for arm with baremetal customizations:

text
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=baremetalpi/toolchain.cmake ..
make tic80studio

Build the kernel:

text
cd baremetalpi
make

This generates the final kernel8-32.img file (or something similar depending on the RPI version). Copy it into your SD card root.

Now you have to download some bootup files that need to be copied to the SD card root together with your kernel8-32.img. This only need to be done once.

text
cd ../../vendor/circle-stdlib/libs/circle/boot/
make

Read the README.md in this folder to see what files needs to be copied to your RPI. For RPi3 should be ok to copy all of them

You can create a tic80 folder into your SD card to put your carts in.

Thanks

This project is built on two awesome projects, circle and circle-stdlib. Without them, this version of TIC-80 would not exist.

Overview (`build/n3ds/README.md`)

3DS build

Requirements

  • devkitARM + the 3ds-dev meta package
  • the following additional packages:
    • 3ds-libpng
    • 3ds-zlib

Building instructions

text
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/3DS.cmake
cmake --build build

You should now be able to find tic80.3dsx in build/bin.

Overview (`build/nswitch/README.md`)

Switch build

Requirements

  • devkitA64 + the switch-dev meta package
  • the following additional packages:
    • switch-libpng
    • switch-zlib
    • switch-sdl2
    • switch-curl

Building instructions

text
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/Switch.cmake
cmake --build build

You should now be able to find tic80.nro in build/bin.

Overview (`templates/c/README.md`)

C Starter Project Template

Pre-requisites

Files in this template

  • buildcart.sh - convenience script to build and run the game cartridge
  • buildwasm.sh - convenience script to build and run the Wasm program
  • Makefile - convenience Makefile that builds the project
  • wasmdemo.wasmp - TIC-80 Wasm 'script' file. Note the embedded game assets data at the end of the file.

Building your game

Define the environment variable WASI_SDK_PATH; e.g., if you installed WASI
into $HOME/wasi-sdk, then export WASI_SDK_PATH=$HOME/wasi-sdk.

The default linker settings reserve TIC-80's first 96 KiB of linear memory by using a stack-first layout with 96 KiB + 8 KiB of configured stack.

Edit src/main.c to implement your game. You are of course free to
organize your code in more than one C source file.

If you create sprites, map, music, etc., for your game, remember to
replace the game asset data at the end of wasmdemo.wasmp with
your creations.

To build the Wasm file, execute make. This generates cart.wasm
in the build directory. To run:

text
% tic80 --fs . --cmd 'load wasmdemo.wasmp & import binary cart.wasm & run & exit'

The script buildwasm.sh contains above steps as a convenience.

To build a TIC-80 cartridge, first build the Wasm file, then build the
cartridge file:

text
% tic80 --fs . --cmd 'load wasmdemo.wasmp & import binary cart.wasm & save game.tic & exit'

You can then run your cartridge as follows:

text
% tic80 --fs . --cmd 'load game.tic & run & exit'

The script buildcart.sh does the above steps as a convenience.

Additional Notes

TIC-80 API functions that merely duplicate standard library functionality are not imported. Please use the memcpy and memset functions provided by the C standard library instead.

Alternative Build System

You can use Zig to build this template.

Install Zig 0.17 or above and run:

text
% zig build

The result will be in zig-out/bin/cart.wasm

You can build and run your cart with:

text
% zig build run

Overview (`templates/cpp/README.md`)

C++ Starter Project Template (using Zig Build System)

Pre-requisites

This is a C++ / TIC-80 starter template.

The build reserves TIC-80's first 96 KiB of linear memory by folding that space into the configured stack size and leaving 8 KiB of actual stack above it.

text
zig build

To import the resulting WASM to a cartridge:

text
tic80 --fs . --cmd 'load cart.wasmp & import binary zig-out/bin/cart.wasm & save'

Or from the TIC-80 console:

text
tic80 --fs .

load cart.wasmp
import binary zig-out/bin/cart.wasmp
save

This is assuming you've run TIC-80 with --fs . inside your project directory.

Or easy call it :)

zsh
zig build run

Overview (`templates/d/README.md`)

D Starter Project Template

Pre-requisites

WASI libc

WASI libc's README states
that "the easiest way to get started with this is to use wask-sdk, which
includes a build of WASI libc in its sysroot."

Just building WASI libc from source
works too, for the purpose of programming TIC-80 games in D. Let's say you
install into $HOME/wasi-sdk/share/wasi-sysroot, which then look like this:

text
% ls -l
total 12
drwxr-xr-x 10 pierce pierce 4096 Apr 24 16:19 include/
drwxr-xr-x  3 pierce pierce 4096 Apr 24 16:19 lib/
drwxr-xr-x  3 pierce pierce 4096 Apr 24 16:19 share/

Files in this template

  • buildcart.sh - convenience script to build and run the game cartridge
  • buildwasm.sh - convenience script to build and run the Wasm program
  • dub.json - D's dub package description file
  • Makefile - convenience Makefile that invokes dub
  • wasmdemo.wasmp - TIC-80 Wasm 'script' file. Note the embedded game assets data at the end of the file.

Building your game

Define the environment variable WASI_SDK_PATH; e.g., if you installed WASI
libc into $HOME/wasi-sdk/share/wasi-sysroot, then export WASI_SDK_PATH=$HOME/wasi-sdk.

The default linker settings reserve TIC-80's first 96 KiB of linear memory by using a stack-first layout with 96 KiB + 8 KiB of configured stack.

Edit src/main.d to implement your game. You are of course free to
organize your code in more than one D source file.

If you create sprites, map, music, etc., for your game, remember to
replace the game asset data at the end of wasmdemo.wasmp with
your creations.

To build the Wasm file, execute make. This generates cart.wasm
in the current directory. To run:

text
% tic80 --fs . --cmd 'load wasmdemo.wasmp & import binary cart.wasm & run & exit'

The script buildwasm.sh contains above steps as a convenience.

To build a TIC-80 cartridge, first build the Wasm file, then build the
cartridge file:

text
% tic80 --fs . --cmd 'load wasmdemo.wasmp & import binary cart.wasm & save game.tic & exit'

You can then run your cartridge as follows:

text
% tic80 --fs . --cmd 'load game.tic & run & exit'

The script buildcart.sh does the above steps as a convenience.

Overview (`templates/go/README.md`)

Go Starter Project Template

This is a Go / TIC-80 starter template using TinyGo to
compile Go to WebAssembly.

Pre-requisites

Files in this template

  • tic80/ - the TIC-80 API wrapper library (cart/tic80)
  • main.go - the demo game source
  • target.json - TinyGo build target for TIC-80's wasm runtime
  • cart.wasmp - TIC-80 Wasm 'script' file with the game assets
  • Makefile - convenience Makefile that builds the project
  • run.sh - convenience script that builds and runs the game

Building your game

Edit main.go to implement your game. Export the callbacks you need
with //go:export (BOOT, TIC, BDR(row), SCN(row),
MENU(index)); only TIC is required.

To build the wasm file, execute make. This generates
build/cart.wasm. To build and run:

text
% sh run.sh

Or manually:

text
% tic80 --fs . --cmd 'load cart.wasmp & import binary build/cart.wasm & save game.tic & run & exit'

If your TIC-80 build cannot load text cartridges (non-PRO builds), create the
cartridge from the console instead:

text
new wasm
import binary build/cart.wasm
save game.tic
run

Memory layout

The build reserves TIC-80's first 96 KiB of linear memory by using a
stack-first layout with 96 KiB + 8 KiB of configured stack, inside the
256 KiB that TIC-80 provides (4 wasm pages). Free memory for your game
starts at 0x18000 (tic80.WASM_FREE_RAM).

Examples

  • examples/pix - pixel drawing and reading, inspired by the pix()
    examples on the TIC-80 wiki. Build and run it with:
text
make pix
tic80 --fs . --cmd 'new wasm & import binary build/pix.wasm & run'
  • examples/bdr - screen shake glitch via the BDR callback, inspired by
    the BDR() example on the TIC-80 wiki. Build and run it with:
text
make bdr
tic80 --fs . --cmd 'new wasm & import binary build/bdr.wasm & run'
  • examples/bdr2 - per-scanline palette gradient (>16 colors) via the
    BDR callback and both video banks, from the TIC-80 wiki. Build and run:
text
make bdr2
tic80 --fs . --cmd 'new wasm & import binary build/bdr2.wasm & run'
  • examples/ttri2 - sprite rotation: two ttri triangles with
    per-vertex z (perspective-correct texture mapping) rotating the 2x2-tile
    sprite at UV (8,0)-(24,16) - with the demo cartridge that is the TIC guy.
    Build and run it with:
text
make ttri2
tic80 --fs . --cmd 'load cart.wasmp & import binary build/ttri2.wasm & save game.tic & run'
  • examples/ttri - textured triangles with a UV window scaled by the
    arrow keys, from the TIC-80 wiki. Build and run it with:
text
make ttri
tic80 --fs . --cmd 'new wasm & import binary build/ttri.wasm & run'

Important notes

  • Call tic80.Init() first thing in BOOT. The TIC-80 wasm runtime
    never calls the module's entry point, so TinyGo's runtime (heap limits,
    GC state) only gets set up when Init runs. Without it the first heap
    allocation kills the game with [trap] unreachable executed.
  • The tilesheet is stored tile-major: tile (x/8, y/8) occupies 32
    consecutive bytes (4 bytes per row, two pixels per byte, low nibble =
    even x). Writing it as a linear 128x64-byte image will look scrambled
    when sampled by spr/ttri - see setSheetPix in the examples.
  • The TinyGo garbage collector is configured as leaking (it never
    collects). Avoid allocations in your game loop: hoist slices, strings and
    other composite literals to package-level variables, like
    transparent14 in main.go.
  • TIC-80 wants NUL-terminated strings, which Go strings don't provide.
    Print, Font and Trace copy your string into a shared
    static buffer (max 255 bytes), so they don't allocate.
  • The map remap callback (tic80.MapOptions{Remap: ...}``) uses wasm function-table entries; the wrapper takes care of the low-level details. Modify the RemapResult``` in place to change the tile that gets drawn.
  • You don't need a main() function; the library provides one.

This template is based on the Go template from the
WASM-4 project.

Overview (`templates/nim/README.md`)

Nim Starter Project Template

This is a Nim / TIC-80 starter template. To build wasm binary and import it into
the 'cart.tic' file, ensure you have a Nim compiler, Wasi-SDK and Tic-80 on your system and run:

The linker settings reserve TIC-80's first 96 KiB of linear memory by using a stack-first layout with 96 KiB + 8 KiB of configured stack.

text
nimble buildcart

Run nimble tasks command to see more build options.

Overview (`templates/rust/README.md`)

Rust Starter Project Template

Important Note

Don't access TIC-80's I/O memory by dereferencing raw pointers. The optimiser will ruin attempts to do this, because Rust has no equivalent to C's volatile for direct access. Instead, use std::ptr::read_volatile and std::ptr::write_volatile, or just use the standard TIC-80 peek/poke.

This template also reserves TIC-80's first 96 KiB of linear memory by forcing a stack-first layout and inflating the configured stack size to 96 KiB + 8 KiB.

This is a Rust / TIC-80 starter template. Before using it, make sure you have installed the wasm32-unknown-unknown target using rustup:

text
rustup target add wasm32-unknown-unknown

Then, to build a cart.wasm file, run:

text
cargo build --release --target=wasm32-unknown-unknown

To import the resulting WASM to a cartridge named game.tic:

text
tic80 --fs . --cmd 'new wasm & import binary target/wasm32-unknown-unknown/release/cart.wasm & save game'

Or from the TIC-80 console:

text
new wasm
import binary target/wasm32-unknown-unknown/release/cart.wasm
save game

This is assuming you've run TIC-80 with --fs . inside your project directory.

wasm-opt

It is highly recommended that you run wasm-opt on the output cart.wasm file, especially if using the usual unoptimised builds. To do so, make sure wasm-opt is installed, then run:

text
wasm-opt -Os target/wasm32-unknown-unknown/release/cart.wasm -o cart.wasm

This will create a new, smaller cart.wasm file in the working directory.

Overview (`templates/zig/README.md`)

ZIG Starter Project Template

This is a ZIG / TIC-80 starter template. To build it, ensure you have the latest development release (0.14.0-dev.1421+f87dd43c1 or newer), then run:

The build reserves TIC-80's first 96 KiB of linear memory by folding that space into the configured stack size and leaving 8 KiB of actual stack above it.

text
zig build

To import the resulting WASM to a cartridge:

text
tic80 --fs . --cmd 'load cart.wasmp & import binary zig-out/bin/cart.wasm & save'

Or from the TIC-80 console:

text
tic80 --fs .

load zig-out/bin/cart.wasmp
import binary cart.wasm
save

This is assuming you've run TIC-80 with --fs . inside your project directory.

Or easy call it :)

zsh
zig build run

Overview (`vendor/fennel/README.md`)

Fennel Integration

The code here is a full implementation of Fennel,
provided as a library. Each time a new Fennel release is made, these files must
be regenerated.

Requirements

  • Lua
  • xxd (provided by vim)

Steps

  1. Clone a copy of Fennel into the same directory you cloned TIC-80 into, making them "siblings".
sh
git clone https://git.sr.ht/~technomancy/fennel

ls here should list both fennel and TIC-80.

  1. Make a full Fennel build.
sh
cd fennel
make
  1. From within TIC-80/vendor/fennel/, delete the previous files and regenerate them.
sh
rm loadfennel.lua fennel.h fennel.lua
make
  1. About 20,000 lines will have changed. Commit the update and open a PR.

Overview (`vendor/s7/README.md`)

s7

s7 is a Scheme interpreter.

documentation

git repository
if you get a certificate complaint: git config --global http.sslVerify false

daily tarball

mailing list

mailing list archive

svn site (Snd)

scheme-for-max and scheme-for-pd (Iain Duncan)

radium (Kjetil Matheussen)

SchemeMosaic (David O'Toole)

Common Music (Rick Taube)

docker container: docker run -it schemers/s7:head (Lassi Kortela)

web assembly (Christos Vagias)

the original

Overview (`demos/bunny/wasmmark/README.md`)

Bunnymark in Zig / WASM

This is a Zig project. To build it you'll need the latest Zig development release (0.14.0-dev.1421+f87dd43c1 or newer).

Building

text
zig build --release=small

Replacing the assets used to build TIC-80

Copy the build over the canonical WASM file:

text
cp zig-out/bin/cart.wasm wasmmark.wasm

During a TIC-80 build the wasm and wasmp file will be merged into a single demo cartridge and embedded into the TIC-80 binary.

Overview (`src/system/libretro/README.md`)

TIC-80 libretro

Provided is a TIC-80 libretro core to render TIC-80 cartridges through the libretro API and RetroArch.

Build

To build the core by itself, run the following commands.

text
git clone https://github.com/nesbox/TIC-80.git
cd TIC-80
git submodule update --init --recursive
cd build
cmake .. -DBUILD_PLAYER=OFF -DBUILD_SDL=OFF -DBUILD_TOOLS=OFF -DBUILD_LIBRETRO=ON
make

Usage

text
retroarch -L lib/tic80_libretro.so sfx.tic

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#8bit Browse 8bit catalog → #fantasy-computer Browse fantasy-computer catalog → #fantasy-console Browse fantasy-console catalog → #gamedev Browse gamedev catalog → #gameengine Browse gameengine catalog → #retro Browse retro catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →