[Discuss] Arduboy Game Format (.arduboy) Guide


(Timothy) #41

This thread needs a TLDR :slight_smile:
The more feedback we get the more I regret using JSON in the first place,
Protocol Buffers have much better support for optional values, backwards compatibility
with updated schema’s etc…

Anyway the main requests for change are:

  • Added information to the images (I have no problem with that, is nice to use in the UI)
  • Remove the device field (if we really only want to support Arduboy, no problem, otherwise it’s still useful)
  • Change “hexes” to “executables” (I have no problem with that either)

Did I miss or misunderstand anything ?


(Timothy) #42

They are not fixed, if you read anywhere that they are fixed, then that documentation is incorrect.
The whole purpose of having them there is so that you can name them whatever you want.
In fact it shouldn’t even matter whether they are PNG, JPEG of whatever.


(Scott) #43

@delegatevoid, I don’t want to eliminate “device”. It’s the opposite: I want a separate “device” field for each executable (hex), so multiple devices can be supported in the same JSON file.


(Holmes) #44

Alright, so, this looks like what we’d be going forward with unless anyone has any objections.

Screenshots: I don’t think we should allow both an array of filenames as well as an array of objects. We should only allow an array of objects. This way, any fields we potentially need in the future can be added. This idea should be applied to any array we add in the future. As @MLXXXp stated, this should work: (Noticed I put filename instead of fileName.)

"screenshots": [
        {
                "title": "Logo",
                "filename": "logo.png"
        },
        {
                "title": "Screenshot",
                "filename": "screenshot1.png"
        },
        {
                "title": "Level 1",
                "filename": "screenshot2.png"
        }
]

Device Field: We would not include the device field in the top of the object. Instead, we’d have one instead of each executable.

Executables: To make it a little more abstract, we’ll change the hexes field to binaries since that’s what the Arduino IDE calls them.

"binaries": [
    {
        "title": "Chapter 1",
        "filename": "start.hex",
        "device": "Arduboy"
    },
    {
        "title": "Chapter 2: Electric Boogaloo",
        "filename": "second.hex",
        "device": "Arduboy"
    }
]

(Scott) #45

That fine, but in doing this you’ll have to “bite the bullet” and update every existing .arduboy file that has an array of filenames, but I guess you have to do this anyway, unless you also allow both the old “hexes” field and the new “binaries” field. (“filename” is equally as acceptable as “flleName” to me)

That’s fine, but again it means updating all existing .arduboy files. As I said before, for backwards compatibility you could just treat the current “device” field, if present, as a global default and then any “device” in “binaries” (if present) overrides it (kind of like CSS).

Also, you should make it completely clear in the documentation that you can only have binaries for more than one type of device if they are all compiled from the same version of the same source code by only changing the board type when compiling (since only a single “sourceUrl” and “version” field can be present in the file). If game play is significantly different between two devices then two separate .arduboy files should be made for them.


(Holmes) #46

I think updating all existing .arduboy files would be easier than programming in a lot of different edge cases, which means more testing as well as possibly confusing people who want to make their own files. These changes will make everything more straight-forward and easier on everyone if we, like you said, bite the bullet.


(Scott) #47

It’s your choice. I’m not the one who’s going to have to do it :wink:
And I agree, it does make things cleaner if you’re willing to spend the effort.


(Timothy) #48

This was actually brought up the idea of defining the target device per hex file in the original thread,
but it got shot down:

In order to add the hex files to the json we could have something like this

{
   "title": "Circuit Dude",
   "author": "crait",
   "url": "http:\/\/www.crait.net\/",
   //--- data cut here for the paste
    "hexfiles" : [
        {
            "filename" : "chapter1.hex", 
            "title" : "It was the best of times.", 
            "targetDevice" : "arduboy" 
        },
        {
            "filename" : "chapter2.hex", 
            "title" : "It was the worst of times."
        }
    ]
}

(The json above is from the original thread)
I, like you, still think it’s a good idea.


(Timothy) #49

Your reply, the one I liked, that’s the one to go with :slight_smile:


(Scott) #50

Sorry for another possible TL;DR

Again I want to emphasize that my specific intended purpose of having a “device” field for each “binaries” object is strictly to allow including, in a single .arduboy file, separate binaries for both the production Arduboy and the DevKit (and/or additional future devices) that were compiled from the same source at the same version level. This is to avoid needing two .arduboy files, one for an Arduboy and one for a DevKit, which are virtually identical except for a different “device” field value and possibly the "filename"s in “binaries”.

Of course, we still want “binaries” to support the original intended purpose of handling multiple levels (“Levels 1 - 10”, “Levels 11 - 20”), chapters (“Chapter 1 - The Maze”, “Chapter 2 - The Shootout”), difficulties (“Easy”, “Normal”, “Hard”), etc.

To that end, I realised that two binaries that use the same source, but differ only in that they each were compiled using a different board type, should have identical titles. Therefore (at the risk of making things a bit more complex), in order to not have to duplicate the “title”, and make it clear that the two binary files are just compiled for different devices, I wonder if each “binaries” object should contain a “title” and a “devices” object containing an array of objects with a “device” and “filename”?

For example:

"binaries": [
    {
        "title": "Chapter 1",
        "devices": [
            {
                "device": "Arduboy",
                "filename": "start_AB.hex"
            },
            {
                "device": "DevKit",
                "filename": "start_DK.hex"
            }
        ]
    },
    {
        "title": "Chapter 2: Electric Boogaloo",
        "devices": [
            {
                "device": "Arduboy",
                "filename": "second_AB.hex"
            },
            {
                "device": "DevKit",
                "filename": "second_DK.hex"
            }
        ]
    }
]

I think this actually makes things easier for a loader to present a given binary title. You show a binary file’s title and then allow selection of which device to upload to.


(Scott) #51

While we’re in “damn the torpedoes, change all loaders and .arduboy files” mode:

I still think multiple “companion” entries should be allowed, and they should include a description of what they’re for:

"companions": [
    {
        "description": "crait's manager, for mirrored screen capture (Windows only)",
        "url": "http://www.crait.net/arduboy/"
    },
    {
        "descripton": "Chrome extension for mirrored screen capture by davidperrenoud",
        "url": "http://community.arduboy.com/t/multi-player-and-screen-capture-using-a-chrome-app/553"
    },
    {
        "description": "Scott's mirrored screen utility for Linux",
        "url": "http://www.MLXXXp.ca"
    }
]

(Timothy) #52

Hey,

So I updated the following here

  "binaries": [
    {
      "title": "Game 1",
      "filename": "filename.hex",
      "device": "Arduboy"
    },
    {
      "title": "Game 2",
      "filename": "filename2.hex",
      "device": "DevKit"
    }
  ],

In the UI this is displayed like this:

This indicates to the user that this Arduboy file contains binaries for multiple devices.
When the user clicks “Upload game” he/she is presented with a list of available hexes (by title) which also
indicates for which device those titles are intended. Having multiple binaries with the same title but a different
device is not a problem. That’s just something that is handled in the UI, don’t think it’s relevant for the model.

Of course it depends on whether or not this will be a very common situation or not.

So… do we keep it as is or update to

{
        "title": "Chapter 2: Electric Boogaloo",
        "devices": [
            {
                "device": "Arduboy",
                "filename": "second_AB.hex"
            },
            {
                "device": "DevKit",
                "filename": "second_DK.hex"
            }
        ]
    }

Either is fine for me, as long as we all agree.
As for the companions, sure no problem.


(Holmes) #53

Oh, man, this is all getting too scope creepy. The companion’s description should be in the main description as it relates to the software. Besides, companion software is likely to hardly ever be used. We shouldn’t go that far, otherwise, we should just allow EVERY field to be an array. It’s just getting too much at this point.


(Holmes) #54

As for embeddding another level into the executables, I think that is too much, also. Would be too much work for people if they only have a single .hex file. I don’t know who this would benifit if it ends up looking the same to the end user, anyway. I say stick with our device field instead of devices.

As I said before… It’s getting too scope creepy! Too spooky!


(Scott) #55

Then eliminate “companion” altogether. Leave it up to the author to provide this information at the “url” site they provide, or in the README file at the “sourceUrl”, or wherever else they may desire.

But they shouldn’t have a single .hex file. There should be an Arduboy and a DevKit .hex file for almost every sketch that can be compiled and run on both. This will become even more true if a next generation Arduboy is released and games for the original Arduboy start being ported to it, in a way that they use the same source, and play identically, on each.

If it’s felt that this is too complicated for developers, then we should consider writing a .arduboy file creator program that just prompts for each field and then builds info.json


(Holmes) #56

Even so, those proposals are still too spooky to me… Unnecessary changes that lead to more modifications down the line.


(Scott) #57

And in the same vein as “companion” I don’t think the “buttons” array should be included.

  • Are only the keywords in the example allowed?
  • What If I want “ButtonUPDownA”? How does the loader parse and display this? What if I use “ButtonADownUp” instead?
  • What if A followed by B does one thing and B followed by A does another?

This is something better left up to the author’s own documentation.

However, if you’re going to keep the “buttons” array, then make it an array of objects which contain free form “control” and “action” text strings that the loader can build into a two column table:

buttons: [
    {
       "control": "Right or Left",
       "action": "Move HeroGirl"
    },
    {
        "control": "A",
        "action": "Use heat vision"        
    {
        "control": "Up",
        "action": "Jump up to leap tall buildings"
    },
    {
        "control": "A, while jumping",
        "action": "Start flying"
    }
]

(Holmes) #58

The fields in the buttons array are keywords. You can add your own if you want without needing to change the format. (The ones listed previously are the only ones displayed in my Arduboy Manager, but others can be read in other programs.) Since it’s not freeform, the data is parsed and not just shown to the user as-is. There is really no need for that. If we have another device come along, we can make a new array called buttonsZero or something since the device fields are very strict and foreseeable. Changing the buttons array is just too unnecessary.


(Scott) #59

So what you’re saying is:
If one of the “buttons” keywords listed doesn’t describe a button combination or sequence that I use, then I can make up my own new keyword, but it will be totally useless because all of the loaders will just ignore it and won’t display anything for it. :confounded:

My ArduboyLife sketch uses Up + Down to toggle sound on and off. I could make a “ButtonUPDown” keyword but what good would it be with your loader or any other?

And that’s the problem. Having only limited “button” keywords that you support is too strict. Even if a new device never comes along, there are many combinations and sequences that even the current Arduboy can have, that your loader can’t display. My technique of allowing the author to describe the sequence in addition to the action is fully flexible. The field names “control” and “action” are very strict but their contents don’t have to be foreseeable, and it makes the need to add something like a new a “buttonsZero” array in the future unnecessary.

As an example, in your Circuit Dude game you press and hold A to to restart the level. You hold B then press A to return to the level selection menu. You can’t press A followed by B to return to level selection. The closest keyword that your loader supports for “return to level selection” is “ButtonAB”, which is ambiguous in this case.

With my method, you would use:

"buttons": [
    {
        "control": "Hold A for a few seconds",
        "action": "Restart the current level"
    },
    {
        "control": "Hold B then press A",
        "action": "Return to the level selection menu"
    }
]

A loader would parse this into a table:

Button or Sequence Action Performed
Hold A for a few seconds Restart the current level
Hold B then press A Return to the level selection menu

Without needing to modify or extend the info.json file specification, the loader can now display any button or sequence and the action that it performs, that the author wishes to describe.


(Holmes) #60

My Arduboy Manager ‘compresses’ buttons. For instance, if you have all directions have the same action, instead of displaying it 4 times, it will display it once with “D-Pad”. Combining the button names is not saying that both buttons have the same function… It’s saying that you push them at the same time. buttonUpDown implies pushing Up and Down at the same time.

The keywords we have cover at least 99% of use cases. Anything beyond that is not necessary, but it’s something that’s been thought of before.

For now, my program does not support anything beyond the given keywords. If you want to add “Hold A + Left”, you can add that in with our current format without inventing a new keyword.

"buttons": [
    "buttonAB": "Restart Level",
    "A + Left": "Super attack",
    "A + Right": "Change item",
    "buttonLeft": "Move Character",
    "buttonRight": "Move Character",
    "buttonUp": "Move Character",
    "buttonDown": "Move Character",
],

Eventually, this feature will be expanded upon and I would support something like that. But since that is a rare combination, the only ones we support with a keyboard ‘out of the box’ is buttonAB, which is A + B at the same time.

As for the Circuit Dude example, my game is set up properly to support A + B being escaping the level to the level-select screen, which is mapped in the metadata appropriately to buttonAB.

The problem comes from the fact that we’d let anyone put anything they want into the control fields… Eventually, I want to make my GUI a bit nicer and have a little map that shows you which button on the Arduboy has each action. I can’t do that if I’m going to see variations of the same thing such as “A” and “Button A” and “A Button”.