How to create a new Room/Scene?

In this section I will describe all the tools and the work process to create a new full Scene.


Game creation process

1 - Create the maps!

I've been using Titled for this since it's a great and easy tool to work with.

The most IMPORTANT considerations here are 2:

"How you split the map layers"

Since this will affect if the layers go over or below the player sprint.


This is coming to replace all the collisions and maps data saved in the DB, instead of that we will be using the same JSON map files to load all that information based on which layers are considered for collisions, which ones for change-points, and how they will behave according to the player.

Is important to understand that the layers name conventions are used for both server and client sides.

From this we have the following conventions:

  • "collisions"

Any layer with this keyword in the name will be used to create blocks used for collisions in the server side. A collision in the server side will be represented by a empty box with the size of a tile, so if you edit your map and hit/collide with an empty space, is probably because you have a tile with a value different from zero in that position in a layer with the word "collisions" on the name.

To avoid this kind of issues I recommend you to use the TiledMap option to "Highlight Current Layer" (available pressing H while editing the map), this way you will easily see if there's any non-empty blocks in any "collision" layer.

  • "over-player"

Any layer with this keyword in the name will get an incremental depth in the client side, this way the map view will be affected by the layers order in the file and by the layers name that will get the incremental depth, so even when you can see the layers properly displayed in the TiledMap editor you may not get the exact same result after we process the layers to all these over the player.

For example: if you have 5 layers, and the 3rd and 5th in the list have "over-player" in the name, the layers will get the following depth in Phaser: L1 = depth 0, L2 = depth 0, L3 = depth 1, L4 = depth 0, L5 = depth 2 > where the player sprite will have depth 0 and go over all the other layers, the L3 and 5 will be over the player.

  • "change-points"

Any layer with this in the name should only have tiles are going to be used as change-points in the server side.

At this time if you used multiple images to create your maps, you will need to merge them in one, for that you can check optimize steps below.

  • "respawn-area"

The layers that starts with this keyword will be used for the respawn objects areas and though this layers requires to have content on them to know the valid tiles for respawn, these will never generate collisions.

2 - Optimize the map!

At this point I've realized that have multiple images for a single tile set where I was using just a few parts of each was not the best, so I've decided to create an optimizer (since I didn't found anyone that do exactly what I needed).

So all you need to do at this point is to drop your JSON file and all your images in the tilemap optimizer and get the optimized image and modified JSON file.

That's it.

Update: issues with bleeding pixels present in WebGL rendering? Here's how to fix it:

- Open FrameExtruder

- CHANGE the size to your tileset tiles size (for example 32x32).

- (Recommended) There's an option in the app to create copy of original file under "_original".

- Only then drop your map "png" file into the FrameExtruder app.

- Edit the map "json" file, set the margin=1, spacing=2, look for the tileset image and update the size with the size of the extrueded image, then save the map.

At this point, the map should be fine, BUT, if it doesn't work (like tiles position are broken), you can do the following:

- Open the map "json" file with Tiled, IMPORTANT: it will ask if you like to fix the references, click on "NO".

- Export the map into a second JSON file, YES, on Tiled go and export the JSON as JSON (this will fix the references properly).

For last, you need to copy your map "png" and the new exported "json" files into your [theme]/assets/maps/ folder, these are the ones that won't have the issue with WebGL.

Since beta.34 the following steps can be avoided by using the map importer command (link soon to come)

3 - Prepare the database

Let's say you have both files for your map ready: yourmap.json and yourmap.png. The first you need to create in the database is a new entry in the scenes table.

For that you need to run the following query (note: I'm not adding any extensions to the file names):

INSERT INTO `rooms` (`name`, `title`, `map_filename`, `scene_images`) VALUES ('YourMapName', 'Your Map Title', 'your-map-file', 'map-image');

Then you have two options here:

  • Set your new room as the default for players start, by updating the initial room config:

    UPDATE `config` SET `value` = `[your-map-entry-id]` WHERE `path` = 'players/initialState/room_id';

  • Edit one of the current rooms change points in the database, to redirect the user to your new scene (see below how to manage the change points and the return positions in the database).

Just with that you should be able to run the game with your new scene.

4 - Configure change points

The change points are defined in the database and to create a change-point you need to know the tile-index where it was specified in the map file.

How to get the index?

Well... If you are using Tiled it will give to you the tile coordinates, let's say "39,19" (x,y) in a "48x28" tiles map (this will be our ReldensTown map, 39,19 is the door on the blue house), if you take that and do the math: tileIndex = y * mapW + x > 19 * 48 + 39 you will get the index 951 which is the value you will see for our change-point in the database.

After you got your tile index you only need to insert the change point like (note 1 and 2 will be the origin and next scene ID's, where the change point is and where is going to take you):

INSERT INTO rooms_change_points ('id', 'room_id', 'tile_index', 'next_room_id') VALUES (NULL, 1, 951, 2);

5 - Configure return positions

What is a return point? Basically, the initial scene position that depends on the previous scene.

For example: you are in the town > go to the first house > this one only has 1 return point saved (since your are always coming from a single door in the town) > but when you move out from the house 1, you will need to specified at which point of the town the player is going to be displayed, so there you will see two return positions for the town in the database: one is the default that will be always the house 1, and the other will be for the house two.

To create these return positions you need to specify:

- The position in pixels

- If it's the "default" position of that scene or not

- And the scene where that position will be trigger

A record in this table will look like this:

INSERT INTO `rooms_return_points` (`id`, `room_id`, `direction`, `x`, `y`, `is_default`, `from_room_id`) VALUES (9, 6, 'right', 400, 400, 0, 2);

  • The "room_id" is where the player will be after the room change. If you go from the town into the house 1 this room_id will be the room_id of the house 1.
  • The "direction", is how the player will be diplayed (looking up, down, left or right).
  • The "x" and "y" values are the position in pixels where the player will be displayed in the map (here will be the position in the house 1)
  • For last, the "from_room_id" is where the player is coming from (the town room ID).

I'll improve this documentation over time so if you have questions about this just ping me on discord or send me an email.

All for now!