Map Data Format

One of the most common requirements when building a game with the HYTOPIA SDK is to create a map for the game world. A map is comprised of block coordinates and the definitions of the unique block types of the world.

Oftentimes, these maps are created and exported as a .json file using https://build.hytopia.com, or other third-party tools.

The format of this file is intentionally simple and verbose, allowing third-party devs to easily create tools to import, modify and export the expected JSON file structure.

Map .json Structure

The map JSON is a single object with 2 top level properties; blockTypes and blocks.

• blockTypes - This is an array of objects that define the unique block types of the world. Each object within the array can have any properties from the BlockTypeOptions object type.

• blocks - This is an object (also known as a dictionary), that maps global coordinates to a block type ID. An example of an entry is "5,13,-4": 1. Please note that the coordinate key in this example does not have any spaces.

Example map.json

Here's an example of a valid map.json file that can be loaded into a world using world.loadMap().

Note: your assets folder in the root of your project will need to include the texture images defined by the textureUri of each block type, otherwise your block will be black in game due to no findable texture. You can learn more about assets here.

{
  "blockTypes": [
    {
      "id": 1,
      "name": "Bricks",
      "textureUri": "blocks/bricks.png" // resolves to assets/blocks/bricks.png
    },
    {
      "id": 2,
      "name": "Bouncy Clay",
      "textureUri": "blocks/clay.png"
      "customColliderOptions": {
        "bounciness": 4
      }
    },
    {
      "id": 3,
      "name": "Diamond Ore",
      "textureUri": "blocks/diamond-ore.png"
    },
    {
      "id": 4,
      "name": "Dirt",
      "textureUri": "blocks/dirt.png"
    },
    {
      "id": 5,
      "name": "Dragons Stone",
      "textureUri": "blocks/dragons-stone.png"
    },
    {
      "id": 6,
      "name": "Water",
      "textureUri": "blocks/water.png",
      "isLiquid": true // applies a liquid shader to the texture
    },
    {
      "id": 7,
      "name": "Grass",
      // textureUri when provided a directory will resolve to
      // the following 6 images mapped to the faces of the block.
      // ---
      // assets/blocks/grass/+x.png
      // assets/blocks/grass/+y.png
      // assets/blocks/grass/+z.png
      // assets/blocks/grass/-x.png
      // assets/blocks/grass/-y.png
      // assets/blocks/grass/-z.png
      // ---
      // This allows you to create more unique block types
      // with different textures on each block face.
      "textureUri": "blocks/grass"
    }
  ],
  "blocks": {
    "0,0,0": 2,
    "1,0,0": 2,
    "0,0,1": 2,
    "1,0,1": 2,
    "2,0,0": 7,
    "0,0,2": 7,
    "-2,0,-2": 7,
    "2,0,-2": 7,
    // etc... order doesn't matter.
  },
}