diff options
Diffstat (limited to 'doc/script_commands.txt')
| -rw-r--r-- | doc/script_commands.txt | 308 |
1 files changed, 254 insertions, 54 deletions
diff --git a/doc/script_commands.txt b/doc/script_commands.txt index 44937a34d..26a4fbfb8 100644 --- a/doc/script_commands.txt +++ b/doc/script_commands.txt @@ -247,8 +247,8 @@ increments of 45 degrees, where 0 means facing towards the top of the map. 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://kalen.s79.xrea.com/npc/npce.shtml as -well as db/constants.conf. +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 @@ -323,10 +323,12 @@ The types that a trader object can have are the following: - 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. @@ -536,7 +538,7 @@ suffix is 32. Some variables are special, that is, they are already defined for you by the scripting engine. You can see the full list somewhere in -'db/constants.conf', which is a file you should read, since it also +'doc/constants.md', which is a file you should read, since it also allows you to replace lots of numbered arguments for many commands with easier to read text. The special variables most commonly used are all permanent character-based variables: @@ -699,7 +701,7 @@ Variable References Hard-coded constants -------------------- Most of the constants defined by the scripting engine can be found in -'db/constants.conf' and have the same value independently of settings +'doc/constants.md' and have the same value independently of settings that are core related, but there are constants that can be used to retrieve core information that's set when the server is compiled. @@ -714,10 +716,11 @@ MAX_BANK_ZENY - Maximum Zeny in the bank MAX_BG_MEMBERS - Maximum BattleGround members MAX_CHAT_USERS - Maximum Chat users MAX_REFINE - Maximum Refine level +MAX_MENU_OPTIONS - Maximum NPC menu options +MAX_MENU_LENGTH - Maximum NPC menu string length Send targets and status options are also hard-coded and can be found -in src/map/script.c::script_hardcoded_constants or in functions that -currently use them. +in 'doc/constants.md'. Operators --------- @@ -1601,21 +1604,24 @@ perfectly equivalent. --------------------------------------- *select("<option>"{, "<option>", ...}) -*prompt("<option>"{, "<option>", ...}) This function is a handy replacement for 'menu' that doesn't use a complex -label structure. It will return the number of menu option picked, -starting with 1. Like 'menu', it will also set the variable @menu to -contain the option the user picked. +label structure. It will return the number of the menu option picked, +starting with 1. If the player presses cancel, the script is terminated. - if (select("Yes:No") == 1) + if (select("Yes", "No") == 1) mes("You said yes, I know."); And like 'menu', the selected option is consistent with grouped options and empty options. -'prompt' works almost the same as select, except that when a character -clicks the Cancel button, this function will return 255 instead. +--------------------------------------- + +*prompt("<option>"{, "<option>", ...}) + +This function behaves exactly like select(), but when a player presses cancel +it returns MAX_MENU_OPTIONS and the script is not terminated. You almost always +want to use select() rather than prompt(). --------------------------------------- @@ -1977,18 +1983,35 @@ prontera,150,150,0 script TestNPC 123,{ *is_function("<function name>") -This command checks whether a function exists. -It returns 1 if function is found, or 0 if it isn't. +This command checks whether or not a function exists and returns its type. +Returns false if it cannot be found. + +return values: + + FUNCTION_IS_COMMAND - built-in script command (eg: mes, select, ...) + FUNCTION_IS_GLOBAL - user-defined global function (callable with callfunc) + FUNCTION_IS_LOCAL - user-defined local function + FUNCTION_IS_LABEL - user-defined label function (callable with callsub) Example: - function script try { + function script func1 { dothat(); } - script test FAKE_NPC,{ - .@try = is_function("try"); // 1 - .@not = is_function("notafunction"); // 0 + function func2 { + do_something(); + } + + func3: + end; + + is_function("func1"); // FUNCTION_IS_GLOBAL + is_function("func2"); // FUNCTION_IS_LOCAL + is_function("func3"); // FUNCTION_IS_LABEL + is_function("select"); // FUNCTION_IS_COMMAND + is_function("invalid"); // false } --------------------------------------- @@ -2477,7 +2500,7 @@ arrays: This function will return the basic stats of an invoking character, referred to by the parameter number. Instead of a number, you can use a -parameter name if it is defined in 'db/constants.conf'. +parameter name if it is defined in 'doc/constants.md'. Example parameters: @@ -2558,15 +2581,12 @@ playerattached() to check for the character attached to the script. --------------------------------------- -*getnpcid(<type>{, "<npc name>"}) +*getnpcid({"<npc name>"}) Retrieves IDs of the currently invoked NPC. If a unique npc name is given, -IDs of that NPC are retrieved instead. Type specifies what ID to retrieve -and can be one of the following: - - 0 - Unit ID (GID) +IDs of that NPC are retrieved instead. -If an invalid type is given or the NPC does not exist, 0 is returned. +If the NPC does not exist, 0 is returned. --------------------------------------- @@ -3223,6 +3243,7 @@ Valid types are: ITEMINFO_VIEWID - View ID ("Sprite" field in the Item DB) ITEMINFO_MATK - MATK (only relevant if RENEWAL is set) ITEMINFO_VIEWSPRITE - View Sprite ("ViewSprite" field in the Item DB) + ITEMINFO_TRADE - Trade Restriction (see "doc/constant.md": item trade restriction) Check sample in doc/sample/getiteminfo.txt @@ -3852,7 +3873,7 @@ mob database and return the info set by TYPE argument. It will return -1 if there is no such monster (or the type value is invalid), or "null" if you requested the monster's name. -Valid types are listed in constants.conf: +Valid types are listed in doc/constants.md: MOB_NAME 0 MOB_LV 1 MOB_MAXHP 2 @@ -4003,7 +4024,7 @@ effect being inflicted, in percent. } You can see the full list of available effect types you can possibly -inflict in 'db/constants.conf' under 'Eff_'. +inflict in 'doc/constants.md' under 'Status effects'. --------------------------------------- //===================================== @@ -4653,7 +4674,7 @@ This command will change the job class of the invoking character. This command does work with numbers, but you can also use job names. The full list of job names and the numbers they correspond to can be found in -'db/constants.conf'. +'doc/constants.md'. 'upper flag' can alternatively be used to specify the type of job one changes to. For example, jobchange(Job_Swordman, 1); will change the @@ -4801,7 +4822,7 @@ Is subject to EXP bonuses and to the `quest_exp_rate` config option. getexp(10000, 5000); You can also assign directly to the parameters defined in -'db/constants.conf': +'doc/constants.md': BaseExp += 10000; JobExp += 5000; @@ -4880,7 +4901,7 @@ installation that you can look at: 'npc/custom/stylist.txt' This command will push the currently attached player to given direction by given amount of square cells. Direction is the same as used when declaring NPCs, and can be specified by using one of the DIR_* constants -(db/constants.conf). +(doc/constants.md). The knock-back is not restricted by items or map flags, only obstacles are taken into account. If there is not enough space to perform the push (e.g. @@ -5835,7 +5856,7 @@ These commands will bestow a status effect on a character. The <effect type> determines which status is invoked. This can be either a number or constant, with the common statuses (mostly negative) found in -'db/constants.conf' with the 'SC_' prefix. A full list is located in +'doc/constants.md' under 'Status Changes'. A full list is located in 'src/map/status.h', though they are not currently documented. The duration of the status is given in <ticks>, or milleseconds. @@ -5976,6 +5997,17 @@ Example usage: --------------------------------------- +*removespecialeffect(<effect number>{, <send_target>{, <unit id>{, <account id>}}}) +*removespecialeffect(<effect number>{, <send_target>{, "<NPC Name>"{, <account id>}}}) + +Works for: + main client from version 2018-10-02 + re client from version 2018-10-02 +This command will remove special effect. All parameters same with specialeffect. +Examples and detailed explanation about parameters see in specialeffect. + +--------------------------------------- + *specialeffect2(<effect number>{, <send_target>{, "<Player Name>"}}) @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@ -6018,6 +6050,22 @@ Amount can be negative. See statusup(). --------------------------------------- +*needed_status_point(<type>, <val>, {<char_id>}); + +Returns the number of stat points needed to change the specified stat <type> by <val>. +If <val> is negative, returns the number of stat points that would be needed to +raise the specified stat from (current value - <val>) to current value. + +List of <type>: +bStr - Strength +bVit - Vitality +bInt - Intelligence +bAgi - Agility +bDex - Dexterity +bLuk - Luck + +--------------------------------------- + *bonus(<bonus type>, <val1>) *bonus2(<bonus type>, <val1>, <val2>) *bonus3(<bonus type>, <val1>, <val2>, <val3>) @@ -6635,7 +6683,7 @@ Examples: *unitemote(<GID>, <Emote>) Okay, these commands should be fairly self explaining. -For the emotions, you can look in db/constants.conf for prefixes with e_ +For the emotions, you can look in 'doc/constants.md' under 'Emotes' PS: unitwarp() supports a <GID> of zero, which causes the executor of the PS: unittalk() can receive 3 extra parameters: show_name: @@ -7064,7 +7112,7 @@ This command will broadcast a message to all or most players, similar to The region the broadcast is heard in (target), source of the broadcast and the color the message will come up as is determined by the flags. -The flag values are coded as constants in db/constants.conf to make them +The flag values are coded as constants in doc/constants.md to make them easier to use. Target flags: @@ -7390,7 +7438,7 @@ to the coordinates specified. This command marks a specified map with a map flag given. Map flags alter the behavior of the map, you can see the list of the available ones in -'db/constants.conf' under 'mf_'. +'doc/constants.md' under 'Mapflags'. The map flags alter the behavior of the map regarding teleporting (mf_nomemo, mf_noteleport, mf_nowarp), storing location when @@ -7663,15 +7711,19 @@ solution rather than sending the map and the monster_id. //===================================== --------------------------------------- -*debugmes("<message>") +*debugmes("<format string>"{, <param>{, ...}}) + +This command will print a message in the server console (map-server window), +after applying the same format-string replacements as sprintf(). It will not be +displayed anywhere else. Returns true on success. + +Example: -This command will send the message to the server console (map-server -window). It will not be displayed anywhere else. -// // Displays "NAME has clicked me!" in the map-server window. - debugmes(strcharinfo(PC_NAME)+" has clicked me!"); + debugmes("%s has clicked me!", strcharinfo(PC_NAME)); + + debugmes("\033[0;32mHello World"); // supports ANSI escape sequences - debugmes("\033[38D\033[K ==Message== \n"); // enable colour code. --------------------------------------- *logmes("<message>"{, <log type>}) @@ -7841,7 +7893,7 @@ A full list of pet IDs can be found inside 'db/pet_db.txt' This command makes an object display an emotion sprite above their own as if they were doing that emotion. For a full list of emotion numbers, see -'db/constants.conf' under 'e_'. The not so obvious ones are 'e_what' (a +'doc/constants.md' under 'Emotes'. The not so obvious ones are 'e_what' (a question mark) and 'e_gasp' (the exclamation mark). The optional target parameter specifies who will get the emotion on top of @@ -8094,7 +8146,7 @@ built-in atcommands and custom atcommands. *has_permission("<permission>"{, <account id>}) Check if the attached or specified player has the specified permission -and returns true or false accordingly. See doc/permissions.txt for +and returns true or false accordingly. See doc/permissions.md for details about permissions. Valid <permission> are: @@ -8567,6 +8619,18 @@ Example: --------------------------------------- +*data_to_string(<data>) + +Returns a string representation of the given data, similar to the .toString() +method in JavaScript. + +Example: + + data_to_string(DATATYPE_VAR) // "DATATYPE_VAR" + data_to_string(.@foo) // ".@foo" + +--------------------------------------- + *charisalpha("<string>", <position>) This function will return true if the character number Position in the given @@ -8906,14 +8970,14 @@ same time. This command will make the pet give a bonus to the owner's stat (bonus type - bInt, bVit, bDex, bAgi, bLuk, bStr, bSpeedRate - for a full list, see the -values starting with 'b' in 'db/constants.conf'). +'doc/constants.md' under 'Bonuses / Parameter IDs'). *petrecovery(<status type>, <delay>) This command will make the pet cure a specified status condition. The curing actions will occur once every <delay> seconds. For a full list of -status conditions that can be cured, see the list of 'SC_' status -condition constants in 'db/constants.conf' +status conditions that can be cured, see the list of 'Status Changes' status +condition constants in 'doc/constants.md' *petloot(<max items>) @@ -9008,7 +9072,7 @@ Each of these can be 'on' or 'off'. Together they define a cell's behavior. This command lets you alter these flags for all map cells in the specified (x1,y1)-(x2,y2) rectangle. 'type' defines which flag to modify. Possible options include cell_walkable, -cell_shootable, cell_basilica. For a full list, see constants.conf. +cell_shootable, cell_basilica. For a full list, see 'doc/constants.md'. 'flag' can be false (clear flat) or true (set flag). Example: @@ -9045,7 +9109,7 @@ remove a nonwalkable row of cells after the barricade mobs. This command will return true or false, depending on whether the specified cell has the 'type' flag set or not. There are various types to check, all mimicking the server's cell_chk enumeration. The types can be found in -db/constants.conf. +'doc/constants.md' under 'Cell checks'. The meaning of the individual types can be confusing, so here's an overview: @@ -9394,10 +9458,11 @@ supported types: values QINFO_SEX: sex QINFO_BASE_LEVEL: min, max QINFO_JOB_LEVEL: min, max - QINFO_ITEM: item_id, amount // append to the items list on each use + QINFO_ITEM: item_id, min amount, max amount // append to the items list on each use QINFO_HOMUN_LEVEL: min QINFO_HOMUN_TYPE: homunculus_type (0 - regular, 1 - evolved, 2 - S) QINFO_QUEST: quest_id, state // append to the quests list on each use + QINFO_MERCENARY_CLASS: mercenary_class --------------------------------------- @@ -9888,6 +9953,7 @@ when the optional NPC_Name param is used. --------------------------------------- *sellitem(<Item_ID>{, <price>{, <qty>}}) +*sellitem(<Item_ID>, <qty>, <currency_id>, <currency_amount>) adds (or modifies) <Item_ID> data to the shop, when <price> is not provided (or when it is -1) itemdb default is used. @@ -9896,11 +9962,15 @@ qty is only necessary for NST_MARKET trader types. when <Item_ID> is already in the shop, the previous data (price/qty), is overwritten with the new. +currency_id and currency_amount can be used only with shop type NST_BARTER + --------------------------------------- *stopselling(<Item_ID>) +*stopselling(<Item_ID>{, <currency_id>, <currency_amount>}) attempts to remove <Item_ID> from the current shop list. +currency_id and currency_amount can be used only with shop type NST_BARTER --------------------------------------- @@ -9958,9 +10028,9 @@ Applicable Data Types (available as constants) - UDT_WALKTOXY: Make a unit walk to certain co-ordinates. (Val1 = (int) x, Val2 = (int) y) UDT_SPEED: Unit Speed. (int) UDT_MODE: Mode (Mobs only) (int) - UDT_AI: Unit AI Type (see constants.conf for Unit AI Types) - UDT_SCOPTION: Status Options. (see constants.conf for Unit Option Types) - UDT_SEX: Gender of the unit. (see constants.conf for Genders) + UDT_AI: Unit AI Type (see doc/constants.md for Unit AI Types) + UDT_SCOPTION: Status Options. (see doc/constants.md for Unit Option Types) + UDT_SEX: Gender of the unit. (see doc/constants.md for Genders) UDT_CLASS: Class of the unit. (Monster ID) (int) UDT_HAIRSTYLE: Hair Style ID. (int) UDT_HAIRCOLOR: Hair Color ID. (int) @@ -10023,9 +10093,9 @@ Applicable Data types (available as constants) - UDT_MAPIDXY: Warp a Unit to a map. (Val1 = (string) MapName, Val2 = (int) x, Val3 = (int) y) UDT_SPEED: Unit Speed. (int) UDT_MODE: Mode (Mobs only) (int) - UDT_AI: Unit AI Type (see constants.conf for Unit AI Types) - UDT_SCOPTION: Status Options. (see constants.conf for Unit Option Types) - UDT_SEX: Gender of the unit. (see constants.conf for Genders) + UDT_AI: Unit AI Type (see doc/constants.md for Unit AI Types) + UDT_SCOPTION: Status Options. (see doc/constants.md for Unit Option Types) + UDT_SEX: Gender of the unit. (see doc/constants.md for Genders) UDT_CLASS: Class of the unit. (Monster ID) (int) UDT_HAIRSTYLE: Hair Style ID. (int) UDT_HAIRCOLOR: Hair Color ID. (int) @@ -10137,3 +10207,133 @@ the available flags are: Opens the styling shop on client --------------------------------------- + +*msgtable(<message_id>{, <color>}) + +Show in client message by <message_id> from msg string table +with optional <color>. + +--------------------------------------- + +*msgtable2(<message_id>, <param>{, <color>}) + +Show in client message by <message_id> from msg string table. +<param> is parameter for this message. Can be string or int. +Optional <color> can be used for set color for whole message. + +--------------------------------------- + +*camerainfo() + +Show or hide camera info window. +Works for 20160525 clients or newer. + +--------------------------------------- + +*changecamera(<range>, <rotation>, <latitude>{, <target>}) + +Change camera range, rotation, latitude. +The optional target parameter specifies who will get changed +camera. +Works for 20160525 clients or newer. + +--------------------------------------- + +*achievement_progress(<ach_id>, <obj_idx>, <progress>, <incremental>{, <account_id>}); + +Make the player progress in the specified achievement. +aid - achievement ID +obj_idx - achievement objective index. +progress - objective progress towards goal. +incremental - (boolean) true to add the progress towards the goal, + false to use the progress only as a comparand. +account_id - (optional) AID to perform on (default to attached player). + +returns progress on success and false on failure + +--------------------------------------- + +*itempreview(<index>) + +Update already opened preview window with item from + inventory with given index. +Works for 20181017 RE and main clients or newer. + +--------------------------------------- + +*enchantitem(<equip_pos>, <card_slot>, <card_id>); + +Insert card into equipped item in EQI_* slot. +card_slot - can be 0 to 3. +card_id - any card item id. + +returns true if all parameters correct +false in other case. +Works for 20160831 main, 20151118 RE, any zero version + +--------------------------------------- + +*servicemessage("<message>", <color>{, <account_id>}) +*servicemessage("<message>", <color>{, <player_name>}) + +That command will send a service message to the chat window of the character +specified by account ID or name, or to connected to npc player. +It will not be seen by anyone else. + +Works for 20170830 RE and main and for any zero clients + +--------------------------------------- + +*expandInventoryAck(<result>{, <itemId>}) + +Send initial inventory expansion result. +Normally this function should be called from script label +inventory_expansion::OnInventoryExpandRequest. + +Valid result statuses: + EXPAND_INVENTORY_ASK_CONFIRMATION - force client to ask player about inventory expansion + EXPAND_INVENTORY_FAILED - other failed reason + EXPAND_INVENTORY_OTHER_WORK - failed because player busy with other work + EXPAND_INVENTORY_MISSING_ITEM - failed because missing item + EXPAND_INVENTORY_MAX_SIZE - failed because inventory size already maximum + +ItemId make sense only if result is EXPAND_INVENTORY_ASK_CONFIRMATION +Works for 20181212 zero clients + +--------------------------------------- + +*expandInventoryResult(<result>) + +Send final inventory expansion result. +Normally this function should be called from script label +inventory_expansion::OnInventoryExpandConfirmed. + +Valid result values: + EXPAND_INVENTORY_RESULT_SUCCESS - success message + EXPAND_INVENTORY_RESULT_FAILED - other failed reason + EXPAND_INVENTORY_RESULT_OTHER_WORK - failed because player busy with other work + EXPAND_INVENTORY_RESULT_MISSING_ITEM - failed because missing item + EXPAND_INVENTORY_RESULT_MAX_SIZE - failed because inventory size already maximum + +Works for 20181212 zero clients + +--------------------------------------- + +*expandInventory(<value>) + +Adjust player inventory to given value. +Maximum inventory size is MAX_INVENTORY. +Minimum inventory size is FIXED_INVENTORY_SIZE. +For supported clients it send inventory change packet. For old clients, +this change is silent. +Current max inventory size can be read by function getInventorySize(). + +--------------------------------------- + +*getInventorySize() + +Return current player max inventory size. +This value always smaller or equal to MAX_INVENTORY. +Size can be changed by group of functions expandInventory* + +--------------------------------------- |