Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/eric200203/mahgen
๐๏ธ mahgen is a simple library that generates corresponding mahjong tile images for given sequences.
https://github.com/eric200203/mahgen
Last synced: about 2 months ago
JSON representation
๐๏ธ mahgen is a simple library that generates corresponding mahjong tile images for given sequences.
- Host: GitHub
- URL: https://github.com/eric200203/mahgen
- Owner: eric200203
- License: mit
- Created: 2022-11-04T06:59:14.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2023-03-08T05:53:26.000Z (over 1 year ago)
- Last Synced: 2024-07-25T04:44:03.283Z (2 months ago)
- Language: TypeScript
- Size: 6.38 MB
- Stars: 26
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.EN.md
- License: LICENSE
Awesome Lists containing this project
README
# Mahgen
English | [ไธญๆ](./README.md)
 |
 |
`mahgen` is a library that generates tile images for given Japanese mahjong patterns. `mahgen` is the abbreviation for ***Mah**jong* ***Gen**erator*.
---
## Features
`mahgen` supports various tile patterns, for example:
* Basic
* Chii
* Pon
* Kan
* Red Dora
* River Mode
You can visit [this website](https://mahgen.ericlab.cc) which uses `mahgen` to generate your own tile images online ans save them locally for other uses. For example, the tile images shown above were all generated by the site.
---
## Installation
**Use CDN**
You can use `mahgen` directly from a CDN via a script tag:
```html
```
You can also download this file and serve it yourself.
**Use NPM**
You can also use `npm` and execute:
```shell
npm install --save mahgen
```
---
## Usage
`mahgen` defines a new custom HTML tag called ``, including three custom attributes:
* `data-seq` is used to specify the pattern of the tile image generated by the tag.
* `data-show-err` is used to specify whether to show error messages when the sequence assigned by `data-seq` is invalid.
* `data-river-mode` is used to specify a river mode image.
Below is a simple example of using `mahgen`:
```html
Mahgen Example
Mahgen Example
```
You can check [this demo](https://jsfiddle.net/eric200203/qLghnmus) to see how it renders.
---
## API
`mahgen` also provides the following API:
```
Mahgen.render(seq: string, river: boolean): Promise;
```
Where:
* `seq` is a string used to describe the pattern(we will describe its syntax in the next section);
* `boolean` is a boolean used to indicate whether to generate a image for river mode.
* The return value is the base64 data of the generated image, which can be used in e.g. the `src` attribute of the `![]()
` tag in HTML.
Note that this is an asynchronous function, so you may need `await` keyword or `.then()` method to retrieve the result.
If the input sequence is not syntactically correct, the function throws an exception of type `ParseError`, which can be caught by `try...catch` statement or `.catch()` method. `ParseError` contains the following two members:
* `code`: an enumeration of type `ErrorCode`, indicating the reason of the error.
* `index`: a number indicating the position of the error(0-based).
In fact, custom tag `` is just a wrapper on top of this API.
---
## Syntax
### Numbered Suits(Pin, So, Man)
In Japanese mahjong, the digits `1-9` are usually used to describe the number of a tile, and the letters `p`, `s`, `m` to describe the suit `Pin`, `So`, `Man`. Therefore, the sequence `1m2m3m` would indicate the pattern *1-wan, 2-wan, 3-wan*, and `5p6p7p` *5-pin, 6-pin, 7-pin*.
> *1m2m3m*
>
> 
> *5p6p7p*
>
> 
In particular, we use the number `0` to denote a red dora, so `0p`, `0s`, `0m` denote *red 5-pin, red 5-so, red 5-wan*, respectively:
> *0pใ0sใ0m*
>
> 
For tiles of the same suit, You can omit all the letters except for the last one for simplicity. For example, you can simplify `1m2m3m` to `123m` and `5p6p7p` to `567p`. You can also write `1m23m` or `12m3m` for they all represent the pattern *1-wan, 2-wan, 3-wan*
### Honor Tiles(Wind Tiles, Dragon Tiles)
The letter `z` is used to represent the honor tiles in Japanese mahjong, with the order "Ton, Nan, Sha, Pei, Haku, Hatsu, Chun". So `1z 2z 3z 4z 5z 6z 7z` represent *Ton, Nan, Sha, Pei, Haku, Hatsu, Chun*, respectively.
> *1z 2z 3z 4z 5z 6z 7z*
>
> 
On this basis, we use `0z` to denote *the back of a tile*. For example, we can use `0z11p0z` to represent *a closed quad of 1-pin*:
> *0z11p0z*
>
> 
Finally, in order to make all the digits meaningful to the honor tiles, we use `8z` and `9z` for two tiles that do not appear in Japanese mahjong, but may be useful: *? and **.
> *8zใ9z*
>
> 
Finally, like the numbered suits, honor tiles can be simplified. For example, `3z3z3z` can be abbreviated to `333z`.
## Spaces
We use `|` to insert a space between two tiles, each space is 1/7 the width of a tile. For example:
> *123p|456s|789m*
>
> 
You can control the width of the space between two tiles by inserting multiple consecutive spaces with multiple `|`.
> *123p||||456s*
>
> 
## Naki
There are three possible variations for a mahjong tile when tile open calls: side, added open quad, or added open quad with red dora involved.
### Side
We use the prefix `_` to indicate that the next tile is placed horizontally. For example, we can use `_123m` to represent a call out of *Chii*:
> *_123m*
>
> 
Here are some more examples:
> *1_11s*
>
> 
> *777_7p*
>
> 
### Added open quad
We use the prefix `^` to indicate that the next tile is an overlap formed by added open quad. For example:
> *77^7z*
>
> 
### Added open quad, involving red dora
We use the prefix `v` to represent that the next tile is an overlap formed by added open quad, while one of them is a red dora. We define that `v0` means the lower tile in the overlap is a red dora, and `v5` means the upper tile in the overlap is a red dora. For example:
> *55v5p*
>
> 
> *5v05s*
>
> 
> *v555m*
>
> 
### Summary
The syntax of `mahgen` basically follows and expands upon the conventions of Japanese mahjong for describing tile patterns:
* Use `1-9` to describe the number of tiles;
* Use `p`, `s`, `m` and `z` to indicate the type of tiles: Pin, So, Man and Honor tiles;
* Use `0` for red dora, `0z` for the back of a tile;
* Use `|` to insert a space;
* Use prefix `_` to indicate placing a tile horizontally, `^` to added open quads, and `v` to added open quads with red dora involved.
By combing these symbols, we are able to construct a variety of tile patterns, for example:
> *1m|_123p|5v05m|0z11s0z|66^6z*
>
> 
Finally, `mahgen` only generates images for given sequences and does not check whether these sequences match the rules, so sequences like `_5^50v0m` are legal for `mahgen`.
---
## River Mode
Started from v1.0.0, `mahgen` supports using `data-river-mode` attribute to generate images for river.
In river mode, the syntax and the semantics for the sequence have the following differences:
* Use `_` for *Reach*, `^` for *Cut*, `v` for *Cut while Reach*;
* `|` is not allowed;
* *Reach* can show only once(including `_` and `v`);
* *Cut* is not a default action after *Reach* for better flexibility.
Example:
> *123^456_7m^8^9^1^2^4^5^8^7^2s*
>
> 
---
## Hexo Plugin
`mahgen` also provides a plugin for [Hexo](https://hexo.io/), see [hexo-mahgen](https://github.com/eric200203/hexo-mahgen).
---
## TODO
* Support for parameters like scaling, ...
* Support for river mode...
---
## Acknowledgements
* Thanks to [@black-desk](https://github.com/black-desk), whose project [mahjim](https://github.com/black-desk/mahjim) greatly inspired this project.
* Thanks to [ๆๅฎๆด็ๆฅๆฌ้บปๅฐไธญๆ็ปดๅบ็พ็ง](http://wiki.lingshangkaihua.com/mediawiki/index.php/%E9%A6%96%E9%A1%B5), for the image materials for this project came from this site.
---
## License
[MIT](./LICENSE)
---
## Changelog
### v1.0.0
Add `data-river-mode` attribute to generate images for river.
### v0.3.1
Add `data-show-err` attribute to display error messages when the sequence is invalid.
### v0.3.0
First version of `mahgen`.