JT's Weblog

The Vimkeys Game

published: December 17, 2025 estimate: 6 min read view-cnt: 7 views

I recently wrote a game design document.

The game was briefly mentioned in the previous article Blazor WASM First Impression: Building a Game with AI and DDD.

I’ve postponed the development for a while, and now I am seeking a fast-paced SDD (Spec-Driven Development) approach instead of DDD.

I felt that most “xxx driven development” methodologies focus on delivering quality code or software.

However, the first priority of my game is to deliver a playable prototype ASAP.

In other words, the goal is to evaluate whether the game is actually fun to play in a short period of time.

Thus, DDD and TDD both sound a bit like “premature optimization” IMHO.

It seems SDD is a more reasonable approach. Instead of grinding out quality code, making a quality spec and letting AI agents do the coding part might accelerate the development process.

We all know that LLMs generate non-deterministic code. The question is: how can we make the output MORE predictable?

My answer is to split the problem into smaller pieces and try to lower your expectations.

For now, there are three parts: code quality, styling and functionality.

A good spec should make LLMs generate “functionally correct” implementation with fewer human interventions (i.e., both code quality and styling are acceptable to be non-deterministic).

OK, enough talking. Let’s see what the game is about.

Here’s the direct intro of the game from the design document:

# The Vimkeys Game
This game is a combination of VIM keybindings and Snake-like gameplay.

## The Basic Gameplay:

The player uses VIM keybindings to move in a grid-like map.
The game scatters collectables at fixed (or random) positions across the view.
If a timer is used, the game ends when the timer hits zero.
Otherwise, the game ends when the last collectable is picked up.

## What Makes This Game Unique and Fun:
The game contains rich movement actions and gameplay options.
The player can configure all the keybindings and gameplay as they wish.
The goal is to let players learn what keybindings and gameplay work best for themselves.

Now, this article is not about elaborating on all the design details of the game. Instead, it’s just a brief review of what I learned from making this design document.

A Brief Review

Since I’ve already partially implemented the game without a spec or design document, the first step was to gather information from the existing task list.

Then, the first decision occurred: should I cover the tasks that were already done or not?

I covered only the to-do tasks initially, but then started from scratch. The mindset was to maintain the idea of “one spec, multiple code implementations”.

The Numeric System

I then organized the design document with this numeric system:

A few notes about the numeric system:

The Abstraction

The second decision occurred: should I split game modes into different sections or not?

It’s obvious that splitting into different sections is easier to manage.

However, the process forces you to think about the abstraction.

For now, although filler mode has its own standalone section, I simply derived it from picker mode by explicitly excluding features that are not applicable.

It would be better to abstract the core further and then derive each game mode from the core.

The Design Principle

My third decision was to keep all the dropped features documented.

I felt that the process of designing a feature is as valuable as making the final decision.

And that is also a key differentiator between a spec document and a design document:

My plan is to create the design document and then ask an LLM to generate detailed spec documents.

Lastly, generate code using the spec documents.

Here are the design principles quoted from the doc:

- **This should be fast-paced gameplay**
  - i.e., every keystroke should impact the game progress to some degree
  - Thus, the gameplay should eliminate non-movement actions if possible
  - e.g., do not make the player tap space to pick up an item
    - Do not make the player tap something to enter a portal
- **Randomize purposefully**
  - Randomly generated levels and fixed levels should be designed differently
  - Some features work best with randomly generated levels, and some do not
  - Even though it is possible to maximize the "configurable" part of the gameplay
  - The game should still treat these config options wisely if they don't make sense in the first place
- **An obvious shortcut doesn't improve the gameplay experience**
  - Do not introduce universally well-rounded functions to the player
  - Spamming the same obvious strategy to beat every level will significantly decrease the gaming experience
  - e.g., a "go back" shortcut that allows the player to navigate back to the previous view anytime and anywhere

Whenever I decided to drop a feature, I referred to these principles. Very useful! 👍👍

The First Version

I ended up with 600+ lines in my first attempt (without the use of AI tools).

Then, I prompted the LLM to check if I missed something.

The document then grew to 1000+ lines, including these changes:

It was quite nice. Most of the extra details and definitions were legit, except for the game flow — the LLM suggested a more standard, stateful approach, but I prefer a minimalistic two-state model: in-game and out-game.

I laid out my definitions of the game flow, and then after a few more tweaks, it was finalized.

Final Thought

This is my very first attempt at writing a game design document.

I can tell how complicated an actual game design document could be from this simple exercise.

For me, the document becomes messy when it grows over 500 lines (even messier when an LLM joins in).

I assume that a good design document should have the following properties:

Now, it’s time to move to the next level: specs and implementation.

Hopefully, I can make it before 2026! See y’all in the next one! 😎😎

No comments yet

Be the first to comment!