From 95f86d39a26edbcf52008ae76b87f950daa9978c Mon Sep 17 00:00:00 2001 From: Andrei Karas Date: Sun, 5 Oct 2014 11:34:32 +0300 Subject: Remove conf dir. --- doc/script_commands.txt | 10363 ---------------------------------------------- 1 file changed, 10363 deletions(-) delete mode 100644 doc/script_commands.txt (limited to 'doc/script_commands.txt') diff --git a/doc/script_commands.txt b/doc/script_commands.txt deleted file mode 100644 index db851128f..000000000 --- a/doc/script_commands.txt +++ /dev/null @@ -1,10363 +0,0 @@ -//===== Hercules Documentation =============================== -//= Hercules Script Commands -//===== By: ================================================== -//= Hercules Dev Team -//===== Description: ========================================= -//= A reference manual for the Hercules scripting language. -//= Commands are sorted depending on their functionality. -//============================================================ - -This document is a reference manual for all the scripting commands and -functions available in current Hercules GIT. It is not a simple tutorial. -When people tell you to "Read The F***ing Manual", they mean this. - -The information was mostly acquired through looking up how things actually -work in the source code of the server, which was written by many people -over time, and lots of them don't speak English and never left any notes - -or are otherwise not available for comments. As such, anything written in -here might not be correct, it is only correct to the best of our -knowledge, which is limited. - -This is not a place to teach you basic programming. This document will not -teach you basic programming by itself. It's more of a reference for those -who have at least a vague idea of what they want to do and want to know -what tools they have available to do it. We've tried to keep it as simple -as feasible, but if you don't understand it, getting a clear book on -programming in general will help better than yelling around the forum for -help. - -A little learning never caused anyone's head to explode. - -Structure ---------- - -The commands and functions are listed in no particular order: - -*Name of the command and how to call it. - -Descriptive text - - Small example if possible. Will usually be incomplete, it's there just - to give you an idea of how it works in practice. - -To find a specific command, use Ctrl+F, (or whatever keys call up a search -function in whatever you're reading this with) put an * followed by the -command name, and it should find the command description for you. - -If you find anything omitted, please tell us. :) - -Syntax ------- - -Throughout this document, wherever a command wants an argument, it is -given in . This doesn't mean you should type the angle -brackets. :) If an argument of a command is optional, it is given in -{curly brackets}. You've doubtlessly seen this convention somewhere, if -you didn't, get used to it, that's how big boys do it. If a command can -optionally take an unspecified number of arguments, you'll see a list like -this: - -command({, ...}) - -This still means they will want to be separated by commas. - -Where a command wants a string, it will be given in "quotes", if it's a -number, it will be given without them. Normally, you can put an -expression, like a bunch of functions or operators returning a value, in -(round brackets) instead of most numbers. Round brackets will not always -be required, but they're often a good idea. - -Wherever you refer to a map, use 'mapname' instead of 'mapname.gat'. - - -Script loading structure ------------------------- - -Scripts are loaded by the map server as referenced in the -'npc/(pre-)re/scripts_main.conf' configuration file. - -The file contains a list of scripts to be loaded (or other configuration files -to be parsed, through the @include directive), in the following format: - -npc_global_list: ( - "npc/path/to/the/script/to/load.txt", - "npc/other/file.txt", -@include "npc/other_configuration_file.conf" -) - -Any script will only get loaded once even if specified twice, to prevent -possible errors. - -It's possible to specify scripts to exclude from loading, by inserting them -(using the same syntax) in the list available in npc/scripts_removed.conf: - -npc_removed_list: ( - "npc/path/to/the/file/to/skip.txt", -) - -Script file format ------------------- - -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 Hercules to ignore. - -Example: -/* This text, - * no matter which new line you start - * is ignored, until the following - * symbol is encountered: */ - -The asterisks (*) in front of each line is a personal preference, and is -not required. - -Upon loading all the files, the server will execute all the top-level -commands in them. No variables exist yet at this point, no commands can be -called other than those given in this section. These commands set up the -basic server script structure - create NPC objects, spawn monster objects, -set map flags, etc. No code is actually executed at this point except -them. The top-level commands the scripting are pretty confusing, since -they aren't structured like you would expect commands, command name first, -but rather, normally start with a map name. - -What's more confusing about the top-level commands is that most of them -use a tab symbol to divide their arguments. - -To prevent problems and confusion, the tab symbols are written as '%TAB%' -or '' throughout this document, even though this makes the text a bit -less readable. Using an invisible symbol to denote arguments is one of the -bad things about this language, but we're stuck with it for now. :) - -Here is a list of valid top-level commands: - -** Set a map flag: - -%TAB%mapflag%TAB% - -This will, upon loading, set a specified map flag on a map you like. These -are normally in files inside 'npc/mapflag' and are loaded first, so by the -time the server's up, all the maps have the flags they should have. Map -flags determine the behavior of the map regarding various common problems, -for a better explanation, see 'setmapflag'. - -** Create a permanent monster spawn: - -,,,,%TAB%monster%TAB%%TAB%,,,,{,,} - -Map name is the name of the map the monsters will spawn on. X,Y are the -coordinates where the mob should spawn. If X's and Y's are non-zero, they -specify the 'radius' of a spawn-rectangle area centered at x,y. Putting -zeros instead of these coordinates will spawn the monsters randomly. Note -this is only the initial spawn zone, as mobs random-walk, they are free to -move away from their specified spawn region. - -Monster name is the name the monsters will have on screen, and has no -relation whatsoever to their names anywhere else. It's the mob id that -counts, which identifies monster record in 'mob_db.txt' database of -monsters. If the mob name is given as "--ja--", the 'japanese name' field -from the monster database is used, (which, in Hercules, actually contains -an English name) if it's "--en--", it's the 'english name' from the -monster database (which contains an uppercase name used to summon the -monster with a GM command). - -Amount is the amount of monsters that will be spawned when this command is -executed, it is affected by spawn rates in 'conf/map/battle.conf'. - -Delay1 and delay2 control monster respawn delays - the first one is the -fixed base respawn time, and the second is random variance on top of the -base time. Both values are given in milliseconds (1000 = 1 second). Note -that the server also enforces a minimum respawn delay of 5 seconds. - -You can specify a custom level to use for the mob different from the one -of the database by adjoining the level after the name with a comma. eg: -"Poring,50" for a name will spawn a monster with name Poring and level 50. - -Event is a script event to be executed when the mob is killed. The event -must be in the form "NPCName::OnEventName" to execute, and the event name -label should start with "On". As with all events, if the NPC is an -on-touch NPC, the player who triggers the script must be within 'trigger' -range for the event to work. - -There are two optional fields for monster size and AI. Size can be 0 -(medium), 1 (small), or 2 (big). AI can be 0 (default), 1 -(attack/friendly), 2 (sphere), 3 (flora), or 4 (zanzou). - -Alternately, a monster spawned using 'boss_monster' instead of 'monster' is able to be -detected on the map with the SC_CASH_BOSS_ALARM status (used by Convex Mirror, item ID# 12214). -A monster spawned using 'miniboss_monster' is spawn monster as mini boss view. - -** NPC names - -/!\ WARNING: this applies to warps, NPCs, duplicates and shops /!\ - -NPC names are kinda special and are formatted this way: - -{::} - -All NPCs need to have a unique name that is used for identification -purposes. When you have to identify a NPC by it's name, you should use -. If is not provided, use -instead. - -The client has a special feature when displaying names: if the display -name contains a '#' character, it hides that part of the name. -Ex: if your NPC is named 'Hunter#hunter1', it will be displayed as 'Hunter' - - must be at most 24 characters in length. - must be at most 24 characters in length. - -** Define a warp point - -,,{,}%TAB%warp%TAB%%TAB%,,,, - -This will define a warp NPC that will warp a player between maps, and -while most arguments of that are obvious, some deserve special mention. - -SpanX and SpanY will make the warp sensitive to a character who didn't -step directly on it, but walked into a zone which is centered on the warp -from coordinates and is SpanX in each direction across the X axis and -SpanY in each direction across the Y axis. - -Warp NPC objects also have a name, because you can use it to refer to them -later with 'enablenpc'/'disablenpc'. - -Facing of a warp object is irrelevant, it is not used in the code and all -current scripts have a zero in there. - -** Define an NPC object. - -,,,%TAB%script%TAB%%TAB%,{} -,,,%TAB%script%TAB%%TAB%,,,{} - -This will place an NPC object on a specified map at the specified -location, and is a top-level command you will use the most in your custom -scripting. The NPCs are triggered by clicking on them, and/or by walking -in their trigger area, if defined. See that below. - -Facing is a direction the NPC sprite will face in. Not all NPC sprites -have different images depending on the direction you look from, so for -some facing will be meaningless. Facings are counted counterclockwise in -increments of 45 degrees, where 0 means facing towards the top of the map. -(So to turn the sprite towards the bottom of the map, you use facing 4, -and to make it look southeast it's facing 5.) - -Sprite is the sprite identifier used to display this particular NPC. For a -full list of sprite numbers see http://nn.ai4rei.net/dev/npclist/ as -well as doc/constants.md. -You may also use a monster's ID constant instead to display a monster sprite -for this NPC, in npcs that have view ids of mobs it's encouraged to use -OnTouch events with a 2,2 range and with an 'end' after the header to avoid -bugs (for more info on why see npc_click@map/npc.c). It is possible to use a job -sprite as well, but you must first define it as a monster sprite in 'mob_avail.txt', -a full description on how to do this is not in the scope of this manual. -A 'FAKE_NPC' sprite will make the NPC invisible (and unclickable). -A 'HIDDEN_NPC' sprite will make an NPC which does not have a sprite, but is -still clickable, which is useful if you want to make a clickable object of -the 3D terrain. - -TriggerX and triggerY, if given, will define an area, centered on NPC and -spanning triggerX cells in every direction across X and triggerY in every -direction across Y. Walking into that area will trigger the NPC. If no -'OnTouch:' special label is present in the NPC code, the execution will -start from the beginning of the script, otherwise, it will start from the -'OnTouch:' label. Monsters can also trigger the NPC, though the label -'OnTouchNPC:' is used in this case. If player left area npc will called -if present label 'OnUnTouch'. - -The code part is the script code that will execute whenever the NPC is -triggered. It may contain commands and function calls, descriptions of -which compose most of this document. It has to be in curly brackets, -unlike elsewhere where we use curly brackets, these do NOT signify an -optional parameter. - -** Define a 'floating' NPC object. - --%TAB%script%TAB%%TAB%FAKE_NPC,{} - -This will define an NPC object not triggerable by normal means. This would -normally mean it's pointless since it can't do anything, but there are -exceptions, mostly related to running scripts at specified time, which is -what these floating NPC objects are for. More on that below. - -** Define a shop/cashshop NPC. - --%TAB%shop%TAB%%TAB%,:{,:...} -,,,%TAB%shop%TAB%%TAB%,:{,:...} - -This will define a shop NPC, which, when triggered (which can only be done -by clicking) will cause a shop window to come up. No code whatsoever runs -in shop NPCs and you can't change the prices otherwise than by editing the -script itself (no variables even exist at this point of scripting, so -don't even bother trying to use them). - -The item id is the number of item in the 'item_db.txt' database. If Price -is set to -1, the 'buy price' given in the item database will be used. -Otherwise, the price you gave will be used for this item, which is how you -create differing prices for items in different shops. - -You can alternatively use "cashshop" in place of "shop" to use the Cash -Shop interface, allowing you to buy items with special points (Currently -stored as account vars in #CASHPOINTS and #KAFRAPOINTS). This -type of shop will not allow you to sell items at it, you may only purchase -items here. The layout used to define sale items still count, and -"" refers to how many points will be spent purchasing the them. - -** Define a trader NPC -,,,%TAB%trader%TAB%%TAB%,{} --%TAB%trader%TAB%%TAB%FAKE_NPC,{} - -All the standards that are valid to script objects are also valid for trader objects -(see ** Define an NPC object for more information). -This will define a trader NPC, which can cause a shop, cashshop or market window -to come up when clicked or called by other means. Unlike shop/cashshop NPCs this -type will run a code and can change the items that are being sold over time without -other NPC objects. -The types that a trader object can have are the following: -- NST_ZENY (0) Normal Zeny Shop (shop) -- NST_CASH (1) Normal Cash Shop (cashshop) -- NST_MARKET (2) Normal NPC Market Shop (where items have limited availability - and need to be refurbished) -- NST_CUSTOM (3) Custom Shop (any currency, item/var/etca, check sample) -- NST_BARTER (4) Barter Shop (each item with own item currency) -Unless otherwise specified via *tradertype an trader object will be defined as -NST_ZENY. - -Note: NST_MARKET is only available with PACKETVER 20131223 or newer. -Note: NST_BARTER is only available with PACKETVER 20181226 zero or newer. -See '12 - NPC Trader-Related Commands' and /doc/sample/npc_trader_sample.txt for -more information regarding how to use this NPC type. - -** Define an warp/shop/cashshop/NPC duplicate. - -warp: ,,{,}%TAB%duplicate(