web reimplementation of Sigmar's Garden https://bits.ondrovo.com/sigmar/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
sigmar/README.md

128 lines
5.1 KiB

Sigmar's Garden
===============
This project implements the Sigmar's Garden mini-game from Zachronics' [Opus Magnum][om]
in HTML5, JavaScript, and SVG.
**Play on-line at [https://bits.ondrovo.com/sigmar](https://bits.ondrovo.com/sigmar).**
The game is fully client-side and static, you can simply download it and open locally as well.
Game rules
----------
There are 55 marbles on the board, composed as follows:
- 8 pieces of the four Elements: Air, Water, Fire, and Earth (total of 32)
- 4 pieces of Salt
- 5 metals and 1 Gold
- 5 pieces of Mercury
- 4 pairs of Vitae and Mors
Your goal is to clear the board.
- Vitae reacts only with Mors
- Elements react with the same element kind, or with Salt
- Salt reacts with Elements or with itself
- Metals react with Mercury, but they unlock one by one, from the most common Lead to Gold.
- Gold is removed by itself as the last metal
The metals sequence is as follows:
1. Lead + Mercury
2. Tin + Mercury
3. Iron + Mercury
4. Copper + Mercury
5. Silver + Mercury
6. Gold
Here is a diagram from the original game *(hosted on [Steam Community][ruleslink])*
![Rules sheet][rulespic]
User Interface Explanation
--------------------------
The user interface contains a few buttons and toggles:
- *Randomize* - start a new game with a random shape and marble placement
- *Try Again* - reset the current game to its initial arrangement
- *Undo* - reverts one game action (reaction of two marbles). There is no limit on how many
steps you can undo.
The bottom left corner contains settings:
- *Effects* - enable graphic effects that look pretty but perform poorly on mobile phones or
browsers without hardware acceleration.
- *Dim Blocked* - highlight marbles that can be played by dimming the others. This makes the game
much harder, but is more realistic.
- *Sloppy Gen* - allow sloppy board filling. Use if building the board takes too long on
your computer. May result in uglier and/or easier boards.
Settings
--------
The game saves its persistent settings in your browser's [localStorage][localStorage].
Settings can be manipulated through the GUI, through some GET parameters, and via JavaScript API
in dev tools. The function of interest is called `game.setCfg({key: value, ...})`.
Here's the settings object. Please refer to the source code, as this is internal API and may be extended
or changed without updating this reference. Search for `SettingsStorage`.
```
{
log: 'info', // default log level
allowTemplateAugmenting: false, // sloppy mode
retryTemplate: 30, // retry attempts within one template
attemptTemplates: 50, // number of templates to try on failure
svgEffects: false, // fancy mode
dimBlocked: true, // highlight active marbles
}
```
GET Arguments
-------------
The game can be parametrised by GET arguments you add to the URL.
This can be used for bookmarks or to share a particular board.
- `debug=1/0` - enable debug, or disable debug and trace logging levels
- `trace=1/0` - toggle trace logging level
- `log=level` - select logging level: trace, debug, info, warn, error
- `seed=123` - set random seed, must be numeric. Share the current board by copying the URL
- `rnd=1` - don't put the seed in URL, so you can randomize by pressing Refresh (F5)
- `template=star` - set board template (shape in which the marbles are arranged).
See the source code for a list of templates. The currently used template is also printed
to the debug console for convenience. Can be combined with 'rnd' or 'seed'.
Note that some templates are hard to fill, so the engine can give up and switch to
a different random template.
Algorithm Quirks
----------------
Every board must be solvable, otherwise it wouldn't be much of a game. Generating a valid board
turned out quite a bit more challenging than I thought. My algorithm is based in some heuristics
and good deal of luck.
To make things more fun, besides the marble matching rules, the board must be laid out in one of
several pre-defined shapes of exactly 55 tiles. The algorithm can sometimes get itself into a dead
end while placing marbles on the board. I experimented with backtracking, but the current version
simply retries the whole thing with a different random seed. There are configurable retry limits
as a failsafe. If the given template fails many consecutive times, the algorithm opts to switch to
a different template. Some templates are harder than others, and some random seeds just seem to
have a problem.
A workaround I added is called Sloppy Mode. When the algorithm can't place an marble, it may choose
to add a new tile to the template, trying to keep the overall shape as tidy as possible. This may
hurt game difficulty, but is generally much faster than retrying over and over.
If you're curious about the inner workings, open dev tools and enable debug logging with the `debug=1`
GET parameter.
[localStorage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
[rulespic]: https://steamuserimages-a.akamaihd.net/ugc/913534190478688278/601AEF665F446DF75AF787D8E102B255F3E905A1/
[ruleslink]: https://steamcommunity.com/sharedfiles/filedetails/?id=1243498813
[om]: http://www.zachtronics.com/opus-magnum/