explodorama / commit
Add LICENSE, CHANGELOG and CONTRIBUTING
CHANGELOG.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE | 29 +++++++++++++++++++++++ README.md | 7 +++++- 4 files changed, 174 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6658cf6 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,72 @@ +# Changelog + +All notable changes to Explodorama are written down here. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). There has been no tagged release +yet, so everything so far is under **Unreleased**. + +A saved run is only resumed if it was made with the same version of the rules +(`SIM_VERSION` in [src/sim/record.ts](src/sim/record.ts)). When a change below bumps it, a run +saved before the change is dropped and the next visit starts a new run. + +## [Unreleased] + +### Added + +- **The board and the turn.** A 31 × 13 board with a stone outer wall, indestructible pillars + (their colour changes from level to level) and wooden crates; the camera follows the player + sideways. Each turn the player picks one action, then enemies step, bombs count down and + explode, and enemies show their next step. +- **Bombs** whose fuses count down with the player's moves, chain reactions, and a danger + preview that shows what will burn before an action is committed. Flame lingers for one turn. +- **Lives.** A death restarts the level with the same layout; with no lives left the run ends + and shows its seed. +- **Seeded levels.** Every random choice comes from the seed, and every run is recorded as its + seed plus its actions, so it replays exactly. +- **The exit door**, hidden under a crate and locked until every enemy is dead. Flaming it lets + out 3 enemies. A par turn count, with a 5-coin bonus for beating it. +- **Enemies:** Blob, Seeker and Drifter. Each commits to 3 moves ahead, shown as a fading column + of arrows. Coin and charge drops; drops never stack on one tile. +- **Action charges:** Shield, Freeze, Diagonal, Pierce, Power, Line and Decoy, with count + badges on their icons. +- **Power-ups**, one per level under a crate: Bomb+, Fire+, Fuse+, Run, Detonator, Wall Pass, + Bomb Pass, Flame Pass, Star, Heart, Coin bag, Kick, Throw and Teleport. A death loses the + passes, the Detonator and a Star. +- **The 50-level run** with a victory banner at the end. +- **Mid-run saving** after every action, in the browser. URLs with test parameters (`?seed`, + `?level`, `?charges`, `?small`, `?dev`, `?god`, `?crumble`) never load or overwrite the save. +- **Touch controls:** tap a neighbouring tile to step, press and hold one to bomb it, tap the + player to wait. +- **Auto-move:** tap a far tile to set a flag; Go (or tapping the flag) takes one safe step + along the way. Once every enemy is gone, the player walks there alone, one step a second. +- **A menu** (top right, or Esc) with the level, the seed, New run, the Kenney credit and an + almanac of power-ups, charges and enemies. +- **"What is that?"** — the **?** button (or the ? key), then a tap on anything, explains it; + things you can walk to offer **Walk there**. +- **New run options:** a Normal board (31 × 13, 50 levels) or a Small one (9 × 11, 20 levels), + plus Developer, God and Crumbling crates modes. +- **Animation** for the player, enemies, bombs, crates, flame, drops, power-ups, top-bar numbers + and dialogs. +- **Art** from Kenney's New Platformer Pack, UI Pack, UI Pack: RPG Expansion, Game Icons and + Board Game Icons (all CC0). Power-ups that improve something get a green modifier badge. +- **Deployment** to GitLab Pages on every push to the default branch, after the tests and the + build pass. + +### Changed + +- The placeholder shapes were replaced with Kenney sprites. +- The action bar is now only Move, Bomb and Wait, plus Shield, Freeze and Decoy while you hold + them. Upgrades make Move and Bomb do more instead of adding buttons. Picking an action shows a + strip that explains what it does right now. +- Kick, Throw and Teleport became power-ups kept for the whole run (they were charges). +- Freeze now holds enemies for this turn and 3 more. +- The Skates power-up is now called Run. +- The outer wall is drawn as a bordered stone frame. + +### Removed + +- The Fuse +1 / −1 charges. + +### Fixed + +- Moving off the auto-move path now clears the flag. +- Thin light seams no longer run through the stone outer wall. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f24274b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing to Explodorama + +Thank you for wanting to help! Bug reports, playtest notes and merge requests are all welcome +on [GitLab](https://gitlab.com/PavelSafronov/explodorama). + +## Reporting a bug + +Open an issue and include: + +- what you did, what you expected, and what happened instead; +- the **seed** (shown in the menu, and on the game-over and victory banners) and the level — + with the seed, the same board can be replayed with `?seed=<number>`; +- the device and browser, and a screenshot if you can. + +## Getting set up + +You need Node.js 22 (the version CI uses). + +```sh +npm install +npm run dev # http://localhost:5173, plus a QR code for a phone on the same Wi-Fi +npm test # Vitest +npm run build # type-check and build into dist/ +npm run screenshots # build, then photograph the game into docs/screenshots/ (Playwright) +``` + +The URL parameters listed in the README (`?seed`, `?level`, `?charges`, `?small`, `?dev`, +`?god`, `?crumble`) are the quickest way to reach the situation you are working on. + +## Before you open a merge request + +1. **`npm test` and `npm run build` both pass.** CI runs exactly these two, and Pages only + deploys when they pass. +2. **Rule changes come with tests.** Game rules live in `src/sim/` and are tested in `test/`. +3. **The docs are up to date.** A change a player can notice belongs in the README and in + [CHANGELOG.md](CHANGELOG.md) under *Unreleased*. A change to the design or to a recorded + decision also updates [PLAN.md](PLAN.md) or [decisions.md](decisions.md). +4. **Screenshots are refreshed** with `npm run screenshots` if the change alters how the game + looks. + +## How the code is laid out + +The README's *How it's built* section describes the layout. The rules that matter most: + +- **`src/sim/` stays pure and deterministic.** No rendering, no DOM, no `Math.random()`: + every random choice comes from the seed, so a run's seed plus its actions always replay to + the same state. +- **Bump `SIM_VERSION`** in [src/sim/record.ts](src/sim/record.ts) whenever a rule change + would make an old record replay differently. Saved runs from another version are dropped + rather than replayed wrongly. Note the bump in the changelog. +- **Rendering** (`src/render/`) and the **HTML UI** (`src/ui/`) only read the state and the + events that `step()` returns; they never change the rules. + +## Art and other assets + +- The game uses art from [Kenney](https://www.kenney.nl) packs only, under CC0. Please ask in + an issue before bringing in a different pack or another artist's work. +- Copy files **unchanged and under the pack's own file names** into the matching + `assets/kenney*/` folder, and keep the pack's licence file next to them. +- Icons with a modifier badge are made from those files by + [tools/compose-icons.sh](tools/compose-icons.sh) (needs ImageMagick 7) into + `assets/composed/`, not drawn by hand. The results are committed. + +## Licence + +By contributing, you agree that your code is released under the project's +[MIT licence](LICENSE). Kenney's art is not covered by it; it stays under CC0. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..92e26f9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +MIT License + +Copyright (c) 2026 Pavel Safronov + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +The art in assets/ is by Kenney (https://www.kenney.nl) and is not covered by +the licence above. It is released under CC0 1.0 (public domain). The folders +whose names start with "kenney" hold the packs' files unchanged, each with its +pack's own licence file; assets/composed/ holds icons built from those files by +tools/compose-icons.sh. See the Attribution section of README.md. diff --git a/README.md b/README.md index 16a412e..5eba2f4 100644 --- a/README.md +++ b/README.md @@ -285,4 +285,9 @@ from the same pack. ## Licence -MIT. +MIT — see [LICENSE](LICENSE). Kenney's art is not covered by it (see Attribution above). + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). What has changed so far is in +[CHANGELOG.md](CHANGELOG.md).