herculesws/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.

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

hercules's Issues

Script Function Override Fail

Code has been the same since eAthena and as I understand this problem is this old, lies at how npc functions try to override if got 2 with same name

npc_parse_function

    func_db = script_get_userfunc_db();
    oldscript = (struct script_code*)strdb_put(func_db, w3, script);
    if( oldscript != NULL )
    {
        ShowInfo("npc_parse_function: Overwriting user function [%s] (%s:%d)\n", w3, filepath, strline(buffer,start-buffer));
        script_free_vars(&oldscript->script_vars);
        aFree(oldscript->script_buf);
        aFree(oldscript);
    }

ours looks sightly different but the design is the same and remains broken

    func_db = script->userfunc_db;
    if (func_db->put(func_db, DB->str2key(w3), DB->ptr2data(scriptroot), &old_data))
    {
        struct script_code *oldscript = (struct script_code*)DB->data2ptr(&old_data);
        ShowInfo("npc_parse_function: Overwriting user function [%s] (%s:%d)\n", w3, filepath, strline(buffer,start-buffer));
        script->free_vars(oldscript->script_vars);
        aFree(oldscript->script_buf);
        aFree(oldscript);
    }

Pretty much if you have a function sleeping/timer'd while this is performed (e.g. by doing @loadnpc on a file already loaded that has a function) the previous pointer stuff screw up and ends up crashing in run_script_main ( claims st->script->script_buf is empty aka 0xfdfdfdfdfd'd by the memory manager ).

homunculus.h

Fully Integrated

battleground.h

Partially Integrated, Incomplete.

Unused setting in .conf file

from conf/login-server.conf:

// Log Filename. All operations received by the server are logged in this file. 
login_log_filename: log/login.log

duel.h

Fully Integrated.

Variadic macros vs C99 support/compilers

Until recently

• 0aee4fd added

#define safesnprintf(buf,sz,fmt,...) strlib->safesnprintf(buf,sz,fmt,##__VA_ARGS__)

• 2f9f7ce added

#define packet(id, size, ...) packetdb_addpacket(id, size, ##__VA_ARGS__, 0xFFFF)

there was no variadic macros in source with the exception for some unused code in nullpo.h:

#if __STDC_VERSION__ >= 199901L
/* C99‚ɑΉž */
#define nullpo_ret_f(t, fmt, ...) \
    if (nullpo_chk_f(NLP_MARK, (void *)(t), (fmt), __VA_ARGS__)) {return(0);}

but as you can see this part was checking for C99 support.

So the question is, are we now just assuming that modern compilers can handle this?

Map Zone @command reload ability

chat.h

Fully Integrated.

party.h

Fully Integrated.

Union Skill BUG

After using the command @skillsall or @skillall the skill points is not working on Union Skill of the Star Gladiator. I already try manual adding points but still not working. Im using latest version of hercules emulator. Sorry my bad english.

itemdb.h

Partially Integrated, incomplete.

Battle & skill code cleanup

This is something I've been thinking about for long time now.

• proper separation of battle and skill code into their own modules (eg int battle_calc_skillratio is placed in battle.c now, instead of skill.c)
• splitting code into smaller functions responsible of performing exactly one task (ideally) for improved readability and reusability of code
• moving as many hardcoded numbers and flags into skill_db*.txt files (eg already mentioned skill damage ratios, certain skills that bypass X, etc)
• removing awful switch (skill_id) in favor of expanding internal skill database representation with function pointers to perform extra actions unique for given skill id (eg. overriding default skill damage ratio calculation, adding extra conditions or extra effects that would be too complex to represent in plain txt db files); in future allow overriding these functions by plugins for easy skill modifications

Opinions, suggestions?

mob.h

No Implementation at all, missing.

pc.h

Fully Integrated.

pc_groups.h

No Integration at all, missing.

mercenary.h

Fully Integrated.

pc_readdb needs player refresh

I'm currently unable to commit due to my working copy being a mess because I'm working on the script update branch and am very unorganised about it xdd anyway I got this from hemagx, @reloadpcdb triggers pc_readdb which re-reads the files, thing is when skill tree data is modified and is then reload, online players data needs to be resync, in this case something similar to what skill_reload() does:

    /* lets update all players skill tree : so that if any skill modes were changed they're properly updated */
    iter = mapit_getallusers();
    for( sd = (TBL_PC*)mapit->first(iter); mapit->exists(iter); sd = (TBL_PC*)mapit->next(iter) )
        clif->skillinfoblock(sd);
    mapit->free(iter);

instance.h

Fully Integrated.

log.h

Fully Integrated.

Storing user passwords

Currently in Hercules there are 2 ways to store user passwords in database:

• unsalted one-round MD5 hash (bad)
• plain text (arguably unacceptable)

I've done little research on storing passwords in safe manner these days, and it looks like bcrypt is generally recommended and widespread solution. It also has ready to use implementations in many languages, most importantly PHP and C.

I think we should provide a way to store passwords in a way that is considered safe. MD5 maybe was good enough several years ago, but with increasing computing power it no longer is.

npc.h

Incomplete, little to no integration (1 member in the interface)

Ability to import/override libconfig files

e.g. conf/atcommand.conf

npc_chat.c

No Integration at all, even the buildin_ is missing the latest update that changed return values from 1/0 to false/true

clif.h

Fully Integrated.

map.h

Fully Integrated

path.h

No Integration at all, missing.

atcommand.h

Fully integrated.

irc-bot.h

Fully Integrated.

skill unit target / BCT_ / guild aura

It's for the http://hercules.ws/board/tracker/issue-7308-guild-aura-on-ally/ report
reference: battle.h

enum e_battle_check_target { //New definitions [Skotlex]
    BCT_NOONE       =   0x000000,
    BCT_SELF        =   0x010000,
    BCT_ENEMY       =   0x020000,
    BCT_PARTY       =   0x040000,
    BCT_GUILD       =   0x080000,
    BCT_NEUTRAL     =   0x100000,
    BCT_SAMEGUILD   =   0x200000,   // No Guild Allies

    BCT_NOGUILD     =   0x170000,   // This should be (~BCT_GUILD&BCT_ALL)
    BCT_NOPARTY     =   0x1b0000,   // This should be (~BCT_PARTY&BCT_ALL)
    BCT_NOENEMY     =   0x1d0000,   // This should be (~BCT_ENEMY&BCT_ALL)

    BCT_ALL         =   0x1f0000,   // Sum of BCT_NOONE to BCT_NEUTRAL
};

skill.c has this thing

int skill_get_unit_target( uint16 skill_id )       { skill_get (skill_db[skill_id].unit_target&BCT_ALL, skill_id); }

which is singling out BCT_SAMEGUILD, how can we best get around this? as I understand modifying BCT_ALL is out of the question as it'd be inconsistent since sameguild excludes guild allies from the check.

intif.h

Fully Integrated.

ers.c documentation is off

GreenBox has remade the system from the ground up a couple months ago but the description in the top of the file is still the same as previous and some are off (I'm not sure about the others), for example:

 *  - A  manager will only auto-destroy when all of its instances are        *
 *    destroyed so memory will usually only be recovered near the end.       *

This is no longer true

EDP Damage

EDP it's not completed, lack of damage on certain skills. More info on issue #7559

Updating Arena

Euphy just committed this: rathena/rathena@13b281b
If a script dev could go over it and check if it's compatible with ours that'd be great.

elemental.h

Fully Integrated.

Git/svn version detection improvements

• As Xgear suggested: we could differentiate between an exported copy that lacks any .git or .svn folders, and a valid working copy where the version detection fails for any other reason (our methods to read that info aren't really orthodox.)

• As Gepard suggested, the string 'exported' can be used in case we find out that it's an exported copy.

• The current git HEAD is quite weak, as it only reports the SHA1 of the current refs/remotes/origin/master, which isn't necessarily the currently running version, but it assumes that (those are probably valid for many users, but not necessarily):

  • The current branch pulls from origin/master
  • The user never runs git fetch, but only git pull, and never does so on other branches
  • The user never uses git checkout

  It is also true that, both now and if we fix that to detect the version of the current HEAD, it may lead to a SHA1 that's not part of the official repository, in case the user has committed changes to their own working copy.

• I'd like to add: our method to detect the current version only does so at runtime, and, in case the sources are an older version than the working copy (i.e. ony the scripts are updated, and the sources haven't been recompiled and/or make install has been used - when and if it'll ever be working), it's not necessarily the correct info we want. I'd like to see the version detection in two different places: one at runtime as it is now, and the other in the build script, so that it gets hardcoded as a string in the compiled executable. I can do this last part for the unix build system for both git and svn, but I have no idea about how to add it to the Visual Studio builds.

chrif.h

Fully Integrated.

buyingstore.h

Fully Integrated.

Battlegrounds Queue

• Enable party/guild support (existent but disabled) and add the splitting algorithm, as Shikazu drafted ( staff link; http://hercules.ws/board/topic/1192-bg-queue-splitting-teams/ )
• in battlegrounds.c bg_canqueue gdelay_var and arena->delay_var checks are checking against time() instead of time()+proper_setting
• script->hq[arena->queue_id].items is apparently not being cleared (after one bg takes place users get their position as if the previous queue was still in place), even though it is thrown in queue delete (might be a queue problem instead of the bg)
• the feature should save your position when you're warped into the bg and warp you back when it ends ( no support for this is currently present )
• when you're in a queue the client has a window displaying your position and a 'leave' button (beside the windows close button), this button is currently doing nothing while it should get you out of the queue.

( taken from http://hercules.ws/board/topic/1302-bg-queue-debug/ )

missing official map flags for maptypeproperty2

clif.c

void clif_maptypeproperty2(struct block_list *bl,enum send_target t) {
    struct packet_maptypeproperty2 p;

    p.PacketType = maptypeproperty2Type;
    p.type = 0x28;
    p.flag.usecart = 1;
    p.flag.party = 1;
    p.flag.guild = 1;
    p.flag.siege = map_flag_gvg2(bl->m) ? 1: 0;
    p.flag.mineffect = 1;
    p.flag.nolockon = 0;
    p.flag.countpk = map[bl->m].flag.pvp ? 1 : 0;
    p.flag.nopartyformation = 0;
    p.flag.noitemconsumption = 0;
    p.flag.summonstarmiracle = 0;
    p.flag.bg = map[bl->m].flag.battleground ? 1 : 0;

    clif->send(&p,sizeof(p),bl,t);
}

as its visible the ones with 0 are missing mapflags, some with a straight 1 could be made into mapflags too (e.g. usecart)

guild.h

Fully Integrated.

Result value of timers is unused

timer.c::do_timer

        if( timer_data[tid].func ) {
            if( diff < -1000 )
                // timer was delayed for more than 1 second, use current tick instead
                timer_data[tid].func(tid, tick, timer_data[tid].id, timer_data[tid].data);
            else
                timer_data[tid].func(tid, timer_data[tid].tick, timer_data[tid].id, timer_data[tid].data);
        }

timer.h

typedef int (*TimerFunc)(int tid, unsigned int tick, int id, intptr_t data);

mapreg.h

No Integration at all, missing.

Missing Header

https://github.com/HerculesWS/Hercules/blob/master/npc/quests/mage_solution.txt

File has no header.

HCache key into a #define

Gepard proposed turning HCache's 1-byte key (currently 'k') into a define, so its not hardcoded in multiple areas as it currently is

battle.h

Fully Integrated.

date.h

Currently no integration at all

Update SQL item database

As pointed out in b543724#commitcomment-3821265 I haven't updated the SQL file to match the item_db (pre-re) changes in b543724.

The current SQL scripts were generated by PhpMyAdmin, which I don't have installed (nor I plan to, for various reasons), If I were to do it with mysqldump, I'd cause an unnecessary amount of line changes due to a different MySQL syntax.

I'm leaving this here as a reminder, for anyone who has the needed software installed and can update the file (@shennetsind?).

Thank you.

Tombstone of Lord Of Death

The tombstone of Lord Of Death in niflheim map is not working. I already set the monster.conf in mvp_tomb_enabled to yes. Please confirm. Thank you

SC__STRIPACCESSARY: Using non-bitmask enumeration in bitwise operations

I found this part when I was exploring enum code a bit:

    case SC__STRIPACCESSARY:
        if( sd ) {
            int i = -1;
            if( !(sd->bonus.unstripable_equip&EQI_ACC_L) ) {
                i = sd->equip_index[EQI_ACC_L];
                if( i >= 0 && sd->inventory_data[i] && sd->inventory_data[i]->type == IT_ARMOR )
                    pc->unequipitem(sd,i,3); //L-Accessory
            } if( !(sd->bonus.unstripable_equip&EQI_ACC_R) ) {
                i = sd->equip_index[EQI_ACC_R];
                if( i >= 0 && sd->inventory_data[i] && sd->inventory_data[i]->type == IT_ARMOR )
                    pc->unequipitem(sd,i,3); //R-Accessory
            }
            if( i < 0 )
                return 0;
        }

EQI_* is not a bitmask, so I guess it's used improperly here.

Quick references lookup backs it up as well:

Solution
    C:\Users\gepard\Documents\GitHub\HerculesWS\Hercules\vcproj-10\map-server.vcxproj
        C:\Users\gepard\Documents\GitHub\HerculesWS\Hercules\src\map\status.c
            status_change_start (6755):    if(sd->bonus.unstripable_equip&EQP_WEAPON)
            status_change_start (6772):    if(sd->bonus.unstripable_equip&EQP_SHIELD)
            status_change_start (6784):    if(sd->bonus.unstripable_equip&EQP_ARMOR)
            status_change_start (6796):    if(sd->bonus.unstripable_equip&EQP_HELM)
            status_change_start (6868):    if( !(sd->bonus.unstripable_equip&EQI_ACC_L) ) {
            status_change_start (6872):    } if( !(sd->bonus.unstripable_equip&EQI_ACC_R) ) {
        C:\Users\gepard\Documents\GitHub\HerculesWS\Hercules\src\map\pc.c
            pc_bonus (2649):    sd->bonus.unstripable_equip |= EQP_WEAPON;
            pc_bonus (2654):    sd->bonus.unstripable_equip |= EQP_ARMOR;
            pc_bonus (2658):    sd->bonus.unstripable_equip |= EQP_HELM;
            pc_bonus (2662):    sd->bonus.unstripable_equip |= EQP_SHIELD;
            pc_readparam (7260):    case SP_UNSTRIPABLE_WEAPON: val = (sd->bonus.unstripable_equip&EQP_WEAPON)?1:0; break;
            pc_readparam (7263):    val = (sd->bonus.unstripable_equip&EQP_ARMOR)?1:0;
            pc_readparam (7265):    case SP_UNSTRIPABLE_HELM: val = (sd->bonus.unstripable_equip&EQP_HELM)?1:0; break;
            pc_readparam (7266):    case SP_UNSTRIPABLE_SHIELD: val = (sd->bonus.unstripable_equip&EQP_SHIELD)?1:0; break;
        C:\Users\gepard\Documents\GitHub\HerculesWS\Hercules\src\map\pc.h
            _struct_4296bde2_296_6e (327):    unsigned short unstripable_equip;

mail.h

Fully Integrated.