I'm trying to understand how I would right a GDD for a programmer to read, since each job in developing a game would follow a different kind of GDD, an artist doesn't need to know how an item interacts with a tile, just as the programmer doesn't need to know how the item looks.

I wanted a programmer/coder/scripter, whoever does this job to give me a general idea on how to handle writing a programmers GDD. An example I wrote earlier is this..

PC uses [Hoe(Item)] on [Untilled Soil(Tile)], this plays the [Hoe:Use] animation and turns the tile from [Untilled Soil] into [Tilled Soil]

Is this along the lines of what I'd have to write for a programmer to work with?

Programmers have to implement every little detail and deal with every possible state the game can be in. Things that might need to be specified:

Is the length of time it takes controlled by the animation? Or should the animation loop for a specific amount of time that you (as a designer) provide in game data?

Can the conversion be cancelled in the middle of the process? If it's cancelled, does the tile remember how much progress has been made so far, or is all of the progress lost?

Are there multiple characters that could try to till the same tile at once? What happens if that is possible? Should it only allow one character to till and give an error message to the second character, or can both characters cooperate to speed up the process?


Many of these things should be decided earlier in the GDD in a "tool use" section that describes the standard conventions for how tools work in the game. This provides the programmers with a standard set of assumptions about how the game should work so that you don't have to specify the details every time you introduce a new tool.

Also, there will inevitably be things that you don't think about when writing the first draft of the GDD. When a programmer gets your GDD, they'll ask you if they have any questions. Make sure to keep your GDD up to date with these things so that programmers have a consistent source of information to go to, and don't have to keep asking you personally.

Programmers can also come up with their own answers to any unknowns they encounter during implementation, and they might not always tell you what decisions they've made. Later on when you see the feature, you might say "no, that's not how it should be!" - this happens due to lack of communication.

Programmers have to implement every little detail and deal with every possible state the game can be in. Things that might need to be specified:

Is the length of time it takes controlled by the animation? Or should the animation loop for a specific amount of time that you (as a designer) provide in game data?

Can the conversion be cancelled in the middle of the process? If it's cancelled, does the tile remember how much progress has been made so far, or is all of the progress lost?

Are there multiple characters that could try to till the same tile at once? What happens if that is possible? Should it only allow one character to till and give an error message to the second character, or can both characters cooperate to speed up the process?


Many of these things should be decided earlier in the GDD in a "tool use" section that describes the standard conventions for how tools work in the game. This provides the programmers with a standard set of assumptions about how the game should work so that you don't have to specify the details every time you introduce a new tool.

Also, there will inevitably be things that you don't think about when writing the first draft of the GDD. When a programmer gets your GDD, they'll ask you if they have any questions. Make sure to keep your GDD up to date with these things so that programmers have a consistent source of information to go to, and don't have to keep asking you personally.

Programmers can also come up with their own answers to any unknowns they encounter during implementation, and they might not always tell you what decisions they've made. Later on when you see the feature, you might say "no, that's not how it should be!" - this happens due to lack of communication.

Thanks, I improved what I had wrote earlier after reading this.

So for an example..

PC uses [Item:Hoe] on [Tile:Untilled Soil], after the animation for [Hoe:Use] finishes, the tile [Untilled Soil] becomes the tile [Tilled Soil].

I plan that none of the Tool Use animations can be canceled so they will always go through. The game is planned as single player only so I don't have to worry about the multiple entities attempting the same action at one time situation.

The tile would convert directly after the animation finishes, the animations will also be very quick ones so there won't be any looping.

If you don't mind could you go into a bit more detail about what you mean here?

"Many of these things should be decided earlier in the GDD in a "tool use" section that describes the standard conventions for how tools work in the game. This provides the programmers with a standard set of assumptions about how the game should work so that you don't have to specify the details every time you introduce a new tool."

What I gather you mean is have a general list of what they interact with and what the effect of them interacting with that entity is, correct?

Make sure you write your documentation in plain English with little room for guessing what you want.

Also look up documentation conventions like BNF for documenting syntax, protocols etc.

If you are a non programmer it is important you learn to communicate with programmers.

I only mention this as I deal with non programmers on a day to day basis who think they are able to provide program specifications and their specifications are like saying "just use Eggs flour and sugar in a bowl" when asked for a recipe to make a cake...

Make sure you write your documentation in plain English with little room for guessing what you want.

Also look up documentation conventions like BNF for documenting syntax, protocols etc.

If you are a non programmer it is important you learn to communicate with programmers.

I only mention this as I deal with non programmers on a day to day basis who think they are able to provide program specifications and their specifications are like saying "just use Eggs flour and sugar in a bowl" when asked for a recipe to make a cake...

Yeah i couldn't understand anything in that BNF link if you gave me a billion years to try to learn it, programming talk is so far beyond my reach it isn't even funny.

With all those brackets and stuff I put in my post that wasn't me trying to speak programmer, it was just to separate the action and entities I was using for examples from the whole sentence itself.

Would it be better if I listed a tools interaction in a format like..

Tool x should only interact with x, x, x tiles and the interaction it has will be x and nothing else. It will also play x animation during the interaction and cannot be interrupted during the animation, after the animation is finished the PC will lose x amount of Energy and then return to normal standby status.( i.e. just standing there and ready for the next player input. )

Is that the kind of plain english with little room for guessing that you mean?

Make sure you write your documentation in plain English with little room for guessing what you want.

Also look up documentation conventions like BNF for documenting syntax, protocols etc.

If you are a non programmer it is important you learn to communicate with programmers.

I only mention this as I deal with non programmers on a day to day basis who think they are able to provide program specifications and their specifications are like saying "just use Eggs flour and sugar in a bowl" when asked for a recipe to make a cake...

You don't really need to use formal languages like BNF when writing GDDs. Normal English (or whatever natural language) is fine. Use flowcharts, tables and diagrams when necessary. Make mock-ups of how you envision UI to be laid out.

If you don't mind could you go into a bit more detail about what you mean here?

"[background=#fafbfc]Many of these things should be decided earlier in the GDD in a "tool use" section that describes the standard conventions for how tools work in the game. This provides the programmers with a standard set of assumptions about how the game should work so that you don't have to specify the details every time you introduce a new tool.[/background]
"

What I gather you mean is have a general list of what they interact with and what the effect of them interacting with that entity is, correct?

An example might be:


Section: Tool Use

There are various tools in the game, such as shovels, hoes, rakes, which are all used in the same manner:

1. The user opens the "tool menu" by pressing a specific button or HUD icon.
2. The tool menu displays any tools that the user has available at the moment.
3. The user can click on one of the tools to begin using it (or close the tool menu instead).
4. If the user picks a tool, the tool menu is closed and "tile-selection mode" is entered. The cursor should change in appearance to let the user know which tool is selected. A small overlay appears at the top of the screen which says "Select a tile to use your [tool name] on."
5. In tile-selection mode, the user may either left-click on a tile, or right click to exit tool use and return to the base game-play state.
6. Most tools only work on specific kinds of tiles. When the user left-clicks on an invalid tile, an error popup should appear. The user should remain in tile-selection mode after dismissing the error.
7. When the user left-clicks on a valid tile, tool-specific animations and tile modifications are performed, then the user is returned to the base game-play state.


Section: Specific tools

Hoe: Converts "untilled" tiles to "tilled" tiles.
Rake: Removes leaves from tiles.
Shovel: If the tile contains rocks, the rocks are removed. If the tile is packed dirt, the tile is converted to loose dirt.

Make sure you write your documentation in plain English with little room for guessing what you want.

Also look up documentation conventions like BNF for documenting syntax, protocols etc.

If you are a non programmer it is important you learn to communicate with programmers.

I only mention this as I deal with non programmers on a day to day basis who think they are able to provide program specifications and their specifications are like saying "just use Eggs flour and sugar in a bowl" when asked for a recipe to make a cake...

You don't really need to use formal languages like BNF when writing GDDs. Normal English (or whatever natural language) is fine. Use flowcharts, tables and diagrams when necessary. Make mock-ups of how you envision UI to be laid out.

If you don't mind could you go into a bit more detail about what you mean here?

"Many of these things should be decided earlier in the GDD in a "tool use" section that describes the standard conventions for how tools work in the game. This provides the programmers with a standard set of assumptions about how the game should work so that you don't have to specify the details every time you introduce a new tool.
"

What I gather you mean is have a general list of what they interact with and what the effect of them interacting with that entity is, correct?

An example might be:


Section: Tool Use

There are various tools in the game, such as shovels, hoes, rakes, which are all used in the same manner:

1. The user opens the "tool menu" by pressing a specific button or HUD icon.
2. The tool menu displays any tools that the user has available at the moment.
3. The user can click on one of the tools to begin using it (or close the tool menu instead).
4. If the user picks a tool, the tool menu is closed and "tile-selection mode" is entered. The cursor should change in appearance to let the user know which tool is selected. A small overlay appears at the top of the screen which says "Select a tile to use your [tool name] on."
5. In tile-selection mode, the user may either left-click on a tile, or right click to exit tool use and return to the base game-play state.
6. Most tools only work on specific kinds of tiles. When the user left-clicks on an invalid tile, an error popup should appear. The user should remain in tile-selection mode after dismissing the error.
7. When the user left-clicks on a valid tile, tool-specific animations and tile modifications are performed, then the user is returned to the base game-play state.


Section: Specific tools

Hoe: Converts "untilled" tiles to "tilled" tiles.
Rake: Removes leaves from tiles.
Shovel: If the tile contains rocks, the rocks are removed. If the tile is packed dirt, the tile is converted to loose dirt.

Used some of your example in this if you don't mind and edited it to fit more what I think I would write in my GDD.

Section: Tool Use

There are various tools in the game, such as watering cans, shovels, hoes, rakes, which are all used in the same manner:

1. The player may use the scroll wheel or specified number on the keyboard to select the tool if that tool is already on their hotbar. If it isn't, the player will open their Inventory using the I button and drag that tool to their desired hotbar slot using the Left Click on the mouse.
2. The hotbar displays any items the player currently has equipped at the moment.
3. When a tool is selected in the hotbar the box around the selected tool/item will have a bright ring around it to alert the player that it has been selected for use, a grid will appear around the PC that indicates the tools usage radius on the tiles. This radius is restricted to tools or tile altering objects.
4. The player only has to scroll to a different item in the hotbar or remove the tool from the hotbar to make the grid radius disappear and return to base game-play status.
5. When attempting to interact with a valid tile a Green glow will appear on that tile to show the player that it can be altered with the current object or tool the player is attempting to use on it.
6. When attempting to interact with an invalid tile a Red glow will appear on that tile to show the player that it cannot be altered with the current object or tool the player is attempting to use on it.

Section: Specific Tools

Hoe: Converts Untilled tiles to Tilled tiles.
Watering Can: Converts Tilled tiles and Seeded tiles into Watered Tiles.

Yeah, you've got the hang of it!

Yeah, you've got the hang of it!

Thanks a ton, you were a LOT of help. Saved me countless hours of trying to figure out a proper format on my own.

Yeah this looks good.

The trick is just to make clear what you need and this is what you're doing.

Have fun! :)