LogoLogo
  • Get Started
  • Getting Started
    • Initial Setup
    • Create Your First Game
    • API Reference
    • Build Your First World Map
    • Multiplayer Testing
    • Use Templates & Examples
    • Styling & Assets
      • Modeling Guidelines
      • Texturing Guidelines
      • Default Assets
  • Build Faster With AI Tools
  • SDK Guides
    • Assets
    • Audio & SFX
      • Audio Manager
    • Blocks & Chunks
      • Block Types
      • Block Type Registry
      • Chunks
      • Chunk Lattice
    • Camera
    • Chat & Commands
    • Debugging
    • Entities
      • Animations
      • Block Entities
      • Colliders & Hitbox
      • Child Entities
      • Entity Controllers
        • Base Entity Controller
        • Pathfinding Entity Controller
        • DefaultPlayer Entity Controller
        • Simple Entity Controller
      • Entity Manager
      • Model Entities
      • Movement & Pathfinding
      • Player Controlled Entities
    • Events
    • Input & Controls
    • Lighting
      • Ambient Light
      • Light Manager
      • Point Lights
      • Spot Lights
      • Sun Light (Directional)
    • Mobile
    • Persisted Data
    • Players
      • Player Manager
      • Persisted Player Data
    • Plugins
    • Physics
      • Colliders
      • Collision Groups
      • Debugging
      • Gravity
      • Raycasts
      • Rigid Bodies
    • User Interface
      • Overlay UI
      • Scene UIs
      • Scene UI Manager
    • Worlds
      • Map Data Format
  • Helpful Resources
    • HYTOPIA Architecture & Platform Overview
    • Useful Third-Party Tools
Powered by GitBook
On this page
  • Map .json Structure
  • Example map.json
Export as PDF
  1. SDK Guides
  2. Worlds

Map Data Format

PreviousWorldsNextHYTOPIA Architecture & Platform Overview

Last updated 4 months ago

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 , 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 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 .

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 .

{
  "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.
  },
}

https://build.hytopia.com
BlockTypeOptions
world.loadMap()
learn more about assets here