Skip to content
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…
C C++ TSQL PHP Perl Python Other
Branch: stable
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github [github] refresh the issue template Oct 3, 2018
3rdparty Fix date part2 Jul 12, 2018
Hercules.xcodeproj Update Xcode project with the new files May 5, 2019
cache Fixed typos on cache/. May 30, 2014
conf Merge pull request #2547 from guilherme-gm/201910-dehardcode-db Oct 20, 2019
db Merge pull request #2553 from skyleo/magnum_break_delay_fix Oct 18, 2019
doc Constants Documentation Sync Sep 23, 2019
log Fixed Typos (+1 squashed commits) Oct 21, 2015
maps Update Maps Database Aug 31, 2018
npc Merge pull request #1935 from dastgirp/2017-4_umbala Oct 18, 2019
plugins Corrected line endings and BOM issues with several files Sep 16, 2013
save Fixed Typos (+1 squashed commits) Oct 21, 2015
sql-files Merge pull request #2551 from guilherme-gm/201910-fix-sc-times Oct 18, 2019
src Merge pull request #2550 from skyleo/cliff_aggro_ranged_no_attack_fix Oct 20, 2019
tools Removed jAthena 1082 legacy code related to Castle Defense Rate. Oct 9, 2019
vcproj-14 Removal of refine database code from status.c and moving it respectfu… May 5, 2019
vcproj-15 Removal of refine database code from status.c and moving it respectfu… May 5, 2019
vcproj-16 replace msvc12 build files with msvc16 Aug 12, 2019
.appveyor.yml update appveyor to use the new visual studio builds Aug 12, 2019
.gitattributes * Implemented suggestion in topic:528, related to GMs being able to w… May 11, 2013
.gitignore Implementation of Item Options System. Apr 4, 2017
.gitlab-ci.yml Update the gitlab-ci builds Sep 22, 2019
.mailmap [ci skip] add some missing entries to mailmap Nov 8, 2018
.travis.yml Update travis build packet version to 20191016 Oct 17, 2019
AUTHORS Added Chilly to AUTHORS Mar 9, 2014
CHANGELOG.md Release v2019.10.20 Oct 21, 2019
CONTRIBUTING.md Proofread & edited CONTRIBUTING document Oct 21, 2018
Hercules-14.sln Removal of the old mapcache tool as new plugin took it place. Feb 17, 2018
Hercules-15.sln
Hercules-16.sln replace msvc12 build files with msvc16 Aug 12, 2019
LICENSE Updated License from GNU GPLv2 to GNU GPLv3. Sep 9, 2010
Makefile.in Remove the unused src/tool directory Nov 11, 2018
README.md Merge pull request #2222 from Helianthella/scoop Jun 1, 2019
athena-start Dropped _sql suffix in server names. Feb 16, 2013
char-server.bat Removed executable flag from some files that don't require it Mar 10, 2014
char-server.sh Dropped _sql suffix in server names. Feb 16, 2013
configure Fix compilation warnings in gcc-9 Oct 17, 2019
configure.ac Fix compilation warnings in gcc-9 Oct 17, 2019
db2sql.bat Renamed some db2sql* plugin functions to itemdb2sql* Jan 29, 2016
dbghelp.dll - Updated dbghelp.dll Jul 10, 2013
libmysql.dll Updated DLLS to match libs. Please DO NOT update the libs from now on… Apr 17, 2006
login-server.bat Removed executable flag from some files that don't require it Mar 10, 2014
login-server.sh Dropped _sql suffix in server names. Feb 16, 2013
mac.start.scpt Added GPL-compliant header to all sources and build scripts Dec 15, 2015
map-server.bat Removed executable flag from some files that don't require it Mar 10, 2014
map-server.sh Dropped _sql suffix in server names. Feb 16, 2013
mariadb.bat add an auto-setup script for mariadb on windows Nov 7, 2018
pcre3.dll * Merged changes ONLY eAthena 15101. May 31, 2012
run-server.bat Removed executable flag from some files that don't require it Mar 10, 2014
script-checker Added GPL-compliant header to all sources and build scripts Dec 15, 2015
script-checker.bat Clean up hercules.ws leftovers Jul 31, 2016
serv.bat Removed executable flag from some files that don't require it Mar 10, 2014
sysinfogen.sh Added GPL-compliant header to all sources and build scripts Dec 15, 2015
zlib1.dll * Merged changes ONLY eAthena 15100. May 31, 2012

README.md

Hercules

Build Status: Build Status AppVeyor Build Status Coverity Scan Build Status GitLab Build Status Coverage Report Code Quality: Cpp Total Alerts

Issues and pull requests: Open Issues Open Pull Requests

Development and Community: GitHub Repository Community Forum IRC Discord Twitter

Project Info: Release Language License GitHub contributors

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

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

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' table to create a proper inter-server user/password (gender 'S')
[Notice]: and then edit your user/password in conf/map-server.conf (or conf/import/map_conf.txt)

Relax. This is just indicating that you're using the default username and password. To fix this, check over the part in the installation instructions relevant to the login table.

  • Your Map Server says the following:
[Error]: make_connection: connect failed (socket #2, error 10061: No connection could be made because the target machine actively refused it.)!

If this shows up on the map server, it generally means that there is no Char Server available to accept the connection.

Helpful Links


The following list of links point to various help files within the repository, articles or pages on the Wiki or topics within the Hercules forum.

More Documentation


Hercules has a large collection of help files and sample NPC scripts located in /doc/

Scripting

It is recommended to look through /doc/script_commands.txt for help, pointers or even for ideas for your next NPC script. Most script commands have a usage example.

@commands

In-game, Game Masters have the ability to use Atcommands (@) to control players, create items, spawn mobs, reload configuration files and even control the weather. For an in-depth explanation, please see /doc/atcommands.txt

Permissions

The Hercules emulator has a permission system that enables certain groups of players to perform certain actions, or have access to certain visual enhancements or in-game activity. To see what permissions are available, they are detailed in /doc/permissions.md

Others

There are more files in the /doc/ directory that will help you to create scripts or update the mapcache, or even explain how the job system and item bonuses work. Before posting a topic asking for help on the forums, we recommend that all users take the time to look over this directory.

You can’t perform that action at this time.