In this topic we would like to discuss the guide and the Arduboy Game File format .arduboy we made. You can give your idea, point out problems or just tell us you like/dislike it.
This format has been created by @delegatevoid, @crait and @JO3RI with help and feedback from the community.
The Arduboy Game File format Guide: Arduboy Game Format Guide: .arduboy files
Hi, great idea and great guide.
I have already made a arduboy-file for my game here: ArduIndy
Cheers Jacoste
How do you provide the URLs for more than one companion? E.g. a bitmap compressor for the images and a MIDI converter for the music?
It should probably be a “companions” array, the same as “screenshots”.
I think the guide should include recommendations for the size/resolution and aspect ratios of the banner and screenshots.
HOLY COW! Adding that in right now! Totes slipped my mind!
We want things to be as simple as possible, so the companion field is really for software for special communication with the Arduboy, like @akkera102’s TOYOSHIKI Tiny Basic needing Tera Term. The examples you gave are more like software used in the development process. I really don’t ever see the possibility of a game/app needing multiple companion software since you can only really use 1 at a time.
OK, then you should clarify the description. It currently says level makers, which I took to mean an offline tool for creating additional or alternate levels, which could be added to the game source code, to be included by recompiling it.
That’s a bad example. It’s just a generic terminal emulator. You could also use PuTTY, minicom, kermit, etc.
What if whatever companion program required had different versions for different operating systems, each developed and maintained by a different person at a different site? So you would have one URL for a Windows version and another for a Mac version. You would need more than one companion URL in this case.
Great idea! Is there a program that can do this file creation stuff automatically for you, i.e. look at the info.json and include the appropriate files into the .arduboy file? I personally don’t like renaming file extensions because of the warnings Windows gives me.
When I get back to this (I need to give some love to my RC stuff) I’m planning on setting up a web site that will use a template version of the .json file and build both the json file & the arduboy file on the fly. I hadn’t planned on putting a desktop UI on it, but it’ll probably have a CLI for testing, and I’ll keep that in mind so adding one shouldn’t be to bad.
^ Changed the sourceurl to be correct case of sourceUrl .
Is the new SAM chip we’re looking at powerful enough to read into zips and decompress them on the fly and pull out files (probably?)? I don’t think that would be feasible with the current hardware (if we say added a SD card without changing the CPU). 
Also think anything JSON would be the wrong format for current hardware.
Obviously a format based on ZIP is great for a PC (personal computer)… but if the Arduboy itself has to read the file, is that still the best format?
Although I supposed you could also have the “manager” software manage the SD card… so that you download .arduboy files on your PC but manager “installs” them onto the SD card by extracting and installing only the right hex file for the Arduboy you own, etc. Or maybe that format is a different (and simpler) binary format…
Or again maybe the SAM chip is so powerful that none of this even matters.
Yes, I think a SD card manager would be the way to go.
Even if the CPU is powerful enough to extract a .zip in a reasonable time, it would still required unnecessary code space. I know the ATSAMD21G18 has lots more flash available, but we still should strive to keep the “support” code (bootloader and libraries) as small and efficient as possible. Even a small (storage wise) SD card has enough capacity that we can afford to store sketches as .hex instead of .zip
The manager could also put a small screen shot and description .txt file for each sketch on the SD card, that a loader could present to the user for selection.
Wouldn’t it be better to have the “device” field as a field in each “hexes” object, along with “title” and “hex”?
As it is, I have to create a separate .arduboy file for a production Arduboy and a Devkit. This means that in addition to creating new .hex files, I have to identically change at least the “date” and “verson” in two different files when I make a new release. If I decide to add or change screenshots or any other field, that’s more redundant changes I have to make.
If I could include the .hex files for both a production Arduboy and a DevKit in the same file, it would mean less work and reduce the possibility of mismatch errors.
Different devices could have different builds, too. This means that we’d also need to add more fields. Also, different authors for different devices is possible… Basically, we’d need to duplicate most fields for each different hex. We ended up deciding that in the future, we’d only have a seperate .arduboy file for each device.
It would be nice if each screenshot could include an optional title or description. It would help with a possible “What am I looking at?” issue.
Instead of:
"screenshots": [
"screenshot00.png",
"screenshot01.png",
"screenshot02.png"
]
have:
"screenshots": [
{
"title: "Intro",
"file: "screenshot00.png"
},
{
"title: "Settings",
"file: "screenshot01.png"
},
{
"title: "Level 1"
"file: "screenshot02.png"
}
]
Since the screenshots are .png images, it’s possible to embed text into them. The idea behind including screenshots is to emulate how the Play Store shows off apps before you download them. They include a list of images that are supposed to be screenshots and a banner at the top.
You could, but doing both a production and DevKit version is practically a “must”. It’s something that you can do for the majority of games with just a re-compile in the IDE. The same will probably be true for a lot sketches ported to the next generation Arduboy, if we do the libraries right, so now you would need 3 files that are practically identical.
All the other situations you’re talking about are less likely. Are any of them something that can be done by just selecting a different board type in the IDE? It would be acceptable to require separate .arduboy files for them. You could even create separate production and DevKit files with my proposed change, but it wouldn’t be necessary.