129 lines
7.2 KiB
Markdown
129 lines
7.2 KiB
Markdown
{.section-title.accent.text-primary}
|
|
# Create your map
|
|
|
|
## Tools you will need
|
|
|
|
In order to build your own map for WorkAdventure, you need:
|
|
|
|
* the [Tiled editor](https://www.mapeditor.org/) software
|
|
* "tiles" (i.e. images) to create your map
|
|
* a web-server to serve your map
|
|
|
|
WorkAdventure comes with a "map starter kit" that we recommend using to start designing your map quickly. It contains **a good default tileset** for building an office and it proposes to **use Github static pages as a web-server** which is both free and performant. It also comes with a local webserver for testing purpose and with Typescript support (if you are looking to use the [map scripting API]({{url('/map-building/scripting')}}).
|
|
|
|
{.alert.alert-info}
|
|
If you are looking to host your maps on your own webserver, be sure to read the [Self-hosting your map](hosting.md) guide.
|
|
|
|
[Building your map - Create your map](https://www.youtube.com/watch?v=lu1IZgBJJD4)
|
|
|
|
## Getting started
|
|
|
|
Start by [creating a GitHub account](https://github.com/join) if you don't already have one.
|
|
|
|
Then, go to the [Github map starter kit repository page](https://github.com/thecodingmachine/workadventure-map-starter-kit) and click the **"Use this template"** button.
|
|
|
|
<figure class="figure my-5">
|
|
<img src="images/use_this_template.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
|
|
<figcaption class="figure-caption">The "Use this template" button</figcaption>
|
|
</figure>
|
|
|
|
You will be prompted to enter a repository name for your map.
|
|
|
|
<figure class="figure my-5">
|
|
<img src="images/create_repo.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
|
|
<figcaption class="figure-caption">The "create a new repository" page</figcaption>
|
|
</figure>
|
|
|
|
**Make sure to check the "Include all branches" checkbox, otherwise the Github Pages deployment process will not be setup automatically.**
|
|
|
|
If you miss that step, don't worry, you can always fix that by clicking on the **Settings tab** of your repository and scroll down to the **GitHub Pages** section. Then select the **gh-pages** branch. It might already be selected, but please be sure to click on it nonetheless (otherwise GitHub will not enable GitHub pages).
|
|
|
|
{.alert.alert-info}
|
|
If you only see a "master" branch and if the **gh-pages** branch does not appear here, simply wait a few minutes and refresh your page. When you created the project, Github Actions triggered a job that is in charge of creating the **gh-pages** branch. Maybe the job is not finished yet.
|
|
|
|
<figure class="figure my-5">
|
|
<img src="images/github_pages.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
|
|
<figcaption class="figure-caption">The GitHub pages configuration section</figcaption>
|
|
</figure>
|
|
|
|
Wait a few minutes... Github will deploy a new website with the content of the repository. The address of the website is visible in the "GitHub Pages" section.
|
|
|
|
<figure class="figure my-5">
|
|
<img src="images/website_address.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
|
|
<figcaption class="figure-caption">Your website is ready!</figcaption>
|
|
</figure>
|
|
|
|
Click on the link. You should be redirected directly to WorkAdventure, on your map!
|
|
|
|
## Customizing your map
|
|
|
|
Your map is now up and online, but this is still the demo map from the starter kit. You need to customize it.
|
|
|
|
### Cloning the map
|
|
|
|
Start by cloning the map. If you are used to Git and GitHub, simply clone the map to your computer using your preferred tool and [jump to the next chapter](#loading-the-map-in-tiled).
|
|
|
|
If you are new to Git, cloning the map means downloading the map to your computer. To do this, you will need Git, or a Git compatible tool. Our advice is to use [GitHub Desktop](https://desktop.github.com/). We recommend you take some time mastering the notion of pull / commit / push as this will make uploading your maps really easier.
|
|
|
|
As an (easier) alternative, you can simply use the "Export" button to download the code of the map in a big Zip file. When you want to upload your work again, you will simply drag'n'drop your files in the GitHub website.
|
|
|
|
### Loading the map in Tiled
|
|
|
|
The sample map is in the file `map.json`. You can load this file in [Tiled](https://www.mapeditor.org/).
|
|
|
|
Now, it's up to you to edit the map and write your own map.
|
|
|
|
Some resources regarding Tiled:
|
|
|
|
* [Tiled documentation](https://doc.mapeditor.org/en/stable/manual/introduction/)
|
|
* [Tiled video tutorials](https://www.gamefromscratch.com/post/2015/10/14/Tiled-Map-Editor-Tutorial-Series.aspx)
|
|
|
|
### Testing your map locally
|
|
|
|
In order to test your map, you need a webserver to host your map. The "map starter kit" comes with a local webserver that you can use to test your map.
|
|
|
|
In order to start the webserver, you will need [Node.JS](https://nodejs.org/en/). When it is downloaded, open your command line and from the directory of the map, run this command:
|
|
|
|
$ npm install
|
|
|
|
This will install the local webserver.
|
|
|
|
$ npm run start
|
|
|
|
This command will start the webserver and open the welcome page. You should see a page looking like this:
|
|
|
|
<figure class="figure my-5">
|
|
<img src="images/start_kit_start_screen.png" class="figure-img img-fluid rounded" alt="" style="width: 70%" />
|
|
<figcaption class="figure-caption">The welcome page of the "map start kit"</figcaption>
|
|
</figure>
|
|
|
|
From here, you simply need to click the "Test this map" button to test your map in WorkAdventure.
|
|
|
|
{.alert.alert-warning}
|
|
The local web server can only be used to test your map locally. In particular, the link will only work on your computer. You cannot share it with other people.
|
|
|
|
### Pushing the map
|
|
|
|
When your changes are ready, you need to "commit" and "push" (i.e. "upload") the changes back to GitHub. Just wait a few minutes, and your map will be propagated automatically to the GitHub pages web-server.
|
|
|
|
## Testing your map
|
|
|
|
To test your map, you need to find its URL. There are 2 kinds of URLs in WorkAdventure:
|
|
|
|
* Test URLs are in the form `https://play.workadventu.re/_/[instance]/[server]/[path to map]`
|
|
* Registered URLs are in the form `https://play.workadventu.re/@/[organization]/[world]/[map]`
|
|
|
|
Assuming your JSON map is hosted at "`https://myuser.github.io/myrepo/map.json`", then you can browse your map at "`https://play.workadventu.re/_/global/myuser.github.io/myrepo/map.json`". Here, "global" is a name of an "instance" of your map. You can put anything instead of "global" here. People on the same instance of the map can see each others. If 2 users use 2 different instances, they are on the same map, but in 2 parallel universes. They cannot see each other.
|
|
|
|
This will connect you to a "public" instance. Anyone can come and connect to a public instance. If you want to manage invitations, or to perform some moderation, you will need to create a "private" instance. Private instances are available in "pro" accounts.
|
|
|
|
<div class="card">
|
|
<div class="card-body">
|
|
<h3 id="need-some-help">Need some help?</h3>
|
|
<p>WorkAdventure is a constantly evolving project and there is plenty of room for improvement regarding map editing.</p>
|
|
<p>If you are facing any troubles, do not hesitate to open an "issue" in the
|
|
<a href="https://github.com/thecodingmachine/workadventure/issues" target="_blank">GitHub WorkAdventure account</a>.
|
|
</p>
|
|
</div>
|
|
</div>
|