[Discuss] Arduboy Game Format (.arduboy) Guide


(Scott) #61

With my way the developer doesn’t have to specify 4 keywords with the same function. They can just use:

{ "control": "D-Pad", "action": "Move Character" }

My way handles 100% of the use cases, and allows for any new buttons added to future devices, without any change to the specification.

Another thing that can’t be handled easily by the current “buttons” field is when the button use completely changes at different stages or situations in the game. With my technique it’s easy:

"buttons": [
    {
        "control": "Right or Left, when on the ground",
        "action": "Run to the right or left"
    },
    {
        "control": "Up, when on the ground",
        "action": "Jump"
    },
    {
        "control": "Down, when on the ground",
        "action": "Duck"
    },
    {
        "control": "D-pad, when flying",
        "action": "Control the direction of flight"
    }
]

Then you’re restricting the specification to allow for a fancy graphical map that can’t cover all the possibilities.

I say, if the “buttons” field isn’t fully flexible for combinations and use, without becoming overly complex, then eliminate it entirely. Just leave it up to the author to describe button usage in their own documentation.

If you want loaders to be able to display a graphical button map, add a general purpose “images” field, which would be an array similar to “screenshots” but which would allow full colour images with dimensions up to a certain maximum. The total number of images allowed could also be restricted if desired.

An author could create a picture with the button map and include its “description” and “filename” in the “images” array. The loader would just display all images provided, in a location that makes sense for that particular loader. This also handles the “changing button use” situation I described above. Authors just have to provide separate button map images for each state.

If you want, take the code that you’ve developed to make the fancy little button map and turn it into a standalone app, or a tool in your manager, that authors can use to create such images.


(Holmes) #62

The entire purpose of the .arduboy file is to make sure that there are as little responsibilities as possible for the programmer when making the file. We want to make creating a .arduboy file as stress-free as possible. Otherwise, creators don’t really have incentive to make the file format.

That’s why so much is optional, including any buttons they want to include. It’s not restricting anything, as I’ve already pointed out… They can still accomplish everything that you’re proposing using the standard, already. It just won’t be supported by my program at release, which will be sometime this evening.

The more complex we make this, the less amount of people we’ll have use it and at this point, I don’t see any reason to introduce more complexity to it.

Maybe I’m lazy or maybe stubborn, but I think we’re already going back to retcon enough as it is… I can’t spend any more time making changes to my software just to change it, again, the next day. I want to release this software as soon as I can since I have people practically begging me for it on Twitter and private messages.

If anything, the standards we have are ‘at a glance.’ More fields can be optional if someone wants to create more fields and elaborate on their game in the .json file, they’re completely welcome to do it. I just can’t possibly accommodate every single variation they come up with. I totally get what you’re suggesting, but to me, it seems like a variation of what’s already implemented and decided on for a while.


(Scott) #63

That’s not the way JSON works. All keywords are supposed to be specified for a given schema. Adding keywords changes the schema and creates a different version of the specification. Adding keywords isn’t adding options, it’s changing the specification.

If you’re in a hurry to release your manager, then just remove “buttons” from the info.json specification. Add it back it when everyone can agree on its format.


(Scott) #64

I think I’m making it less complex. I’ve reduced “buttons” from having “buttonUp”, “buttonDown”, “buttonLeft”, “buttonRight”, “buttonA”, “buttonB”, “buttonAB” and any number of as yet undefined keywords, to just objects with “control” and “action” keywords.


(Holmes) #65

Everyone has pretty much agreed on a format for it, already. :smile:


(Timothy) #66

HTML5 was under development for years :slight_smile:
What @MLXXXp is saying does follow what I feel as well.

While I was working on the UI yesterday I already prepared an ItemsControl (a repeater over bound data)
for Buttons when I realized that Buttons wasn’t an array and I was thinking well oh shit no KONAMI codes then :stuck_out_tongue:

And I really don’t see the complexity, JSON is super easy to parse, no matter how deep the structure goes.

I agree that both Buttons and Companions should be an array.

Making it easy for authors to make an Arduboy file is not a valid reason to limit the json,
worst case we provide a tool to automatically generate the arduboy file.


(Holmes) #67

I’m not going to okay having multiple companion URL’s. There no reason to have more than one and it’s completely unnecessary to expand on it. Any argument you have in favor of multiple companion URL’s can be applied to any field that isn’t an array. Why not have an array of source URL’s, e-mails, authors, or genres? It’s too scope creepy.


(Holmes) #68

As for buttons, I’m going to go ahead and start updating everything to include the button objects as @MLXXXp specified.


(Timothy) #69

If a game requires/has multiple companion apps, those could be listed on the page
that the single companion field refers to. I suppose if you need multiple companion apps,
it probably isn’t a bad idea to put them on a single page together with instructions on how to set it all up.

So,

Companion remains unchanged.
Buttons become an array

For the binaries, I’m not sure I got a reply to [Discuss] Arduboy Game Format (.arduboy) Guide (or scroll up).

Personally I don’t mind having multiple entries, so I’d stick with

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

Proper grouping and filtering can be done by the UI based on this information,
unless you guys really want the expanded version:

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

The first allows for a title mismatch as a result of a typing error,
the second one makes it a little harder to write by hand, but I feel, at then end of the day
both provide all the information required for a UI to build itself.

So… what will it be?


(Holmes) #70

Definitely the first one where we describe each binary instead of defining a groups of binaries. The less levels to this file, the better.


(Timothy) #71

Jobs done :smiley:
That was easy


#72

Voila,
You talked it all out, perfect !


(Scott) #73

OK, lets look at all the currently defined fields to see which ones could benefit from being an array to allow multiple instances:

  • “title”: Is the intent to include more than one game in a single .arduboy file? If not then an array makes no sense.
  • “version”: Is the intent to include more than one version of a game in a single .arduboy file? If not then an array makes no sense.
  • “genre”: The spec. says “This field must be one of the following:” (emphasis on one mine). An array make no sense.
  • “date”: If this is a release date, you can’t release the same thing at two different times. An array makes no sense.
  • “author”: The example shows multiple authors listed in a single string, separated by dashes. I assume that this field is something that would just be displayed, not parsed by a loader. If parsing is envisioned, for instance to sort or search for games associated with a particular author, then yes, an array may be useful. (You would have to make sure that a given author always used the same spelling, for this to work.) Otherwise, an array is unnecessary.
  • “url”: Since the author has control of the site that the URL points to, in the uncommon case that the provided information is spread over multiple sites, the author has the ability to provide links to them all from the main site. An array is unnecessary.
  • “companion”: I’ve already provided an example of a case where a screen mirroring program is a companion, and multiple programs from different authors at different sites may be available that can do this. Since the game author may not have control of the site that the companion URL points to, then links to multiple URLs can’t be provided there. An array is useful for this field. And, a “description” field for what each URL points to would be helpful.
  • “sourceUrl”: Same as “url”.
  • “email”: The spec. says “Contact e-mail for help or support or more information”. Anyone using the address for this purpose would probably be confused by more than one. They would just use the first one listed. Besides, the recipient could forward messages to a different address if necessary. An array makes no sense.
  • “publisher”: More than one publisher is unlikely, but it’s the same as “author”: If it’s just to be displayed, then an array is unnecessary. If it’s to be parsed for sorting, then an array could be useful.
  • “idea”, “code”, “art”, “sound”: Same as “author”. If it’s just to be displayed, then an array is unnecessary. If it’s to be parsed for sorting, then an array could be useful.
  • “banner”: The term banner usually implies only one. An array is unnecessary. As I’ve already proposed, an array of provided “images” may be of some use, but they could also just be placed by the author on the “url” site.
  • “buttons”, “binaries”, “screenshots”: Already are arrays.

So from what I can gather, unless there’s a need for the ability to easily parse, to sort or search by “author”, “publisher”, “idea”, “code”, “art” or “sound”, then “companion” is the only defined field, that’s not an array, with a compelling reason to make it one.

To that end, personally if feel that “companion”, and to some extent “buttons” and “email”, shouldn’t be included in the spec. at all. Presumably, most authors will also make their sketch available for installation via the Arduino IDE, not just from a game loader. For that reason, they will likely provide full information on button use, contact info, and required companion programs in the documentation they provide at the “url” site or by some other means. Putting that same information in the info.json file (although optional), is redundant and is just more responsibilities for the programmer when making the file.


(Scott) #74

Some issues with the current guide:

  • The Fields section states that “date” should be in ISO 8601 format but in the provided info.json example it’s not. For human readable format with separators, It should be
    "2017-01-15T22:31:21".

  • What fields are required in info.json? The Requirements section includes “screenshots”. Both @mwm and @crait have stated that “sreenshots” shouldn’t be required. @crait has said that with his manager “almost everything is optional” but hasn’t clarified what isn’t optional.

    My opinion is that “title”, “description” and (of course) “binaries” should be required, and perhaps also “author” and even “version”. I wouldn’t make “url” required but would state that including it is strongly recommended and that the site that “url” points to, or the “sourceUrl” site (if included), should include a license agreement. All other fields can be optional.


(Holmes) #75

In my opinion, title and at least one binaries object (filename, title, device) should be required and that’s pretty much it.


(Timothy) #76

They are included in the spec because I wanted to display them in our UI.
There is no other motivation than that. If people feel they don’t need a certain field or feel it’s to much work
then the software simply won’t display that field. It’s not the end of the world.


(Scott) #77

That brings up another question:
Are the “title” fields in the “screenshots” and “binaries” objects required when one of those objects is given?

My opinion is that neither should be required. For “screenshots”, it’s a recent addition anyway, and any self-describing screen shot shouldn’t require a “title”. For “binaries”, if a “title” field isn’t present then just the “filename” can be displayed (possibly without the extension), which presumably the author felt was self-describing enough to not need a “title”.

For a "“binaries” object, both the “filename” and the “device” should be required.


(Holmes) #78

If I recall correctly, the title field is not required in either the binaries nor screenshot objects.


(Scott) #79

The guide says the banner and screenshots “should always be in standard .png format”. Is this the case, or are GIF, animated GIF, JPEG and other image formats allowed?

I think any image format should be allowed. If a particular loader doesn’t support it, then it just behaves as it would if the “banner” or the specific “screenshot” object wasn’t present in info.json


(Holmes) #80

If we’re going to be potentially putting the .arduboy files onto devices, we should probably make sure that a singular type is set to conserve memory and to make the files more universally available. Additionally, my upload script checks for viruses, etc. I don’t want to have to scan every file uploaded. Instead, my script ignores anything that isn’t .hex, .png and .json. Letting people use any image format they want also defeats the idea of even having fields associated with images. I would just grab all the images and show them, that way.