[Discuss] Arduboy Game Format (.arduboy) Guide

No, having fields is still useful to indicate the purpose of the image and what the manager/loader should do with it. The single, fixed dimension “banner” (likely) goes at the top of the entry. The “sceenshots” have a fixed size (otherwise you should reject or scale them), and could be arranged in a tiled format. My proposed “images” array, if implemented, would allow general purpose images of various sizes and, for instance, could be displayed as a slide show.

The banner could potentially be smaller as a JPEG than a PNG, depending on its content.

I meant the code to display the content of the .arduboy file.

Is “version” for the game or package? We might as well as assume our JSON format may change over time (they always do) so it should include a json_version or pkg_version or something so future bootloaders can either know how to process older versions or at least tell you “This is an older .arudboy file, it won’t work.” or something rather than just blowing up.

It’s the version of the game. Read back a bit for discussion about a version for info.json. I proposed it but I think it’s been rejected.

Ok, I misread the format spec about the screenshot file names. I think I was mislead by the names used in it looking like they were generated. While this error is on me, possibly changing the names in the format to to be less regular (firstscreenshot.png, secondss.png, …) would help others avoid that mistake.

As for what should be/is required: There’s a list of fields that in the section labelled “Requirements” that I assumed were, well, requirements.

Personally, I think the requirements should be the minimal amount that would be useful to the end user. Making something optional doesn’t really save the application developer any work, since they still need to check for them to deal with “broken” files or risk crashing. And if they find such a file, they have to figure out how to deal with them - the user friendly option being doing something that will let the user download the file anyway.

The binaries field contains the minimal amount the user needs to work use the entry: the title and a hex file to download and what device it works on.

Along the same lines, having two titles seems a bit redundant for what I assume is going to be the common case of a single hex file for the game. I’d argue that the “title” field in “binaries” should be optional, at least if there’s only on entry, and main “title” field be required.

You know when you probably should be doing something more important but you end up putting it off and doing something more interesting? Well, (guilty as charged :blush:) rationalizing that I was learning something and creating something useful, I spent some time creating a schema for the info.json format, using the current example in the guide. The schema can be used as documentation, or for validation, or even for building forms for the creation of an info.json file.

I started by creating a base schema using this site, by copying the info.json example into the JSON field, checking the Include metadata keywords option and then clicking Generate Schema.

I then grabbed the resulting schema and edited it to add titles, descriptions and validation rules. This site and others helped with that. The descriptions and validation are based on the .arduboy guide and my interpretation of the answers to the questions I recently asked in this thread. It seems to work quite well.

I put the result in a GitHub gist for now.

This site seems to do a good job of using it to validate an info.json file. You can copy the schema and your info.json contents to it. It will then immediately report any problems found.

I also found a GitHub repository containing code to generate HTML forms from a JSON schema. You can even use the provided interactive demo to create the contents of a .arduboy info.json file (although it doesn’t seem to validate the output as well as the previous site). *See below.

If my schema appears to be useful, it could be added to the guide, or the guide could include a link to a site hosting it in a more permanent and useful way than my gist.

*This forum doesn’t seem to like making a link with a very long URL. Copy the following link and paste it into your browser’s URL field to open the interactive demo with my schema.

1 Like

1 Like

I think we can all be reasonable about what formats are considered considerably common these days:

jpg, bmp, png, gif, animated gif

I have no problem displaying any of these.

I forked the schema but can’t seem to create a pull request for a gist.

I’ve must have missed that.
Adding a json version isn’t a bad idea at all

No, gists aren’t that sophisticated. Do you want me to turn it into a repository? Or you could make a repository and we could maintain it there. You and the other loader authors have more interest in it than I do.

I’ll talk to Crait about it, he has more time then I do. (and I secretly hate git)

I think @crait does as well.

Maybe it could be hosted on Arduboy’s GitHub account.

1 Like

I’m a Mercurial (hg) guy :stuck_out_tongue:
@JO3RI and @crait you guys figure this out

We shouldn’t have to be afraid to show our true colors. You’re not alone in your hatred for git! :stuck_out_tongue:

Really people ? Than you can just go with HEX files.

  • at least 1 binary
  • at least 1 screenshot
  • a banner
  • a json file with:
  • title
  • description
  • game version
  • author

you don’t want to provide those ? well just provide a HEX file.

@crait @MLXXXp @delegatevoid

Ok look, we have to finalize this. If we really are going to discuss on how to use json in a proper way, well @MLXXXp suggested how and I think @delegatevoid did too. This is how it should look properly:

Read it, check it and us it.

@MLXXXp this version has only some very small changes to the version you have in the gist (like “sketch” is replaced with “.arduboy file”, PNG is changed into PNG/BMP/JPG/GIF)

1 Like

Ok, let that repo be the single source of truth.

That’s fine, if this is what all the fields are meant to describe. I was just going by the guide.

In the guide’s Fields section, the descriptions for “title”, “description”, “genre”, “soruceUrl” and “author” all refer to game/app, not .arduboy file. Since “code”, “idea”, “art” and “sound” are similar to “author”, I assumed they referred to the game/app as well. The same goes for “publisher”, which refers to game instead of game/app. I just used sketch instead of game/app, since sketch covers both a game and an app.

So, if all these fields are supposed to refer to the .arduboy file, then you should sync up the guide to match.

However, the schema’s “buttons” description now says:
Descriptions of the actions that each button or button sequence performs to control the .arduboy file.
I don’t think that makes sense. This should be changed back to ...control the sketch or ...control the game/app.

Also, for the new “schemaVersion” field:

  • Meta-data “title” fields are supposed to be something human readable, as you would want them to appear to the user in an entry form generated from the schema. "title" : "SchemaVersion" should be "title": "Schema version" with a space between the words (and lower case “v” in version for consistency with the rest of the titles).

  • If “schemaVersion” is intended to be used by the loader to determine if the loader supports that version, it may be better to make it a “number”, rather than a “string”. JSON numbers are floating point so you could have the integer portion be the major number and the fraction be the minor number. Or, you could specify that it must be an integer and not have a minor number. You really only need to change the version when the schema becomes non backwards compatible, in which case a single integer value would probably suffice. If it is decided that just an integer is sufficient, you can validate it using keywords "minimum": 1 and "multipleOf": 1

    If, however, you want to leave it as a “string” you should probably specify its exact format in the “description”, so the loader will be able to properly parse it. I would also be good to validate it using the “pattern” keyword with an expression that matches only the desired format.

  • The first time that the schema is changed such that it becomes non backwards compatible and “schemaVersion” is changed to reflect this, “schemaVersion” should be made a required field. For now it can be optional and assumed to be v1.0 if not present, so that all the existing .arduboy files don’t have to be changed again with a new info.json file.

  • Nitpicking - So that “schemaVersion” is formatted the same as the rest of the schema fields:

  • The opening brace should follow “schemaVersion:” on the same line.

  • The keywords under it are indented 2 spaces too far.

  • The space between the keywords and the following colon should be removed.

I considered that just including .hex files could be a bare minimum .arduboy file but in actual fact you also need to be able to specify the target device for each .hex file, so the minimum would be .hex file(s) plus an info.json containing only a “binaries” field. That is, unless you want to change the spec so that the .hex filename itself must somehow indicate what device it is for.

Anyway, that’s why I’ve been asking the questions about which info.json fields are required. Once all of you can agree on this, the “required” keywords in the schema should be updated and the Requirements section of the guide should be changed as well.

No I mean , our loaders can just upload a HEX too.

Reviewing the other stuff you said, but at first sight most what you say is correct and needs to be changed

1 Like