Skip to content

Commit

Permalink
Enhance README
Browse files Browse the repository at this point in the history
  • Loading branch information
@ValdoTR
ValdoTR committed Oct 9, 2024
1 parent 72334f5 commit 9477a7f
Showing 1 changed file with 44 additions and 36 deletions.
80 changes: 44 additions & 36 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,86 +1,94 @@
# WorkAdventure Map Starter Kit
# 🗺️ WorkAdventure Map Starter Kit

<a href="https://discord.gg/G6Xh9ZM9aR" target="blank"><img src="https://img.shields.io/discord/821338762134290432.svg?style=flat&label=Join%20Community&color=7289DA" alt="Join Community Badge"/></a>
<a href="https://x.com/workadventure_" target="blank"><img src="https://img.shields.io/twitter/follow/workadventure_.svg?style=social" /></a>
![visitors](https://vbr.nathanchung.dev/badge?page_id=workadventure.map-starter-kit&color=00cf00)

![office map thumbnail](./office.png)

This is a starter kit to help you build your own map for [WorkAdventure](https://workadventu.re).
🗺️ This is a starter kit to help you build your own map for [WorkAdventure](https://workadventu.re).

To understand how to use this starter kit, follow the tutorial at [https://docs.workadventu.re/map-building/tiled-editor/](https://docs.workadventu.re/map-building/tiled-editor/).
📚 To understand how to use this starter kit, follow [our tutorial](https://docs.workadventu.re/map-building/tiled-editor/).

If you have any questions, feel free to ask in [WorkAdventure office](https://play.staging.workadventu.re/@/tcm/workadventure/wa-village).
👨🏻‍🔧 If you have any questions, feel free to ask in the [WorkAdventure office](https://play.staging.workadventu.re/@/tcm/workadventure/wa-village).

## Upload your map
## 🚀 Upload your map

In the .env file you can set your upload strategy to `GH_PAGES` (default) or `MAP_STORAGE`. Simply comment the option you don't want to use.
In the `.env` file, you can set your upload strategy to `GH_PAGES` (default) or `MAP_STORAGE`. Simply comment out the option you don't want to use.

Uploading a map using [Github Pages](https://docs.github.com/pages) will host your project in the Github servers and it's the most straight forward way to add new maps to your world.
Uploading a map using [GitHub Pages](https://docs.github.com/pages) will host your project on GitHub servers, and it's the most straightforward way to add new maps to your world.

Uploading a map using the [WA map storage](https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted) will host your project in the WA servers. It's a bit more difficult to setup but it comes with great advantages like being able to have private repositories.
Uploading a map using the [WA map storage](https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted) will host your project on WA servers. It's a bit more difficult to set up, but it comes with great advantages, like being able to have private repositories.

## Structure
## 🗂️ Structure

We recommend following this file structure:

* *public/*: Static files like PDFs or audio files
* *src/*: Scripts files or design source files
* *tilesets/*: All PNG tilesets
- *`public/`*: Static files like PDFs or audio files
- *`src/`*: Script files or design source files
- *`tilesets/`*: All PNG tilesets

> **Pro tips**
> If you want to use more than one map file, just add the new map file in the root folder (we recommend creating a copy of *office.tmj* and editing it, in order to avoid any mistakes).
> We recommend using 512x512 images for the map thumbnails.
> If you are going to create custom websites to embed in the map, please reference the HTML files in the `input` option in *vite.config.js*.
> [!TIP]
> - If you want to use more than one map file, just add the new map file in the root folder (we recommend creating a copy of *office.tmj* and editing it to avoid any mistakes).
> - We recommend using **512x512** images for the map thumbnails.
> - If you are going to create custom websites to embed in the map, please reference the HTML files in the `input` option in *vite.config.js*.
## Requirements
## 📜 Requirements

Node.js version >=17
- Node.js version >= 18

## Installation and testing

With npm installed (comes with [node](https://nodejs.org/en/)), run the following commands into a terminal in the root directory of the project:
## 🛠️ Installation and Testing

With npm installed (which comes with [Node.js](https://nodejs.org/en/)), run the following command in the root directory of the project:

```shell
```bash
npm install
```

Then, you can test your map by running:

```sh
```bash
npm run dev
```

You can also test the optimized map as it will be in production by running:

```sh
```bash
npm run build
npm run prod
```

You can manually upload your map to the map storage by running:
You can manually [upload your map to the WA Map Storage]([WA Map Storage](https://github.com/workadventure/upload-maps)) by running:

```sh
```bash
npm run upload
```

The 3 important variables that control the upload feature are:
The three important variables that control the upload feature are:

1. `MAP_STORAGE_API_KEY` *(local: created in .env.secret by the upload command / CI: to be added as a Github secret)*
2. `MAP_STORAGE_URL` *(local: created in .env by the upload command / CI: to be added as a Github secret optionally)*
1. `MAP_STORAGE_URL` *(local: created in .env by the upload command / CI: to be added as a Github secret optionally)*
2. `MAP_STORAGE_API_KEY` *(local: created in .env.secret by the upload command / CI: to be added as a Github secret)*
3. `UPLOAD_DIRECTORY` *(local: created in .env by the upload command / CI: to be added as a Github secret optionally)*

Read [the doc](https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted) to know more about the upload feature.
Read [the documentation](https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted) to learn more about the upload feature.

## Licenses
## 📜 Licenses

This project contains multiple licenses as follows:

* [Code license](./LICENSE.code) *(all files except those for other licenses)*
* [Map license](./LICENSE.map) *(`office.tmj` and the map visual as well)*
* [Assets license](./LICENSE.assets) *(the files inside the `src/assets/` folder)*
* [Assets license](./LICENSE.assets) *(the files inside the `tilesets/` folder)*

### About third party assets
> [!IMPORTANT]
> If you add third party assets in your map, do not forget to:
> 1. Credit the author and license of a tileset with the "tilesetCopyright" property by etiding the tileset in Tiled.
> 2. Add the tileset license text in *LICENSE.assets*.
> 3. Credit the author and license of a map with the "mapCopyright" property in the custom properties of the map.
> 4. Add the map license text in *LICENSE.map*.
If you add third party assets in your map, do not forget to:
## ❓ Need Help

1. Credit the author and license of a tileset with the "tilesetCopyright" property by etiding the tileset in Tiled.
2. Add the tileset license text in *LICENSE.assets*.
3. Credit the author and license of a map with the "mapCopyright" property in the custom properties of the map.
4. Add the map license text in *LICENSE.map*.
If you have any questions or need further assistance, don't hesitate to ask either by [email](mailto:[email protected]) or [Discord](https://discord.gg/G6Xh9ZM9aR)!

0 comments on commit 9477a7f

Please sign in to comment.