Scripts are loaded by the map server as referenced in the 'conf/map_athena.conf' configuration file, but in the default configuration, it doesn't load any script files itself. Instead, it loads the file 'npc/scripts_main.conf' which itself contains references to other files. The actual scripts are loaded from txt files, which are linked up like this:
npc: <path to a filename>
Any line like this, invoked, ultimately, by 'map_athena.conf' will load up the script contained in this file, which will make the script available. No file will get loaded twice, to prevent possible errors.
Another configuration file option of relevance is:
delnpc: <path to a filename>
This will unload a specified script filename from memory, which, while seemingly useless, may sometimes be required.
Whenever '//' is encountered in a line upon reading, everything beyond this on that line is considered to be a comment and is ignored. This works wherever you place it.
// This line will be ignored when processing the script.
Block comments can also be used, where you can place /* and */ between any text you wish rAthena to ignore.
/* This text,
* no matter which new line you start
* is ignored, until the following
* symbol is encountered: */
/* The leading *
in front of each line is a personal preference,
and is not required.*/
Most scripting commands and functions will want to request data about a character, store variables referenced to that character, send stuff to the client connected to that specific character. Whenever a script is invoked by a character, it is passed a so-called RID - this is the account ID number of a character that caused the code to execute by clicking on it, walking into its OnTouch zone, or otherwise.
If you are only writing common NPCs, you don't need to bother with it. However, if you use functions, if you use timers, if you use clock-based script activation, you need to be aware of all cases when a script execution can be triggered without a RID attached. This will make a lot of commands and functions unusable, since they want data from a specific character, want to send stuff to a specific client, want to store variables specific to that character, and they would not know what character to work on if there's no RID.
Unless you use 'attachrid' to explicitly attach a character to the script first.
Whenever we say 'invoking character', we mean 'the character who's RID is attached to the running script. The script function "playerattached" can be used to check which is the currently attached player to the script (it will return 0 if the there is no player attached or the attached player no longer is logged on to the map-server).
GID stands for the Game ID of something, this can either be the GID obtained through mobspawn (mob control commands) or the account ID of a character. Another way would be to right click on a mob, NPC or char as GM sprited char to view the GID.
This is mostly used for the new version of skill and the mob control commands implemented.
Each item in the item database has three special fields - Script , OnEquip_Script and OnUnequip_Script. The first is script code run every time a character equips the item, with the RID of the equipping character. Every time they unequip an item, all temporary bonuses given by the script commands are cleared, and all the scripts are executed once again to rebuild them. This also happens in several other situations (like upon login) but the full list is currently unknown.
OnEquip_Script is a piece of script code run whenever the item is used by a character by double-clicking on it. OnUnequip_Script runs whenever the equipment is unequip by a character
Not all script commands work properly in the item scripts. Where commands and functions are known to be meant specifically for use in item scripts, they are described as such.
Every pet in the pet database has a PetScript field, which determines pet behavior. It is invoked wherever a pet of the specified type is spawned. (hatched from an egg, or loaded from the char server when a character who had that pet following them connects) This may occur in some other situations as well. Don't expect anything other than commands definitely marked as usable in pet scripts to work in there reliably.
Beside the common decimal numbers, which are nothing special whatsoever (though do not expect to use fractions, since ALL numbers are integer in this language), the script engine also handles hexadecimal numbers, which are otherwise identical. Writing a number like '0x<hex digits>' will make it recognized as a hexadecimal value. Notice that 0x10 is equal to 16. Also notice that if you try to 'mes 0x10' it will print '16'. Number values can't exceed the limits of an integer variable: Any number greater than INT_MAX (2147483647) or smaller than INT_MIN (−2147483648) will be capped to those values and will cause a warning to be reported.
.@var = 1;
.@var = -219;
.@var = 0xFF0000;
NOTE: DO NOT use quote (" ... ") for number!