Upload new map and wam associate

Author: gparant

.github/workflows/build-and-deploy.yml

@@ -1,40 +1,93 @@
-name: Optimize map and deploy
+name: Build and deploy
 
-on: [ push ]
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch: # allow manual execution
 
 permissions:
   contents: write
   pages: write
   actions: write
 
 jobs:
-  deploy:
+  build-and-deploy:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout
+      - name: Checkout Repository
         uses: actions/checkout@v3
 
-      - uses: actions/setup-node@v3
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
         with:
-          node-version: '16.x'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "18.x"
+          registry-url: "https://registry.npmjs.org"
 
-      - name: "Install dependencies"
+      - name: Install Dependencies
         run: npm install
 
-      - name: "Build scripts"
+      - name: Build project
         run: npm run build
 
-      - name: Deploy
+      - name: Extract UPLOAD_MODE from .env
+        run: |
+          UPLOAD_MODE=$(grep '^[^#]*UPLOAD_MODE' .env | cut -d '=' -f2)
+          if [ -z "$UPLOAD_MODE" ]; then
+            echo "Error: UPLOAD_MODE is not set in .env."
+            exit 1
+          fi
+          echo "UPLOAD_MODE=$UPLOAD_MODE" >> $GITHUB_ENV
+
+      - name: Set up Environment Variables
+        if: ${{ env.UPLOAD_MODE == 'MAP_STORAGE' }}
+        run: |
+          # MAP_STORAGE_API_KEY must always come from GitHub Secrets in CI
+          if [ -z "${{ secrets.MAP_STORAGE_API_KEY }}" ]; then
+            echo "Error: MAP_STORAGE_API_KEY is not set in GitHub Secrets."
+            exit 1
+          fi
+          echo "MAP_STORAGE_API_KEY=${{ secrets.MAP_STORAGE_API_KEY }}" >> $GITHUB_ENV
+
+          # MAP_STORAGE_URL can fall back to .env if not in GitHub Secrets
+          if [ -n "${{ secrets.MAP_STORAGE_URL }}" ]; then
+            echo "MAP_STORAGE_URL=${{ secrets.MAP_STORAGE_URL }}" >> $GITHUB_ENV
+          else
+            MAP_STORAGE_URL=$(grep '^[^#]*MAP_STORAGE_URL' .env | cut -d '=' -f2)
+            if [ -z "$MAP_STORAGE_URL" ]; then
+              echo "Error: MAP_STORAGE_URL is not set in GitHub Secrets or .env."
+              exit 1
+            fi
+            echo "MAP_STORAGE_URL=$MAP_STORAGE_URL" >> $GITHUB_ENV
+          fi
+
+          # UPLOAD_DIRECTORY can fall back to .env if not in GitHub Secrets, and to an arbitrary value if not in .env
+          if [ -n "${{ secrets.UPLOAD_DIRECTORY }}" ]; then
+            echo "UPLOAD_DIRECTORY=${{ secrets.UPLOAD_DIRECTORY }}" >> $GITHUB_ENV
+          else
+            UPLOAD_DIRECTORY=$(grep '^[^#]*UPLOAD_DIRECTORY' .env | cut -d '=' -f2)
+            if [ -n "$UPLOAD_DIRECTORY" ]; then
+              echo "UPLOAD_DIRECTORY=$UPLOAD_DIRECTORY" >> $GITHUB_ENV
+            else
+              USERNAME=${{ github.repository_owner }}
+              REPO=${{ github.event.repository.name }}
+              UPLOAD_DIRECTORY="${USERNAME}-${REPO}"
+              echo "UPLOAD_DIRECTORY=$UPLOAD_DIRECTORY" >> $GITHUB_ENV
+              echo "Warning: UPLOAD_DIRECTORY was not found; set to $UPLOAD_DIRECTORY."
+            fi
+          fi
+
+      - name: Deploy using WA Map Storage
+        if: ${{ env.UPLOAD_MODE == 'MAP_STORAGE' }}
+        run: npm run upload-only
+
+      - name: Deploy using Github Pages
+        if: ${{ env.UPLOAD_MODE == 'GH_PAGES' }}
         uses: JamesIves/github-pages-deploy-action@releases/v3
-        if: github.ref == 'refs/heads/master'
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          BRANCH: gh-pages # The branch the action should deploy to.
-          FOLDER: dist/ # The folder the action should deploy.
+          BRANCH: gh-pages
+          FOLDER: dist/
           BASE_BRANCH: master
 
-      - name: Bash2
-        run: |
-          ls -al

README.md

@@ -1,55 +1,94 @@
-# WorkAdventure Map Starter Kit
+# 🗺️ WorkAdventure Map Starter Kit
 
-![map](./map.png)
+<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)
 
-This is a starter kit to help you build your own map for [WorkAdventure](https://workadventu.re).
+![office map thumbnail](./office.png)
 
-To understand how to use this starter kit, follow the tutorial at [https://workadventu.re/map-building](https://workadventu.re/map-building).
+🗺️ This is a starter kit to help you build your own map for [WorkAdventure](https://workadventu.re).
 
-## Structure
-* *public*: Static files like PDFs or audio files
-* *src*: Scripts files
-* *tilesets*: All tilesets
-* *map.tmj*: Map file
-* *map.png*: The map thumbnail displayed on the in-game map information
+📚 To understand how to use this starter kit, follow [our tutorial](https://docs.workadventu.re/map-building/tiled-editor/).
 
-If you want to use more than one map file, just add the new map file on root or in a folder.
+👨🏻‍🔧 If you have any questions, feel free to ask in the [WorkAdventure office](https://play.staging.workadventu.re/@/tcm/workadventure/wa-village).
 
-we recommend using 500x500 images for the map thumbnails.
+## 🚀 Upload your map
 
-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*.
+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.
 
-## Requirements
+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.
 
-Node.js version >=16
+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.
 
-## Installation
+## 🗂️ Structure
 
-With npm installed (comes with [node](https://nodejs.org/en/)), run the following commands into a terminal in the root directory of this project:
+We recommend following this file structure:
 
-```shell
+- *`public/`*: Static files like PDFs or audio files
+- *`src/`*: Script files or design source files
+- *`tilesets/`*: All PNG tilesets
+
+> [!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
+
+- Node.js version >= 18
+
+## Installation and testing
+
+## 🛠️ 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:
+
+```bash
 npm install
+```
+
+Then, you can test your map by running:
+
+```bash
 npm run dev
 ```
 
-## Test production map
+You can also test the optimized map as it will be in production by running:
 
-You can test the optimized map as it will be in production:
-```sh
+```bash
 npm run build
 npm run prod
 ```
 
-## Licenses
+You can manually [upload your map to the WA Map Storage]([WA Map Storage](https://github.com/workadventure/upload-maps)) by running:
+
+```bash
+npm run upload
+```
+
+The three important variables that control the upload feature are:
+
+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 documentation](https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted) to learn more about the upload feature.
+
+## 📜 Licenses
 
 This project contains multiple licenses as follows:
 
 * [Code license](./LICENSE.code) *(all files except those for other licenses)*
-* [Map license](./LICENSE.map) *(`map.tmj` and the map visual as well)*
-* [Assets license](./LICENSE.assets) *(the files inside the `src/assets/` folder)*
+* [Map license](./LICENSE.map) *(`office.tmj` and the map visual as well)*
+* [Assets license](./LICENSE.assets) *(the files inside the `tilesets/` folder)*
+
+> [!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*.
 
-### About third party assets
+## ❓ Need Help
 
-If you add third party assets in your map, do not forget to:
-1. Credit the author and license with the "tilesetCopyright" property present in the properties of each tilesets in the `map.tmj` file
-2. Add the license text in LICENSE.assets
+If you have any questions or need further assistance, don't hesitate to ask either by [email](mailto:hello@workadventu.re) or [Discord](https://discord.gg/G6Xh9ZM9aR)!