IFComp walkthrough best practices

Are there any agreed upon best practices for IFComp walkthroughs?

Things like:

  • Do people prefer a bare list of commands (or choices), an annotated list of commands, or a general ‘do this then do this…’ without including the specific inputs

  • In games with multiple endings should you show instructions for all the endings, just the best / canonical ending, or just the worst good ending and leave better endings as an exercise for the reader, or something else?

  • Should the instructions take the shortest possible path to the ending or should you take time to smell the roses?

  • The format


There was a bit of discussion about walkthroughs in this thread a few years ago, which I dug up after misremembering it as an “IFComp walkthrough” thread, which it actually is not. There’s another short discussion here, which is also not the thread I was looking for.

Speaking entirely now of my own preferences.

Writing a walkthrough is a skill in itself! I like a walkthrough to be an explicit, step-by-step guide through a game. But in addition to a complete list of steps, I want there to be helpful annotations: indications of what my current immediate goal is, or what small- and medium-sized problems I’m currently working on. I want to be able to drop into the walkthrough halfway through a game when I’m stuck instead of having to work through the whole game with the walkthrough from the beginning. Comments drawing my attention to the fiddly bits of difficult puzzles, warning me of ways I might make the game unwinnable, or helping around guess-the-verb problems are great. Anything that helps me to quickly figure out what I missed and then get back to playing without the walkthrough is welcome.

It’s frustrating to try to play a game, realize I’m completely stuck, find a walkthrough, and then be frustrated by not being able to get actual help out of the walkthrough because it’s nothing more than a sequence of commands that result in a winning state if and only if you execute them in exactly that order from the very beginning of the game. A good walkthrough puts itself in the reader’s/player’s place and offers affordances, just like a good piece of parser IF does. If I’m coming to a walkthrough near the end of the game and – to pick just one example – it turns out I missed grabbing the bronze key from under the flowerpot, I want to be able to skim through the walkthrough, see a mention of a bronze key, and think, “Woah, I never got that. That must be what opens the bronze door.” Knowing that the bronze key is what I’m missing directs my attention to that problem, and I can work backwards from there: ah, it’s on Apartment Landing, I know how to get there, sure … and I have to search all of the flowerpots … and … . I can then go back and correct my errors (assuming that missing the bronze key hasn’t made the game unwinnable somehow).

In contrast, if the walkthrough has the PC picking up the bronze key with TAKE ALL, and the phrase “bronze key” never appears in the walkthrough itself until the walkthrough has me type UNLOCK BRONZE DOOR WITH BRONZE KEY, I won’t be able to figure out from the walkthrough what I’m missing. In that case, my only hope is to restart the game from scratch, following the walkthrough slavishly from the beginning. That’s no fun, and that says little about how much effort the walkthrough writer put into writing their walkthrough. Like all expository writing, good walkthrough writing involves thinking about how someone who’s not you and doesn’t have the information you’re trying to convey will encounter the words you’re putting in the document.

In my opinion, the person who most consistently writes excellent walkthroughs is David Welbourn, who collects them here – they’re absolutely worth looking at if you haven’t seen them before.


Volker T. Blasius’ narrative walkthrough for World is a work of art in itself.
Downloadable from the IFDB game page (worldsol.zip) here: World - Details (ifdb.org)

Hear, hear!


I much prefer gradual hints instead of walkthroughs.


Sound advice, thank you!

I agree, they’re great! I guess an implicit part of my question was “is a good IFComp walkthrough the same as a good general purpose walkthough?” If so I suppose the best advice is “Just do what David does.” :slight_smile:

Thanks for bringing that walkthrough to my attention, I’ll be sure to have a look at it.

I personally agree, but perhaps A, different people have different tastes so it doesn’t hurt to have both. And B, within the scope of the competition perhaps some players don’t want to (or have time to) engage with the puzzles and just want to zoom through the game.


Good old plain text is fine, or you could alternatively consider PDF or HTML, then you could distribute the content over several pages and have a clickable table of contents to let players jump to specific sections, minimizing their exposure to (unintended) spoilers.

I like plain text for maximum opening speed and ease of use – sometimes a PDF reader or a browser opens sluggishly, when a lot of tabs were open in the last session. But the TOC aspect could make these other formats worthwhile. Or you could even get fancy and make it look like a sort of in-universe resource, feelie-style, as long as that doesn’t impede its usability for a frustrated player.

(About the content itself, I have nothing to add to Patrick’s great answer. :+1:)


If you’re going to release it as a PDF, it better be a pretty one to makeup for the format’s limitations.

PDF readers in general suck. They’re bad on PC and they’re much worse on mobile. Disregarding the fact that there are only a handful of PDF readers even worth using on Android (which I recently discovered while trying to play PDF gamebooks), their fixed page sizes make for itty bitty text on mobile. So small that you have to read the PDF in landscape mode just to be able to see it well. It makes for very poor reading.

So, again, if you’re not going to use any features that make it a reasonable choice over HTML, just use HTML please. Thanks.


Last year, I did a screen recording of me playing the game and explaining what to do. That format was natural for me as I do website tutorials like that all the time. Are there any thoughts about this type of walkthrough?


I generally dislike video content compared to text content, but I think for the specific case of game walkthroughs I’m even more strongly in favor of text content, because you can search text. If I get stuck and can’t figure out what to do with the chicken, being able to search through the walkthrough for “chicken” could be really helpful.



That’s maybe a question of age-related IT preferences - my girlfriend is ten years younger than me, Insta-maniac, always prefering her phone over her laptop and getting all her everyday information via Youtube while I feel uncomfortable without a keyboard, scan Google results for renowned sites and commit Wikipedia to memory. She thinks I’m frumpy, I think she’s ineffective.

As a consequence: I’d always prefer Ctrl+F’ing a .txt/.pdf/.doc/.html in no time to being glued to the screen to watch a video, but I have learned that many people think vice versa, and that statistically I’ll die before them.


Agreeing with the earlier comment about a list of commands being next to useless, I am including an InvisiClues page with my IFComp entry this year. It is basically an HTML page using the standard “details” tag, so the text is hidden until the user clicks on it. Each puzzle has a series of clues getting more and more explicit. The page can be accessed from the game by typing “hint”.


This is absolutely not a best practice, but I thought it was a notable example of something you COULD do.

For our #8th placed IFComp 2008 game, Ürs, the game is written in 2nd person of course, but the walkthrough was written as a history of the character as if they had already completed the game:

The ifdb entry if you want to know more:


That reminds me of Alan Wake. That game is about a novelist and the voice over in the game is told like a noir-style novel. So it only makes sense that the entire strategy guide is written like a novel.


This thread is extremely useful-- I’ve totally changed everything about my walkthrough after reading through it. Thanks for starting it, Nils.


What about Savoir-Faire style Invisiclues as a walkthrough? I like that format because you can uncover hints slowly, although the text is awfully pale when you mouse-drag over it. I like this because I can divide the walkthrough into individual rooms that can be clicked on without you having to search through a text document that might give spoilers.

Thoughts on this as a best practice?

Highlighting white-on-white text isn’t standardized. It doesn’t work on all browsers. In particular, it tends not to work on mobile browsers.


Good to know. So that’s right out. Standard walkthrough it is.

You can of course always include a menu with gradually more explicit hints in your game itself, and for the external walkthrough, you could try what @The_Pixie suggested above, and put the individual hints behind the details HTML tag: <details>: The Details disclosure element - HTML: HyperText Markup Language | MDN


I love just using spoiler tags here on the forum. Here’s an example of invisiclues I made for Counterfeit Monkey.


This is too late for IFComp (this year) but I had some thoughts I hope are helpful.

First, yes, I agree David Welbourn’s walkthroughs are great! If you’ve seen his Trello website, you’ll notice he fills in a lot of details. More than you as an author might want to. But you can pick and choose what works best for you, what parts of his checklist are a good use of time.

I’ve often based my walkthrough, or the first draft, on the test commands I wrote. It’s not hard to do a search-and-replace in Notepad++ or your favorite text editor e.g. replace / with \n\n> or \r\n\r\n>. (It’s also not TOO bad to write a python script tracking that these are synced between your test command and/or walkthrough.) That way, I know I have something that just barely works. The extreme case is when I’ve seen walkthroughs that go

e / n / w / etc.

And I know the programmers 1) used Inform’s TEST command (“test win with e/n/w/etc.”) which is good and 2) didn’t use much else, which is not.

I know I take into account what my testers had trouble seeing when writing a walkthrough. I think there will also be certain checkpoints where it’s useful to say, okay, you should have X, Y and Z at this point. You should have unlocked room W. This is a good place to save.

@StJohnLimbo I totally didn’t know about the details tag! That is pretty awesome. I remember wishing there was one but figuring it didn’t have enough general usefulness.

I prefer text content, largely due to searchability, but I think being able to break videos up helps a lot … someone at least knows where approximately to start. And there’s always watching at double speed. All these small features make me really want to try a video walkthrough.

Also, I appreciate (in addition to annotations) if the author says “OK, this one is one worth putting the walkthrough aside to solve.” Sometimes when I try to plow through a competition, some entries need to be in heavy-walkthrough mode, and I get the gist of them with just a walkthrough and then trying to recall the way through later.

But I’ve found some things work in terms of general process:

First, a walkthrough is worth looking at once a week. Make time for it. That doesn’t sound like much, but it helps me pull back and see the big picture after focusing on one area of coding. Sometimes the others get a bit fuzzy, and that’s good, because if I’ve forgotten an assumption I made when writing a walkthrough, I’ll find a hole in the walkthrough. Proofreading my walkthrough can also help me get back in the flow if I’ve left a game to sit. The better it is early on, the more there is to revisit and picture someone saying “Hey, that doesn’t quite make sense!”

Second, it helps to have a “gunner” tester with a week or two who might not be the game’s target audience, but they’re willing to sit down and maybe even play dumb with the walkthrough. They might not even worry about the story–just verify things work or say “you should write X or Y in.”