//===== 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) { } 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) { } 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