Please document gameplay of your game!

More than once I’ve installed a game that was billed as “a port of the classic game …” . While this is a good thing, it isn’t an adequate guide to game play. I know it’s common for games these days to have no help or documentation, but they do have a tutorial level that prompts the player to do the right thing.

Ok, this is an arduino. Pretty much everything is limited, so maybe it didn’t fit. Check the game announcement and sure enough, there’s a section on game play. But it just says how to get the game started, and nothing on actual game play. Ok, check the sites linked from the announcement. Nothing but copies of the announcement. A quick look at the source to see if anything obvious stands out. Nope. Time to move on and install something that provides a little guidance on game play.

You wrote the game. Of course you know how to play it. That doesn’t mean anybody else does. It may be a port of a classic, and that means a lot of people will want to play and will put in some effort to figure out the translation. That doesn’t mean everybody can or will do that. It probably seems obvious to you, but you have a unique relationship with the game - you wrote it!

Document the game play! That isn’t how to start the game, that’s what the stuff on the screen does, and what you’re trying to do, and how you manipulate the stuff on the screen to try and do that. At the very least, a video of completing a practice level to show that would help people get started.

1 Like

Good advice.

Some games - especially puzzles - are not always intuitive and need explanation. A shoot 'em up game is pretty obvious!

I spent a bit of time with my Dominoes game ( to explain how to play ‘All Fives’ the game and then how I have implemented it. Anyone who has played the actual game (with real bones) would skip over the first part but the game play description itself would still be valuable as the Arduboy screen size has forced me to re-think how to fit it into a small area.

I won’t ask which game you were playing but hopefully the author recognises it as theirs.

1 Like

This is definitely good advice. I think it adds to the article I wrote for last month’s Arduboy Magazine about the future of Arduboy and the things we can learn from previous retro consoles. :slight_smile: The more documentation and better explanations, the better.

I wonder what would be better. A document with how to work things, tutorials in the game, or a separate tutorial Arduboy file. Some games would be easy to have a document but for more complex controls I wonder if tutorials are better.

1 Like

In game would be the best as it never get separated but let’s be honest, who has the space to do that in a complex game?

Like @filmote says, tutorials in the game are best, if you can afford to fit them in.

Frankly I think written tutorials are just less effort and few games are complicated enough to require anything fancy. Puzzle games are the only ones I find tend to benefit from anything more elabourate than “A to shoot, B to jump”. Most people with video game experience can infer the controls through genre, trial and error anyway. In puzzle games it’s typically the objective that needs explaining.

I think an .md file on a github repo, or using github’s wiki feature are both good ideas, but supplying it as part of the .arduboy format is also a good idea (and to be honest I’m in favour of giving the arduboy format a makeover, I don’t like the current format).

1 Like
  1. Thanks to whoever changed the title.

  2. I tried to make it hard to figure out what game I was talking about, in hopes that authors of games I wasn’t talking about would think it was them

  3. Shooters generally need less documentation, and puzzle games need more, but the notion that captures this is “discoverability”. I.e - how likely is the user to figure out (“discover”) that information just by poking at the game.

In general, what the buttons do is very discoverable, as there are only 6 of them. So what they do doesn’t need documentation, so long as it has an on-screen effect. I.e. - “A shoots” isn’t needed, but if B cycles weapons and has no on-screen effect, then the users first guess is that it does nothing. Maybe document that.

In a puzzle game. “A draws” or “A toggles all the pieces” or “A places the current piece” are discoverable, and doesn’t really need documenting. But if you can’t really tell what that achieves until you finish something non-trivial, that’s not so discoverable. Documenting the button action as part of that is natural, so “Use A to draw lines to connect all the FOOBARS”. If you can’t draw lines on some objects, or drawing a line on an object costs you a life, or - well, anything that has obvious on-screen consequences when you do it - the user will probably figure it out as pretty quickly.

Or if there are some things you’re not supposed to shoot - they cost you a life, or points, or instantly lose the game - that’ll be obvious when you shoot them. If you need to run over them rather than shoot them to “rescue” them for points, or to finish a level, or whatever, that’s not. If running into other things is costly, you may well avoid running into anything, making this bit particularly hard to discover. So you should document this. Doesn’t need to be explicit - just some hint that you need to do something else, like “Rescue the humans”. That will be a hint that the player needs to do something different, like running over the humans. Or coupled with “B changes your gun” would be a hint to try shooting them with the “other” gun, but I’d call that a stretch.

A lot of this is good game design - things should be discoverable, as that not only requires less documentation, but discovering things is fun. Not necessarily applicable for ports of classic games, but something to keep in mind when you start changing things so they fit the hardware, etc. And a guide to what you should document after you’re done.