diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5f584dc..b1c6a7e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -11,17 +11,9 @@ ## Your credit (optional) - - +- Name for the credits: - outlasttrialsstats.com profile URL: ## Checklist -- [ ] My name is listed in `meta.authors` of the map I worked on -- [ ] The exported files (`map.json`, and `elements.json`/`zones.json` if changed) come from the web editor (validation ran before export) -- [ ] All screenshots in this PR were captured by me in-game -- [ ] No extracted game assets (textures, sounds, models) are included +- [ ] The exported files (`map.json`, the trial files, and `elements.json`/`zones.json` if changed) come from the web editor (validation ran before export) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7daf01..f735e0e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,8 @@ All map content is plain JSON under `public/data/`. You build and fix maps in the web editor at [maps.outlasttrialsstats.com/editor](https://maps.outlasttrialsstats.com/editor), so there is nothing to install and no code to write. What you need is a free GitHub account and about five minutes. Nothing you -submit goes live directly; a maintainer reviews every change first. +submit goes live directly; a maintainer reviews every change first. Questions at any point? Ask in the +support channel on [our Discord](https://discord.outlasttrialsstats.com/). ## 1. Get a GitHub account @@ -16,22 +17,21 @@ maintainer either merges it or asks you a question. ## 2. Build your map in the editor Open the [editor](https://maps.outlasttrialsstats.com/editor) and either start a new map, load an existing -one to correct it, or import a `map.json` you worked on earlier. Your progress is saved in the browser +one to correct it, or import files you exported earlier. Your progress is saved in the browser automatically, so you can close the tab and continue later. -When you create a new map the start dialog asks for your name and puts it into `meta.authors`, which is -what the viewer shows in the map's Credits panel. If you are correcting someone else's map instead, just -write your name into the pull request and a maintainer will add you. +The start dialog of a new map asks for your name; filling it in is optional. Credits are handled in the +pull request later, a maintainer takes care of them (see the credits section below). ## 3. Export Click **Export**. Validation runs first, and if something is wrong (an icon pointing at a deleted element, a room without a shape, …) you get a list and the export stays blocked until it's clean. -The dialog then shows one row per file you changed, each with the exact path it belongs to in the -repository: `map.json` always, plus `elements.json` and `zones.json` if you touched the libraries. Every row -has a copy button that puts the JSON on your clipboard and a Download button. For the next step, copying is -the easier path. +The dialog then shows one row per file, each with the exact path it belongs to in the repository: +`map.json` and one file per trial always, plus `elements.json` and `zones.json` if you touched the +libraries. Every row has a copy button that puts the JSON on your clipboard and a Download button. For the +next step, copying is the easier path. ## 4. Put the file on GitHub @@ -47,15 +47,20 @@ For an existing file, which is the common case: (Ctrl+V). Replacing the entire content is correct, the export is the complete file. 4. Click **Commit changes…** and write one short line describing what you did, for example "Fix key position in Holding Cells". Leave the rest at its defaults and confirm. -5. GitHub now offers **Create pull request**. Click it. +5. GitHub now offers **Create pull request**. If this was your only file, click it and jump to step 5. -If you changed the libraries too, repeat this for `public/data/elements.json` and -`public/data/zones.json`. +Usually there is more than one file — at least a trial file, maybe the libraries. Those have to go on the +same branch, so don't create the pull request yet. Go to your copy at `github.com//maps`, +switch the branch dropdown (top left) from `main` to the branch GitHub just created (usually `patch-1`), +open the next file from the export dialog, click the pencil icon and paste and commit like before. When +all files are in, GitHub shows a **Compare & pull request** button on your copy — click that. For a brand-new map: - Create `map.json` via `https://github.com/OutlastTrialsStats/maps/new/main/public/data/maps/` and type - `/map.json` as the filename, then paste. + `/map.json` as the filename, then paste and commit. That creates your copy, same as above. +- Add the rest in your copy on that branch, via **Add file → Create new file**: each trial file as + `/trials/.json`, exactly as listed in the export dialog. - Set `"enabled": true` for your map in `public/data/maps/index.json`. All planned maps are already listed there and stay hidden on the start page until that flag is flipped. - Screenshots go to `public/data/maps//img/`. Those are images, so pasting doesn't work: use @@ -63,8 +68,8 @@ For a brand-new map: ## 5. Open the pull request -The form is pre-filled with a template asking what changed, which map and trials are affected, and where -the screenshots came from. Answer briefly, tick the checklist, submit. +The form is pre-filled with a template asking what changed and which map and trials are affected. Answer +briefly, tick the checklist, submit. Automatic checks validate your files against the schemas within a couple of minutes. If something is red, click the details, it names the file and the problem. Fix it by editing the file in your pull request and @@ -72,24 +77,23 @@ the checks re-run by themselves. A maintainer then reviews the content (does the the images yours?) and merges. Merged changes go live with the next release, which a maintainer publishes manually. -Stuck somewhere? Open an issue and say where. +Stuck somewhere or unsure about anything? Ask in the support channel on +[our Discord](https://discord.outlasttrialsstats.com/) — any time, no question is too small. Opening an +issue here works too. ## Credits and the Map Contributor badge -Your name in `meta.authors` shows up in the map's Credits panel in the viewer. +Credits are managed by the maintainers, you never edit the files for them yourself. Put your name and, if +you want to be linked, your outlasttrialsstats.com profile URL into the pull request — the template has +fields for both. Your name then shows up in the map's Credits panel in the viewer; with a profile URL you +also get your card on the start page (avatar, profile link, the maps you worked on) and the Map Contributor +badge on outlasttrialsstats.com. -If you want to be linked, add your outlasttrialsstats.com profile URL to the pull request, there is a field -in the template for it. A maintainer then adds you to `public/data/contributors.json`, which puts you on -the start page with avatar, profile link and the maps you worked on, and grants you the Map Contributor -badge on outlasttrialsstats.com. You never edit `contributors.json` yourself. +## Element icons -## Rules for images - -- Screenshots: jpg, png or webp, at most 500 KB each. Aim for under 300 KB. -- Element icons are referenced by file name only (e.g. `objectif_key`); host and `.webp` are added - automatically, the file must exist on `outlasttrialsstats.com/game-assets/`. No icon files are - stored in this repository. -- Never include extracted game assets such as textures, sounds or models. +Element icons are referenced by file name only (e.g. `objectif_key`); host and `.webp` are added +automatically, the file must exist on `outlasttrialsstats.com/game-assets/`. No icon files are stored in +this repository. ## Elements and zones are shared @@ -98,15 +102,3 @@ by all maps. You can create, edit and delete entries directly in the editor via the export dialog offers the changed files automatically. Because a rename or a colour change affects every map, these changes get a closer look in review. Deleting an entry is blocked while another map still uses it. - -## For developers - -Fork, branch, commit, push, open a pull request against `main`. Node.js ≥ 24 and pnpm (via `corepack enable`) -required. Before pushing: - -```bash -pnpm install --frozen-lockfile -pnpm validate:data # exactly what CI runs on your data -pnpm lint -pnpm typecheck -``` diff --git a/README.md b/README.md index 0f5df42..cab046d 100644 --- a/README.md +++ b/README.md @@ -12,27 +12,6 @@ The editor lets you draw rooms, place elements, set up floors and trials, and ex Map content goes through the [web editor](https://maps.outlasttrialsstats.com/editor) and a pull request, so you don't need a dev setup for it. [CONTRIBUTING.md](CONTRIBUTING.md) has the full walkthrough, the image rules and how the **Map Contributor** badge works. -## Stack - -Vue 3 + Vite + TypeScript (strict), Vue Router, Pinia, PrimeVue 4 with a dark custom theme, SVG rendering with d3-zoom/d3-selection for pan and zoom, Ajv for JSON schema validation. There is no backend; the app is a static build hosted on GitHub Pages. - -## Development - -Requires Node.js ≥ 24. The package manager is pnpm; `corepack enable` picks up the version pinned in `package.json`. - -```bash -pnpm install -pnpm dev # dev server -pnpm build # static build into dist/ -pnpm preview # serve the production build locally -pnpm lint # ESLint -pnpm typecheck # vue-tsc -pnpm format # Prettier -pnpm validate:data # validate public/data against the JSON schemas -``` - -`pnpm lint` and `pnpm typecheck` have to pass before every pull request. CI also runs `validate:data`. - ## Project structure ``` @@ -46,10 +25,6 @@ scripts/ data validation used by CI `core/` never imports from `viewer/` or `editor/`, and those two never import from each other. -## Deployment - -The site is hosted on GitHub Pages under the custom domain `maps.outlasttrialsstats.com`. Deploys happen exclusively through the manual **Release** workflow (GitHub → Actions → Release → Run workflow), which bumps the version, updates the changelog, tags the release and publishes the fresh build to Pages. Nothing deploys automatically on merge. - ## Assets and attribution No game assets are stored in this repository. Element icons are referenced by file name on `outlasttrialsstats.com/game-assets/`, screenshots are captured and provided by contributors. The Outlast Trials is a trademark of Red Barrels. This is an unofficial, non-commercial fan project.