Hercules

Build Status:

Issues and pull requests:

Development and Community:

Project Info:

Table of Contents

1. What is Hercules?
2. Prerequisites
3. Installation
4. Troubleshooting
5. Helpful Links
6. More Documentation

What is Hercules?

---

Hercules is a collaborative software development project revolving around the creation of a robust Massively Multiplayer Online Role-Playing Game (MMORPG) server package. Written in C, the program is very versatile and provides NPCs, warps and modifications. The project is jointly managed by a group of volunteers located around the world as well as a tremendous community providing QA and support. Hercules is a continuation of the original Athena project.

Prerequisites

---

Before installing Hercules, you will need to install certain tools and applications. This differs between the varying Operating Systems available, so the following list is broken down into Windows and Unix (incl. Linux) prerequisites.

For a list of supported platforms, please refer to the Supported Platforms wiki page.

Windows

• Git client
• Microsoft Visual Studio Community

Unix/Linux/BSD (names of packages may require specific version numbers on certain distributions)

• git
• gcc or clang (version 4.5 or newer, recommended 5.0 or newer)
• GNU make
• MySQL (mysql-server) or MariaDB
• libmysqlclient (mysql-devel)
• zlib (zlib-devel)
• libpcre (pcre-devel)
• Optional dependencies for development only
  • perl (required to rebuild the HPM Hooks and HPMDataCheck)
    • requires the XML::Simple module, which in turn requires libexpat-dev
  • Doxygen (required to rebuild the HPM Hooks and HPMDataCheck)

Mac OS X

• Xcode or the Xcode command-line tools.
• MySQL-compatible server (installation of mysql or mariadb through Homebrew is recommended)
• PCRE library (installation of pcre through Homebrew is recommended)
• Optional dependencies for development only
  • Doxygen (required to rebuild the HPM Hooks and HPMDataCheck)

Optional, useful tools

• MySQL GUI clients
  • MySQL Workbench (cross-platform)
  • HeidiSQL (Windows)
  • DBeaver (cross-platform)
  • Sequel Pro (Mac OS X)
    • More options available at mariadb.com
• GUI Git clients
  • GitHub Desktop (cross-platform)
  • GitKraken (cross-platform)
  • SmartGit (cross-platform)
  • Atlassian SourceTree (Windows, Mac OS X)
    • More options available at git-scm.com
• Text editors with syntax highlighting
  • Visual Studio Code (cross-platform)
  • Atom (cross-platform)
  • Notepad++ (Windows)
    • More options available at wikipedia.org

Installation

---

This section is a very brief set of installation instructions. For more concise guides relevant to your Operation System, please refer to the Wiki (links at the end of this file).

Windows

Easy installation

1. Install the prerequisites.
2. Clone the Hercules repository using a git client, into a new folder.
   • If you do not want to use the command line, you can instead clone with GitHub Desktop.
3. Run mariadb.bat to automatically install and configure MariaDB.
4. Start Visual Studio and load the provided solution:
   • Compile and run the three projects, login-server, char-server, map-server.

Manual installation

1. Install the prerequisites.
2. Install a MySQL-compatible server, such as MariaDB (recommended) or MySQL Community Edition
3. Clone the Hercules repository Hercules repository using a git client, into a new folder.
4. Connect to the MySQL server as root:
   • Create a database (hercules): CREATE DATABASE hercules;
   • Create a user (hercules): CREATE USER 'hercules'@'localhost' IDENTIFIED BY 'password';.
   • Give permissions (GRANT SELECT,INSERT,UPDATE,DELETE) to the user: GRANT SELECT,INSERT,UPDATE,DELETE ON hercules.* TO 'hercules'@'localhost';
5. Connect to the MySQL server as the new user:
   • Import the .sql files in /sql-files/ into the new database.
6. Start Visual Studio and load the provided solution:
   • Compile and run the three projects, login-server, char-server, map-server.

Unix

1. Install the prerequisites through your distribution's package manager
   • (Red Hat compatible / CentOS) yum install gcc make mysql mysql-devel mysql-server pcre-devel zlib-devel git
   • (Debian compatible) apt-get install gcc make libmysqlclient-dev zlib1g-dev libpcre3-dev mysql-server git
   • (FreeBSD) pkg install clang35 gmake mysql56-server mysql-connector-c pcre git
   • (Mac OS X):
     • Install Xcode through the Mac App Store
     • Initialize the build tools through the Terminal xcode-select --help
     • Install Homebrew as described on the project page
     • Install the other prerequisites: brew install mysql pcre
2. Clone the Hercules repository git clone https://github.com/HerculesWS/Hercules.git ~/Hercules
3. Configure the MySQL server and start it.
4. Connect to the MySQL server as root:
   • Create a database (hercules): CREATE DATABASE hercules;
   • Create a user (hercules): CREATE USER 'hercules'@'localhost' IDENTIFIED BY 'password';.
   • Give permissions (GRANT SELECT,INSERT,UPDATE,DELETE) to the user: GRANT SELECT,INSERT,UPDATE,DELETE ON hercules.* TO 'hercules'@'localhost';
5. Connect to the MySQL server as the new user:
   • Import the .sql files in /sql-files/ into the new database.
6. Enter the Hercules directory and configure/build Hercules
   • ./configure
   • make clean && make sql (on FreeBSD, replace make with gmake)
7. Start the three servers login-server, char-server, map-server.

Troubleshooting

---

If you're having problems with starting your server, the first thing you should do is check what's happening on your consoles. More often than not, all support issues can be solved simply by looking at the error messages given.

Examples:

• You get an error on your map-server_sql that looks something like this:

[Error]: npc_parsesrcfile: Unable to parse, probably a missing or extra TAB in file 'npc/custom/jobmaster.txt', line '17'. Skipping line...
        * w1=prontera,153,193,6 script
        * w2=Job Master
        * w3=2_F_MAGICMASTER,{
        * w4=

If you look at the error, it's telling you that you're missing (or have an extra) TAB. This is easily fixed by looking at this part of the error: * w1=prontera,153,193,6 script. If there was a TAB where it's supposed to be, that line would have prontera,153,193,6 at w1 and script at w2. As there's a space instead of a TAB, the two sections are read as a single parameter.

• You have a default user/password warning similar to the following:

[Warning]: Using the default user/password s1/p1 is NOT RECOMMENDED.
[Notice]: Please edit your 'login'