---
# System prepended metadata

title: Slots

---

# Slots

Code name: `slots` (plural, because this is for a set of multiple games on the
FE menu, not just a single game).

## About

There's a box contains multiple reels, each reels has a number of symbols (9,
10 or even 12). User can place bet follow some custom rules, and spin the
reels. After that, base on the visible part of the reels and predefined set of
paylines, user may or may not get reward.

Let see some example before going through more concepts.

## Examples

### Slots 3x3

- 3 reels
- Each one has many symbols, minimum is 9.
- Each real has 3 visible symbols after spin, there symbols may or may not be
  repeated, may or may not maintain the order. This can be customized from our
  game config.

![Slot 3x3](./img/slot_3x3.jpg)

### Slots 3x5

- 5 reels
- Each one has many symbols, minimum is 9.
- Each real has 3 visible symbols after spin, there symbols may or may not be
  repeated, may or may not maintain the order. This can be customized from our
  game config.

![Slot 3x5](./img/slot_3x5.jpg)

## Concepts

### Traditional Slot

The reels in physical slots machines is has 9 symbols, fixed order, thus, we
can have 9^3 possible output for `slot_3x3` and 9^5 possible output for
`slot_3x5`. The chances to win this is quite small.

To support this type of slots, our implementation should take following params:

- Number of reels: 3 or 5
- Number of symbols per reels: minimum is 9
- Skins for the symbols.
- All reels need to maintains same order of symbols (1, 2, 3, ... 10)
- The paylines for this type of games, vary depends on number of reels.

### Video Slot

Since computer become popular, the game is implemented using software. And
because it's not physical machine, there's no need to keep the symbols order,
and no need to avoid repeated symbols. So, some casinos add mew rules, new
symbols, more increase the possible patterns, and more chance for user to
wins.

To support this type of slots, our implementation should take the same params
with Traditional Slot, with following changes:

- There's some special symbols that can change how the paylines are constructed
  and the reward.
- Reels no need to maintain symbol orders.
- Symbols can or can not repeat within a reel.

### Symbols

There's can be 3 kinds

- `Normal`: Traditional slots only have this kind of symbols. They're label from
  1 to `n` (`n` is number of Normal symbols).

Video Slot can contains following symbols, and it's up to us to implement them
or not:

- `Wild`: can substitute any other symbols to make the best paylines, can
  appear only in reel 2, 3, 4 and 5.
- `Bonus`: when this type of symbols appears on the reels, user may get
  additional reward or some mini games are triggered. This is totally up to our
  implementation and the business/marketing.
- `Free spins`: similar to `Bonus` types, if the `Free spins` symbols appear
  and match game condition, user will get additional spins for free.

### Paylines

Paylines are special patterns of the reels that rarely happens.

Let's consider slot 3x5 matrix, with `X` is one of our symbols, following
pattern of `X` are most common paylines (there's over 30 possible paylines for
3x5):

```
X X X X X
- - - - -
- - - - -
```

```
- - - - -
X X X X X
- - - - -
```

```
- - - - -
- - - - -
X X X X X
```

Note that `Wild` (`W`) can replace any `X` and still turn above pattern valid
paylines

```
- - - - -
- - - - -
W X X X X
```

```
- - - - -
- - - - -
X W X X X
```

- Paylines are predefined for each slots games.
- Paylines are only from left to right.
- For each bet, user can pay an amount on a payline, and can pay for one or
  many paylines as their will.
- For each selected paylines appears in the visible patterns after spin, user
  get corresponding reward.

## API

Since this game is complicarted, we will start with the API design and explain
our thought before get to the DB design.

### RPC API

#### User to place bet

```
POST /api/game/slots/bet
```

Request:

```json
{
  "game_type": 2,
  "bet_per_pay_line": 100,
  "pay_lines": [
    "3X3_01",
    "3X3_02",
    "3X3_03"
  ]
}
```

Explain the request:

- `pay_lines` contains a list of selected paylines

- `bet_per_pay_line` is amount of money per payline. The total bet amount will
   be the multiplication of number of paylines and `bet_per_payl_ine` 

- `game_type` is the enum value of the game type. For the example, let just say
  `4` mean `slot_3x5_video`. The server will base on the game type, generate
  reels data and calculate bet result.

Response

```json

{
    "all_reels": [
        [1, 13, 12],
        [1, 15, 11],
        [1, 15, 11]
    ],
    "pay_line_results": [
        {
            "game_result": 1,
            "pay_line": "3X3_01",
            "reward_amount": 500,
            "symbol": 1,
            "symbol_count": 3
        },
        {
            "game_result": 2,
            "pay_line": "3X3_02",
            "reward_amount": 0,
            "symbol": 13,
            "symbol_count": 1
        },
        {
            "game_result": 2,
            "pay_line": "3X3_03",
            "reward_amount": 0,
            "symbol": 12,
            "symbol_count": 1
        },
        {
            "game_result": 2,
            "pay_line": "3X3_04",
            "reward_amount": 0,
            "symbol": 15,
            "symbol_count": 2
        },
        {
            "game_result": 2,
            "pay_line": "3X3_05",
            "reward_amount": 0,
            "symbol": 12,
            "symbol_count": 1
        }
    ],
    "total_reward_amount": 500
}

```

### User to query game records

Since we have only 1 endpoint to support multiple type of slots, caller needs to
specify game type to query correct game records.

`POST /api/me/slot/get?q[game_type]=eq:4`

Request:
api/game/slot/bet

```json
{
  "game_type": 2,
  "bet_per_pay_line": 1000000,
  "pay_lines": ["3X3_01","3X3_02","3X3_03","3X3_04","3X3_05"]
}
```
Response:

```json

{
    "all_reels": [
      [14, 15, 12],
      [17, 17, 12],
      [18, 13, 15]
    ],
    "pay_line_results": [
        {
            "game_result": 2,
            "pay_line": "3X3_01",
            "reward_amount": 0,
            "symbol": 14,
            "symbol_count": 1
        },
        {
            "game_result": 2,
            "pay_line": "3X3_02",
            "reward_amount": 0,
            "symbol": 15,
            "symbol_count": 1
        },
        {
            "game_result": 2,
            "pay_line": "3X3_03",
            "reward_amount": 0,
            "symbol": 12,
            "symbol_count": 2
        }
    ],
    "total_reward_amount": 0
}

```

You might notice that the response is just a con of user bes request and
response. Yes, that would be enough for to display game history.

However, this design can't fully support history tracing. If we change the
paytables, i.e: increase pay rate of full 5 slots from 10x to 20x; user might
get confused when checking their game records.

## DB

Now we understand how the API should works, let see how the we organize the
data.

### Game config

- Table name: `slots_game_config`
- Should have Audit and Comment
- Fields:

  - `id`, `ctime`, `mtime`, `status`
  - `game_type`: not null, enum, skin of the game, this is related to a game on
    FE game menu, and each one has a different paytable.
  - `partner_id`: not null, but unlike other tables, this is not unique, because each
    Partner might choose to enable one or more skins.
  - unique key on `(partner_id, game_type)`.

### Game record

- Name: `slots_game_record`
- Fields:

  - `id`, `ctime`: no `mtime` and `status` because this is read-only
  - `total_bet_amount`: how much money user bet for all of his selected
    paylines.
  - `total_reward_amount`: how much money user got after the bet
  - `bets`: JSON string of the `bets` map of payline and amout for that line.
  - `game_type`
  - `all_reels`: JSON string of the generated matrix.
  - `payline_results`: JSON array of number of the winning lines and respective
    reward.
  - `result_type`: `UserWin` if `total_bet_amount` is less than
    `total_reward_amount`, or `UserLose` otherwise.

Note that to support dynamic data, we have to compromise our design, use JSON
to store the bets and the matrix instead of named columns. This is acceptable
given our data size is small (up to 1000 paylines, 15 number for the `all_reels`,
and up to 1000 key-value for the `payline_results`).

> TODO (jl): check if we can use postgres jsonb for those JSON fields.
> sqlboiler seems to be able to generate it >

## Game Type

- This is an enum.
- Each game type related to a visible game on the game menu
- Each game type has its own paytable (it doesn't prevent 2 game types to have same
  paytable, though).
- Each game type has its own graphics (game types might have same graphics, but
  different in other params, such as number of Symbols, or Paytable, ...)
- Example possible values:
  - `slot_3x3_traditional`: 1
  - `slot_3x3_video`: 2
  - `slot_3x5_traditional`: 3
  - `slot_3x5_video`: 4
  - `slot_3x3_video_with_bonus`: 5 
  - `slot_3x3_traditional_jungle`: 6
  - `slot_3x3_traditional_batman`: 7
  - `slot_3x3_video_jungle`: 8
  - `slot_3x3_video_batman`: 9

Given above requirements, we can see that whenever we add a new game types,
following things must be done:

- BA design the pay tables and rate, make sure that we won't lost money with
  that paytable.
- BE add new game type, associates it with the defined paytable.
- Designer works on new symbol graphics.
- FE add new game on the menu, with the new graphics.


## Implementation

- A user enter game table and press play

- Card backend (CB) authorize user session. If session valid move to next step,
  otherwise return 401 

- CB validate user's bet. If request valid move to next step, otherwise return
  403
  - validate whether bet amount exceed user's balance

- CB generate 3 values of  first_reel, second_reel, third_reel, fourth_reel, and
  fifth_reel 

- CB compute winning_lines and total_reward

- CB create a slot_3x5_game_record

- CB create a bet transaction

- CB update user wallet, that the balance is deducted by amount of user's bet

- If the user win any bet, reward user

  - CB create a reward transaction, with change equal to total reward amount
  - CB update user wallet, that the balance is added up by total reward amount

- CB return back to user


## Enums
  Please refer  [slot_enum](./slot_enum.md)
    
## References

- https://www.winkslots.com/skin/magazine/slots-paylines.php
- https://en.wikipedia.org/wiki/Slot_machine
- https://www.onlinecasinoselite.org/free-slots/3-reels
- http://stoppredatorygambling.org/wp-content/uploads/2012/12/The-Secrets-of-a-Slot-Machine.pdf
  this link is very good about internal of physical slots machine.
