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.
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.
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.
},
}A World is a core part of a HYTOPIA game's lifecycle. You can think of a world as a container for all controls related to gameplay - audio, entities, lighting, physics, chunk terrain, tick loop, and more.
When you start your server, a default world is automatically created and provided for you to use. This world houses everything related to its own gameplay.
Creating additional world instances allows you to create completely isolated game world instances within your server. These instances exist in the same physical server instance. If you've played games like Minecraft, you can think of multiple world instances in a similar way to how Minecraft seperates The Overworld, The Nether, and The End worlds.
By default, players will automatically join into the default world when they join your game, but you can at any point in time join them to another World instance within your server through the player.joinWorld()method, documented in .
In nearly all cases, you won't need to use any other world instances besides the default one returned in the callback of startServer(world => {}) .
Using additional world instances beyond the default world may only make sense in the following situations.
Your game needs to explicitly isolate its physics simulations where isolated world instances could achieve this, since each world runs its own physics simulation.
Your game needs control of environment lighting and visuals in a way that can't be done with a single world. Such as if your game has an overworld with sunny lighting, but also requires another world in "outer space" setting where no lighting, or completely different environmental lighting is required.
For now, we strongly recommend you isolate gameplay to a single world in most cases unless you know what you're doing.
Cleaning Up World Instances
To clean up a world instance when it's no longer needed, call world.stop(). This ensures the resources are freed, maintaining server efficiency.
A World instance exposes all of the managers and various functionality required to control game behavior.
You can find the most up to date list of available managers as properties of a World instance in the .
You can change the skybox of your world by adding cubemap images to an assets/cubemaps/skyboxfolder in your project.
This assets/cubemaps/skyboxfolder should include the following 6 images to use for the skybox.
+x.png
+y.png
+z.png
-x.png
These 6 images will be used for the 6 faces of the skybox on their appropriately named axes.
If no cubemap is provided by you in a assets/cubemaps/skyboxfolder that you create, then the default skybox will be used.
The World class is constantly evolving. You Can find the latest .
If there are features that we don't currently support for Worlds that you'd like to see added to the HYTOPIA SDK, you can .
-z.png