Hercules
========

Build Status:
![Github Action Status](https://github.com/HerculesWS/Hercules/workflows/build/badge.svg)
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/cm9xbwurpbltqjop?svg=true)](https://ci.appveyor.com/project/Haru/hercules)
[![Coverity Scan Build Status](https://scan.coverity.com/projects/3892/badge.svg)](https://scan.coverity.com/projects/herculesws-hercules)
[![Pipeline Status](https://gitlab.com/HerculesWS/Hercules/badges/master/pipeline.svg)](https://gitlab.com/HerculesWS/Hercules/-/commits/master)
[![Coverage Report](https://gitlab.com/HerculesWS/Hercules/badges/master/coverage.svg)](https://gitlab.com/HerculesWS/Hercules/-/commits/master)

Issues and pull requests:
[![Open Issues](https://img.shields.io/github/issues-raw/HerculesWS/Hercules.svg?label=Open%20Issues)](https://github.com/HerculesWS/Hercules/issues)
[![Open Pull Requests](https://img.shields.io/github/issues-pr-raw/HerculesWS/Hercules.svg?label=Open%20Pull%20Requests)](https://github.com/HerculesWS/Hercules/pulls)

Development and Community:
[![GitHub Repository](https://img.shields.io/badge/github-HerculesWS/Hercules-green.svg?logo=github)](https://github.com/HerculesWS/Hercules)
[![Community Forum](https://img.shields.io/badge/forum-herc.ws-orange.svg)](http://herc.ws)
[![IRC](https://img.shields.io/badge/IRC-Rizon/Hercules-yellow.svg)](irc://rizon.net/Hercules)
[![Discord](https://img.shields.io/badge/discord-Hercules%20Emulator-7289da.svg)](https://discord.gg/rqCxS8p)
[![Twitter](https://img.shields.io/badge/twitter-@HerculesWS-blue.svg?logo=twitter)](https://twitter.com/HerculesWS)

Project Info:
[![Release](https://img.shields.io/github/release/HerculesWS/Hercules.svg)](https://github.com/HerculesWS/Hercules/releases)
![Language](https://img.shields.io/badge/language-C-yellow.svg)
[![License](https://img.shields.io/badge/license-GPLv3-663399.svg)](https://github.com/HerculesWS/Hercules/blob/master/LICENSE)
[![GitHub contributors](https://img.shields.io/github/contributors/HerculesWS/Hercules.svg)](https://github.com/HerculesWS/Hercules/graphs/contributors)

Table of Contents
---------
1. [What is Hercules?](#what-is-hercules)
2. [Prerequisites](#prerequisites)
3. [Installation](#installation)
4. [Troubleshooting](#troubleshooting)
5. [Helpful Links](#helpful-links)
6. [More Documentation](#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](https://github.com/HerculesWS/Hercules/wiki/Supported-Platforms) wiki page.

- git
- gcc or clang or msvc (on windows)
- cmake
- python3
- A build system like GNU make or Ninja (Ninja is preferred build system on windows, recommended for *Unix as well)
- MariaDB
- *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)

For a full list of prerequisites, please refer to the [Building](https://github.com/HerculesWS/Hercules/wiki/Building) wiki page.

#### Optional, useful tools
  - MySQL GUI clients
    - [MySQL Workbench](http://www.mysql.com/downloads/workbench/) (cross-platform)
    - [HeidiSQL](http://www.heidisql.com/) (Windows)
    - [DBeaver](http://dbeaver.jkiss.org/) (cross-platform)
    - [Sequel Pro](http://www.sequelpro.com/) (Mac OS X)
       - *More options available at [mariadb.com](https://mariadb.com/kb/en/library/graphical-and-enhanced-clients/)*
  - GUI Git clients
    - [GitHub Desktop](https://desktop.github.com/) (cross-platform)
    - [GitKraken](https://www.gitkraken.com/git-client) (cross-platform)
    - [SmartGit](https://www.syntevo.com/smartgit/) (cross-platform)
    - [Atlassian SourceTree](https://www.sourcetreeapp.com/) (Windows, Mac OS X)
        - *More options available at [git-scm.com](https://git-scm.com/downloads/guis)*
  - Text editors with syntax highlighting
    - [Visual Studio Code](https://code.visualstudio.com) (cross-platform)
    - [Atom](https://atom.io) (cross-platform)
    - [Notepad++](https://notepad-plus-plus.org) (Windows)
        - *More options available at [wikipedia.org](https://en.wikipedia.org/wiki/Comparison_of_text_editors#Overview)*


## Building and Installation
------------

For guides on building and installing hercules please check our wiki at [Building](https://github.com/HerculesWS/Hercules/wiki/Building) and [Installation](https://github.com/HerculesWS/Hercules/wiki/Installation) wiki pages.


## 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.

* Hercules Forums:
  http://herc.ws/board/

* Hercules Wiki:
  http://herc.ws/wiki/Main_Page

* Git Repository URL:
  https://github.com/HerculesWS/Hercules

* Discord Server Invite URL:
  https://discord.gg/ZUzbRSp

* Hercules IRC Channel:
  Network: `irc.rizon.net`
  Channel: `#Hercules`

## 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.