From 1d77a9f6ff0d8adec7240a593851a9617d13358a Mon Sep 17 00:00:00 2001
From: Euphy <euphy.raliel@rathena.org>
Date: Sat, 15 Feb 2014 21:15:18 -0500
Subject: [PATCH] Added documenation providing an overview of rAthena's source
code. (credits: @lighta, @aleos89) This is not comprehensive by any means,
but gives some basic explanation of how rAthena works. Other topics will
likely be added at a later date.
Signed-off-by: Euphy <euphy.raliel@rathena.org>
---
doc/source_doc.txt | 432 +++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 432 insertions(+)
create mode 100644 doc/source_doc.txt
diff --git a/doc/source_doc.txt b/doc/source_doc.txt
new file mode 100644
index 0000000000..62745fc710
--- /dev/null
+++ b/doc/source_doc.txt
@@ -0,0 +1,432 @@
+//===== rAthena Documentation ================================
+//= Source Documentation
+//===== By: ==================================================
+//= rAthena Dev Team
+//===== Last Updated: ========================================
+//= 20140215
+//===== 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 |
+ ============
+ Except for mapreg_db, vending_db, and vending_items_db, the other map-serv
+ tables are optional alternatives to TXT databases located in 'db/*.txt'.
+
+ Table Contents
+ ----- --------
+ mapreg_db permanent map-serv global variables (ex. $agit_result_timer)
+ vending_db live vendors database (map_pos, aid, shop title, etc.)
+ vending_items_db items currently being sold by live vendors
+
+ 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
+ ------ -----------
+ atomic adapter to atomic operations for Windows API
+ 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
+ evdp handles events
+ 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
+ mempool handles shared memory pool for thread support
+ mmo.h common structures and defines across serv
+ msg_conf handles msg in src from configuration
+ mutex handles Mutual exclusion (Mutex) for thread support
+ netbuffer iobuffer initialisation for thread support
+ network updated socket module, with ipv6 and thread support
+ nullpo checks and dumps info for debug mode
+ raconf processes the conf files
+ random generation of random numbers
+ showmsg display messages in console with a certain color
+ socket handling of sockets (listening, close, open, etc.)
+ spinlock handles synchronization (waiting loop) for thread support
+ sql.c MySQL database proxy
+ strlib.c string handling
+ thread.c thread creation and destruction
+ timer.c timer-related functions
+ utils.c misc functions
+ winapi.h Windows redefine and include
+
+ ==============
+ | Login-serv |
+ ==============
+
+ Module Description
+ ------ -----------
+ account persistence for account data
+ ipban offers IP banishment
+ login main module of login-serv
+ 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
+ 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.c' 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.c' or 'mob.c')
+ 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.c 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.c and its header, new.h), 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 http://rathena.org/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