OpenGDD

World space & grids

Dungeon map

dungeon-map · an adoption of Grid and direction, version 2

Tests included

Use in your package

The first button opens the authoring tool with these answers and numbers already filled in. You still add the rules and tuning of your own game.

Open in the authoring tool Download zip file
What is in the zip file

The zip file holds the adoption and its acceptance tests. In the authoring tool, choose Add contract and pick this zip file. If you edit your package outside the authoring tool, unpack the zip file in your package folder. The files of the zip file go into contracts/.

Download adoption JSON · Download verification pack

The contract that this adoption uses

This contract covers square grids and the direction words that your game uses. It says where numbering starts, which cells touch, and how a position belongs to a cell. It says how rules measure distance, decide a tie between two cells, list cells in order, and turn. This contract does not cover grid edges, pathfinding, cells that are not squares, or a third axis.

Read the full Grid and direction contract →

Questions

The supplied answer is marked on each question. Pick other answers to see what changes. Nothing is saved here: the zip file and the authoring tool use the supplied answers.

Where is this grid's first cell, and which way do its row and column numbers grow?

Supplied answer The first cell is the top-left corner. Column numbers grow right, and row numbers grow down.
The first cell is the bottom-left corner. Column numbers grow right, and row numbers grow up.
There is no first cell or corner. The grid continues through negative and positive numbers. Columns grow right, and rows grow down from the cell your game calls zero.
There is no first cell or corner. The grid continues through negative and positive numbers. Columns grow right, and rows grow up from the cell your game calls zero.
Why this is asked

Every later rule needs one shared reading of row and column numbers. This contract supports only columns that grow to the right. State a grid that grows to the left in your own prose.

When you write a cell with two numbers, does the row or column come first?

The column comes first. The pair (3, 5) means column 3, row 5.
The row comes first. The pair (3, 5) means row 3, column 5.
Supplied answer The game never names a cell with a pair of numbers. It uses a layout, cell contents, or another name instead.
Why this is asked

Swapping the two numbers turns rows into columns. A grid with the same number of rows and columns can hide that mistake, so the order must be clear.

Do the first row and column use zero or one?

Asked when
Origin and axes is Top left or Bottom left.
Supplied answer The first row and column are numbered zero. A ten-cell row runs from zero through nine.
The first row and column are numbered one. A ten-cell row runs from one through ten.
Why this is asked

Starting at zero or one changes every written cell address. Naming the start prevents a build in which every address is one cell away from the design.

A point lies exactly on the line between two cells. Which cell owns it?

The cell with the larger number owns the line. The line where cell five ends and cell six begins belongs to cell six, on either side of zero.

Divide the position by cell-size and round down, then add one when counting-starts-at is one. A boundary position belongs to the cell with the larger coordinate.
The cell farther from zero owns the line. The zero cell reaches one cell-size to each side, so it is twice as wide as the others. The name of this answer describes the calculation: the fraction is cut off, which moves the number toward zero.

Divide the position by cell-size and truncate toward zero, then add one when counting-starts-at is one. Coordinate zero spans one cell-size on each side.
Whole numbers mark cell centers. A point halfway between two centers belongs to the cell with the larger number.

Cell coordinates name centers. Divide the position by cell-size and round to the nearest whole coordinate, taking an exact half toward the larger coordinate, then add one when counting-starts-at is one.
Supplied answer Your rules only use whole cells, never positions between them. No boundary choice is needed.
Why this is asked

A boundary point needs one owner. Different rounding rules can place the same point in different cells, especially beside zero.

When your rules say nearest or within some distance, how do they measure between cells?

Add the steps across and down the grid (Manhattan). A cell two across and one up is three steps away.
Supplied answer Count the larger of the across and down steps (Chebyshev). A cell two across and one up is two steps away.
Straight steps cost one, and diagonal steps cost the square root of two (octile). The distance is the cheapest mix of those steps. Your game's comparison rule decides when two distances count as equal.

For absolute coordinate differences dx and dy, multiply the smaller difference by the square root of two minus one (about 0.414), then add the result to the larger difference. Equal means equal at whatever precision this game compares its distances with. For straight-line and octile distance, the adoption must state that comparison rule in the distance test's verification scope.
Measure a straight line between the cell centers (Euclidean). Use position units when positions exist; otherwise use cells. Your game's comparison rule decides when two distances count as equal.

Equal means equal at whatever precision this game compares its distances with. For straight-line and octile distance, the adoption must state that comparison rule in the distance test's verification scope.
No rule measures distance between cells. Rules may still use neighbors, named shapes, or links.
Why this is asked

Games often use several distance rules. This answer only controls what your written rules mean by nearest or within a distance.

From one cell, which other cells can a thing reach in one step?

Only the four cells sharing an edge are one step away. A diagonal cell cannot be reached in one step.
Supplied answer All eight surrounding cells are one step away. A thing may move across an edge or diagonally across a corner.
Nothing moves one cell at a time. Things are placed directly or move freely while the grid only reads their final cell.
Why this is asked

Movement neighbors do not follow automatically from distance or effect range. A game can use different cells for each.

When a rule says two cells are next to each other, do corners count?

Only cells sharing an edge count as neighbors. Two cells touching only at a corner are not next to each other.
Supplied answer All eight surrounding cells count as neighbors. Cells touching only at a corner are still next to each other.
No rule uses next to by itself. Each rule names the cells it means, or no rule asks whether cells are neighbors.
Why this is asked

Movement and effects can count neighbors differently. This answer keeps words such as next to from changing meaning between rules.

In what order does an authored layout list its cells?

Supplied answer List every cell in one row before starting the next row. Start with the smallest row and column numbers. A text map with one line per row already uses this order.
List every cell in one column before starting the next column. Start with the smallest row and column numbers.
List cells inside blocks such as chunks, regions, or screens. Your game's prose states block size, block order, and the order inside each block.
No authored layout lists the grid's cells. No order is needed for the material designers write and read.
Why this is asked

Drawing, updates, and save files may use different orders. This answer covers only layouts designers write and read.

A rule rates two cells equally and must pick one. The two cells are the candidates. How does the rule decide?

The rule picks the cell with the smaller column number. Between a cell in column 2 and a cell in column 4, the rule picks the cell in column 2. If the column numbers are equal, the rule picks the cell with the smaller row number.
Supplied answer The rule picks the cell with the smaller row number. Between a cell in row 2 and a cell in row 4, the rule picks the cell in row 2. If the row numbers are equal, the rule picks the cell with the smaller column number.
The rule tries the grid-fixed direction words in the order that you give them. It picks the tied neighbor in the first direction that has one. Use another answer when the tied cells are not neighbors.
The rule picks the candidate that arrived first. Your game names whether arrival means creation, placement, storage, or entering play. Replaying the same run gives the same choice. After a save and a reload, your persistence rules decide. No automatic check covers this answer. A person who reviews the design checks it.
The rule picks the candidate whose kind is listed first in your game's priority order. Cell position never decides.
The rule may pick either candidate, and players must not depend on which one. Replaying the same run repeats the choice, but loading a save may not.
The rule picks one candidate at random from a random stream that your game declares. A random stream is a series of random numbers that starts from a seed. The same run and its replay pick the same candidate. No automatic check covers this answer. A person who reviews the design checks it.
The player chooses the candidate. If the game cannot ask, the rule does nothing instead of guessing. No automatic check covers this answer. A person who reviews the design checks it.
No rule ever chooses one of two equal candidates. The situation cannot happen, or the rule affects every tied candidate.
Why this is asked

Equal choices are common and rarely written down. A fixed answer stops two builds from choosing different cells.

When your rules turn a facing by an amount, which way does the amount go on the grid?

A positive turn goes clockwise on the grid. A rotated view may show it differently, but the grid rule stays the same.
A positive turn goes counter-clockwise on the grid. A rotated view may show it differently, but the grid rule stays the same.
Supplied answer No rule turns a facing by an amount. A piece may still turn at once to face its movement or a target.
Why this is asked

Axis direction does not decide turn direction. Naming clockwise or counter-clockwise prevents equivalent formulas from reading as opposite rules.

Numbers1 number

Each value is either a number set here or a reference to a decided number in your tuning. It cannot reference an open number.

Cell size = 0

fixed as written

cell-size

The length of one cell in your position units. For center-based cells, measure from one center to the next. Use a positive size when rules read positions. Use zero when they only read whole cells. Changing this number changes which cell holds a position.

Rules1 rule

A rule is a check between the numbers. Validation reports a rule that fails.

  • cell-size >= 0
Lists1 list

Each list holds the rows this adoption supplies. A list can be empty.

Directions

directions

IdFramePointsOrder
northgridup—
north-eastgridup-right—
eastgridright—
south-eastgriddown-right—
southgriddown—
south-westgriddown-left—
westgridleft—
north-westgridup-left—
Test inputsscope and seeds

Some tests need a scope or seeds from the adoption before they can run.

distance-is-measured

Distance is measured

Scope
every movement, monster-sense, spell, and area-effect rule that says nearest, in range, or within on the dungeon map
Seeds
["dungeon-distance-room","dungeon-distance-corridor"]

one-step-moves

One step moves

Scope
player and monster one-cell moves from every floor cell in the authored rooms and corridors, including diagonal moves beside walls and doors; whether a diagonal may pass between blocked straight neighbors is stated in the game's own movement prose
Seeds
["dungeon-move-room","dungeon-move-corner"]

next-to-means

Next to means

Scope
every melee, trap, aura, and area-effect rule that uses next to on the dungeon map, including cells touching only at a corner
Seeds
["dungeon-effect-room","dungeon-effect-corner"]

tie-break-settles

Tie break settles

Scope
the north-east and south-west neighbors of a floor cell are both distance one from that cell; the rule picks the north-east cell because its row number is smaller, even though the south-west cell has the smaller column number
Acceptance tests15 tests apply

The contract comes with 22 tests. A test that runs once per row is counted once for each row. Tests that do not apply to these answers are still listed, with the reason.

axes-grow

the numbers grow one way

scenarioonce

Applies to dungeon-map.

In dungeon-map the two numbers grow right across rows and down columns, one per cell. This test uses the layout that this package declares, not the finished picture. A build may draw the grid in any way that its presentation chapter allows, and must still number it this way.

Test steps and diagnostics
Given

dungeon-map as this package lays it out, with at least two rows and at least two columns

When
  • a cell is located in the layout
  • the cells one step from it across and down are located
Then
  • the numbers grow right across rows and down columns
  • moving one cell that way raises exactly one of the two numbers by one and lowers neither
  • moving one cell the opposite way lowers exactly one of them by one
Diagnostics
  • dungeon-map-cell-addresses
  • dungeon-map-declared-layout

the-first-cell-is-in-one-corner

the grid has a first cell, in one named corner

scenarioonce

Applies to dungeon-map.

dungeon-map is a bounded rectangle whose first cell — the one whose two numbers are both smallest — is the top-left corner of the grid as this package lays it out. A build that numbers from the opposite corner fails this test even when every layout still loads.

Test steps and diagnostics
Given

dungeon-map as this package lays it out

When
  • the cell whose two numbers are both the smallest on the grid is located in the layout
Then
  • that cell is the top-left corner of the grid as this package lays it out
  • no other corner of dungeon-map holds a smaller pair of numbers
  • the grid is bounded: every cell of it lies inside the declared number of rows and columns
Diagnostics
  • dungeon-map-cell-addresses
  • dungeon-map-declared-layout

the-grid-has-no-first-cell

the grid continues in every direction

scenarioonce

Does not apply to dungeon-map: origin and axes is top left, not unbounded right and down or unbounded right and up.

coordinate-reading

a written pair names the cell this package means

scenarioonce

Does not apply to dungeon-map: coordinate order is not applicable, not column first or row first.

every-position-has-one-cell

every position belongs to exactly one cell

generalonce

Does not apply to dungeon-map: cell ownership is not applicable, not next cell along or truncate toward zero or cell centers are whole numbers.

boundary-belongs-to-one-cell

a position on a shared line belongs to one cell

scenarioonce

Does not apply to dungeon-map: cell ownership is not applicable, not next cell along or truncate toward zero or cell centers are whole numbers.

distance-is-measured

distance between two cells is measured one way

generalonce

Applies to dungeon-map.

Where a rule of dungeon-map says nearest, in range, or within, the distance it means is the larger of the steps across and the steps down, as a whole number of cells. The distance is zero from a cell to itself, it does not depend on which cell is asked about first, and every such rule returns the same number for the same pair. One worked case states the exact arithmetic, so that an approximate value fails: measured from one cell, a cell 10 across is at 10, and a cell 8 across and 5 down is at 8. A game may measure distance in more than one way. This test does not forbid that: a route planner's own estimate is the builder's choice and is outside every movement, monster-sense, spell, and area-effect rule that says nearest, in range, or within on the dungeon map. The test forbids two rules that give a player two different distances for the same two cells.

Test steps and diagnostics
Diagnostics
  • dungeon-map-distance-trace
  • first-disagreeing-rule
Holds

the distance the rule uses between the two cells is the larger of the steps across and the steps down, as a whole number of cells; the distance from a cell to itself is zero; it is the same whichever cell is asked about first; every rule in every movement, monster-sense, spell, and area-effect rule that says nearest, in range, or within on the dungeon map returns the same number for the same pair; and the worked case holds — measured from one cell, a cell 10 across is at 10, and a cell 8 across and 5 down is at 8

Seeds

["dungeon-distance-room","dungeon-distance-corridor"]

Scope

every movement, monster-sense, spell, and area-effect rule that says nearest, in range, or within on the dungeon map

equal-distance-is-decided

two distances count as equal by a declared rule

scenarioonce

Does not apply to dungeon-map: distance metric is diagonals count the same, not straight line or octile.

one-step-moves

one step reaches exactly the neighboring cells

generalonce

Applies to dungeon-map.

From any cell of dungeon-map, one step reaches exactly the eight cells sharing an edge or a corner with it, when nothing blocks the step. Other parts of this package say what happens when a step would leave the grid, and whether something in the way blocks a step. This test checks only which cells a step can reach.

Test steps and diagnostics
Diagnostics
  • dungeon-map-reachable-in-one-step
  • first-unexpected-destination
Holds

of the cells on the grid, the ones a thing can move to from this cell in one step, when nothing blocks the step, are exactly the eight cells sharing an edge or a corner with it — no more and no fewer

Seeds

["dungeon-move-room","dungeon-move-corner"]

Scope

player and monster one-cell moves from every floor cell in the authored rooms and corridors, including diagonal moves beside walls and doors; whether a diagonal may pass between blocked straight neighbors is stated in the game's own movement prose

next-to-means

next to means the same cells in every rule

generalonce

Applies to dungeon-map.

Wherever a rule of dungeon-map says one cell is next to another, it means the eight cells sharing an edge or a corner with it, and it means the same cells in every rule that says it. This question is separate from the movement question, because a game can answer the two differently.

Test steps and diagnostics
Diagnostics
  • dungeon-map-neighbor-set-per-rule
  • first-disagreeing-rule
Holds

wherever a rule of this game treats one cell as next to another, the cells it means are exactly the eight cells sharing an edge or a corner with it, and the answer is the same in every such rule

Seeds

["dungeon-effect-room","dungeon-effect-corner"]

Scope

every melee, trap, aura, and area-effect rule that uses next to on the dungeon map, including cells touching only at a corner

authored-order-lists-every-cell

this package's own material lists every cell once

generalonce

Applies to dungeon-map.

An authored layout of dungeon-map lists every cell exactly once, one whole row at a time, counting from the smallest numbers upward, and reading that layout back gives the same cells in the same places. This does not set save-file order, drawing order, update order, or the order in which rules visit cells. Naming the authored order prevents a rule from depending on one of those other orders without stating it.

Test steps and diagnostics
Scope

an authored layout of dungeon-map, with every cell distinguishable from every other, read from the first cell to the last as designers write it

Holds

the material lists every cell of dungeon-map exactly once, one whole row at a time, counting from the smallest numbers upward, and a board that is written out and read back has the same cells in the same places

Diagnostics
  • dungeon-map-authored-order-sequence
  • first-cell-out-of-order
  • cells-listed-twice-or-never

block-layout-is-declared

the blocks this material is written in are declared

scenarioonce

Does not apply to dungeon-map: enumeration order is rows then columns, not block tiled.

tie-break-settles

a tie between two cells is decided the same way every time

scenarioonce

Applies to dungeon-map.

When a rule of dungeon-map must pick between two candidates it ranks equally, it picks the candidate with the smaller row number, and if those are equal the one with the smaller column number. The adoption demonstrates that answer with this worked case: the north-east and south-west neighbors of a floor cell are both distance one from that cell; the rule picks the north-east cell because its row number is smaller, even though the south-west cell has the smaller column number. The test repeats the case after reversing creation and drawing order. A choice that changed would be a different answer to this question.

Test steps and diagnostics
Given

a rule of this game that must pick one cell, and the worked pair of equally ranked candidates described here: the north-east and south-west neighbors of a floor cell are both distance one from that cell; the rule picks the north-east cell because its row number is smaller, even though the south-west cell has the smaller column number

When
  • the rule runs
  • the same situation is set up again, with the two candidates created in the opposite order and drawn in the opposite order
Then
  • the rule picks the candidate with the smaller row number, and if those are equal the one with the smaller column number
  • it picks the same candidate both times
  • the order the candidates were created in, the order they are drawn in, where the pointer is, and how the animation runs change nothing
Diagnostics
  • dungeon-map-tie-break-report
  • dungeon-map-candidate-set

tie-break-follows-arrival

in a tie between two cells, the rule picks the candidate that came first

scenarioonce

Does not apply to dungeon-map: tie break between cells is lower row wins, not arrival order.

tie-break-is-arbitrary

a tie between two cells is decided the same way in a replay

scenarioonce

Does not apply to dungeon-map: tie break between cells is lower row wins, not deliberately arbitrary.

tie-break-is-drawn

a tie between two cells is decided by a draw from a declared stream

scenarioonce

Does not apply to dungeon-map: tie break between cells is lower row wins, not random from a declared seed.

tie-break-asks-the-player

the player decides a tie between two cells

scenarioonce

Does not apply to dungeon-map: tie break between cells is lower row wins, not player chooses.

no-tie-ever-arises

no rule ever has to decide a tie between two cells

generalonce

Does not apply to dungeon-map: tie break between cells is lower row wins, not not applicable.

a-positive-turn-goes

a positive turn goes one way

scenarioonce

Does not apply to dungeon-map: turn direction is not applicable, not clockwise or counter clockwise.

grid-direction-points · north

north points toward the top of the declared grid

scenarioper directions row

Applies to the north row.

In dungeon-map, the word north means the direction toward the top of the declared grid. It is fixed to the grid: it points the same way whoever uses it, and it never follows the facing of a thing. Naming the direction does not say whether anything may move that way. The movement question decides that. A game whose pieces move to four neighbors may still name a diagonal for an effect or a line of sight. The word means this direction in every rule of this package and never another direction.

Test steps and diagnostics
Given

a cell of dungeon-map with a cell on every side of it

When
  • a rule of this game moves something, points something, or reads a cell north of that cell
Then
  • the cell it uses is the one toward the top of the declared grid
  • the word north means that same direction in every rule of this package and never another
  • the direction does not depend on the thing that uses it
Diagnostics
  • dungeon-map-direction-resolution
  • dungeon-map-cell-addresses

grid-direction-points · north-east

north-east points diagonally toward the top-right of the declared grid

scenarioper directions row

Applies to the north-east row.

In dungeon-map, the word north-east means the direction diagonally toward the top-right of the declared grid. It is fixed to the grid: it points the same way whoever uses it, and it never follows the facing of a thing. Naming the direction does not say whether anything may move that way. The movement question decides that. A game whose pieces move to four neighbors may still name a diagonal for an effect or a line of sight. The word means this direction in every rule of this package and never another direction.

Test steps and diagnostics
Given

a cell of dungeon-map with a cell on every side of it

When
  • a rule of this game moves something, points something, or reads a cell north-east of that cell
Then
  • the cell it uses is the one diagonally toward the top-right of the declared grid
  • the word north-east means that same direction in every rule of this package and never another
  • the direction does not depend on the thing that uses it
Diagnostics
  • dungeon-map-direction-resolution
  • dungeon-map-cell-addresses

grid-direction-points · east

east points toward the right of the declared grid

scenarioper directions row

Applies to the east row.

In dungeon-map, the word east means the direction toward the right of the declared grid. It is fixed to the grid: it points the same way whoever uses it, and it never follows the facing of a thing. Naming the direction does not say whether anything may move that way. The movement question decides that. A game whose pieces move to four neighbors may still name a diagonal for an effect or a line of sight. The word means this direction in every rule of this package and never another direction.

Test steps and diagnostics
Given

a cell of dungeon-map with a cell on every side of it

When
  • a rule of this game moves something, points something, or reads a cell east of that cell
Then
  • the cell it uses is the one toward the right of the declared grid
  • the word east means that same direction in every rule of this package and never another
  • the direction does not depend on the thing that uses it
Diagnostics
  • dungeon-map-direction-resolution
  • dungeon-map-cell-addresses

grid-direction-points · south-east

south-east points diagonally toward the bottom-right of the declared grid

scenarioper directions row

Applies to the south-east row.

In dungeon-map, the word south-east means the direction diagonally toward the bottom-right of the declared grid. It is fixed to the grid: it points the same way whoever uses it, and it never follows the facing of a thing. Naming the direction does not say whether anything may move that way. The movement question decides that. A game whose pieces move to four neighbors may still name a diagonal for an effect or a line of sight. The word means this direction in every rule of this package and never another direction.

Test steps and diagnostics
Given

a cell of dungeon-map with a cell on every side of it

When
  • a rule of this game moves something, points something, or reads a cell south-east of that cell
Then
  • the cell it uses is the one diagonally toward the bottom-right of the declared grid
  • the word south-east means that same direction in every rule of this package and never another
  • the direction does not depend on the thing that uses it
Diagnostics
  • dungeon-map-direction-resolution
  • dungeon-map-cell-addresses

grid-direction-points · south

south points toward the bottom of the declared grid

scenarioper directions row

Applies to the south row.

In dungeon-map, the word south means the direction toward the bottom of the declared grid. It is fixed to the grid: it points the same way whoever uses it, and it never follows the facing of a thing. Naming the direction does not say whether anything may move that way. The movement question decides that. A game whose pieces move to four neighbors may still name a diagonal for an effect or a line of sight. The word means this direction in every rule of this package and never another direction.

Test steps and diagnostics
Given

a cell of dungeon-map with a cell on every side of it

When
  • a rule of this game moves something, points something, or reads a cell south of that cell
Then
  • the cell it uses is the one toward the bottom of the declared grid
  • the word south means that same direction in every rule of this package and never another
  • the direction does not depend on the thing that uses it
Diagnostics
  • dungeon-map-direction-resolution
  • dungeon-map-cell-addresses

grid-direction-points · south-west

south-west points diagonally toward the bottom-left of the declared grid

scenarioper directions row

Applies to the south-west row.

In dungeon-map, the word south-west means the direction diagonally toward the bottom-left of the declared grid. It is fixed to the grid: it points the same way whoever uses it, and it never follows the facing of a thing. Naming the direction does not say whether anything may move that way. The movement question decides that. A game whose pieces move to four neighbors may still name a diagonal for an effect or a line of sight. The word means this direction in every rule of this package and never another direction.

Test steps and diagnostics
Given

a cell of dungeon-map with a cell on every side of it

When
  • a rule of this game moves something, points something, or reads a cell south-west of that cell
Then
  • the cell it uses is the one diagonally toward the bottom-left of the declared grid
  • the word south-west means that same direction in every rule of this package and never another
  • the direction does not depend on the thing that uses it
Diagnostics
  • dungeon-map-direction-resolution
  • dungeon-map-cell-addresses

grid-direction-points · west

west points toward the left of the declared grid

scenarioper directions row

Applies to the west row.

In dungeon-map, the word west means the direction toward the left of the declared grid. It is fixed to the grid: it points the same way whoever uses it, and it never follows the facing of a thing. Naming the direction does not say whether anything may move that way. The movement question decides that. A game whose pieces move to four neighbors may still name a diagonal for an effect or a line of sight. The word means this direction in every rule of this package and never another direction.

Test steps and diagnostics
Given

a cell of dungeon-map with a cell on every side of it

When
  • a rule of this game moves something, points something, or reads a cell west of that cell
Then
  • the cell it uses is the one toward the left of the declared grid
  • the word west means that same direction in every rule of this package and never another
  • the direction does not depend on the thing that uses it
Diagnostics
  • dungeon-map-direction-resolution
  • dungeon-map-cell-addresses

grid-direction-points · north-west

north-west points diagonally toward the top-left of the declared grid

scenarioper directions row

Applies to the north-west row.

In dungeon-map, the word north-west means the direction diagonally toward the top-left of the declared grid. It is fixed to the grid: it points the same way whoever uses it, and it never follows the facing of a thing. Naming the direction does not say whether anything may move that way. The movement question decides that. A game whose pieces move to four neighbors may still name a diagonal for an effect or a line of sight. The word means this direction in every rule of this package and never another direction.

Test steps and diagnostics
Given

a cell of dungeon-map with a cell on every side of it

When
  • a rule of this game moves something, points something, or reads a cell north-west of that cell
Then
  • the cell it uses is the one diagonally toward the top-left of the declared grid
  • the word north-west means that same direction in every rule of this package and never another
  • the direction does not depend on the thing that uses it
Diagnostics
  • dungeon-map-direction-resolution
  • dungeon-map-cell-addresses

direction-walk-order

Row.id is tried at place Row.order in the direction order

scenarioper directions row

Does not apply to dungeon-map: tie break between cells is lower row wins, not direction order.

piece-direction-follows-facing

Row.id is read from the facing of the thing that uses it

scenarioper directions row

Does not apply to dungeon-map: no row in directions matches frame piece.

JSONthe adoption as one file

Answers you try on this page do not change this file. To change an adoption, open it in the authoring tool.

{
  "contract": "grid-and-direction",
  "version": 2,
  "origin": "https://opengdd.org/contracts/grid-and-direction-2",
  "summary": "This contract covers square grids and the direction words that your game uses. It says where numbering starts, which cells touch, and how a position belongs to a cell. It says how rules measure distance, decide a tie between two cells, list cells in order, and turn. This contract does not cover grid edges, pathfinding, cells that are not squares, or a third axis.",
  "mechanism": [
    "The mechanism is one grid of equal square cells. A row runs across it, and a column runs down it. When a game names a cell with two whole numbers, coordinate-order says which one comes first; a layout may name cells by their contents instead. The grid may be a bounded rectangle with a first cell in one corner, or continue in every direction with signed numbers and no first cell; the first question says which.",
    "This paragraph defines the grid's own frame. Every answer below refers to the grid as this package declares it: the layout your content writes out, or your own chapter's sentence about which way the numbers grow. Up, down, left and right mean those directions on the declared grid. On a bounded grid where content writes the grid out row by row, the first written row is nearest the declared origin corner: the top row for top-left, and the bottom row for bottom-left. These directions never follow the finished picture, which a build may draw any way its presentation chapter allows. A Delegated view can never change a Fixed answer.",
    "Where a game also has positions, a thing can be between cells and not only on a cell. Zero is the same place for cells and for positions. Where a cell-ownership option makes the cell at zero a different width, that option says so. Two neighboring cells share a line, and cell-ownership says which cell the line belongs to. Every conversion below divides by the cell size and, where the grid counts from 1, adds 1. Each cell-ownership option that uses positions states how position zero and shared lines are treated.",
    "This contract does not cover these related decisions: the grid's edge, two things in one cell, corner-cutting (a diagonal step past the corner of a blocked cell), pathfinding, a third axis, cells that are not squares, and whether a pass over the whole grid reads the changes that the same pass has already made."
  ],
  "questions": {
    "origin-and-axes": {
      "asks": "Where is this grid's first cell, and which way do its row and column numbers grow?",
      "rationale": "Every later rule needs one shared reading of row and column numbers. This contract supports only columns that grow to the right. State a grid that grows to the left in your own prose.",
      "options": {
        "top-left": {
          "meaning": "The first cell is the top-left corner. Column numbers grow right, and row numbers grow down."
        },
        "bottom-left": {
          "meaning": "The first cell is the bottom-left corner. Column numbers grow right, and row numbers grow up."
        },
        "unbounded-right-and-down": {
          "meaning": "There is no first cell or corner. The grid continues through negative and positive numbers. Columns grow right, and rows grow down from the cell your game calls zero."
        },
        "unbounded-right-and-up": {
          "meaning": "There is no first cell or corner. The grid continues through negative and positive numbers. Columns grow right, and rows grow up from the cell your game calls zero."
        }
      }
    },
    "coordinate-order": {
      "asks": "When you write a cell with two numbers, does the row or column come first?",
      "rationale": "Swapping the two numbers turns rows into columns. A grid with the same number of rows and columns can hide that mistake, so the order must be clear.",
      "options": {
        "column-first": {
          "meaning": "The column comes first. The pair (3, 5) means column 3, row 5."
        },
        "row-first": {
          "meaning": "The row comes first. The pair (3, 5) means row 3, column 5."
        },
        "not-applicable": {
          "meaning": "The game never names a cell with a pair of numbers. It uses a layout, cell contents, or another name instead."
        }
      }
    },
    "counting-starts-at": {
      "asks": "Do the first row and column use zero or one?",
      "rationale": "Starting at zero or one changes every written cell address. Naming the start prevents a build in which every address is one cell away from the design.",
      "when": {
        "flag": {
          "origin-and-axes": [
            "top-left",
            "bottom-left"
          ]
        }
      },
      "options": {
        "zero": {
          "meaning": "The first row and column are numbered zero. A ten-cell row runs from zero through nine."
        },
        "one": {
          "meaning": "The first row and column are numbered one. A ten-cell row runs from one through ten."
        }
      }
    },
    "cell-ownership": {
      "asks": "A point lies exactly on the line between two cells. Which cell owns it?",
      "rationale": "A boundary point needs one owner. Different rounding rules can place the same point in different cells, especially beside zero.",
      "options": {
        "next-cell-along": {
          "meaning": "The cell with the larger number owns the line. The line where cell five ends and cell six begins belongs to cell six, on either side of zero.",
          "semantics": "Divide the position by cell-size and round down, then add one when counting-starts-at is one. A boundary position belongs to the cell with the larger coordinate."
        },
        "truncate-toward-zero": {
          "meaning": "The cell farther from zero owns the line. The zero cell reaches one cell-size to each side, so it is twice as wide as the others. The name of this answer describes the calculation: the fraction is cut off, which moves the number toward zero.",
          "semantics": "Divide the position by cell-size and truncate toward zero, then add one when counting-starts-at is one. Coordinate zero spans one cell-size on each side."
        },
        "cell-centers-are-whole-numbers": {
          "meaning": "Whole numbers mark cell centers. A point halfway between two centers belongs to the cell with the larger number.",
          "semantics": "Cell coordinates name centers. Divide the position by cell-size and round to the nearest whole coordinate, taking an exact half toward the larger coordinate, then add one when counting-starts-at is one."
        },
        "not-applicable": {
          "meaning": "Your rules only use whole cells, never positions between them. No boundary choice is needed."
        }
      }
    },
    "distance-metric": {
      "asks": "When your rules say nearest or within some distance, how do they measure between cells?",
      "rationale": "Games often use several distance rules. This answer only controls what your written rules mean by nearest or within a distance.",
      "options": {
        "no-diagonals": {
          "meaning": "Add the steps across and down the grid (Manhattan). A cell two across and one up is three steps away."
        },
        "diagonals-count-the-same": {
          "meaning": "Count the larger of the across and down steps (Chebyshev). A cell two across and one up is two steps away."
        },
        "octile": {
          "meaning": "Straight steps cost one, and diagonal steps cost the square root of two (octile). The distance is the cheapest mix of those steps. Your game's comparison rule decides when two distances count as equal.",
          "semantics": "For absolute coordinate differences dx and dy, multiply the smaller difference by the square root of two minus one (about 0.414), then add the result to the larger difference. Equal means equal at whatever precision this game compares its distances with. For straight-line and octile distance, the adoption must state that comparison rule in the distance test's verification scope."
        },
        "straight-line": {
          "meaning": "Measure a straight line between the cell centers (Euclidean). Use position units when positions exist; otherwise use cells. Your game's comparison rule decides when two distances count as equal.",
          "semantics": "Equal means equal at whatever precision this game compares its distances with. For straight-line and octile distance, the adoption must state that comparison rule in the distance test's verification scope."
        },
        "not-applicable": {
          "meaning": "No rule measures distance between cells. Rules may still use neighbors, named shapes, or links."
        }
      }
    },
    "adjacency-for-movement": {
      "asks": "From one cell, which other cells can a thing reach in one step?",
      "rationale": "Movement neighbors do not follow automatically from distance or effect range. A game can use different cells for each.",
      "options": {
        "four-neighbors": {
          "meaning": "Only the four cells sharing an edge are one step away. A diagonal cell cannot be reached in one step."
        },
        "eight-neighbors": {
          "meaning": "All eight surrounding cells are one step away. A thing may move across an edge or diagonally across a corner."
        },
        "not-applicable": {
          "meaning": "Nothing moves one cell at a time. Things are placed directly or move freely while the grid only reads their final cell."
        }
      }
    },
    "adjacency-for-effects": {
      "asks": "When a rule says two cells are next to each other, do corners count?",
      "rationale": "Movement and effects can count neighbors differently. This answer keeps words such as next to from changing meaning between rules.",
      "options": {
        "four-neighbors": {
          "meaning": "Only cells sharing an edge count as neighbors. Two cells touching only at a corner are not next to each other."
        },
        "eight-neighbors": {
          "meaning": "All eight surrounding cells count as neighbors. Cells touching only at a corner are still next to each other."
        },
        "not-applicable": {
          "meaning": "No rule uses next to by itself. Each rule names the cells it means, or no rule asks whether cells are neighbors."
        }
      }
    },
    "enumeration-order": {
      "asks": "In what order does an authored layout list its cells?",
      "rationale": "Drawing, updates, and save files may use different orders. This answer covers only layouts designers write and read.",
      "options": {
        "rows-then-columns": {
          "meaning": "List every cell in one row before starting the next row. Start with the smallest row and column numbers. A text map with one line per row already uses this order."
        },
        "columns-then-rows": {
          "meaning": "List every cell in one column before starting the next column. Start with the smallest row and column numbers."
        },
        "block-tiled": {
          "meaning": "List cells inside blocks such as chunks, regions, or screens. Your game's prose states block size, block order, and the order inside each block."
        },
        "not-applicable": {
          "meaning": "No authored layout lists the grid's cells. No order is needed for the material designers write and read."
        }
      }
    },
    "tie-break-between-cells": {
      "asks": "A rule rates two cells equally and must pick one. The two cells are the candidates. How does the rule decide?",
      "rationale": "Equal choices are common and rarely written down. A fixed answer stops two builds from choosing different cells.",
      "options": {
        "lower-column-wins": {
          "meaning": "The rule picks the cell with the smaller column number. Between a cell in column 2 and a cell in column 4, the rule picks the cell in column 2. If the column numbers are equal, the rule picks the cell with the smaller row number."
        },
        "lower-row-wins": {
          "meaning": "The rule picks the cell with the smaller row number. Between a cell in row 2 and a cell in row 4, the rule picks the cell in row 2. If the row numbers are equal, the rule picks the cell with the smaller column number."
        },
        "direction-order": {
          "meaning": "The rule tries the grid-fixed direction words in the order that you give them. It picks the tied neighbor in the first direction that has one. Use another answer when the tied cells are not neighbors."
        },
        "arrival-order": {
          "meaning": "The rule picks the candidate that arrived first. Your game names whether arrival means creation, placement, storage, or entering play. Replaying the same run gives the same choice. After a save and a reload, your persistence rules decide. No automatic check covers this answer. A person who reviews the design checks it."
        },
        "named-priority-list": {
          "meaning": "The rule picks the candidate whose kind is listed first in your game's priority order. Cell position never decides."
        },
        "deliberately-arbitrary": {
          "meaning": "The rule may pick either candidate, and players must not depend on which one. Replaying the same run repeats the choice, but loading a save may not."
        },
        "random-from-a-declared-seed": {
          "meaning": "The rule picks one candidate at random from a random stream that your game declares. A random stream is a series of random numbers that starts from a seed. The same run and its replay pick the same candidate. No automatic check covers this answer. A person who reviews the design checks it."
        },
        "player-chooses": {
          "meaning": "The player chooses the candidate. If the game cannot ask, the rule does nothing instead of guessing. No automatic check covers this answer. A person who reviews the design checks it."
        },
        "not-applicable": {
          "meaning": "No rule ever chooses one of two equal candidates. The situation cannot happen, or the rule affects every tied candidate."
        }
      }
    },
    "turn-direction": {
      "asks": "When your rules turn a facing by an amount, which way does the amount go on the grid?",
      "rationale": "Axis direction does not decide turn direction. Naming clockwise or counter-clockwise prevents equivalent formulas from reading as opposite rules.",
      "options": {
        "clockwise": {
          "meaning": "A positive turn goes clockwise on the grid. A rotated view may show it differently, but the grid rule stays the same."
        },
        "counter-clockwise": {
          "meaning": "A positive turn goes counter-clockwise on the grid. A rotated view may show it differently, but the grid rule stays the same."
        },
        "not-applicable": {
          "meaning": "No rule turns a facing by an amount. A piece may still turn at once to face its movement or a target."
        }
      }
    }
  },
  "declares": {
    "values": {
      "cell-size": {
        "description": "The length of one cell in your position units. For center-based cells, measure from one center to the next. Use a positive size when rules read positions. Use zero when they only read whole cells. Changing this number changes which cell holds a position."
      }
    },
    "rows": {
      "directions": {
        "description": "List every direction word your game uses. Each row says whether it follows the grid or a piece. A grid direction also says where it points. An empty list means the game names no directions. If the tie-break answer is direction-order, list every grid-fixed direction in which a tied neighbor can lie. No automatic check covers this. A person who reviews the design checks it.",
        "record": {
          "id": {
            "type": "string",
            "required": true,
            "pattern": "kebab-case",
            "unique": true,
            "description": "The direction word your game uses, such as north, forward, or starboard. Write it in lowercase with hyphens between words."
          },
          "frame": {
            "type": "string",
            "required": true,
            "options": [
              "grid",
              "piece"
            ],
            "description": "Whether the direction follows the grid or a piece. A grid direction always points the same way: north stays north. A piece direction changes when that piece turns: forward, left, and behind turn with it."
          },
          "points": {
            "type": "string",
            "when": {
              "row": {
                "frame": [
                  "grid"
                ]
              }
            },
            "options": [
              "up",
              "down",
              "left",
              "right",
              "up-left",
              "up-right",
              "down-left",
              "down-right"
            ],
            "description": "Where this grid-fixed direction points on the grid. Omit it for a direction that follows a piece. This does not decide whether movement is allowed that way."
          },
          "order": {
            "type": "integer",
            "when": {
              "flag": {
                "tie-break-between-cells": [
                  "direction-order"
                ]
              },
              "row": {
                "frame": [
                  "grid"
                ]
              }
            },
            "unique": true,
            "description": "The place of this direction in the order in which the tie-break tries the directions. The direction with number one is tried first. Give each grid-fixed direction a different number. Use this field only when the tie-break answer is direction-order."
          }
        }
      }
    }
  },
  "rules": {
    "cell-size-not-negative": "cell-size >= 0"
  },
  "pack": "sha256:6f0b75c6c274b81fc83da206fdab2ed800c8447599764b0b04634acfca585fe9",
  "answers": {
    "origin-and-axes": "top-left",
    "coordinate-order": "not-applicable",
    "counting-starts-at": "zero",
    "cell-ownership": "not-applicable",
    "distance-metric": "diagonals-count-the-same",
    "adjacency-for-movement": "eight-neighbors",
    "adjacency-for-effects": "eight-neighbors",
    "enumeration-order": "rows-then-columns",
    "tie-break-between-cells": "lower-row-wins",
    "turn-direction": "not-applicable"
  },
  "values": {
    "cell-size": 0
  },
  "rows": {
    "directions": [
      {
        "id": "north",
        "frame": "grid",
        "points": "up"
      },
      {
        "id": "north-east",
        "frame": "grid",
        "points": "up-right"
      },
      {
        "id": "east",
        "frame": "grid",
        "points": "right"
      },
      {
        "id": "south-east",
        "frame": "grid",
        "points": "down-right"
      },
      {
        "id": "south",
        "frame": "grid",
        "points": "down"
      },
      {
        "id": "south-west",
        "frame": "grid",
        "points": "down-left"
      },
      {
        "id": "west",
        "frame": "grid",
        "points": "left"
      },
      {
        "id": "north-west",
        "frame": "grid",
        "points": "up-left"
      }
    ]
  },
  "verification": {
    "distance-is-measured": {
      "seeds": [
        "dungeon-distance-room",
        "dungeon-distance-corridor"
      ],
      "scope": "every movement, monster-sense, spell, and area-effect rule that says nearest, in range, or within on the dungeon map"
    },
    "one-step-moves": {
      "seeds": [
        "dungeon-move-room",
        "dungeon-move-corner"
      ],
      "scope": "player and monster one-cell moves from every floor cell in the authored rooms and corridors, including diagonal moves beside walls and doors; whether a diagonal may pass between blocked straight neighbors is stated in the game's own movement prose"
    },
    "next-to-means": {
      "seeds": [
        "dungeon-effect-room",
        "dungeon-effect-corner"
      ],
      "scope": "every melee, trap, aura, and area-effect rule that uses next to on the dungeon map, including cells touching only at a corner"
    },
    "tie-break-settles": {
      "scope": "the north-east and south-west neighbors of a floor cell are both distance one from that cell; the rule picks the north-east cell because its row number is smaller, even though the south-west cell has the smaller column number"
    }
  }
}