[Discuss] Arduboy Game Format (.arduboy) Guide

@JO3RI, you should embed an example info.json file into code tags so people can copy/paste the content. It’s fine to have the schema there, but I have been using that thread to quickly grab the example file.

@crait, If you were grabbing the example file as a template to create a new info.json, you can use the link to the example form I provided above. Until you add values to the form, the JSON Output box contains the text for a blank, but complete info.json file.

Or, fill in all the form fields before copying the output, for a completed info.json file. Use the form’s Properties buttons to remove any unwanted optional fields.

1 Like

@MLXXXp fair enough ! I will add both the Jeremy Dorn’s example and a proper info.json example link to the guide.

@crait Yep will do, I’ll add en example info.json too


@MLXXXp @crait DONE !

1 Like

I found another site that seems to do a good job of validating JSON against a JSON schema.
With a schema in the left box, just copy JSON into the right side box. It will report whether both the schema and corresponding JSON text is valid.

Here’s a URL for it with the .arduboy info.json V2 schema and a bare minimum valid info.json:

Sorry, but in updating my one arduboy file, I have to wonder:

Do we want an optional field in the eeprom object for a possible “flag” value? That is, if your game stores a byte (or two) to start it’s eeprom field to decide whether there’s a valid structure there, should we note that?

Or maybe this discussion should be delayed until we have some kind of eeprom manager that could actually use that info, and we revisit the contents of the eeprom object.

Yeah, for now just fill out the fields. We will have to start an other discussion about .ase (Arduboy Saved EEPROM, or some other name) format.


Not trying to be judgemental, just an observation:

In my opinion, most .arduboy files are violating license agreements. This is true even if the file was created by the original author, or with his or her blessing.

Most open source software licenses, including BSD, Apache and MIT require copyright and license related text (or at least a link) to be included even with a binary only distribution. I think GPL and LGPL also require the original source (or a way of obtaining it) to be included. I would consider a .arduboy file to be a binary distribution.

I suggest that the .arduboy guide be updated to say that a LICENSE, LICENSE.txt, LICENSE.md, LICENSE.pdf or similar file is allowed, and should be included in a .arduboy file in order to satisfy whatever license requirements apply to the other included files.

If I were creating a .arduboy file from someone else’s work, I would do this to “cover my ass” or at least as a courtesy. If not apparent, I would contact the author for clarification.

If the original author is creating a .arduboy file and uses such a license, by not including it they’re violating their own license agreement. In this case, they should consider changing the license.

As an author, I would insist that whatever license agreement I specified be followed.

It may even be desirable to make including a LICENSE file mandatory. It could possibly contain just “Public domain” or “Unknown”.

We provide a field

“sourceUrl”: “”,

Follow the link and you should find license and source like needed.

That’s not sufficient to satisfy BSD or Apache licenses, and by most interpretations MIT as well.

From the Apache License Version 2.0 (emphasis mine):

You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
a. You must give any other recipients of the Work or Derivative Works a copy of this License; and […]

From the BSD license (emphasis mine):

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

They don’t say you can provide a link to somewhere where you might be able to find a license agreement, and I don’t think many people would interpret the above as so.

So again … we need an extra field, unless you provide everything WITH the .arduboy file.

And what if, say you don’t have a Arduboy Loader, you would still need to be able to see the license, so actually you would need it to be outside the .arduboy file.

I think it should not be IN the .arduboy file, you would have to provide it WITH .arduboy file , presenting it on the download page and that is what we do.

But indeed this might be a good idea, going to let it sip in and listen to @crait about this

I don’t think we need an extra field in info.json. Just allow and strongly suggest that a LICENSE file be included in a .arduboy file.

If you don’t have loader all the contents of a .arduboy file are irrelevant unless you unzip it manually yourself. If you do a manual unzip, the LICENSE file will be extracted and thus satisfy the requirements. We already make it clear that a .arduboy file is just a renamed .zip file.

I don’t see why it can’t be included in the .ardbuboy file. If we were to insist that it be named LICENSE.txt and contain only plain text, a loader program could even read it a make it available for display to the user.

To argue my point:
If I decide to license my sketch under a version of the BSD license, it’s perfectly legal under the license terms for me to release only a .hex file and keep the source closed. The BSD license allows me to do this by including the license text in a file along with the .hex file in whatever form I use to distribute it. In this case, there’s no way to point to a source URL containing the license. Would you want to make it impossible to create a .arduboy file for my sketch?

1 Like

I think we should just include a field. When creating the repository, I’m going to have to make the license a field, regardless of what we do inside of the file. Making it a field will help keep things somewhat universal. Besides, the whole reason for using a .json file was so that we could include new fields any time we needed them.

Remember, using a seperate file (.txt, .md, .pdf, etc.) will mean that the license cannot be displayed inside of the game loader, especially on mobile.

And why would that be … especially LICENSE.txt shouldn’t be any problem (when included in the .arduboy) at all … even if you can’t show it, it would be included and that is what @MLXXXp was talking about.

1 Like

Do you mean include 1) a string field that contains the entire license text, or 2) a string field that contains a filename? You have to include the license text somewhere within the .arduboy file.

If 1): Putting the license text itself in info.json could be messy and cumbersome.

If 2): Including a license filename in info.json can be done, but if we standardise on a single name LICENSE.txt, the field is unnecessary because its value would always be “LICENSE.txt”. Having the loader display the licence text isn’t necessary. Just including LICENSE.txt in the .arduboy file is enough to satisfy the majority of license agreements. However, if having the loader display the license text to the user is desired, the loader just has check if a file named LICENSE.txt is included in the .arduboy file and display its contents if found.

Creating a LICENSE.txt for inclusion in the .arduboy file will usually be easy.

  • In some cases, there will already be a LICENSE.txt file in the source repository. It just has to be copied for inclusion.
  • In many other cases, there will be a plain text license file in the source repository named something other that LICENSE.txt (like LICENSE without an extension). It just has to be renamed to LICENSE.txt before inclusion.
  • If not one of the above, the license text will likely be included in a comment block at the start of the source code file(s) itself. This license text just has to be copied into a file named LICENSE.txt for inclusion.
  • In rare cases, the license info may be in a form other than plain text, such as markdown or PDF. This would require converting the info to plain text to create LICENSE.txt. I’d be surprised, though, if there is any license out there that doesn’t have a plain text version that could be used, with the specific copyright message added manually if necessary.

Only if you want your loader to be able to display the license text.

Your repository JSON doesn’t actually contain the .hex and image files. It contains URLs which have been created from the filenames included in info.json. If the filename is always LICENSE.txt then that hard coded name can be used to create the URL, without getting it from info.json

But again, adding a new “license” field to info.json (which always has a value of “LICENSE.txt”) is fine if it makes things easier for you.

Of course, I would want my loader to display the license. Also, uploading .arduboy files somewhere would probably benefit from having a license that could uniformly extracted and displayed on a web page. Allowing a PDF or DOCX (which can contain macros) would be a shaky and inconsistent thing to do, in my opinion.

1 Like

Agreed. That’s why I suggest specifically requiring the filename to be LICENSE.txt and specifying that it must be plain text. And again, requiring that it be named LICENSE.txt means that putting a field for it in info.json isn’t required.

1 Like