Dev on Firefly Zero docs

Installation

Mon, 01 Jan 0001 00:00:00 +0000

🐚 Installing CLI#

🐧 Linux

Choose one of the following:

Installation script (recommended)

Run the following command in the terminal and watch the magic happen:

bash -c "$(curl https://fireflyzero.com/install.sh)"

Cargo (Rust package manager)

If you have cargo (the Rust package manager) installed, you can use it to install firefly-cli:

cargo install firefly_cli

After that, open ~/.bashrc (or ~/.zshrc if you use zsh) and add at the end the following:

alias ff="firefly_cli"

Manual

Download the latest release. You need the one containing -linux- in the name. If you don’t know which one you need, it’s probably the one ending with -x86_64-unknown-linux-gnu.tar.gz.

Emulator

Mon, 01 Jan 0001 00:00:00 +0000

The emulator allows you to run any Firefly Zero apps on your computer. To install it, follow the Installation guide.

🕹 Input#

The emulator supports the following input methods, from best to worst.

Firefly Zero device
Steam controller
Gamepad
(⌛ Coming soon) UI buttons
Keyboard

📱 Firefly Zero device#

The device can be used as a gamepad (not only for the emulator). See firefly-gamepad.

💨 Steam controller#

It is discontinued but you may find a used one. It has a touchpad just like Firefly Zero, and that makes it a better fit, compared to Xbox controllers, for apps requiring a precise input.

Your first app

Mon, 01 Jan 0001 00:00:00 +0000

👉 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.

firefly.toml

Mon, 01 Jan 0001 00:00:00 +0000

The firefly.toml configuration file tells firefly-cli how to build a ROM for the project. It should be placed at the root of the project (though you can explicitly specify the path using --config) and must be in the TOML format.

Required:

author_id (string): your username. It should be unique, otherwise users may get a warning about invalid signature when launching your app. The best way to ensure that your author_id is unique is to add it into catalog.fireflyzero.com. There are also limitations on the length of the ID and used characters. If your ID (or any of the options below) is invalid, the build command will tell you.
app_id (string): the app ID. Must be unique for the given author. The combination author_id.app_id is the full ID of the app, and that must be globally unique.
author_name (string): your name. It will be shown in the launcher next to the app name. It must use ASCII Latin alphabet. Non-latin names have to be transliterated.
app_name (string): the human-readable name of the game. Shown in the launcher. It must use ASCII Latin alphabet. It should use Title Case. For example, “The Plant vs the Zombie”.

Optional:

Callbacks

Mon, 01 Jan 0001 00:00:00 +0000

Callback is a function with a specific name that you define in your code and then the runtime calls it in the right time. None of the callbacks are required but you’ll need to define at least one of them for your app to actually do something.

📚 Supported callbacks#

Firefly Zero supports the following callbacks:

boot is called only once, after all the memory is initialized and all runtime functions are available but before any other callback is called. This is the best place to load fonts, sprites, and other assets, initialize the default state, read configurations, etc.
update is called ~60 times per second. It is guaranteed to be never called more often, and it won’t be called less often if the game doesn’t consume too much resources. This is the best place to update the state of objects, position of NPCs, read and handle user input, etc.
render is called before updating the image on the screen. It might be called less often than update if the device sees that the game is slow and needs more resources. This is the best place to call all drawing functions.
before_exit is called before the app is closed.
cheat handles cheat codes (see Cheat codes).
handle_menu is called when a custom menu item is selected.

Use the right callback!

Graphics

Mon, 01 Jan 0001 00:00:00 +0000

🔬 Pixels#

The screen size 240x160 pixels, just like GameBoy Advance. Pixels are quite big, so it’s safe to draw one pixel wide lines and letters, they will be visible.

Coordinates: x=0 is left, x=240 is right, y=0 is top, and y=160 is bottom.

🖼 Frames#

All those moments will be lost in time.

Each update of the image on the screen is called “frame”. Before each frame is rendered, the render callback function is called. This is where you should call all drawing functions you need.

Input

Mon, 01 Jan 0001 00:00:00 +0000

Buttons#

Just feel that you’re the hardest little button to button.

Firefly Zero has 4 primary buttons:

N (North) on the top.
S (South) on the bottom.
W (West) on the left.
E (East) on the right.

There are also Menu and Power buttons but regular apps don’t have access to these.

The read_buttons function returns which buttons are currently pressed. The SDKs also provide convenience methods to compare two states to get which buttons were just pressed or just released.

Multiplayer

Mon, 01 Jan 0001 00:00:00 +0000

Firefly Zero has a very unique approach to multiplayer: every game (or app) can be played together! The only question is how the app handles multiple inputs. And this section covers how you can do that. And don’t worry, it’s very simple.

⚙️ How it works#

If you take two or more calculators and punch into all of them the same expression, you’ll get the same result. However if you make a typo in any of them, the result might be very different.

Accessibility

Mon, 01 Jan 0001 00:00:00 +0000

Accessibility is about making your game accessible to as many people as possible. Everyone is different and have different limits to their abilities. If you can play your game yourself doesn’t mean that others can play it too. And this page will help you to fix it.

📑 Game Manuals#

Writing a manual is the easiest way to explain people how to play your game. Even if you have an in-game tutorial (which is always the best option if done right), it’s still a good idea to write a manual just in case.

Badges and scores

Mon, 01 Jan 0001 00:00:00 +0000

🏅 Badges#

Badges are achievements that the game rewards to the player for doing some actions. Fore example, collecting a certain number of collectables, finding a rare item, doing a hard combo, etc. You can add badges to your game to encourage players to experiment with features they might not normally use, or to approach your game with entirely different play styles.

Badges are defined in firefly.toml:

[badges]
1 = { name = "m i tasti", descr = "bite yourself" }
2 = { name = "u r tasti", descr = "bite someone else" }
3 = { name = "apel tasti", descr = "eat 100 apples", steps = 100 }

The key of each badge is the ID used to refer to it in the game. It must start at 1, go sequentially up, and never change between releases. For now, there can be at most 20 badges in a single game.

Debugging

Mon, 01 Jan 0001 00:00:00 +0000

This page covers how to find bugs in your apps.

😎 Cheat codes#

Breaking the law, breaking the law.

You can add cheat codes to your apps. Cheat codes can be used to put the app into a specific state: jump to a specific level, reset NPCs’ positions, set character health, etc.

First, add [cheats] table into firefly.toml. The table maps cheat code names to numbers that get passed into the app:

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Firefly Zero has an official framework for writing tests for apps. It’s written in Python and works great with pytest. If you don’t know Python, don’t worry. It’s quite a simple language and you don’t need to know much to succesfully write tests.

Under the hood

The firefly-test Python package is a wrapper around the actual Firefly runtime written in Rust and embedded into the package using PyO3. So, you can be sure that it works exactly as it will in emulator and you don’t even need to have the emulator installed.

Terms

Mon, 01 Jan 0001 00:00:00 +0000

Below are different terms that the documentation uses. If there is a technical word in the ocumentation that you don’t understand, it should be in there. If it’s not, send us a pull request or open an issue!

Asset is a file that an app needs but which isn’t the code. It includes sprites, music, sounds, sometimes dialogs and configurations, etc.
Frame is what is show on the screen at one specific moment. Each frame is a rectangle of 240 per 160 pixels.
Host function is a function defined by Firefly runtime (as opposed to functions defined in the app). The Firefly SDK for your language is a wrapper for host functions.
ROM is a distribution of your game. It includes a WebAssembly binary, game assets, metadata, signature, etc. A ROM is distributed in a ZIP (*.zip) file and on the device is stored as a collection of files in a directory in /roms/.
TOML is a configuration format that we use for the firefly.toml config. It’s stricter than YAML and more readable than JSON. If you’ve seen INI (*.ini) files in WIndows games, TOML should look very familiar.
WebAssembly (aka wasm) is a binary format in which all Firefly apps compile. It’s like EXE (*.exe) on Windows.

Bulb Script

Mon, 01 Jan 0001 00:00:00 +0000

Bulb is a scripting language inspired by Bitsy and Pulp and designed specifically for Firefly to create simple adventure games.

What kind of games?

Bulb is designed for making adventure games: you can walk around, talk to NPCs, interact with objects, and solve puzzles. Bulb cannot be used to implement reaction-based games, physics, real-time behaviors, complex fighting systems, or multiplayer. If your game needs any of these features, go to the main Getting started to make a game in a proper programming language.