[Discuss] Arduboy Game Format (.arduboy) Guide

(Scott) #102

Well it’s a bit dangerous for a loader to allow this, for the reason I mentioned. A user could grab a .hex from somewhere, not knowing that it was for a DevKit, then add it to their local loader repository. We would then get complaints from that person when they upload it to a production Arduboy and it doesn’t work.

I you want to take that risk, then you can allow standalone .hex files to be loaded, but make it clear in whatever documentation that you provide, that this could happen.

(Scott) #103

Sorry, I forgot to mention: You can also add a “default” keyword to “schemaVersion” in the schema, which should be set to the current version.

(Timothy) #104
  • Schema Version - agreed (all of it)
  • Nitpicking - Braces on the same line, damn you Java people :stuck_out_tongue:it fucks with my OCD

oh and .arduboy vs sketch, also makes sense.
Feel free to fork, edit, and submit a pull request

(Scott) #105

Reformatting the schema is fine by me. Actually, either the schema or the example in the guide should be reformatted so that both match.

(Timothy) #106

Seriously though, either if fine, I’m just messing around.
For JS/Java I don’t mind, as long as they don’t do that in C#.

We’ll just run the json through some pretify and problem solved.


@MLXXXp @delegatevoid @crait

What if we add an EEPROM field ? This might be helpfull if you create an EEPROM Backup/restore TOOL. I know some games use a function to just look for an empty spot in EEPROM, but most games would just use a fixed place off addresses.

If the .Arduboy holds the range of addresses, you could backup the bytes and stick a game name to the backup.

  "start" : "A number between 16 and 1023 and lower than the end Address, holding the first EEPROM address used",
  "end" : "A number between 16 and 1023 and higher or equal to the start Address, holding the last EEPROM address used"

I remember some addresses are used by the Arduoby library for sound and maybe other stuff, does anyone know at what address backup can start ? (obviously not zero) => found it and changed it

(spinal) #108

Why not zero? I don’t claim to know much at all about eeprom, or what arduboy uses by default, but surely backing up the entire eeprom, and restoring the entire eeprom would leave the arduboy in the same state as if you never performed the task. So no matter what parts of the eeprom a game uses, it’d be backed up correctly.


@spinal Nope, you would backup per game. But the first amount of bytes are taken by the arduboy config, you should not touch those. Just copying the complete EEPROM doesn’t give you much more value, if you could backup every games backup separately, you can choose which one to backup/restore.

Besides, we are talking about per game metadata !


@MLXXXp okay found it, 0-15 are reserved:


(Timothy) #111

@JO3RI @MLXXXp @crait if that’s something you guys use, then why not, it doesn’t hurt adding it.
It’s outside of my domain, so I can’t decide on that.

(Scott) #112

It would also be good if the loaders provide a feature or tool that scans all the .arduboy files in their repository and uses this EEPROM information to report any overlaps discovered. A summary could be displayed, even if no conflicts were found, for the user’s benefit and for developers looking for an empty slot.

EEPROM information, if present, should also be displayed by loaders (along with the other information and images) in a given .arduboy file’s listing, again for the user’s benefit.

What should a game put in the info.json EEPROM fields if it does this?

Maybe we should add an optional boolean EEPROM field that indicates that the sketch does this. I can’t think of a good name for it. Maybe “various”? If “various” is set to true then the “start” and “end” fields must be set to cover the entire possible range that the sketch may use. If my above proposed scanning tool were implemented, it could flag sketches that do this and use it as a consideration in overlap calculations.

Circuit Dude [2.1] - Awesome Puzzle Game With 50 Levels!
(Mike) #113

So long as your loading tool can deal with that, that’s fine. The real issue is which of them do you have to have for your chosen loader to work. If that’s different for different loaders (which seems to be the case now), then you’re going to get arduboy files that work on some loaders and not others. Without interoperability, there’s not much reason to have a standard.

I looked at it from the user point of view, so lets try it as a game author. Most of the required fields fall out of just developing the game. A title, author, and description should be artifacts of the process. A version you really ought to have if you’re going to distribute it, so you know what people have.

That leaves a screenshot and a banner. A screenshot might well be part of the development process. Then again, it might not. Requiring it might require extra work by the developer, so it ought to be optional.

The banner doesn’t come up during game development. From the description in the guide, it’s clearly part of the marketing campaign. If you didn’t do one of those, you don’t have a banner. It really ought to be optional.

Frankly, I no longer care. I’ll add default banner (the classic white cow eating marshmallows in a snowstorm) and screenshot images to arduweb so game authors can treat them as optional. I think it would be better for everyone if they were actually optional: Developers wouldn’t have to waste time deciding what to do about them, I wouldn’t have to add them to the zip file, end users wouldn’t have to download them, and loader authors could do something that suited their loader better than displaying whatever images authors who don’t want to provide them come up with.

(Scott) #114

I don’t intend to develop a game loader, so don’t put much weight on my opinion, but I agree that “banner” and “screenshots” should be optional. All the other currently required fields are fine.

@mwm, If it’s decided they remain required:
Rather than arduweb defaulting to blank images, you could create a PNG banner containing the text from “title” in a standard font. For “screenshots”, use an image that says something like “No screenshot available” in a way that wouldn’t be confused with an actual screenshot.

(Holmes) #115

Actually, the problems that I can think up for EEPROM addresses…

First of all, if we have multiple binaries, it might be best to put the EEPROM usage in each binaries object since each one could possibly use a separate location to save. The RPG I’m making has separate chapters that uses a different location for each game, which would be how you can carry over your save data from the previous game. Not only that, but each game could have multiple save locations for different things. Also, with different binaries for different systems, saving data may be handled differently, so we would need to think about a better naming convention for it other than EEPROM. As for storing the info into the .json, we would also need to figure out a way to meaningfully incorporate the data. Would it be a simple range of addresses? A list of addresses? A list of ranges?

(Scott) #116

I also considered that (but also remembered your concerns about things getting too complex :wink:). In a situation such as yours, even though each chapter uses different and possibly multiple locations, overall I would hope that all these locations reside in a single contiguous block. Therefore, one start and end address should be sufficient. Also, doing this would mean a nested object under “binaries” and you objected to nested objects, when I suggested it to allow common “binaries” titles.

If a different system saves data differently, we would add a new field specifically named and tailored for that new way. Overall (not just for storage), if for specific cases things get too complicated having multiple binaries in the same .arduboy file, then you would separate them out into multiple .arduboy files, similar to the way it would have previously been done for the production Arduboy and DevKit when there was only a single “device” field.


@mwm @crait I understand your concern. I had hoped to make it required as an extra for the users, but okay let’s not put the bargin on the shoulders of the “game providers”

“required”: [

If that’s different for different loaders (which seems to be the case now)

If a loader is pre-released and isn’t capable of “reading” old and new versions … well …

I agree with @MLXXXp on EEPROM

(Scott) #118

I’ve updated, fixed and formated the “official” schema to include changes discussed here and elsewhere.

  • Fixes to the “schemaVersion” field.
  • Made “banner” and “screenshots” fields not required.
  • Changed the “EEPROM” field to lower case “eeprom”.
  • Proper formatting and validation of “eeprom” fields.
  • Added “variable” field to “eeprom”, used to indicate that the area used is not a fixed location.
  • Made “buttons” and “screenshots” require at least one entry.
  • Rearranged the fields in an order (which I feel) is desirable for a form that is built from the schema.

You can test out an example form created from it by going to the following URL:


With Firefox at least, I find it easiest to double or triple click on the URL (to select it all) and then right-click and select Open Link (whatever).

If everyone agrees that it is correct, the guide should be updated to match this schema (including making sure that the example info.json has all the fields and validates properly against the schema, which it currently doesn’t).

(Scott) #119

No one has responded to my previous post, so I assume either everyone is now satisfied with the schema, and .arduboy format in general, or is tired of discussing it and has taken a “whatever” attitude, or is busy with other things. I don’t want to spend much more time on it myself, but in the interest of making the schema more explicit and self-documenting:

With JSON a null string is valid, so even though some strings, such as “title”, are set as “required”, something like "title: "" would be valid. I’m sure that our intent in making some strings “required” was that the author provides at least one character in them.

The JSON schema specification includes “minLength” and “maxLength” keywords to constrain the size of strings. I’m thinking of adding "minLength": 1 to all the “required” string fields: “title”, “version”, “author”, button “control” and “action”, and the “filename” fields.

However, I have two questions:

  1. Should even the optional string fields, if included, be required to provide at least one character?

    It depends on how a loader parses and presents optional string fields. If they’re always presented as an empty title, even if not included in info.json, then it doesn’t matter. If the loader checks for a null string and treats it the same as if the field were not included in info.json, then again it doesn’t matter. If the loader expects that if the field is present it should contain something that can be displayed, then it helps to try and assure that.

  2. Do we want to restrict some/all strings to a maximum length? (in which case “maxLength” could be added to specify this.)

    I’m sure that loaders wouldn’t allow an “infinite” size string, and things like “title” probably have a limited display area reserved for proper formatting and presentation. Things like filenames could be limited by the O/S itself (255 is a typical maximum filename length).

So do any of the loaders presently have any of the restrictions above, or are there any thoughts on what they should be?

FYI the optional strings (other than filenames) are: “description”, “publisher”, “idea”, “code”, “art”, “sound”, and “title” for binaries and screenshots.

(Mike) #120

I would say that all strings should have a minLength of 1. If the string is required, allowing it to be empty sort of defeats the point. For optional strings, I can’t see where an empty string lets you do something that leaving it off won’t do, meaning it’s liable to be a mistake that we should let the user know about (is there some way to annotate that things as warnings instead of violations?). So those should have at least one character unless someone can come up with such a use.

(Mike) #121

I could have sworn I saw that a schemaVersion had been added, but all I can find is one mention of it here (of course, that the site subverts the browser search facility means I don’t really trust the search).

Did this get rejected, so that the now “old” versions arduboy files I’m currently building are simply broken?

Edit: I tried to tweak arduweb to deal with this in the suggested manner (i.e. fields being optional) by building hexes from binaries (and vice versa) and outputting them both, but this doesn’t work for screenshots. The previous version of screenshots was a list of strings, the new one is a list of dictionaries.