TSC-80 - TypeScript for the TIC-80

The documentation for TSC-80 1.0 is available here - Projects created for TSC-80 1.0 are incompatible with 2.0

Write your TIC-80 PRO games in TypeScript.

TSC-80 contains all the functions declarations (.d.ts) for the TIC-80 API, and will compile your TypeScript code in JavaScript to inject it into your TIC-80 cart.

Installation and usage

Pre-requisites

This tool has been tested with TIC-80 version 1.2.x (pro edition) on Windows 10, and should work on all platforms compatible with TIC-80 and TypeScript.

Install NodeJS LTS
Install TypeScript: npm install -g typescript
Install TSC-80: npm install -g tic80-typescript

Create a project

tsc80 init will create the necessary files (config, declarations, and game files) into the current directory
Set the correct values inside the tsc80-config.json

Configuration

You need to complete the tsc80-config.json for each project.

{
  "ticExecutable": "path/to/tic/executable/file", // The file path to your TIC executable.
  "entry": "main.ts", // The entry point of your game's code
  "outfile": "build/output.js", // Path to bundled file. You should not have to change this.
  "minify": false // If you want to minify your build. May provide very slight performances improvements
}

Run TSC-80

$ tsc80 build will build your game into the "build" directory
$ tsc80 run will build, watch the changes, and launch your game through TIC-80

Once that TIC-80 is running, all code changes in .ts files will be reflected after a reload (ctrl+r). You can update and save your assets directly in TIC-80.

Workflow

$ tsc80 run continuously watches changes in your .ts files and compiles them on the fly. You then alt-tab to TIC-80, and hit ctrl+r to reload the game. This instructs TIC-80 to load game.js and inject the compiled code inside the cart.

❗ You must not edit the compiled JavaScript code inside the TIC-80 editor. Your changes would be overwritten.

You must only edit assets (sprites, map, sounds, music) inside the TIC-80 editor. Don't forget to save your changes before reloading the code.

When you hit ctrl+s inside TIC-80, game.js is saved as a standalone TIC-80 cart.

Version control

The build folder can be ignored, but you must commit game.js, since it contains all non-code assets.

Code & Modules

If you know TypeScript and modern web development, writing your TIC-80 game with TSC-80 should be straightforward. It uses esbuild to compile and bundle the code, targets ES2020 and uses the modern ESM syntax (import & export).

tsc80 build|run only transpiles your TypeScript files to JavaScript, and compiles them together as a single output file. Internally, TIC-80 uses QuickJS as its JavaScript engine.

The following limitations apply:

JS code up to ES2020. This tool does not provide polyfills.
! No export from your entry file
Required to have a single file output
Tree-shaking is disabled by default, as esbuild would strip important "unused" functions like TIC()

Issues

TIC-80 doesn't reload my code

If you're building TIC-80 yourself, make sure to use the correct settings

$ cd <path-to-tic>/build
$ cmake -G "Visual Studio 16 2019" -DBUILD_PRO=On -DCMAKE_BUILD_TYPE=MinSizeRel ..
$ cmake --build . --config MinSizeRel --parallel

Changelog

2.0.0 - 2024-02-16 - BREAKING CHANGES

Projects created for TSC-80 1.0 must be refactored to be compatible with 2.0
Builds are now done with esbuild, instead of tsc
Projects now use ESM, with import and export

1.1.0 - 2023-08-18

Formal tsconfig update to output ES2020 code for TIC-80 1.1.x

1.0.3 - 2023-08-09

Dependencies update

1.0.1 - 2022-06-22

Cleaner code
Fixed race condition by @tmountain

1.0.0 - 2022-05-15

Official release for TIC-80 1.0
Added ttri()

1.0.0-dev - 2021-08-19

Refactoring to make this tool compatible with TIC-80 1.0.x-dev
Simplified workflow
Added peek1(), peek2(), poke1(), poke2(), vbank()

0.4.9 - 2021-07-17

Added elli(), ellib(), and trib()

0.4.8 - 2021-04-19

Fixed mouse() signature

0.4.7 - 2021-04-08

Removing "use strict" from output file, since it breaks the global scope in TIC-80 engine.
Updated dependencies
Stricter TypeScript
Better documentation

0.4.6 - 2021-04-03

Cleaned a bit of code
Added information in README
compress and mangle now default to true

0.4.5 - 2020-06-15

Added new function declarations (up-to-date with TIC version 0.80)
Added jsdocs for all functions. Thanks a lot @miltoncandelero

0.4.3 - 2019-01-17

Fixed the return types of multiple functions
Updated the boilerplate code to meet TS standards

0.4.2 - 2018-04-19

Added key(), keyp() and reset() declarations
Updated the boilerplate code for latest TIC-80 version
Updated README for better, step-by-step instructions

0.4.1 - 2017-10-13

Fixed missing input support (thanks @matanegui)
Fixed tsc80 cmd help message

0.4 - 2017-10-08

Added textri() declaration

0.3 - 2017-08-05

Refactored code

0.2 - 2017-08-04

Making a real npm package

2017-07-31

Added a backup option to copy your cart to your project's folder

2017-07-29

Updated print() and spr() declarations

2017-07-27

Added exit() declaration to tic.d.ts
Updated README.md

2017-07-19

Updated tic.d.ts

2017-07-11

Compile from TS to JS (finally...)
Renamed "main.ts" to "sample.ts"
Described a small trick to ensure that the init code waits for its dependencies
Removed the require of the compiled file
Cleared README a bit

2017-07-09

Added a require of the compiled code to catch exceptions
Added uglify-js to compress the compiled code
Rewrote the launch script

2017-07-06

Project birth: created a definitions file for TIC-80, and a tsconfig.json

tic80-typescript