Why It Is Important to Document Even the Smallest Decisions

A week or so ago, I was configuring the hero summoning queue for my villages in “Stop That Hero!” (still available for pre-order!), and I couldn’t figure out why I had a special “END_QUEUE” for the last item in my queues. None of my code handled it, so it got ignored, and removing it didn’t change anything adversely that I could see, so I removed it since I couldn’t remember why I put it there in the first place.

Today, while working on a new level layout, I created a village that summoned only one farmer. When play-testing, I found that right when the farmer appears, the game ends in victory for the player.

Premature Victory

That’s odd…why would that happen?

My victory monitoring code checks all entities to see if there are any that are not on the player’s team. If there aren’t, then it checks all structures that summon entities owned by non-player teams to see if they are currently summoning anything. The idea is that at the beginning of the level, when no heroes have been summoned, the game doesn’t end in victory since they’re still coming, and victory only occurs when there are no more heroes being summoned AND there no more heroes left in the level.

The issue I was seeing is that right when a village spawns a farmer, the farmer doesn’t exist yet. It’s simply a new command to create a farmer. But the village no longer has a farmer in its queue and is empty. So the victory condition goes off and creates the end-game-in-victory-for-player command. So that’s why I see the farmer when the victory screen comes up. The farmer gets created and the game ends because both commands are run in the same update step.

And that’s why I had an “END_QUEUE” summon that doesn’t do anything. It’s to prevent this situation from happening. Now I remember. I ran into this issue before. The END_QUEUE summon is ignored, but the victory condition monitor sees that there is still something in the queue. By the time the END_QUEUE is “summoned” and gone, the entity creation should have happened for the previous item in the queue.

It was a stupid abuse of the system that I should have handled better the first time, but I didn’t think much of it. I needed to get things done, so I did the quick solution and promptly forgot about it.

Since I didn’t document what “END_QUEUE” was supposed to do when I came up with it, I spent part of my day trying to figure it out.

So there you go. Document your decisions, no matter how small. In fact, maybe the small decisions are even more important to document than the bigger ones.

Comments are closed.