Skip to content

scambier/tic80-typescript

Repository files navigation

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.

  1. Install NodeJS LTS
  2. Install TypeScript: npm install -g typescript
  3. Install TSC-80: npm install -g tic80-typescript

Create a project

  1. tsc80 init will create the necessary files (config, declarations, and game files) into the current directory
  2. 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