You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
433 lines
21 KiB
Plaintext
433 lines
21 KiB
Plaintext
//===== 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
|