# Advanced user guide

## Downloading the github repo <a href="#h.o7xws776nppt" id="h.o7xws776nppt"></a>

Go to the [Git repo](https://gitlab.com/tohaheavyindustries/WebCities) and [clone it](https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html#clone-a-repository).

### Hosting your own developer tool. <a href="#h.cw6xqhnkr7a1" id="h.cw6xqhnkr7a1"></a>

This page cannot be loaded just by opening it's index on a web browser, since it will cause a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors), so you need to either host it on an actual [server](#h.b6r96qpseb9a) or [locally](#h.nzd9o6qstlgk) on your own machine.

#### Local host <a href="#h.nzd9o6qstlgk" id="h.nzd9o6qstlgk"></a>

The easiest and fastest is a local host, that means that only you will be able to use the page, so it's not really connected to the wider internet.

To do this you will require [visual studio code](https://code.visualstudio.com/).

Once on visual studio code, go to the Extensions section, and download a plugin called "[Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer)" by Ritwick Dey.

Run the live server, and you are good to go. Remember that this method requires visual studio code to be opened, and the live server running, so if you close either of these or turn off your computer, you will need to re open the server.

#### Server <a href="#h.b6r96qpseb9a" id="h.b6r96qpseb9a"></a>

WIP

## File modification <a href="#h.g8atv967ml7r" id="h.g8atv967ml7r"></a>

### TileTypes.json <a href="#h.rgyps8g817lt" id="h.rgyps8g817lt"></a>

¿What is this file? When you load up a tileset, you have a bunch of sprites all in the same image file, but then in run time, those are rendered individually, to accomplish this the coordinates and size of each tile on the tileset is saved in this file.

```
{
    "0":{"colour":"#999999","name":"name 0","floor":1,"sprite":[{"x":0,"y":0,"w":32,"h":32}]},
    "1":{"colour":"#999999","name":"name 1","floor":1,"sprite":[{"x":32,"y":0,"w":32,"h":32}]},
    "2":{"colour":"#999999","name":"name 2","floor":1,"sprite":[{"x":64,"y":0,"w":32,"h":32}]},
    "3":{"colour":"#999999","name":"name 3","floor":1,"sprite":[{"x":96,"y":0,"w":32,"h":32}]},
    "4":{"colour":"#999999","name":"name 4","floor":1,"sprite":[{"x":128,"y":0,"w":32,"h":32}]},
    "5":{"colour":"#999999","name":"name 5","floor":1,"sprite":[{"x":160,"y":0,"w":32,"h":32}]},
    "6":{"colour":"#999999","name":"name 6","floor":1,"sprite":[{"x":192,"y":0,"w":32,"h":32}]},
    "7":{"colour":"#999999","name":"name 7","floor":1,"sprite":[{"x":224,"y":0,"w":32,"h":32}]},
}
```

Your file should look something like this, with more or less data, depending on how many tiles you have, but the data structure is the same.

<mark style="color:red;">"0"</mark> : { <mark style="color:yellow;">"colour":"#999999"</mark> , <mark style="color:green;">"name":"name 0"</mark> , <mark style="color:orange;">"floor":1</mark> , <mark style="color:purple;">"sprite":\[{"x":0,"y":0,"w":32,"h":32}]</mark>} ,

<mark style="color:red;">ID</mark>: First you have a key or ID, the first number in between quotes at the beginning of each line <mark style="color:red;">(colored red)</mark>, that's the code for that individual tile, and it's what you use in code to call it to be drawn on screen.

<mark style="color:yellow;">Color</mark>: This is the second parameter <mark style="color:yellow;">(Colored yellow)</mark>, it's currently unused, but it will serve as a fallback if the tile image cannot be found or if you want a plain color for a tile.

<mark style="color:green;">Name</mark>: <mark style="color:green;">(Colored green)</mark>The name is used mainly to facilitate user readability and identification of tiles, when you download the file for the first time, all of the names will be generic and tied up to the id of that tile, but you can change it to whatever you want.

<mark style="color:orange;">Floor</mark>: <mark style="color:orange;">(Colored orange)</mark>This is currently unused, but determines what type of floor or tile this is, if it is solid, or walkable or if any special properties may apply, this is used only if you add a player module(Not available for now)

<mark style="color:purple;">Sprite</mark>: <mark style="color:purple;">(Colored purple)</mark>These are the coordinates of that tile in the tile set, with its size, all measured on Pixels, you can check them yourself, by opening your tileset on an image editor, and looking for the x and y coords.

If you don't want a sprite and just want your plain color to display, remove the x,y,w and h parameters, and the curly brackets, and replace it with “none” (quote included). It should look something like this:\
<mark style="color:red;">"0"</mark> : { <mark style="color:yellow;">"colour":"#472d3c"</mark> , <mark style="color:green;">"name":"name 0"</mark> , <mark style="color:orange;">"floor":1</mark> , <mark style="color:purple;">"sprite":\[ "none" ]</mark>} ,\


_At any time you can open any of the configuration files and change things yourself ( **Do a backup first ! ! !** ), this will allow for modifications nota available on the editor._

### Project.json <a href="#h.q084b7o4qn1m" id="h.q084b7o4qn1m"></a>

```
{
    "settings": 
    {
        "tileSetUrl" : "./ProjectUtumno_full.png",
        "tileW" : 32,
        "tileH" : 32,
        "scale" : 2,
        "mapW" : 10,
        "mapH" : 10,
        "zLevels" : 4
    },
    "map":
    [
        173,173,173,173,173,173,173,173,173,173,
        173,173,173,173,177,173,173,173,173,173,
        173,173,173,173,173,173,173,179,173,173,
        173,173,173,179,173,173,173,173,173,173,
        173,173,179,173,173,173,173,177,173,173,
        173,173,173,173,179,173,173,173,173,173,
        173,165,173,173,165,173,173,173,173,173,
        173,173,173,173,173,173,173,177,173,173,
        173,173,173,173,165,173,173,173,173,173,
        173,173,173,173,173,173,173,173,173,173
    ],
    "zContent":
    {
        "1":{"36":75},
        "2":{"45":74},
        "3":{"65":79},
        "4":{"22":67,"31":67,"65":90}
    },
    "events":
    {
        "goToPage":
        [
            {"pos":0,"args":["https://cranile.neocities.org/",true],"name":"Check out my Neo City" },
            {"pos":1,"args":["https://cranile.wordpress.com/",true],"name":"Read my blog"},
            {"pos":22,"args":["https://github.com/NicolasCrapanzano?tab=repositories",true],"name":"See my git repos"},
            {"pos":3,"args":["https://cranile.itch.io/",true],"name":"Check my itchio"}
        ],
        "changeMap":
        [
            {"pos":5,"args":["./maps/New.json"],"name":"Go to the castle"}
        ]
    }
}
```

The project file has most of the data needed to run your city and its divided on 4 "sections" [settings](#h.sfhjxzril9re), [map](#h.rs6vwv9rw0tj), [zContent](#h.hn263jfpgtf8) and [event](#h.tl24cu4hdwhg)

#### settings <a href="#h.sfhjxzril9re" id="h.sfhjxzril9re"></a>

This part of the file stores the basic information that the program needs to start.

#### tileSetUrl <a href="#h.n3yghrm7p0zn" id="h.n3yghrm7p0zn"></a>

This is the path where your image file is stored, by default it should be set to the root folder, in case you want to move it just change the path to wherever you have it stored.

#### tileW & tileH <a href="#h.9ix5xk37vikp" id="h.9ix5xk37vikp"></a>

This is the Width and Height of each tile measured on pixels.

#### scale <a href="#h.x6u708dk3190" id="h.x6u708dk3190"></a>

When creating a city with small tiles you may run into the problem that everything looks too small, if that is the case change the scale factor, this will multiply the tiles width and height by the scale without generating distortion on the images. The default value is 1 ( one ).

#### mapW & mapH <a href="#h.ouj04otve82r" id="h.ouj04otve82r"></a>

This is the Width and Height of your entire city measured on tiles. So if your tiles are 32x32 and the city is 10x10 with a scale of 2. (tileW \* mapW) \* scale || ( 32 \* 10 ) \* 2 = 640 your canvas size will be 640 px on width.

#### Zlevels <a href="#h.gvm3xo6xsr5q" id="h.gvm3xo6xsr5q"></a>

This is the maximum amount of layers that your project supports.

#### map <a href="#h.rs6vwv9rw0tj" id="h.rs6vwv9rw0tj"></a>

Your city "structure" is saved in code as an array, it's read from left to right and top to bottom.

The example above is indented in such a way that it represents how the map actually looks when drawn on screen, but instead of graphics it has the ID of each tile.

The program automatically cuts each row by the mapW.

None of the array values should be set to a value that is missing on the tileTypes list, it is recommended that you have at least one "blank" tile in your tileset for a situation where you want to leave empty spaces. The code will take the tile with id 0 (zero) by default, ~~but this can be changed if yours is on a different spot (WIP)~~.

#### zContent <a href="#h.hn263jfpgtf8" id="h.hn263jfpgtf8"></a>

Here is where the "layers" or zIndex contents are saved.

"zContent":

{

<mark style="color:red;">"1"</mark> : <mark style="color:green;">{"36":75}</mark>,

<mark style="color:red;">"2"</mark> : <mark style="color:green;">{"45":74}</mark>,

<mark style="color:red;">"3"</mark> : <mark style="color:green;">{"65":79}</mark>,

<mark style="color:yellow;">"4" : { "22":67 , "31":67 , "65":90 }</mark>

}

This works with the same logic as the map array, each variable represents a position iside the tileset coords, and the content is the actual tile image.

As you can see, inside the "zContent" section you have four lines, that start with a number inside quotes <mark style="color:red;">(Colored red)</mark> each of this represent their entire layer, you may notice that there is no 0 (zero) layer, thats because its not saved here, but in the previous section [map](#h.rs6vwv9rw0tj).

To the right you have some brackets (colored green), with multiple values inside, the first one, inside quotes is the tile position on the map, the second is the tile id image. In layer 4<mark style="color:yellow;">(Colored yellow)</mark> you can see there multiple tiles, on the positions 22,31 and 65, each layer can have as many tiles as the map can hold, in this case 10 x 10 ( mapW \* mapH ).

#### events <a href="#h.tl24cu4hdwhg" id="h.tl24cu4hdwhg"></a>

"events":

{

&#x20;<mark style="color:red;">"goToPage"</mark>:\
\[&#x20;

&#x20; <mark style="color:purple;">{"pos":0, "args":\["https://cranile.neocities.org/",true], "name":"Check out my Neo City" },</mark>\
&#x20; <mark style="color:purple;">{"pos":1,"args":\["https://cranile.wordpress.com/",true],"name":"Read my blog"},</mark> \
&#x20; <mark style="color:purple;">{"pos":22,"args":\["https://github.com/NicolasCrapanzano?tab=repositories",true],"name":"See my    git repos"},</mark> \
&#x20; <mark style="color:purple;">{"pos":3,"args":\["https://cranile.itch.io/",true],"name":"Check my itchio"}</mark> \
],&#x20;

<mark style="color:red;">"changeMap"</mark>: \
\[

&#x20;<mark style="color:purple;">{"pos":5,"args":\["./maps/New.json"],"name":"Go to the castle"}</mark>

]

}

**¿How do events work?**

An event is an action that you can save and execute inside the city, all of the event instances are saved in the project.json file under the events section, these are just the parameters for the events, not the code that runs the actions itself.

**¿Where are events saved?**

Events are actually just functions saved under the utilities.js file.

_(For more info. about how events work_ [_see_](../how-to-use#h.g6sl3dxglls1)_)_

You can only save events that are already available in the code, there needs to be a working function and a reference save on the eventTypes variable on the game.js file.

The event section is subdivided on event Types <mark style="color:red;">(Colored red)</mark> ; these names are the ones saved on the eventTypes variable.

Inside each of this types the event parameters are saved.

{ <mark style="color:orange;">"pos" : 0</mark>, <mark style="color:yellow;">"args" : \["https://cranile.neocities.org/",true]</mark>, <mark style="color:green;">"name" : "Check out my Neo City"</mark> },

Let's take a look at this event of the type goToPage for example, it can be divided in three parts, the position <mark style="color:orange;">(Colored orange)</mark>, this tells us that this particular event is located on the position 0, which is the very top left tile. Next inside an array we have two values <mark style="color:yellow;">(Colored yellow)</mark>, those are the parameters for that particular event, and lastly <mark style="color:green;">(Colored green)</mark>, the name of the event, this is used for the developer to know what the event is, ~~and can also be displayed as flavor text on the screen WIP~~.

## Code modification <a href="#h.us4jamucvdr" id="h.us4jamucvdr"></a>

### game.js <a href="#h.a9rinwfk0dxr" id="h.a9rinwfk0dxr"></a>

WIP

### picker.js <a href="#h.aw9rkdeon08" id="h.aw9rkdeon08"></a>

WIP

### index.html <a href="#h.kfrklfpfnq6b" id="h.kfrklfpfnq6b"></a>

WIP
