🔥 Firefly Zero documentation on Firefly Zero docs

File formats

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

💾 ROM#

Running firefly_cli export creates a single-file distribution for an app’s ROM. This ROM can be imported back using firefly_cli import.

This file is a regular zip archive with zstd compression. Because zstd compression support is added into the zip specification only in 2020, your archive viewer program might not be able to open it.

🏷️ Metadata#

The app metadata is stored in _meta and encoded using Postcard Wire Format. The schema is defined in firefly-types.

File system

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

roms/
- <AUTHOR_ID>/
  - <APP_ID>/
    - _bin: the main executable WASM binary of the app.
    - _meta: the app metadata.
    - _key: the app author’s public key.
    - _hash: the SHA256 hash of all files in the directory (both their content and their names) except _sig and _hash itself.
    - _sig: the PKCS 1 v1.5 signature signing the _hash with the author’s private key. Can be verified using _key.
    - May also contain any other files (game assets) that the app needs to run.
data/
- <AUTHOR_ID>/
  - <APP_ID>/
    - etc/: directory writable by the app. More precisely, the only directory in the whole FS where a non-sudo app can create, modify, list, or delete files. Empty by default. Usually, used to store game saves or assets produced using the app.
    - shots/: directory with app screenshots in PNG format.
    - stats
sys/
- priv/: directory with private keys.
  - <AUTHOR_ID>: the author’s private key. Used to sign apps when building with firefly_cli build. Private keys are only present on the emulator’s virtual file system but never on the device. Use firefly_cli key to manage keys.
- pub/: directory with public keys.
  - <AUTHOR_ID>: the author’s public key. Used to verify signatures of installed ROMs.
- launcher: short metadata of the launcher. This is the first app that is launched when device/emulator starts.
- new-app: short metadata of the latest installed app. If there is no launcher installed in the system, this is the app that will be launched first when device/emulator starts.
- name: the device name. By default, generated to be unique but users may change the device name. For multiplayer, we require all connected devices to have a unique name to avoid confusion. The name has the same validation rules as author and app IDs and can be at most 16 characters long.

Getting started

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

👉 Pick the language#

Firefly Zero supports lots of programming languages:

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

Experimental:

🌙 Lua
🧪 Elixir
⌛ Coming soon: more languages (Python, JS, Kotlin).

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.

Installation

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

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

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!

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.

Settings

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

You can change device settings in the “System Settings” app.

Navigation:

Press up or down on the touchpad to move the cursor between available options.
Press left or right when the cursor is on the header to switch between tabs.
Press E (Enter on emulator) to activate or change the selected option.

💬 Language#

Select the preferred interface language. This affects all system apps and some games. Translations are a community effort. If your languages is not on the list or some translations are incorrect, you can help us by translating the relevant app.

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.

Multiplayer

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

To establish a multiplayer connection, take 2 or more devices (or launch 2 or more copies of the emulator) and on each device:

Open the launcher.
Launch “Start multiplayer” (the first app on the list) by pressing E (Enter on the emulator).
Wait for all other devices to appear on the list.
Press E on both devices (in any order) to stop scanning.
Select “confirm” and press E on both devices (in any order) to confirm that the list of devices is complete.

Then on any of the devices select and launch the app you want to play together. That’s it! The app should start on all devices and you all should have control.

Designing SDKs

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

When designing a new SDK for Firefly Zero, we follow these principles:

Reduce type conversions. Try to use the same integer type everywhere. WebAssembly is a 32-bit system, so in Rust it will be i32. In Go, len and slice indexing use int, so that’s the best “default” type. If the language supports generic constructors, consider using it to automatically cast 8-bit and 16-bit integers to the default integer type. Using an 8-bit or 16-bit integer in some types, like Pad, would potentially reduce the size of heap allocations, but most of the time these definitions never leave the stack, and in WebAssembly on the stack everything takes at least 32 bits.
Provide type casts. If the language provides custom type casting, define it for converting Pad to Point (and back), Pad to DPad, Canvas to Image, Style to LineStyle (and back), etc.
Provide custom types. While load_file can return a raw byte array and draw_image can accept any byte array, it’s good to provide custom File and Image types (and other custom types too whenever possible). Even if the language doesn’t provide nominal type safety, a definition like enemy: Image is much more descriptive than Enemy: []byte.
Host calls are functions. You can optionally provide Line type with draw method for the user’s convenience. However, there must be always a draw_line function, like for any other WebAssembly host call. The idea is that host calls are side-effects and that’s how we make it explicit.
Keep the host functions names. If the host function is called draw_line, the SDK function wrapping it must be called draw_line (or drawLine, or DrawLine) too. Don’t call it render_line or anything else. The called host function names are visible in the runtime error messages and in firefly_cli inspect, so it should be easy for the user to map it to the SDK function calls in their code.
Keep consistent type names. Use the following type names:
1. Graphics: Angle, Canvas, Color, Font, Image, LineStyle, Point, RGB, Size, Style, SubImage.
2. FS: File.
3. Input: Pad, DPad, Buttons.
4. Net: Peer, Peers, Stash.
5. Stats: Badge, Board, Progress.
6. Shapes: Shape, Line, Rect, RoundedRect, Circle, Ellipse, Triangle, Arc, Sector.
Follow the language style guides. Follow the naming convention and all the best practices. If there are several competing standards, pick the most commonly used one. Use all possible linters and code formatters.
Keep modules flat. There should be only 2 public modules: firefly.audio with everything related to audio and firefly with everything else (and sudo if your SDK provides sudo functions). Even though the host runtime defines modules like graphics, misc, and more, the SDKs’ public API shouldn’t reflect that structure. Make it fast and easy for users to find and import all they need.
Avoid allocations. It should be possible to use the SDK to write allocation-free apps. For example, in Go, ReadPad returns (Pad, bool) instead of *Pad so it doesn’t escape on the heap. In case of reading a file, most users will want the file be automatically allocated with the correct size, so you should make both possible. For example, the Go version of LoadFile accepts an optional buffer and if it is nil, a new one is automatically allocated. Or in the Rust version, there are two implementations: load_file and load_file_buf.
Optimize (for size). You should provide a simple-to-use API but it must never sacrifice binary size or performance. If someone wants to push the limits of what Firefly Zero can do, they should be able to do that without bypassing the official SDK. However, in many cases, the compiler is smart enough to optimize out unused code branches, so always validate your assumptions.
Keep the argument order. The host functions follow strict rules for arguments order. In particular, drawing functions always accept Point first and Style last. Your wrappers should follow the same order.
Use 32-bit float. 32-bit float arithmetic is much faster on the device than 64-bit arithmetic.
Provide helpers. Don’t stop just at the host function wrappers. Provide everything that a typical game might need. For example, arithmetic operations for Point, radial coordinates for Pad, or optional integration with a popular 2D math library.

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.

Repair

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

Firefly Zero is a sustainable device and we believe in your right to repair. We want everyone to truly own the things they buy and understand how these things work.

Opening and disassembling Firefly Zero does not void the warranty. However, breaking the device while disassembling (just like other intentional damage) voids the warranty. So, before you get started, make sure you know what you’re doing. And this page is here to guide you.

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.

Audio

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

🧱 Basics#

Sound in Firefly Zero is constructed as a tree of nodes. There is already one node present, called OUT. Everything connected to it will play on the speakers (or headphones) of the device. Some nodes, called sources, can produce a sound by generating it using math or by reading it from memory or file system. For example, to play note A in 4th octave (440 Hz) using a sine wave:

Releases

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

Making a release#

We use task everywhere and most of the projects provide release task for making a release which accepts the release number without any prefixes. For example, task release -- 0.1.0. The task will gracefully fail if the release number must be set in the source code first.

Firefly consists of multiple projects scattered accross separate repositories. When releasing a project depending on other internal projects, don’t forget to update the dependency version.

Projects

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

Some of the repositories on this list are private. It includes failed experiments and unfinished projects.

Core (firmware and hardware):

Developer tools:

SDKs:

Websites:

UI

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

This is the design guide for designing user interfaces for the system apps.

We follow Neobrutalism design adjusted for low-res pixelated screens.
Font: eg_6x9.
Respect user language
Respect user color scheme
Colors:
- Primary: text, box borders
- Secondary: disabled elements, inactive elements
- Accent: active elements, headers
- BG: background.
Margins: 1, 2, 4N (N>0) px.
Rounded corners: 4px.
Box border width: 1px.
Use lowercase text except where the grammar requires it (abbreviations, names, country names in English, etc) and paragraphs of text.
Cursor has 1px shadow on bottom-right.
Pairs of yes/no buttons are aligned on the same line, with no/back/previous/cancel on the left and yes/forward/next/accept on the right.

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.

Marketing

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

The key point in everything we do is we’re not a big evil corporation. We are geeks that are tired of ads, AI, and investor-driven businesses. This might make it harder to reach wider audience but the people that do find us will have a stronger bond with our vision.

Writing style
- Keep it simple and honest. Keep it short and to the point.
- Avoid bullshit words and business speak, like “empowering e-commerce businesses to disrupt the industry of AI”. Here is some good writing:
  - Big Walk trailer
  - Playdate website
- Use only hashtags relevant to the post content, especially on small platforms.
Advertisement channels
- Bad: buying annoying ads.
- Good: posting useful content to our socials that people will want to re-post.
- Bad: paying people for feedback.
- Good: providing free (or not) early previews to the geekiest geeks, encouraging them to post their honest reviews.
- Bad: spamming every community.
- Good: authentically being part of many communities and talking about Firefly.
Graphical style:
- Use SWEETIE-16 color palette.
- Use pixelated images and fonts (for titles), in the spirit of the graphics on the device.
- Avoid overly-pixelated fonts for the main text, it might make it hard to read.
- Use the official art: firefly-art.
- If the platform allows it, provide alt-text.
Availability: no important information should be confined to platforms that cannot be viewed without registration, like Xitter, Instagram, or Discord. Open for read (and search indexing) resources: Mastodon, Pixelfed, docs.fireflyzero.com, blog.fireflyzero.com, Github.
Ethics: avoid unethical trends (including past trends), like AI, blockchain, or NFTs.

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.