Skip to content

Commit

Permalink
Merge pull request #9 from cloudmaker97/documentation/readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@cloudmaker97
cloudmaker97 authored Nov 26, 2024
2 parents d3061d4 + b56c177 commit bdb80db
Show file tree
Hide file tree
Showing 2 changed files with 98 additions and 71 deletions.
133 changes: 62 additions & 71 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# Farming Simulator 25 - Discord Bot

This bot will post the server stats of a Farming Simulator 25 server to a Discord channel. The bot will post the server
name, server password, server time, and the player count. The bot will update the server stats every x seconds (
configurable).
This bot periodically updates a Discord channel with stats from a Farming Simulator 25 server.
It posts the server name, password, time, and player count. Written in Node.js, it uses the
discord.js library to interact with Discord and fetches server stats via the XML feed
(accessible through the server's web interface). The update interval is configurable.


## Screenshots

Expand All @@ -20,83 +22,72 @@ configurable).

</details>

## How it works

The bot is written in Node.js and uses the [discord.js](https://discord.js.org/) library to interact with the Discord
API. It uses the XML-Feed from the Farming Simulator 25 server to get the server stats (you can find the feed URL in the web
interface of the server).
<details>
<summary>Terminal output (NodeJS)</summary>

![bot_terminal.png](misc%2Fimages%2Fbot_terminal.png)

</details>

## Requirements

- Node.js - if you want to run the bot without Docker
- NPM - if you want to run the bot without Docker
- Docker (optional) - if you want to run the bot in a Docker container
- **Node.js**: Required if you want to run the bot without Docker.
- **NPM**: Required if you want to run the bot without Docker.
- **Docker (optional)**: Use Docker if you prefer running the bot in a containerized environment.

## Install the bot
---

### Create a Discord bot
## Installation Guide

1. Open the [Discord Developer Portal](https://discord.com/developers/applications)
2. Click on `New Application`
3. Name your application
4. Click on `Bot` in the left menu
5. Click on `Copy` to copy the bot token
6. Click on `Installation` in the left menu
7. Add the Permission 'Administrator' to the bot guild installation (bottom of the page)
8. Click on `Copy` to copy the URL to install the bot to a guild
9. Your installation link url should look like this: `https://discord.com/oauth2/authorize?client_id=CLIENT_ID`
### Step 1: Create a Discord Bot

### Configure the bot
1. Open the [Discord Developer Portal](https://discord.com/developers/applications).
2. Click on `New Application` and give your application a name.
3. Navigate to the `Bot` section in the left menu and click on `Add Bot`.
4. Copy the bot token by clicking `Copy` (you'll need this later).
5. Go to the `OAuth2` > `URL Generator` section in the left menu.
6. Under "Scopes," select `bot`, and under "Bot Permissions," select `Administrator`.
7. Copy the generated URL to invite the bot to your Discord server.
- The URL should look like this:
`https://discord.com/oauth2/authorize?client_id=CLIENT_ID&scope=bot&permissions=8`

1. Clone the repository to your server
2. Move the `config.example-de.json` or `config.example-en.json` to `config.json` (depending on your language)
3. Fill in the required fields in the `config.json` file, do not delete fields, just leave them empty for default values
4. All fields with a `(*)` are required fields for the bot to work. The other fields are optional and can be left by
default

| **- Key -** | **- Description -** |
|----------------------------------------------|---------------------------------------------------------------------------|
| (*) application.serverPassword | The password to join the server (or leave empty) |
| (*) application.serverStatsUrl | The feed URL to the server stats (from the web interface from the server) |
| (*) application.serverMapUrl | The feed URL to the server map (from the web interface from the server) |
| (*) application.updateIntervalSeconds | The interval in seconds to update the server stats |
| (*) discord.channelId | The channel id where the bot should post the server stats |
| (*) discord.botToken | The bot token from the Discord Developer Portal |
| translation.discordEmbed.title | The title of the Discord embed |
| translation.discordEmbed.descriptionOnline | The description when the server is online |
| translation.discordEmbed.descriptionOffline | The description when the server is offline |
| translation.discordEmbed.descriptionUnknown | The description when the server status is unknown |
| translation.discordEmbed.titleServerName | The title of the server name |
| translation.discordEmbed.titleServerPassword | The title of the server password |
| translation.discordEmbed.titleServerTime | The title of the server time |
| translation.discordEmbed.titlePlayerCount | The title of the player count |
| translation.discordEmbed.noPlayersOnline | The message when no players are online |
| translation.discordEmbed.titleServerMap | The title of the server map |
| translation.discordEmbed.titleServerMods | The title of the server mods |
| translation.common.monthJanuary | The month January in the language of the server |
| translation.common.monthFebruary | The month February in the language of the server |
| translation.common.monthMarch | The month March in the language of the server |
| translation.common.monthApril | The month April in the language of the server |
| translation.common.monthMay | The month May in the language of the server |
| translation.common.monthJune | The month June in the language of the server |
| translation.common.monthJuly | The month July in the language of the server |
| translation.common.monthAugust | The month August in the language of the server |
| translation.common.monthSeptember | The month September in the language of the server |
| translation.common.monthOctober | The month October in the language of the server |
| translation.common.monthNovember | The month November in the language of the server |
| translation.common.monthDecember | The month December in the language of the server |

### Run inside a Docker container

1. Run `docker-compose up -d --build` in the root directory of the repository
2. The bot should be running now and posting the server stats to the Discord channel

### Run without Docker (Node.js)
---

### Step 2: Configure the Bot

1. Clone the repository to your server
2. Run `npm install`
3. Run `npm start`
4. The bot should be running now and posting the server stats to the Discord channel
5. If you close the terminal, the bot will stop running
2. Locate the configuration files:
- Use either
- `config.example-de.json` (for German)
- `config.example-en.json` (for English)
- Rename the chosen file to `config.json`.
3. Open `config.json` and fill in the required fields:
- Refer to `SETTINGS.md` for detailed descriptions of each field.
- Fields marked with `(*)` are important to check; other fields can be left empty for default values.

---

## Running the Bot

### Option 1: Run Inside a Docker Container

1. Navigate to the root directory of the cloned repository.
2. Build and start the container:
```bash
docker-compose up -d --build
```
3. The bot should now be running and posting server stats to the specified Discord channel.

### Option 2: Run Without Docker (Using Node.js)

1. Navigate to the root directory of the cloned repository.
2. Install dependencies:
```bash
npm install
```
3. Start the bot:
```bash
npm start
```
4. The bot should now be running and posting server stats to the specified Discord channel.
- Note: Closing the terminal will stop the bot. Use a process manager like [PM2](https://pm2.io/) to keep it running.
36 changes: 36 additions & 0 deletions SETTINGS.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Settings and configuration

These are the settings that can be configured in the `config.json` file. The file is located in the root directory of the project. All
fields marked with `(*)` are required to be checked, or leave empty for default values.

| **- Key -** | **- Description -** |
|----------------------------------------------|---------------------------------------------------------------------------|
| (*) application.serverPassword | The password to join the server (or leave empty) |
| (*) application.serverStatsUrl | The feed URL to the server stats (from the web interface from the server) |
| (*) application.serverMapUrl | The feed URL to the server map (from the web interface from the server) |
| (*) application.updateIntervalSeconds | The interval in seconds to update the server stats |
| (*) discord.channelId | The channel id where the bot should post the server stats |
| (*) discord.botToken | The bot token from the Discord Developer Portal |
| translation.discordEmbed.title | The title of the Discord embed |
| translation.discordEmbed.descriptionOnline | The description when the server is online |
| translation.discordEmbed.descriptionOffline | The description when the server is offline |
| translation.discordEmbed.descriptionUnknown | The description when the server status is unknown |
| translation.discordEmbed.titleServerName | The title of the server name |
| translation.discordEmbed.titleServerPassword | The title of the server password |
| translation.discordEmbed.titleServerTime | The title of the server time |
| translation.discordEmbed.titlePlayerCount | The title of the player count |
| translation.discordEmbed.noPlayersOnline | The message when no players are online |
| translation.discordEmbed.titleServerMap | The title of the server map |
| translation.discordEmbed.titleServerMods | The title of the server mods |
| translation.common.monthJanuary | The month January in the language of the server |
| translation.common.monthFebruary | The month February in the language of the server |
| translation.common.monthMarch | The month March in the language of the server |
| translation.common.monthApril | The month April in the language of the server |
| translation.common.monthMay | The month May in the language of the server |
| translation.common.monthJune | The month June in the language of the server |
| translation.common.monthJuly | The month July in the language of the server |
| translation.common.monthAugust | The month August in the language of the server |
| translation.common.monthSeptember | The month September in the language of the server |
| translation.common.monthOctober | The month October in the language of the server |
| translation.common.monthNovember | The month November in the language of the server |
| translation.common.monthDecember | The month December in the language of the server |

0 comments on commit bdb80db

Please sign in to comment.