If not, maybe include a sample call to the example dungeon to be clear.... A sample call for each function using the getDungeon call as sample data would help me here a ton.
Here’s the API written out with a single example used throughout. I’ve decided to remove the getRooms() and getHallways() calls for now because I don’t think there’s an easy way to make them deterministic (e.g. always return the top left room first) given the code length constraints of the smart contract. May revisit this if there’s alot of demand but it’s fairly trivial for developers to identify rooms from the getDungeon() call.
API
The dungeon contract exposes the following endpoints to allow developers to use and query dungeons in their games and applications.
We’ll use this dungeon for all examples below:
Dungeon Geometry
getDungeon() (array) - Returns a 2D array representing all tiles in the dungeon as ascii characters. The array uses a zero-based index and the top left corner of the dungeon starts at (0, 0). We’ll use this dungeon as an example for subsequent calls:
[
['X', 'X', 'X', 'X', 'X', 'X', 'X', 'X'],
['X', 'X', 'X', 'X', ' ', 'i', ' ', 'X'],
['X', ' ', ' ', 'X', ' ', ' ', ' ', 'X'],
['X', ' ', ' ', 'X', ' ', ' ', ' ', 'X'],
['X', ' ', ' ', 'X', ' ', ' ', ' ', 'X'],
['X', ' ', ' ', ' ', 'D', ' ', 'X', 'X'],
['X', ' ', ' ', 'X', 'X', 'X', 'X', 'X'],
['X', 'X', 'X', 'X', 'X', 'X', 'X', 'X'],
['X', 'X', 'X', 'X', 'X', 'X', 'X', 'X']
]
Dungeon Attributes
getName() (string) - Returns the name of the dungeon. In our example: Den of the Twins.
getEnvironment() (int) - Returns the environment of the dungeon. There are six total environments and each affects the color of the original SVG. Developers can choose to embrace or ignore these environments. In our example: 0
numDoors() (int) - Returns the number of doors present in the dungeon. In our example: 1.
Useful for: Querying for dungeons with a specific number of doors.
numPoints() (int) - Returns the number of points of interest present in the dungeon. In our example: 1.
Useful for: Querying for dungeons with a specific number of points.
numFloors() (int) - Returns the number of accessible floor tiles in the dungeon. This includes doors and points of interest. In our example: 26
Useful for: Determining probabilities of objects based on the amount of floor space. Making sure a given dungeon is suitable for a given party size.
numTiles() (int) - Returns the overall size of the dungeon. In this case, we have an 8x8 dungeon, so in our example: 64
Useful for: Querying for dungeon based on size
Specific Locations
getDoors() (array) - Returns a list of coordinates of doors. Coordinates are represented as an array of [x, y]. In our example: [ [4, 5] ]
Useful for: Querying for dungeons that have doors in a specific location
getPoints() (array) - Returns a list of coordinates of points of interest. Coordinates are represented as an array of [x, y]. In our example: [ [5, 2] ]
getTile(x, y) (char) - Returns the character at a specific tile. Characters used are as follows:
'X': wall
' ': floor tile
'D': door
'i': point of interest
I’m also considering converting getDungeon() from an array to a uint256 or string. The int would contain integers to represent tiles (similar to the array) or the string would contain characters to allow us to scale to more use cases (e.g. decorative art).
Reconstructing the dungeon: Because all dungeons are square, you can deduce the size of the dungeon by taking the sqrt() of the string’s length. You can treat the first character as the top left (0, 0). This allows you to create a 2d array in a few lines of code.
For example the above example dungeon would become:
00000000000013100110111001101110011011001112100011000000000000000000000
'0': wall
'1': floor tile
'2': door
'3': point of interest
This is a little bit harder to process but dramatically compresses the amount of data sent over the wire. Because dungeons are always square, it becomes really simple to reconstruct the dungeon as an array from this int.
