Data-Driven Documentation - v0.2.0

Keep in mind that this is all subject to change in future versions.

Below is the JSON room documentation as of v0.2.0.

v0.2.0 includes additions such as room object scale, simplification of the wall system, dependents, room rarity, room object spawn chances, dependents, and all new JSONification of items. 

Below is an example of a JSON room (LoopVault) that should be used to assist in learning how JSON rooms can be made.

JSON files are placed within dungeon-framework-Data/StreamingAssets. Be sure to add the name of your room or item into "rooms_index.json" or "items_index.json" in order for it to spawn during gameplay.

Everything within a JSON file must be wrapped within a pair of curly brackets {}. Ensure that every declaration is followed by a comma (except the final element in an object or list).

• Booleans default to false if not otherwise specified.
• Integers default to 0 if not otherwise specified.

Room Data

At the top of the JSON, you define the rules of the room layout:

• room_name (string): The display/identifier name for your room (e.g., "room_name": "Corner Chest").
• directional (bool): When true, players will always enter from the southernmost door. The game automatically rotates the entire layout of the room so that it aligns with the direction of approach.
• random_flip (bool): Gives the engine a 50/50 chance to dynamically mirror the room layout on placement.
• random_rotate (bool): Dynamically chooses an orientation of 0, 90, -90, or 180 degrees upon generation.
• rarity (string): Set how common the room will be. common: 65%, uncommon: 25%, rare: 10%. Defaults to common. 

random_rotate and directional are mutually exclusive. If both are set to true, the engine will default to directional behavior.

Object Data

Objects represent all of the stuff within a room. Every object block is declared within a  pair of curly brackets {} that contain its data, all in the "objects" list.

All objects can use the following fields:

• type (string): Tells the Room Manager parser which prefab you want to place.
• name (string): A unique string identifier that allows this object to be referred to by other objects (such as triggers and doors).
• x / y (float): Grid coordinates based on a 17x17 room scale (spanning 8.5 in each direction away from the (0, 0) center point). Placing an object at 8.5 or -8.5 aligns it directly in the center of the outer wall.
• scale_x / scale_y (float): Grid coordinates based on a 17x17 room scale (spanning 8.5in each direction away from the (0, 0) center point). Placing an object at 8.5 or -8.5 aligns it directly in the center of the outer wall.
• rotation (int): Defines the object's orientation in degrees.
• spawn_chance (float): Between 0 and 1. Percentage chance that this object will appear when the room is placed. Unlockers spawn chance is determined by the spawn chance of their target object.
• dependent(bool): Will only spawn if the target object spawns.
• target (string): The exact name string of the object this object depends on.
  

Levers, coins, and chests can use the following field (any object can have this field but it won't do anything):

• rotate_fix (bool): Set to false if you want the object to change rotation (direction facing) with the room it is placed in. Defaults to 'true'.

Objects are split into three sections based on similarity:

1. Basic Stuff

• box: Pushable crates.
• wall: A standard 1x1 cube wall, customizable size with scale_x and scale_y.

2. Unlockers

Triggers that act as switches to unlock or open interactive objects somewhere else in the room layout.

• lever: A manual switch flipped by the player.
• pressure_plate: A floor button activated by either the player or by a box pushed on top of it.

Special Unlocker Properties:

• main_unlocker (bool): Tells the unlocker that it is the primary unlocker for the target toggleable.
• target (string): The exact name string of the target toggleable that this unlocker toggles.
  
• unlockers (list of strings): Used only by the main unlocker. A list containing the name strings of all secondary unlockers that must simultaneously be active to unlock the target toggleable. (Do not include the main unlocker's own name in this list, as the Room Manager puts it in automatically).

3. Toggleables

Things that are toggled as a result of the activation of an unlocker or group of unlockers

• chest: A container that contains a piece of loot for the player to pick up.
• door: A blockade that must be activated in order for the player to pass through it.

Special Toggleable Properties:

• name (string): This is technically a basic field, however it is here to reiterate that you need a name in order to use a toggleable. Your unlocker won't know which door or chest to look for if you don't name it and match it in the unlocker target.

Below is an example of a JSON item (Gem).

Item Data

All items can use the following fields:

• item_name (string): The display/identifier name for your item
• random_sprite (bool): Whether the item has multiple sprites it can randomly pick from (i.e. color variants)
• sprite_filename (string): Usually the name of a .png file located in the Items/Sprites folder. If random_sprite is true, then it should point to a .json with a list formatted similarly to "rooms_index.json" and "items_index.json" containing every .png file the item should pick between.
• value(int): Determines the value of the item in gold. (How many coins the witch will give you for the item.)
• stackable (bool): Determines whether multiple of this item will stack into one inventory slot.
• pixels_per_unit (int): Defaults to 16. Tells the game the size of the sprite file for the item. Allows for larger/smaller sprite sizes for items.