Document how to start the bot #322

Merged
Vylpes merged 1 commit from feature/81-document-bot into develop 2024-07-26 18:32:12 +01:00
2 changed files with 179 additions and 1 deletions
Showing only changes of commit 136bc0805e - Show all commits

View file

@ -1,2 +1,60 @@
# card-drop # Card Drop
Card Drop is a Discord Bot designed to allow users to "drop" random cards into
a channel and have the ability to claim them for themselves or let others if
they so choose.
The cards are randomly chosen based on weights of their card type (i.e. Bronze
is more common than Gold). The user who ran the drop command has 5 minutes to
choose if they want the card to themselves before its claimable by anyone, or
until the drop command is ran again.
## Installation
Downloads of the latest version can be found from the [GitHub Releases](https://github.com/vylpes/card-drop/releases)
or [Forgejo Releases](https://git.vylpes.xyz/external/card-drop/releases) page.
Copy the config template file and fill in the strings.
## Requirements
- NodeJS
- Yarn
- Docker
## Usage
Install the dependencies and build the app:
```bash
yarn Install
yarn build
```
Setup the database (Recommended to use the docker-compose file
```bash
docker compose up -d
```
Copy and edit the settings file
```bash
cp .env.template .env
```
> **NOTE:** Make sure you do *not* check in these files! These contain
sensitive information and should be treated as private.
If you're not using `DB_SYNC=true` in `.env`, make sure to migrate the database
```bash
yarn db:up
```
Start the bot
```bash
yarn start
```

120
docs/cards.md Normal file
View file

@ -0,0 +1,120 @@
# Cards
This document will describe how to add cards to the bot. This is from the
perspective of the development side and doesn't go into details of syncing
from an external place such as with the Google Drive Sync function.
The cards will be put into the `$DATA_DIR/cards` folder. `$DATA_DIR` is
configured in the `.env` file.
## Folder Structure
The general structure of the cards folder is as follows:
```
cards # The main cards folder
| Series 1 # Series folder
| | BRONZE # Type folder
| | | 1000.jpg # Card image
| | | 1001.jpg
| | 1.json # Card metadata file
| Series 2
| | SILVER
| | | 2000.jpg
| | 2.json
```
- The root of the cards folder will have a folder foor each series
- Each series will contain folders for each of the card types containing the
card images.
- The series folder will also contain a metadata JSON folder containing the
metadata of the cards within that series.
The bot when loading will search the cards folder recursively for each json,
and then read them to determine what cards should be used for the bot.
## Series Metadata
An example of what the metadata files could look like are as follows:
```json
[
{
"id": 1,
"name": "Series 1",
"cards": [
{
"id": "1000",
"name": "Card 1000 of Series 1",
"type": 1,
"path": "Series 1/BRONZE/1000.jpg"
},
{
"id": "1001",
"name": "Card 1001 of Series 1",
"type": 1,
"path": "Series 2/BRONZE?1001.jpg",
"subseries": "Custom Series Name"
}
]
}
]
```
This file will load a series called "Series 1" with the id of 1, containing 2
cards:
- Card 1000, with type 1 (Bronze), with its image located at (from root)
"Series 1/BRONZE/1000.jpg"
- Card 1001 is the same, except has a custom "subseries" name which will
override the main series name if shown, helpful for an "other" category.
### Card Type
<table>
<thead>
<tr>
<th>Number</th>
<th>Name</th>
<th>Chance</th>
<th>Sacrifice Cost (Coins)</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>Unknown</td>
<td>-</td>
<td>-</td>
</tr>
<tr>
<td>1</td>
<td>Bronze</td>
<td>62%</td>
<td>5</td>
</tr>
<tr>
<td>2</td>
<td>Silver</td>
<td>31%</td>
<td>10</td>
</tr>
<tr>
<td>3</td>
<td>Gold</td>
<td>4.4%</td>
<td>30</td>
</tr>
<tr>
<td>4</td>
<td>Manga</td>
<td>2%</td>
<td>40</td>
</tr>
<tr>
<td>5</td>
<td>Legendary</td>
<td>0.6%</td>
<td>100</td>
</tr>
</tbody>
</table>