Skip to main content

Game design document

A mod's quality lives in how the player experiences it in the open world, and much of it is decided before a single line of code is written. That is the role of the game design document (GDD): one page describing what you want to build, how the player experiences it, and how you will build it with the engine's real tools.

Lab 0 checked the installation. Now, before writing gameplay code, we give the mod a one-page GDD. We revise the same document as the mod grows instead of starting a new one at every step.

Writing a GDD needs no new tool: paper or a text editor is enough. The next two lessons cut the mod into playable increments and check which game capabilities those increments need.

Design first: the modder's craft​

Before writing a prompt or touching a line of C#, the decisive step happens in your head: you have to know exactly what you want and be able to describe it clearly in plain language.

Never just say: "I want street drug deals in the game." A vague intention produces a shallow, mechanical script that breaks at the first unexpected situation.

You have to think through the scene chronologically from the player's point of view:

  • What does the player see first? Does the buyer walk up naturally, hold eye contact, or make a discreet gesture?
  • Under what conditions? Does the scene only happen at night, in an alley, or in the middle of a gang territory?
  • What if the unexpected happens? What if a police cruiser turns the corner mid-transaction? Does the buyer run, toss the package, or pull a gun?
  • How does the player experience it? Is it a real line in a subtitle, or a menu that breaks the immersion? What feedback tells the player the action succeeded or failed?

Behind every plain-language intention lies an engine reality that nobody will invent for you:

  • "He holds eye contact": the game must be able to direct one character's attention at another. Does a behavior exist for that? You search the native tables, or isolate the action as still needing confirmation.
  • "In an alleyway": GTA's engine has no magical concept of an 'alley'. You invent the definition, and a definition has to be measurable: walls tight on both sides, a narrow opening, away from a busy road. Then you check the game can measure distance and detect walls nearby.
  • "In gang territory": no map draws gang borders for you. You decide what proves it: a map zone, gang members around you, or a territory list you define and feed to the game. Every option is a capability to check.
  • "Making a discreet gesture": an animation must exist in the game files, and a small prop must exist to place in the hand. You find both in the real animation and model lists.

Leaving these details to guesswork leads straight to failure: an invented method like World.IsPlayerInAlley() is rejected at compile time (CS0117), while an imaginary animation name (anim@drug_deal@nod) or non-existent prop hash will refuse to load in the game.

Designing means tying your vision to real mechanics and assets, using reference databases:

You can run this thinking with an AI too: ask it to interrogate your idea, point out blind spots, or suggest variations. But an AI has no taste, no sense of rhythm, and no memory of what makes GTA gripping to play. Building a coherent experience players enjoy takes a real human eye. That is the modder's actual job.

Contents of a one-page GDD​

Five sections are enough to frame the project before the code:

  1. The concept: the mod in one sentence, without technical jargon.
  2. The player journey: step by step, what the player sees, hears, and is allowed to do. This is where the "what if" questions get their answers.
  3. The conditions: when and where the mod exists (time, zone, distance, state of the world).
  4. The failures: what can break, and what happens then (abandon, return to calm, cleanup).
  5. The technical anchors: the real natives, animations, props, and models that will answer these intentions, checked against the reference databases. Never from memory.

Plus one scope rule: what will not be in the first version. It is a hard section to write, and the one that saves you.

Example: a first street encounter​

This excerpt describes an early playable increment of a street-encounter mod:

  • Concept: one rival approaches the player at a street corner; an ally is nearby.
  • Player journey: the rival comes closer, may shove the player, then draws a weapon if the confrontation escalates. The ally reacts to the fight. The player sees when the scene ends.
  • Conditions: choose a visible street corner and a clear trigger for starting the scene. The exact distance remains to be tested.
  • Failures: if an actor dies or disappears, the remaining actors stop following the old plan and the scene cleans up what it owns.
  • Technical anchors to check: an approach task, a confrontation behavior, combat and the actor cleanup path. Record the real API names only after verifying them against the SDK and source.
  • Scope: no territory economy or branching dialogue in this first increment.

Unknowns stay visible in the document. The next lesson cuts the scene into increments, and the lesson after that checks the required game capabilities.

One GDD for the growing mod​

A mod keeps one GDD. Before each new increment, update its player journey, failure cases and technical anchors. The page remains a working plan for the same mod.

The GDD is also a check against the in-game result: compare what the player actually sees with what the page promised.

Check your own​

  1. Draft the one-page GDD for the mod you want to build.
  2. For each intention, record at least one verified technical anchor, or note that it remains to be found. Keeping unknowns visible in the GDD is healthy: it marks research to do, not a guess to invent.
  3. State what the first playable increment leaves out.

Next, cut the scope into playable increments, then check whether the game can support them.