Your first app

👉 Pick the language#

Firefly Zero supports lots of programming languages:

  • 🦀 Rust
  • 🏃 Go
  • 🐀 C and C++
  • ⚡️ Zig
  • 🐦‍⬛ Odin
  • 🐰 MoonBit
  • 🟦 AssemblyScript (a subset of TypeScript)

Experimental:

  • 🌙 Lua
  • 🧪 Elixir

For simple apps and games, it’s a good idea to stick to what you already know. But if you’re ready to learn something new for better results, we recommend using Go. It’s easy to learn, sufficiently fast, and memory-safe.

For simple adventure games, it’s also possible to use Bulb or Bitsy.

📥 Install tools#

  1. Install firefly_cli
  2. Install WebAssembly compiler for your language:
rustup update nightly
rustup component add rust-src --toolchain nightly
rustup target add wasm32-unknown-unknown
  1. Install Go
  2. Install TinyGo
Install Zig. Make sure to select the latest stable release, NOT a “master” build.
Install Node.js and npm.

The preferred way to build a C (or C++) app is using wasi-sdk:

  1. Go to wasi-sdk releases.
  2. Download and install the latest release for your OS.
  3. This should install wasi-sdk into /opt/wasi-sdk. If you used an alternative installation method and installed wasi-sdk in a different place, provide the absolute path to it in the WASI_SDK_PATH environment variable.
  1. Install odin:
    1. Go to odin releases
    2. Download and extract the latest release for your OS.
    3. Add the bin directory from the extracted path into $PATH.
  2. Install wasi-sdk:
    1. Go to wasi-sdk releases.
    2. Download and install the latest release for your OS.
    3. This should install wasi-sdk into /opt/wasi-sdk. If you used an alternative installation method and installed wasi-sdk in a different place, provide the absolute path to it in the WASI_SDK_PATH environment variable.
curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash
Nothing to install for Lua, you’re ready to go!
Nothing to install for Bitsy, you’re ready to go!
Nothing to install for Bulb, you’re ready to go!

💻 Create the project#

A new project can be created using ff new:

ff new --lang=rust hello-world
ff new --lang=go hello-world
ff new --lang=zig hello-world
ff new --lang=as hello-world
ff new --lang=c hello-world
ff new --lang=cpp hello-world
ff new --lang=odin hello-world
ff new --lang=moon hello-world
ff new --lang=lua hello-world
ff new --lang=bitsy hello-world
ff new --lang=bulb hello-world

In this example, it will create hello-world directory and initialize in it a new app called hello-world using your chosen programming language. Don’t think about it too hard, you can later change the project name in the config (hello-world/firefly.toml).

🏃 Build and run#

Build the app and launch it in the emulator: ff run.

Have troubles using emulator? Check out the emulator user guide.

📦 Distribute#

  1. Export the app as a ROM (zip file): ff export.

  2. Publish the file anywhere you like. For open-source projects, a good option is Github Releases.

  3. People then can download and install the app:

    ff import ./joearms.hello-world.zip

  4. Optional: add your app into the catalog: catalog.fireflyzero.com.

🤔 Inspiration#

Need inspiration for your next game? Try combining and .

🔄 regenerate

Another cool place for inspiration is My Famicase Exhibition. It’s a gallery of covers (with a short description) created for non-existing games. Wouldn’t it be fun to bring one of these games to life?

random Famicase image 🔄 reload

Also have a look at our catalog to see what other people made and check out popular games for PICO-8.

🌱 Ecosystem#

This section lists third-party packages that can be useful for making Firefly Zero apps and games. All of these packages are tested to compile to Firefly Zero, be fast, and produce very small binaries.

  • micromath: Math library featuring fast, safe floating point approximations for common arithmetic operations, trigonometry, 2D/3D vector types, statistical analysis, and quaternions.
  • nalgebra: Linear algebra optimized for computing graphics and physics.
  • firefly-toml: A macro for statically parsing firefly.toml.
  • tinymath: The fastest Go math library for constrained environments.
  • firefly-go-math: Go game math library for Firefly Zero. Includes random functions using Firefly Zero random source, Vec2 type, and some other math utils.
  • micromath.mbt: Embedded math arithmetic, optimized for small code size at the cost of precision.

🧠 Further reading#

There are several things you should know to make a game:

  1. How the runtime works in general. Start by reading about firefly.toml and then go through all other pages in this documentation in order.
  2. How to make games and what patterns make it easier. We recommend reading Game Programming Patterns.

And take a look at resources for your language:

You can edit the main.bitsy file using the official Bitsy editor: make.bitsy.org. Use the “load data” button to upload the file into the editor and “save data” to download the file from the editor back into the saved file.

To learn how to make Bitsy games, go to the official documentation.

Go to the Bulb documentation to learn how to write a game.
Backward Emulator 💻 firefly.toml ⚙️ Forward