[Discuss] Arduboy Game Format (.arduboy) Guide

(Holmes) #21

Originally, this is one of the main reasons I was arguing in favor of having multiple .hex files zipped into a single .arduboy file. To be honest, I think there’s probably a more logistical way to implement multiple devices into a single file that we just haven’t thought of, yet. A list of hexes is still important. I have a project planned that will be in multiple chapters since it’ll be so big.

(Scott) #22

But with the 128 x 64 size of an Arduboy screenshot, it could be difficult to know what was the shot and what was the overlay. You could use colored text or other ways to make it obvious, but with such a small screen you might block a lot of the underlying shot, especially if you want the description to be more that just a few words.

It can’t hurt to put this is the spec. The title/description would be an optional field and a loader program wouldn’t have to use it. Also, a creator could still leave out the title and use an overlay.

(Scott) #23

I think that asking the question “Is this something that results from only changing the board type and recompiling?” could determine if it can be in the same .arduboy file. My proposal covers this, and still allows for multiple .hex files for the same board type. If your game is segmented into 3 sketches, you would have 6 .hex files total; 3 with “device”: “Arduboy” and 3 with “device”: “DevKit”.

(Holmes) #24

Would there even be a need for a device field outside of the hexes category?

(Scott) #25

No, the “device” field would be removed from where it is now. The fact that the overall file has a .arduboy extension pretty much covers it.

(Holmes) #26

Well, I’d need to update my Arduboy Manager, example files, repo guideline, .arduboy guideline, as well as let others know to update their already-released .arduboy files. I’m fine doing all that, but @JO3RI, @mockfrog, @delegatevoid would have to agree to be on board for this change. This would mean going back to change the rest of the TEAM a.r.g. games, too. If we are all in agreeance, I can move forward on my end.

As for screenshot descriptions, I’m still not sold on it. Seems a little superfluous.

(Scott) #27

Better to change 2 or 3 loader programs in the early stages of use than make extra work and error opportunities for the dozens or hundreds of sketches that maintain .arduboy files.

(Scott) #28

Again, it can’t hurt to put it in the spec. as an optional field. What If I want to describe a 128 x 64 sceenshot as “HeroGirl is being attacked by 3 ogres and a dragon” using an overlay?

Also, if you want to be able to use color to make it clear that ovelay text isn’t part of the screenshot, you would have to change the spec. from saying that screenshots can be only black and white.

(Scott) #29

You should add versioning for the .json file itself. That way you can continue to use the current spec. without breaking anything and update the loaders to use additional newer, non backwards compatible, .json formats in parallel. You could do this using the name of the .json file or adding a field:

  1. File name info.json for the current spec. or infoV2.json for the new one. You could also additionally accept infoV1.json for the current spec.
  • Add field “jsonVersion”. If it doesn’t exist or its value is “1” then its the current spec. If its value is “2” then it’s the newer version.

Of course, the version doesn’t have to be single digits. If desired, semantic versioning could be used.

(Holmes) #30

The idea is that we want to have anything new that’s being added to be optional, so any game loader should load any .arduboy file. It’s still in its infancy, so anything can be changed at this point. The goal is to make everything as future-proof as possible.

(Scott) #31

Sure, but you just complained about you or @JO3RI having to do it at this stage. I just offered a way to make the transition less painful and allowing for handling unforeseen non backwards compatibility in the future.

(Holmes) #32

:laughing: Maybe you could interpret it as complaining, but I just want to make sure we are rigorous about making changes that other users will have to keep up with. :yum: I’m just happy that we have a format that contains metadata.

(Scott) #33

If the changes turn out the to be non backwards compatible, then using versioning of the .json file itself means that users don’t have to “keep up with” these changes. Loaders continue to support the current format then additionally add support for the new version. Users can update their .arduboy files at their leisure, or when they release a new sketch version, or never.

It’s the same kind of thing as I did with creating the Arduboy2 library. Users can use Arduboy2 for new development to gain its advantages. Existing sketches can continue to use Arduboy, or switch to Arduboy2 when convenient. Arduboy becomes “grandfathered” to avoid making it non backwards compatible, which would break some existing sketches.

(Scott) #34

I would consider changing the name of the “hexes” field to something more generic, like “executables”, and also change “hex” to “file” or “fileName”. Let the file extension or a magic number within the code file determine the file type. The actual format and extension may change in the future.

For instance, if the next generation Arduboy is ATSAMD21 based, like the Arduino Zero, it will create and upload .bin files instead of .hex, so you would need to add a “bins” field. Using “hexes” for .bin files would be confusing.

"executables": [
        "title": "Game Name",
        "fileName": "app1.hex"
        "title": "Game Name 2: Electric Boogaloo",
        "fileName": "app2.hex"

(Holmes) #35

That’s actually a good point that I would 100% agree with. Maybe something like binaries or whatever would be a little more clearer, especially if we add in target devices.

(Scott) #36


In a JSON file, is it legal to have a field that contains either an a array of single elements or an array of multiple element objects (but not both for our case)? In other words, could you have either:

"screenshots": [


"screenshots": [
                "title: "Intro",
                "fileName: "screenshot00.png"
                "title: "Settings",
                "fileName: "screenshot01.png"
                "title: "Level 1"
                "fileName: "screenshot02.png"

If it’s legal, then is this something that all the loaders can easily detect and parse?
If so, then all the changes I proposed today can be backwards compatible.

  • Detect whether “screenshots” is an array of file name strings or an array of objects containing “fileName” and (optional) “title” fields, and handle it appropriately.
  • Keep the existing “hexes” field but deprecate it in favor using the name “executables” or “binaries” which contains “fileName” instead of “hex” fields. Loaders could look for and handle both (even in the same file, for that matter).
  • Keep the existing “device” field but deprecate it in favor of having a “device” field in each “executables” object. If an “executables” object doesn’t have a “device” field then the original global device field is used for it. If no “device” field is present anywhere for a given executable file, then do whatever you do now when the “device” field isn’t present.
  • It still doesn’t hurt to add an optional “jsonVersion” field for future contingencies. The loader would always check for it. If the field isn’t there or it has a value of 1, then it’s the current spec. A value other than 1 indicates a format that’s not backward compatible with version 1, so if the loader doesn’t have support added for this new version, it gives an error.

(Holmes) #37

Almost everything is legal in standard JSON, but as for API’s respecting the legality of it, a lot of them don’t and are finicky. The API I’m using can tell the difference and allow me to handle them differently, but it’s something that people would have to make sure they take into account. I think if we’re going to expand something (like screenshots) it’s probably best to make sure they’re arrays of objects instead of having the possibility of either.

Having different iterations of a standard kinda underminds the idea of allowing almost any field to be optional.

(Scott) #38

I’m just trying to address the issue of forcing a requirement to update existing .arduboy files. That’s why it would be nice to know how easily it could be handled by all the loaders. Note that the plan would be to deprecate the current “screenshots” format, but not eliminate it, and possibly not accept any new .arduboy files submitted with the old format.

However, if you want to switch to only the new format, and update all existing .arduoby files, and tell people who are just about to submit a file that they have to go back and change it, and deal with currently submitted files that are locked in a repository that’s no longer maintained because the authors have dissapeared so people can’t grab them from the repository for use in their own loader, then be my guest. Once a format is in general use, it helps if backwards compatibility can be retained. It’s up to you and the other loader developers to decide if the .arduboy format is in general use yet.

Have you looked at the various iterations of the (so called) Microsoft Word “standard” :wink:

You can’t foresee the possibility that some day you may wish to totally overhaul the format such that you would need a lot of “if/then/else”, etc., tests for tons of fields order to handle all the possibilities. At some point it may be easier for the loader to just do:

  • If jsonVersion = 1, parse version 1 format
  • else if jsonVersion = 2, parse version 2 format (no need to deal with any V1 formatting)
  • else, error

It’s entirely possible that the version will remain at 1 forever, but including “jsonVerson” in the spec. and testing for it in the loader isn’t a big deal and makes things more future proof.

(Mike) #39

Ok, I’ve got a web server that generates arduboy files as well as ardumate json repos on the fly. More on that after some testing and I publication. Hopefully tomorrow.

For now, some feedback on the format:

The banner and screenshots shouldn’t be required. Sure, it’s nice to have them, but that’s an unnecessary burden to place on someone who just wants to share their work as opposed to advertise it. Ardumate will fill in a nice generic graphic if you don’t have a screenshot (good for it!) and I provide a generic banner that just says there’s no banner in my arduboy files.

That the screenshots array in the json file requires you to list file names but the file names for screenshots are fixed just seems like an unneeded point of failure. Either let me use the file names I want - like you do with hex files and banners - so I get some benefit from listing them, or just say how many there are, and let the program figure out the file names. It’s a lot less likely to make an error generating the name than I am.

(Holmes) #40

I agree- My Arduboy Manager is set up so that almost everything is optional, including images.

The filenames can be anything you want them to be. I was thinking of having them fixed, but @JO3RI persuaded me to define them.