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

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.

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.

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.