Setup

1. Get the files

NOTE: MAKE SURE YOU HAVE PYTHON 3.6 INSTALLED (See FAQ)

Option A: The latest and greatest! (Git clones)

Here are 3 ways you can do this:

GitHub Desktop Route (GUI)

• Make sure you have GitHub Desktop installed
• In the toolbar, click File -> Clone repository...
  • Alternatively use the keyboard shortcut Ctrl+Shift+O
• Click on the URL tab, and paste in https://github.com/Descended/MaplestoryDiscBot
• Set the Local path as the folder where you want the bot source code to be stored
• Click Clone

Sourcetree Route (GUI)

• Make sure you have Sourcetree installed
• In the toolbar, click File -> Clone/New...
  • Alternatively use the keyboard shortcut Ctrl+N
• In the Source Path/URL field, paste in https://github.com/Descended/MaplestoryDiscBot
• In the Destination Path field, select the folder where you want the bot source code to be stored
• Click Clone

Command Line Route

• Make sure you have Git installed
  • You can use the following command: choco install git if you are using Chocolatey to manage your software
  • Otherwise, install using the instructions from the Git Website
• Navigate to the folder you want to use
  • E.g. cd server_tools/my_bot
• Clone the repository
  • HTTPS: git clone https://github.com/Descended/MaplestoryDiscBot.git
  • SSH: git clone git@github.com:Descended/MaplestoryDiscBot.git
  • GitHub CLI: gh repo clone Descended/MaplestoryDiscBot

Option B: Official releases (zip files)

Alternatively, you may choose to download the stable releases:
Go to the release page to find all the source code archives

---

2. Generate the virtual environment

Command line route:

• In the root of the repository, create a virtual environment using Python -m venv venv
  • Substitute "Python" with whichever command you have assigned to Python 3.6
  • Refer to the FAQ if you encounter an error
• Activate the virtual environment using call venv\scripts\activate.bat in Command Prompt
  • The command is venv/scripts/activate in Power Shell
  • Note: PowerShell can take both backslash and forward slashes, but CMD only accepts backslashes
  • Note: You can deactivate the venv by using the command deactivate
• Use the command venv/scripts/pip install -r requirements.txt to install the required modules
  • Use venv\scripts\pip install wheel, if the above commands throw errors

GUI route:

... Err
Good luck.

---

3. Generate A Token

Creating a New Discord Application/Bot:

• Visit the Discord Developer Portal
  • Login (if applicable)
• Click on the New Application button, at the top right of the page
  • Enter your desired application name
• Make sure the new application that you've just created is currently selected (which should automatically be the case)
  • Select Bot in the left side-panel
• Click on the Add Bot button (under the Build-A-Bot section), at the top right of the page
• Under Token, click on the Copy button to have it added to your clipboard
  • Note: Scroll down to SERVER MEMBER INTENTS and enable it for the bot to access role adding feature! (See FAQ)

---

4. Configure The Bot

PLEASE CONFIGURE THE BOT PRIOR TO FIRST USE
You will need to fill in the required fields in the config file before running the bot for the first time!

Configuration file path: src/settings/Config.py

• The config file has all the required fields marked out as REQUIRED
• The config file has all its fields explained with comments

NOTE: This bot assumes that it is run on the same machine as the private server & its database

• This behaviour can be altered through the config file as well

5. Installing the Web API

The Web API is used to establish a connection between the Discord bot and the MapleStory server, for a feature-rich Discord presence
At the moment, it only supports HeavenMS-based sources (see Technical-Details)

Option A: Maven-based Project

• Head to the Spring Initializr to have a Spring Boot project structure automagically generated for you
  • Change the Java version to the one you're using, and make sure "Spring Web" is in the dependencies list
  • If your project is not a maven project visit this tutorial by Jetbrains
  • Grab the pom.xml from the generated zip file.
  • Add its contents into the pom.xml of your MapleStory source code
  • Maven should automagically import/resolve the dependencies
    • If this is not the case, open the Maven tab and click on "Re-import all Maven Projects"

Option B: Manual Dependency Management

... You're on your own for this (unless someone wishes to contribute documentation)

6. Setting up the Web API

• After resolving dependencies, create a new folder in the source code for the API-related files
• Create a new apiApplication class with the following code:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
   
@SpringBootApplication
public class ApiApplication { 
    public static void init() {
        SpringApplication.run(ApiApplication.class);
    }
}  

• Download the proprietary API functions from this page (or make your own)
• Go to the part of your source code that launches your MapleStory server and add the following line:

apiApplication.init();