//===== rAthena Documentation ================================

//= Source Documentation

//===== By: ==================================================
//= rAthena Dev Team
//===== Last Updated: ========================================
//= 20140218
//===== Description: =========================================
//= Explanation of source behaviours and structures.
//============================================================

This file provides basic information about rAthena's source code.

The format of this file is as follows:
1. Glossary
2. Intro & Emulation
3. Interface and Communications
4. Databases and Independence
5. Package and Module Purposes
6. Nomenclature
7. Variable Notes
8. Building
9. Atcommands & Script Commands

===============
| 1. Glossary |
===============
The following terms will be frequently used throughout this file, so it is
important to have a thorough understanding of what they are to avoid confusion.

Term Description
---- -----------
serv a program/daemon that runs indefinitely offering a service
host a machine that has one or more servs running
command a request of an action on the server or client
(atcommand, script_command, packet_request)
interface a class/module that offers a list of commands

========================
| 2. Intro & Emulation |
========================
rAthena is an emulation of Ragnarok Online, which runs on software known as AEGIS.
AEGIS is separated into 4 servs:

Serv Description
---- -----------
account handles player account information and logins.
char handles character data (persistent information).
inter handles broadcasting across map-serv. [merged into rAthena's char-
serv]
map handles all player runtime actions.

These servs are an aggregation of each other:

login-serv => 1 - * char-serv, 1 - * map-serv

In this case, * is 30. This means that 1 login-serv is able to manage up to

30 char-serv, which itself can manage up to 30 map-serv. Note that due to these
aggregations, the login-serv and map-serv never directly communicate with each
other.

===================================
| 3. Interface and Communications |
===================================
We have 3 types of communication:

1. serv <=> serv (AH,HA,HZ,ZH)

This type of server-to-server communication is referred to as "inter-serv"
communication.

2. serv <=> client (AC,CA,HC,CH,ZC,CZ)

This is what our servs send or receive to a player client.

3. serv <=> console/terminal

This is the only kind of communication which doesn't use packets (currently).
It's only done in localhost from console to servs (a way to input args in
servs runtime).

The packet notation and structure are well defined in

'doc/packet_struct_notation.txt'.

Note that scripts and atcommands are another kind of interface, as they allow
users to input data into the serv.

=================================
| 4. Databases and Independence |
=================================
Each server can theoretically be set in a different host with its own databases
associated (although this is currently broken due to years without documentation).
In other words, you shouldn't expect to find char-serv data on a map-serv host
and access it directly, but rather ask the char-serv to fetch it.

The list below details the association of database tables with the servs.
For real table names, see 'conf/inter_athena.conf'.

==============
| Login-serv |
==============

Table Contents
----- --------
login_db all account-related information
reg_db permanent account variables (ex. #CASHPOINTS)

=============
| Char-serv |
=============

Table Contents
----- --------
char_db all char-related information
hotkey_db hotkeys set for each character
scdata_db character status at disconnection
cart_db list of items in each character's cart
inventory_db list of items in each character's inventory
charlog_db char-serv logs
storage_db list of items in each character's storage (Kafra)
reg_db permanent character variables (ex. ADVJOB)
skill_db character learned skill database
interlog_db inter-serv logs
memo_db character Memo_point database
 guild_db guild record (name, master, lv, exp, emblem, etc.)
guild_alliance_db guild relations database (allies, enemies)
guild_castle_db guild owned castle database
guild_expulsion_db guild expulsion logs
guild_member_db guild current member titles and positions
guild_skill_db guild learned skills database
guild_position_db guild positions configuration (names, taxes, rights)
guild_storage_db guild item storage
party_db party record (name, leader, shared_exp, shared_item)
pet_db saved pet objects database
friend_db character friends database
mail_db mail database
auction_db auction database
quest_db character quest realisation database
homunculus_db saved homunculus objects database
skill_homunculus_db homunculus learned skills database
mercenary_db saved mercenary objects database (HP, SP, level, etc.)
mercenary_owner_db character proprietary link to mercenary object save and use
stats
elemental_db saved Elemental objects database (HP, SP, FLEE, etc.)
ragsrvinfo_db map-serv rate record (similar to 'conf/battle/drop.conf',
possibly a leftover?)
skillcooldown_db character skill cooldowns at disconnection
bonus_script_db character bonus_script at disconnection

============
| Map-serv |
============

Table Contents
----- --------
mapreg_db permanent map-serv global variables (ex.
$agit_result_timer)
buyingstore_db live buyers database (map_pos, aid, shop title, etc.)
buyingstore_items_db items currently being purchased by live buyers
vending_db live vendors database (map_pos, aid, shop title, etc.)
vending_items_db items currently being sold by live vendors

The tables below are optional alternatives to TXT databases located in

'db/*.txt'.

item_db item database (Pre-Renewal)

item_db_re item database (Renewal)
item_db2 item database import (Pre-Renewal)
item_db2_re item database import (Renewal)
item_cash_db cash shop database
item_cash_db2 cash shop database (import)
mob_db monster database (Pre-Renewal)
mob_db_re monster database (Renewal)
mob_db2 monster database import (Pre-Renewal)
mob_db2_re monster database import (Renewal)
mob_skill_db monster skill database (Pre-Renewal)
mob_skill_db_re monster skill database (Renewal)
mob_skill_db2 monster skill database import (Pre-Renewal)
mob_skill_db2_re monster skill database import (Renewal)

==================================
| 5. Package and Module Purposes |
==================================
The following list describes each module and its purpose.

============
| 3rdparty |
============
The '3rdparty/' folder contains libraries used by the project but are not
maintained by us.

==========
| Common |
==========
The 'src/common' folder contains all the modules which are used by more then 1
serv.

Module Description
------ -----------
cbasetypes adapter to OS and arch specification (function name, bit
representation)
cli console Line Interface handling (get arguments from terminal at
beginning and runtime)
conf facade of libconfig api
core MAIN program entry (initialization of each serv starts here)
db database module (create, parse, and destroy databases)
des Data Encryption Standard algorithm modified for rAthena
ers Entry Reusage System to help memory allocation
grfio handles *.grf files (searches for files in them and decodes them)
malloc handles runtime memory allocation (so that memory manager could
check for leaks)
mapindex handles the processing and reading of the mapcache.dat
md5calc offers md5 encryption
mmo.hpp common structures and defines across serv
msg_conf handles msg in src from configuration
nullpo checks and dumps info for debug mode
random generation of random numbers
showmsg display messages in console with a certain color
socket handling of sockets (listening, close, open, etc.)
sql.cpp MySQL database proxy
strlib.cpp string handling
timer.cpp timer-related functions
utils.cpp misc functions
winapi.hpp Windows redefine and include

==============
| Login-serv |
==============

Module Description
------ -----------
account persistence for account data
ipban offers IP banishment
login main module of login-serv
loginclif client <=> login-serv connections interface (send and receive
packets to/from client)
loginchrif char-serv <=> login-serv connections interface (send and
receive packets to char-serv)
logincsnlif console <=> login-serv connections interface (send and receive
packets to/from console (internal buffer))
loginlog records all operations into log for login-serv
 =============
| Char-serv |
=============
The char-serv is responsible for persistence (save/load data permanently) and
also serves as a controller that handles all associated map-servs. Further, it
is responsible for ensuring that there are no duplicate party names among the
map-servs (which could create conflicts if a party transfers map-servs).

Module Description
------ -----------
char currently holds all the char-serv (EA) process
-- char_clif client <=> char-serv connections interface (send and receive
packets to/from client)
-- char_csnlif console <=> char-serv connections interface (send and receive
packets to/from console (internal buffer))
-- char_mapif map-serv <=> char-serv connections interface (send and receive
packets to map-serv)
-- char_logif login-serv <=> char-serv connections interface (send and
receive packets to login-serv)
inter main entry to inter-serv; delegates packet handling to
submodules
-- int_auction handles auction request and saving
-- int_elemental handles elemental data (BL_ELE => Sorcerer mob)
-- int_guild handles guild data (creation, destruction, add member, etc.)
-- int_homun handles homunculus data (BL_HOM => Alchemist mob)
-- int_mail handles mail data
-- int_mercenary handles mercenary data (BL_MER => All class mob)
-- int_party handles party data (creation, destruction, add member, etc.)
-- int_pet handles pet data (BL_PET => All class mob)
-- int_quest handles quest data
-- int_storage handles storage data (save storage, load storage, etc.)

============
| Map-serv |
============

Module Description
------ -----------
atcommand handles GM commands (ex. @who)
battle handles damage calculation where target is enemy and battle
configuration settings
battleground functions for Battleground system (create, destroy, messaging,
join, etc.)
buyingstore functions for player Buying Stores (create, search, sell)
cashshop functions to set up the server cashshop (from cashshop_db), and
contains function to buy items from cashshop
channel functions for the channel system (create, delete, join/auto-join,
leave, broadcast, alter options)
chat functions for the chatroom system (create, delete, trigger
chatroom_event, change owner, etc.)
chrif char-serv <=> map-serv connections interface (send and receive
packets to char-serv)
clif client <=> map-serv connections interface (send and receive
packets to/from client)
date functions for time
duel functions for the duel system
elemental functions for Sorcerer Elementals processing (create, delete,
etc.)
guild functions for the guild system
 homunculus functions for Alchemist Homunculi processing (create, delete, get
stats, death, etc.)
instance functions for instance system
intif map-serv <=> inter-serv interface (meant to communicate with
'char/inter.cpp' or its submodules)
itemdb functions for the item database
log functions for server log system
mail functions for mail system
map map-serv main module, and a representation of a map object
adds or removes other objects into map (blocklist) and provides
iterators (ex. map_foreachpc)
mapreg functions to save or read variables in mapreg_db (global variables
for all map-serv)
mercenary functions for Mercenary system (create, search, get stats, dead)
mob functions for mob data, structures, and mob routines
npc functions for NPC data (create, delete, calling NPCs)
npc_chat functions for PCRE and NPC interaction
party functions for the party system (create, join, delete, alter
options, etc.)
path functions for path finding (check_distance, search path unit will
use)
pc functions for player processing (loot/drop/delete items, player
bonus handling, player dead, etc.)
pc_groups functions for players groups system (manage player permissions and
atcommand access)
pet functions for the pet system (similar to mercenary, homunculus,
player, etc.)
quest functions for the quest log system (add, complete, remove, etc.)
script handles script language logic (used in NPC scripts), script
commands, and mapflags
searchstore functions for the Vendor Shop Search feature
skill functions for skills (skill_casttime calculation, skill
behaviours, skill_chk_cast, requirement checks, 'db/skill_*.txt' processing)
status functions for statuses on a bl (add, remove, calculation of
effects as a temporary bonus)
status is a struct available by most units as common attributes
(bl_type only attribute are dealt in bl specific files, like 'pc.cpp' or 'mob.cpp')
storage functions for the storage system: Kafra, cart, guild, inventory
(add, transfer, remove items between containers)
also ensures container mutex (e.g. guild_storage) and
preparation for save requests
trade functions to perform a trade (request, accept, add items/Zeny,
checks, complete trade)
unit functions for controlling player/mob/NPC actions (walk, follow,
skill use)
vending functions for Merchant Vending (create, purchase)

===================
| 6. Nomenclature |
===================
The following are standard naming conventions used by rAthena.

Type Prefix Example

---- ------ -------
function module_ pc_addspiritball -> located in pc.cpp file
structure s_ s_quest_db
enum e_ e_race
status SC_ SC_INTOABYSS
skill classmid_ AL_TELEPORT -> AL = Acolyte
 bonus SP_ SP_ATK_RATE

NOTES:
- If a status name conflicts with a skill name, another '_' is added (e.g.
SC__WEAKNESS).
- All constants should be written in all caps.
- battle_config vs. #define macro:
battle_config can be changed during runtime (ex. @setbattleflag), but this
requires
more processing and could render the server less stable than a macro would.

=====================
| 7. Variable Notes |
=====================
The following variables are commonly used in the source code.

Variable Full Name Description

-------- --------- -----------
sd session data represents the session of a client into a serv
(login, char, or map)
tsd target sd same as sd, but for a target
pl_sd usually in an iteration loop, the current sd of
index
it_sd a variant of pl_sd (for iter_sd)
fd file descriptor a link to an I/O like a socket or file
md mob data represents monster information; also used to
represent mercenary information
hd homunculus data represents homunculus information
nd NPC data represents NPC information
ed elemental data represents elemental information
pd pet data represents pet information
sc status change a structure containing all the possible status
applied to a character
tsc target sc same as sc, but for a target
sce status change entry represents data of a specific inflicted status
bl blocklist common data of one object (a skill, pet, player,
etc); also represents a 2-way chain-link
tbl target bl same as bl, but for a target
st script stack the stack of an NPC
aid account id a player account ID
gid game id the general unique ID of a Unit, which is the aid
for players
(since a single character per account can be
connected at one time)
cid character id a player character ID
rid character id a variant of cid
su skill unit a skill with a unit that remains on the ground

===============
| 8. Building |
===============
When adding a new src file or library (new.cpp and its header, new.hpp), you'll
also
need to update the following files to fully integrate it into the project so that
users can compile it.

There are 3 ways to compile the project:

> configure + makefile (requires POSIX environment + C compiler)

 This flow is mainly used by Linux users, but can be done in any POSIX environment
(ex. Windows + Cygwin).
- Configure.in: Template file to generate the configure script by autoconf.
- Makefile.in: Template makefile to generate the real makefile according to
configure. Each subfolder needs its own makefile.
- Makefile: File filled with rules for gcc to compile folder.
The sequence is as follows:
1) configure.in => configure by autoconf ('autoconf configure.in >
configure')
2) configure => Makefile by Makefile.in
3) Makefile => binary by 'make all' or alternative

> cmake (requires C compiler + cmake)

- CmakeList: Comparable to Makefile, but in a more cross-OS way.
The sequence is as follows:
1) Define which toolchain to use, acting like a configure ('cmake -G "Unix
Makefiles"' or 'cmake -G "Visual Studio 10"')
2) Enter the build folder where the Makefiles are generated and launch 'make
install' to produce binaries from them

> sln (requires Visual Studio)

- *.sln: Solution project for Visual Studio (Windows).

See https://github.com/rathena/rathena/wiki/compiling for more detailed compilation

instructions.

===================================
| 9. Atcommands & Script Commands |
===================================
To implement an atcommand or script command, you must define a function and
add its reference to the appropriate array. See the files in 'src/custom/'
for examples.

Atcommands
----------
ACMD_FUNC(name)
{
<code>
}

ACMD_DEF(name) - OR - ACMD_DEFR(name,restriction)
- OR -
ACMD_DEF2("alias",name) - OR - ACMD_DEF2R("alias",name,restriction)

Restriction Description
----------- -----------
1 restrict usage in console
2 restrict usage in script_command

Script Commands
---------------
BUILDIN_FUNC(name)
{
<code>
}

BUILDIN_DEF(name,"arguments")
- OR -
BUILDIN_DEF2(name,"alias","arguments")
 Argument Description
-------- -----------
i integer
s string
v variable
l label
r reference (of a variable)
? optional parameter (one)
* optional parameter (unknown count)
null (no arguments)

Useful functions:
script_hasdata(st,i); // Returns if the stack contains data at the target
index
script_getdata(st,i); // Returns the script_data at the target index (data
is a glob type)
script_getnum(st,val); // Returns the int at the target index
script_getstr(st,val); // Returns the string at the target index
script_getref(st,val); // Returns the reference of a variable at the target
index (useful for arrays, ex. 'checkweight2')
script_getfuncname(st); // Returns the current function name (useful for
function variants, ex. 'sc_start')
script_pushint(st,val); // Pushes an int into the stack
script_pushstr(st,val); // Pushes a string into the stack
script_isstring(st,i); // Returns if the data at at the target index is a
string
script_isint(st,i); // Returns if the data at at the target index is an
int