Skip to main content

Features

IsaacScript is a framework that allows you to code The Binding of Isaac: Repentance mods using the TypeScript programming language instead of the Lua programming language. It automatically converts your TypeScript code into Lua, similar to how a C++ compiler automatically converts C++ code into X86.


The Downsides of Lua​

The vast majority of Isaac mods are programmed in Lua. So why would you want to use TypeScript over Lua? Why would you want to introduce a compiler into your workflow and make things more complicated for yourself?

Programming mods in Lua can be really painful:

No Type Safety​

With Lua, it is easy to shoot yourself in the foot after making even the smallest typo. When building an Isaac mod, you end up wasting an enormous amount of time running around in-game debugging run-time errors, and pouring through the "log.txt" file. Not my idea of fun, and probably not yours either.

Limited Language Constructs​

In Lua, you type x = x + 1. In TypeScript, you type x++. Lua doesn't have increment/decrement operators, assignment operators, switch statements, optional function arguments, array/object destructuring, or map/filter/reduce. And that's just to start with.

No Automatic Importing​

In Lua, you can't just start typing a function and have it magically be imported from where it lives. So you are stuck between using monolithic files (messy), or manually typing "require" over and over (tedious).

Bad In-Editor Tooling​

Lua has gotten some nifty improvements in the past few years, like Sumneko's Lua language server. Using the language server brings us some of the in-editor goodies that we are used to from other languages, like variable renaming. But the experience still pales in comparison to other modern programming languages like TypeScript and Rust.


The Upsides of TypeScript​

After five years of programming Isaac mods in Lua, I got frustrated enough to take a level 2 action - to build the ultimate Isaac developer experience, using TypeScript as a basis. The improvement is so significant that once you start, you will never go back. Here's a short list of features:

The Entire Isaac API, Strongly Typed​

  • Code fearlessly without having to worry about the format of the API call or whether using it incorrectly will crash the game.
  • The compiler catches every possible type error, making refactoring your code easier than you ever imagined that it could be.

Mouseover Documentation​

  • Don't waste time looking up API methods in the docs. Instead, hover over the classes and functions in your actual code editor to see what they do and what parameters they expect.
  • Many methods have extensive documentation written inside of the mouseover tooltip.

Automatic Mod Reloading​

  • Never close and reopen your game again when working on your mods. Never type the luamod console command again.
  • With the IsaacScript watcher, as soon as you press Ctrl + s to save a file, you can instantly view the changes in-game without having to do anything else.
  • If you use require hacks to get around the limitations of include + luamod, don't bother - that isn't needed here.

Automatic Formatting​

  • Never waste time formatting a file again. Automatic file formatting with Prettier comes running out-of-the-box.

Automatic Linting​

  • Squash all the bugs and ensure code consistency with the world's best linter, ESLint. It comes running out-of-the-box.

Extra Enums​

Expanded Standard Library​

  • Seamlessly utilize hundreds of helper functions and features from the expanded standard library, allowing you to write high-level code that is concise and easy to read.

Extra Callbacks​


There are plenty of reasons to use IsaacScript, but it isn't for everyone. Read on.