# Technical Documentation: nesbox/TIC-80 > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/nesbox/TIC-80) ### Overview (`README.md`) [](https://github.com/nesbox/TIC-80/actions?query=workflow%3ABuild) **TIC-80 TINY COMPUTER** — [tic80.com](https://tic80.com) - [About](#about) - [Features](#features) - [Binary Downloads](#binary-downloads) - [Nightly builds](#nightly-builds) - [Unofficial Linux/arm64 nightly builds](#unofficial-builds) - [Pro Version](#pro-version) - [Pro Features](#pro-features) - [Community](#community) - [Contributing](#contributing) - [Build Instructions](#build-instructions) - [Windows](#windows) - [MSVC (Microsoft Visual C++)](#msvc-microsoft-visual-c) - [Windows XP / Windows 7 32-bit (x86)](#windows-xp--windows-7-32-bit-x86) - [Windows 10 / 11 64-bit (x64)](#windows-10--11-64-bit-x64) - [MSYS2 / MINGW](#msys2--mingw) - [Windows 10 / 11 64-bit (x64)](#windows-10--11-64-bit-x64-1) - [Linux](#linux) - [Ubuntu](#ubuntu) - [Ubuntu 22.04 (Jammy Jellyfish)](#ubuntu-2204-jammy-jellyfish) - [Ubuntu 24.04 (Noble Numbat)](#ubuntu-2404-noble-numbat) - [Arch](#arch) - [Fedora](#fedora) - [Fedora 36](#fedora-36) - [Fedora 40](#fedora-40) - [openSUSE](#opensuse) - [openSUSE Tumbleweed / Leap 16.0](#opensuse-tumbleweed--leap-160) - [Raspberry Pi](#raspberry-pi) - [Raspberry Pi OS (64-Bit) (Bookworm)](#raspberry-pi-os-64-bit-bookworm) - [Raspberry Pi (Retropie)](#raspberry-pi-retropie) - [Mac](#mac) - [FreeBSD](#freebsd) - [Install Instructions](#install-instructions) - [Linux](#linux-1) - [Android](#android) - [iOS / tvOS](#ios--tvos) - [Credits](#credits) # 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](https://www.lua.org), [Moonscript](https://moonscript.org), [Javascript](https://developer.mozilla.org/en-US/docs/Web/JavaScript), [Ruby](https://www.ruby-lang.org/en), [Wren](https://wren.io/), [Fennel](https://fennel-lang.org), [Squirrel](https://www.squirrel-lang.org), [Janet](https://janet-lang.org), and [Python](https://www.python.org). - 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](https://github.com/nesbox/TIC-80/releases) page. ## Nightly Builds Can be downloaded from official [nightly.link](https://nightly.link/nesbox/TIC-80/workflows/build/main) page or from the [Github Actions](https://github.com/nesbox/TIC-80/actions?query=branch%3Amain) page. ## Unofficial Builds Linux (arm64) builds can be downloaded from _aliceisjustplaying_ [nightly.link](https://nightly.link/aliceisjustplaying/TIC-80/workflows/build-linux-arm64/main?preview) 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](https://nesbox.itch.io/tic80). 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](https://tic80.com/play). The community also hangs out and discusses on [Telegram](https://t.me/tic80) or [Discord](https://discord.gg/HwZDw7n4dN). # Contributing You can contribute by reporting a bug or requesting a new feature on our [Issues](https://github.com/nesbox/TIC-80/issues) page. Keep in mind when engaging on a discussion to follow our [Code of Conduct](https://github.com/nesbox/TIC-80/blob/main/CODE_OF_CONDUCT.md). You can also contribute by reviewing or improving our [Wiki](https://github.com/nesbox/TIC-80/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](https://git-scm.com/download/win), [CMake](https://cmake.org/download), [Visual Studio 2019 Build Tools](https://winstall.app/apps/Microsoft.VisualStudio.2019.BuildTools) and [Ruby+Devkit 2.7.8 x86](https://github.com/oneclick/rubyinstaller2/releases/download/RubyInstaller-2.7.8-1/rubyinstaller-devkit-2.7.8-1-x86.exe) - 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](https://www.msys2.org) and development toolchain - Add MSYS2's [`gcc`](https://gcc.gnu.org) at `C:\Ruby27\msys32\mingw32\bin` to your `$PATH` [(guide)](https://www.java.com/en/download/help/path.html#:~:text=your%20java%20code.-,Windows%207,-From%20the%20desktop) - Open a new elevated Command Prompt and run the following commands: ``` 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. - Install [Git](https://git-scm.com/download/win), [CMake](https://cmake.org/download), [Visual Studio 2019 Build Tools](https://winstall.app/apps/Microsoft.VisualStudio.2019.BuildTools) and [Ruby+Devkit 2.7.8 x64](https://github.com/oneclick/rubyinstaller2/releases/download/RubyInstaller-2.7.8-1/rubyinstaller-devkit-2.7.8-1-x64.exe) manually or with [WinGet](https://github.com/microsoft/winget-cli): ``` 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](https://www.msys2.org) and development toolchain - Add MSYS2's [`gcc`](https://gcc.gnu.org) at `C:\Ruby27-x64\msys64\mingw64\bin` to your `$PATH` [manually](https://www.java.com/en/download/help/path.html#:~:text=Mac%20OS%20X.-,Windows,-Windows%2010%20and) or with the following PowerShell command: ``` [Environment]::SetEnvironmentVariable('Path', $env:Path + ';C:\Ruby27-x64\msys64\mingw64\bin', [EnvironmentVariableTarget]::Machine) ``` - Open a new elevated prompt and run the following commands: ``` 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. - Install [Git](https://git-scm.com/download/win), [CMake](https://cmake.org/download) and [Ruby+Devkit 2.7.8 x64](https://github.com/oneclick/rubyinstaller2/releases/download/RubyInstaller-2.7.8-1/rubyinstaller-devkit-2.7.8-1-x64.exe) manually or with [WinGet](https://github.com/microsoft/winget-cli): ``` winget install Git.Git Kitware.CMake RubyInstallerTeam.RubyWithDevKit.2.7 ``` - Run `ridk install` with options `1,3` to set up [MSYS2](https://www.msys2.org) and development toolchain - Add MSYS2's [`gcc`](https://gcc.gnu.org) at `C:\Ruby27-x64\msys64\mingw64\bin` to your `$PATH` [manually](https://www.java.com/en/download/help/path.html#:~:text=Mac%20OS%20X.-,Windows,-Windows%2010%20and) or with the following PowerShell command: ``` [Environment]::SetEnvironmentVariable('Path', $env:Path + ';C:\Ruby27-x64\msys64\mingw64\bin', [EnvironmentVariableTarget]::Machine) ``` - Open a new elevated prompt and run the following commands: ``` 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: ``` # 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](#install-instructions) #### Ubuntu 24.04 (Noble Numbat) Run the following commands from a terminal: ``` 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](#install-instructions) ### Arch run the following commands in the Terminal ``` 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](#install-instructions) ### Fedora #### Fedora 36 run the following commands in the Terminal ``` 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](#install-instructions) #### Fedora 40 Run the following commands from a terminal: ``` 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](#install-instructions) ### openSUSE #### openSUSE Tumbleweed / Leap 16.0 Run the following commands from a terminal: ``` 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](#install-instructions) ### Raspberry Pi #### Raspberry Pi OS (64-Bit) (Bookworm) Run the following commands from a terminal: ``` 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](#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 ``` # 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](#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 ``` 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: ``` 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 ``` 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 </dev/null EOF chmod +x ~/Applications/tic80dev.app/Contents/MacOS/tic80 ``` ## FreeBSD run the following commands in the Terminal ``` 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: ``` 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 - 0.60.3: https://github.com/brunophilipe/TIC-80 - 0.45.0: https://github.com/CliffsDover/TIC-80 ## Android You can find the compiled version ready download and install [on F-Droid](https://f-droid.org/packages/com.nesbox.tic/): [Get it on F-Droid](https://f-droid.org/packages/com.nesbox.tic/) ## Credits * Filippo Rivato — [Twitter @HomineLudens](https://twitter.com/HomineLudens) * Fred Bednarski — [Twitter @FredBednarski](https://twitter.com/FredBednarski) * Al Rado — [Twitter @alrado2](https://twitter.com/alrado2) * Trevor Martin — [Twitter @trelemar](https://twitter.com/trelemar) * MonstersGoBoom — [Twitter @MonstersGoBoom](https://twitter.com/MonstersGo) * Matheus Lessa — [Twitter @matheuslrod](https://twitter.com/matheuslrod) * CliffsDover — [Twitter @DancingBottle](https://twitter.com/DancingBottle) * Frantisek Jahoda — [GitHub @jahodfra](https://github.com/jahodfra) * Guilherme Medeiros — [GitHub @frenetic](https://github.com/frenetic) * Andrei Rudenko — [GitHub @AndreiRudenko](https://github.com/AndreiRudenko) * Phil Hagelberg — [@technomancy](https://technomancy.us/colophon) * Rob Loach — [Twitter @RobLoach](https://twitter.com/RobLoach) [GitHub @RobLoach](https://github.com/RobLoach) * Wade Brainerd — [GitHub @wadetb](https://github.com/wadetb) * Paul Robinson — [GitHub @paul59](https://github.com/paul59) * Stefan Devai — [GitHub @stefandevai](https://github.com/stefandevai) [Blog stefandevai.me](https://stefandevai.me) * Damien de Lemeny — [GitHub @ddelemeny](https://github.com/ddelemeny) * Adrian Siekierka — [GitHub @asiekierka](https://github.com/asiekierka) [Website](https://asie.pl/) * Jay Em (Sweetie16 palette) — [Twitter @GrafxKid](https://twitter.com/GrafxKid) * msx80 — [Twitter @msx80](https://twitter.com/msx80) [Github msx80](https://github.com/msx80) * Josh Goebel — [Twitter @dreamer3](https://twitter.com/dreamer3) [Github joshgoebel](https://github.com/joshgoebel) * Joshua Minor — [GitHub @jminor](https://github.com/jminor) * Julia Nelz — [Github @remi6397](https://github.com/remi6397) [WWW](https://nelz.pl) * Thorben Krüger — [Mastodon @benthor@chaos.social](https://chaos.social/@benthor) * David St—Hilaire — [GitHub @sthilaid](https://github.com/sthilaid) * Alec Troemel — [Github @alectroemel](https://github.com/AlecTroemel) * Kolten Pearson — [Github @koltenpearson](https://github.com/koltenpearson) * Cort Stratton — [Github @cdwfs](https://github.com/cdwfs) * Alice — [Github @aliceisjustplaying](https://github.com/aliceisjustplaying) * Sven Knebel — [Github @sknebel](https://github.com/sknebel) * Graham Bates — [Github @grahambates](https://github.com/grahambates) * Kii — [Github @kiikrindar](https://github.com/kiikrindar) * Matt Westcott — [Github @gasman](https://github.com/gasman) * NuSan — [Github @TheNuSan](https://github.com/thenusan) * Li Jin — [Github @pigpigyyy](https://github.com/pigpigyyy) * Dania Rifki — [Github @Kaleidosium](https://github.com/Kaleidosium) * Carsten Teibes — [GitHub @carstene1ns](https://github.com/carstene1ns) --- ### 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](https://wasm4.org) project [templates](https://github.com/aduros/wasm4/tree/main/cli/assets/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`. ``` 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 ``` 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 ``` adb logcat --pid `adb shell pidof com.nesbox.tic` ``` ## STOP APP ``` 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](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). 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): ``` PATH=/home/you/gcc-arm-none-eabi-8-2018-q4-major/bin/:$PATH ``` Get a fresh copy of TIC-80 repository: ``` 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): ``` cd vendor/circle-stdlib ./configure -r 3 make ``` Make some addon that are not compiled automatically: ``` cd libs/circle/addon/vc4/sound/ make cd ../vchiq make cd ../../linux make cd ../../../../../.. ``` Build `tic80studio` for arm with baremetal customizations: ``` cd build cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=baremetalpi/toolchain.cmake .. make tic80studio ``` Build the kernel: ``` 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. ``` 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](https://github.com/rsta2/circle) and [circle-stdlib](https://github.com/smuehlst/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 ``` 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 ``` 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 - [WASI SDK](https://github.com/WebAssembly/wasi-sdk) ## 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: ``` % 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: ``` % tic80 --fs . --cmd 'load wasmdemo.wasmp & import binary cart.wasm & save game.tic & exit' ``` You can then run your cartridge as follows: ``` % 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](https://ziglang.org/) to build this template. Install Zig 0.17 or above and run: ``` % zig build ``` The result will be in zig-out/bin/cart.wasm You can build and run your cart with: ``` % zig build run ``` --- ### Overview (`templates/cpp/README.md`) # C++ Starter Project Template (using Zig Build System) ## Pre-requisites - [Zig Compiler](https://ziglang.org/) 0.17 or above 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. ``` zig build ``` To import the resulting WASM to a cartridge: ``` tic80 --fs . --cmd 'load cart.wasmp & import binary zig-out/bin/cart.wasm & save' ``` Or from the TIC-80 console: ``` 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 - [LDC](https://wiki.dlang.org/LDC) - [WASI libc](https://github.com/WebAssembly/wasi-libc) ### WASI libc WASI libc's [README](https://github.com/WebAssembly/wasi-libc#usage) 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](https://github.com/WebAssembly/wasi-libc#building-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: ``` % 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: ``` % 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: ``` % tic80 --fs . --cmd 'load wasmdemo.wasmp & import binary cart.wasm & save game.tic & exit' ``` You can then run your cartridge as follows: ``` % 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](https://tinygo.org) to compile Go to WebAssembly. ## Pre-requisites - [TinyGo](https://tinygo.org/docs/getting-started/) (0.42 or newer) - Optional: [wasm-opt](https://github.com/WebAssembly/binaryen) for smaller builds ## 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: ``` % sh run.sh ``` Or manually: ``` % 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: ``` 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: ``` 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: ``` 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: ``` 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: ``` 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: ``` 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](https://wasm4.org) 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. ``` 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`](https://doc.rust-lang.org/std/ptr/fn.read_volatile.html) and [`std::ptr::write_volatile`](https://doc.rust-lang.org/std/ptr/fn.write_volatile.html), 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: ``` rustup target add wasm32-unknown-unknown ``` Then, to build a cart.wasm file, run: ``` cargo build --release --target=wasm32-unknown-unknown ``` To import the resulting WASM to a cartridge named `game.tic`: ``` tic80 --fs . --cmd 'new wasm & import binary target/wasm32-unknown-unknown/release/cart.wasm & save game' ``` Or from the TIC-80 console: ``` 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: ``` 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. ``` zig build ``` To import the resulting WASM to a cartridge: ``` tic80 --fs . --cmd 'load cart.wasmp & import binary zig-out/bin/cart.wasm & save' ``` Or from the TIC-80 console: ``` 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](https://fennel-lang.org/), 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`. 2. Make a full Fennel build. ``` sh cd fennel make ``` 3. From within `TIC-80/vendor/fennel/`, delete the previous files and regenerate them. ``` sh rm loadfennel.lua fennel.h fennel.lua make ``` 4. 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](https://ccrma.stanford.edu/software/snd/snd/s7.html) [git repository](https://cm-gitlab.stanford.edu/bil/s7.git) if you get a certificate complaint: git config --global http.sslVerify false [daily tarball](https://ccrma.stanford.edu/software/s7/s7.tar.gz) [mailing list](http://ccrma-mail.stanford.edu/mailman/listinfo/cmdist) [mailing list archive](https://cm-mail.stanford.edu/pipermail/cmdist/) [svn site (Snd)](https://sourceforge.net/p/snd/svn1/) [scheme-for-max](https://github.com/iainctduncan/scheme-for-max) and [scheme-for-pd](https://github.com/iainctduncan/scheme-for-pd) (Iain Duncan) [radium](https://users.notam02.no/~kjetism/radium/) (Kjetil Matheussen) [SchemeMosaic](http://xelf.me/scheme-mosaic.html) (David O'Toole) [Common Music](http://commonmusic.sourceforge.net/) (Rick Taube) docker container: docker run -it schemers/s7:head (Lassi Kortela) [web assembly](https://github.com/actonDev/s7-playground/) (Christos Vagias) [the original](https://en.wikipedia.org/wiki/Sunbeam_S7_and_S8) --- ### 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 ``` zig build --release=small ``` ### Replacing the assets used to build TIC-80 Copy the build over the canonical WASM file: ``` 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](https://tic.computer) libretro core to render TIC-80 cartridges through the [libretro](https://www.libretro.com) API and [RetroArch](https://www.retroarch.com). ## Build To build the core by itself, run the following commands. ``` 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 ``` retroarch -L lib/tic80_libretro.so sfx.tic ``` --- --- METRICS --- - Files Extracted: 18 - Estimated Token Budget: ~10428 tokens - Canonical Reference: https://codewiki.google/github.com/nesbox/TIC-80