NPC Commands

From Legend of Mir 2 Wiki
Jump to: navigation, search

Introduction

To create an NPC script you should begin by placing a text document within the NPC/ folder. All NPCs (apart from special ones such as 00default) must begin with the page name "[@MAIN]", this will tell the server where the starting point is when you click the NPC.

Scripts are very straight forward to create and read in a pseudo like format. At its most basic an NPC can just contain a single page, with a single #SAY block - which will output text to the player.

Below is a simple example of the core mechanics of an NPC script.

[@MAIN]
#IF
ISADMIN
#SAY
You are an admin.
#ACT
GIVEITEM GMScroll 1
#ELSESAY
You are not an admin.
#ELSEACT
GIVEITEM TownScroll 1

Although you can create basic scripts with a single page, most NPCs will use multiple pages to navigate the player to the correct response.

[@MAIN]
#SAY
Hello <$USERNAME>.
<Transport to Bichon/@bichon>

[@BICHON]
#ACT
MOVE 0 300 300
TAKEGOLD 500

Special Page Names

Command Function
[@MAIN] Required to start every NPC script. Without this the script cannot be called.
[@BUY] Displays an item list that shows all items available to purchase with gold.
[@SELL] Displays a window used to sell items to the NPC.
[@BUYSELL] Displays both the buy and sell windows.
[@REPAIR] Displays a window used to normal repair items (reduces maximum durability on repair).
[@SREPAIR] Displays a window used to special repair items (does not reduce maximum durability).
[@BUYBACK] Displays an item list that shows all items you have sold to the NPC within the last hour.
[@STORAGE] Displays a storage window used to store and retrieve items.
[@CONSIGN] Displays a window used to sell an item to the trade market.
[@MARKET] Displays a window that shows all items being sold in the trade market.
[@CONSIGNMENT] Displays a window that shows all items you have sold to the trade market.
[@CREATEGUILD] Starts the guild creation process. Asks for the guild name to be entered.
[@REQUESTWAR] Starts the guild war process. Asks for the enemy guild name to be entered.
[@SENDPARCEL] Displays a window used to send mail or gold to other players.
[@COLLECTPARCEL] Collects all parcels that a player has been sent, allowing them to be moved in to their inventory.
[@AWAKENING] Displays the awakening window.
[@DISASSEMBLE] Displays a window used to dismantle items and turn in to materials.
[@DOWNGRADE] Displays a window used to downgrade an items awakening level.
[@RESET] Displays a window used to reset an items awakening to zero.
[@PEARLBUY] Displays an item list that shows all items available to purchase with pearls.
[@BUYUSED] Displays an item list that shows all items other players have sold to the NPC.
[@REFINE] Displays a window used to refine and upgrade an item.
[@REFINECOLLECT] Returns any item that has just been refined back to the player.
[@REFINECHECK] Checks if a recently refined item has been successfully upgraded.
[TRADE] All item names and their quantities that are available to buy from the NPC should be listed here.
[TYPES] All item types that can be sold to the NPC should be listed here.
[QUESTS] Any quest id's that the NPC has should be listed here. Starting points should be positive IDs, Ending points should be negative IDs.

#IF Commands

Command Parameters Function
ISADMIN Checks that player is an administrator.
LEVEL [Operator] [Value] Checks against players level.
CHECKITEM [ItemName] [Amount] Checks X items are in players bag.
CHECKGOLD [Operator] [Amount] Checks gold in players account.
CHECKGENDER [Male/Female] Checks player is specified gender.
CHECKCLASS [Warrior/Wizard/Taoist/Assassin/Archer] Checks player is specified class.
DAYOFWEEK [Monday - Sunday] Checks current day matches specified day.
HOUR [0 - 23] Checks current hour matches specified hour.
MIN [0 - 59] Checks current minute matches specified minute.
CHECKNAMELIST [Filename] Checks player name is present within the name list file. Filename should exclude extension (e.g. "BorderProv/NameList_A")
CHECKPKPOINT [Operator] [Value] Checks against players pk points.
CHECKRANGE [X_Coord] [Y_Coord] [Range] Checks player is within the specified range of the chosen coordinates (ignores map checks).
CHECK [Value] [0/1] Checks players flag value matches the specified value. Requires the value to be surrounded with "[" and "]".
CHECKHUM [Operator] [Amount] [MapNumber] Checks amount of players on specified map matches operator.
CHECKHUM [Operator] [Amount] [MapNumber] [InstanceID] Checks amount of players on specified map and instance matches operator.
CHECKMON [Operator] [Amount] [MapNumber] Checks amount of monsters on specified map matches operator.
CHECKMON [Operator] [Amount] [MapNumber] [InstanceID] Checks amount of monsters on specified map and instance matches operator.
CHECKEXACTMON [MonsterName] [Operator] [Amount] [MapNumber] Checks amount of specific monsters on specified map matches operator.
CHECKEXACTMON [MonsterName] [Operator] [Amount] [MapNumber] [InstanceID] Checks amount of specific monsters on specified map and instance matches operator.
RANDOM [Value] Checks a random number between 0 and the value entered. Value of 10 equals 10% chance.
GROUPLEADER Checks if the player is leader of a group.
GROUPCOUNT [Operator] [Value] Checks against the amount of players in the group.
CHECKPET [MonsterName] Checks if the player owns any pets with the specified name.
PETLEVEL [Operator] [Value] Checks against the players pets levels. All pets must match this criteria.
PETCOUNT [Operator] [Value] Checks against the amount of pets the player owns.
CHECKCALC [Variable] [Operator] [Variable] Checks operator against two variables.
INGUILD Checks the player is in a guild.
INGUILD [GuildName] Checks the player is in the specified guild.
CHECKMAP [MapName] Checks the player is on the specified map.
CHECKQUEST [QuestID] [Active/Complete] Checks the player has taken the quest and is either "ACTIVE" or "COMPLETE".
CHECKRELATIONSHIP Checks the player is already in a relationship.
CHECKWEDDINGRING Checks the player already has a wedding ring.
CHECKCREDIT [Amount] Checks X game shop credits is in players account.
HASBAGSPACE [Operator] [Amount] Checks if the player has the appropriate empty slots in their bag.
ISNEWHUMAN Checks if any other characters exist on the same account.
CHECKCONQUEST [ConquestID] Checks if a war is on.
AFFORDGUARD [ConquestID] [GuardID] Checks if the guild bank can afford to purchase / repair a guard.
AFFORDGATE [ConquestID] [GateID] Checks if the guild bank can afford to purchase / repair a gate.
AFFORDWALL [ConquestID] [WallID] Checks if the guild bank can afford to purchase / repair a wall.
AFFORDSIEGE [ConquestID] [SiegeID] Checks if the guild bank can afford to purchase / repair a siege weapon.
CONQUESTAVAILABLE Checks if Conquest Index 1 has already got a scheduled war. Do this check before scheduling a new war.
CONQUESTOWNER [ConquestID] Checks if the player is a member of the owning guild.
CHECKPERMISSION [PermissionNumber] Checks if the player has a specific guild permission. CanChangeRank = 1, CanRecruit = 2, CanKick = 4, CanStoreItem = 8, CanRetrieveItem = 16, CanAlterAlliance = 32, CanChangeNotice = 64, CanActivateBuff = 128

#ACT Commands

Command Parameters Function
MOVE [MapNumber] Teleports the player to the specified map.
MOVE [MapNumber] [X_Coord] [Y_Coord] Teleports the player to the specified map and coordinates.
INSTANCEMOVE [MapNumber] [InstanceID] [X_Coord] [Y_Coord] Teleports the player to the specified map instance and coordinates.
GIVEGOLD [Amount] Gives the player X amount of game gold.
TAKEGOLD [Amount] Takes X amount of game gold from the player.
GIVEITEM [ItemName] [Amount] Gives the player X amount of the specified item.
TAKEITEM [ItemName] [Amount] Takes X amount of the specified item from the players inventory.
GIVEEXP [Amount] Gives the player X amount of experience.
GIVEPET [MonsterName] Spawns a monster as the players pet.
GIVEPET [MonsterName] [Amount] Spawns X amount of monsters as the players pet.
GIVEPET [MonsterName] [Amount] [Level] Spawns X amount of monsters at a set level as the players pet.
REMOVEPET [MonsterName] Removes all pets with the specified name.
CLEARPETS Kills all the players pets.
ADDNAMELIST [Filename] Adds the players name to the specified name list.
DELNAMELIST [Filename] Removes the players name from the specified name list.
CLEARNAMELIST [Filename] Clears all names from the specified name list.
GIVEHP [Amount] Gives X amount of HP to the player.
GIVEMP [Amount] Gives X amount of MP to the player.
CHANGELEVEL [Value] Changes the players level to the specified value.
SETPKPOINT [Value] Sets the players PK points to the specified value.
REDUCEPKPOINT [Value] Reduces the players PK points by the specified value.
INCREASEPKPOINT [Value] Increases the players PK points by the specified value.
CHANGEGENDER Swaps the players gender.
CHANGECLASS [Warrior/Wizard/Taoist/Assassin/Archer] Changes the players class.
LOCALMESSAGE "[Message]" [ChatType] Outputs the message as the specified chat type (listed separately). Displayed only to the player regardless of the type used.
GLOBALMESSAGE "[Message]" [ChatType] Outputs the message as the specified chat type (listed separately). Displayed to everyone online regardless of the type used.
GOTO [Page] Changes the NPC page to the specified page.
GIVESKILL [SkillName] Gives the specified skill to the player.
GIVESKILL [SkillName] [Level] Gives the specified skill at a set level to the player.
REMOVESKILL [SkillName] Removes the specified skill from the player.
SET [Value] [0/1] Sets or unsets the specified flag. (Value must be surrounded by brackets []).
PARAM1 [MapNumber] [InstanceID] Used with MONGEN command. Sets the map number and instance a monster will be spawned on.
PARAM2 [X_Coord] Used with MONGEN command. Sets the X coordinate a monster will be spawned on.
PARAM3 [Y_Coord] Used with MONGEN command. Sets the Y coordinate a monster will be spawned on.
MONGEN [MonsterName] [Count] Spawns a specified amount of monsters. Requires PARAM1, PARAM2 and PARAM3 to be entered prior to calling.
TIMERECALL [Time] [PageName] Recalls the player to their current coordinates after X time as passed (in seconds).
TIMERECALLGROUP [Time] [PageName] Recalls the player and their group to their current coordinates after X time as passed (in seconds).
BREAKTIMERECALL Removes all upcoming TIMERECALL countdowns.
MONCLEAR [MapNumber] Kills all monsters on the specified map.
MONCLEAR [MapNumber] [InstanceID] Kills all monsters on the specified map instance.
GROUPRECALL Recalls all group members to the players current coordinates.
GROUPTELEPORT [MapNumber] Teleports the player and their group members to the specified map (random coordinates).
GROUPTELEPORT [MapNumber] [InstanceID] Teleports the player and their group members to the specified map instance (random coordinates).
GROUPTELEPORT [MapNumber] [X_Coord] [Y_Coord] Teleports the player and their group members to the specified map and coordinates.
GROUPTELEPORT [MapNumber] [InstanceID] [X_Coord] [Y_Coord] Teleports the player and their group members to the specified map instance and coordinates.
DELAYGOTO [PageName] [Time] Changes the NPC page to the specified page after X time has passed.
MOV [Variable] [Value] Stores the specified value inside the variable. (Put value in quotations if using spaces)
CALC [Variable] [Operator] [Value] Calculates the variable against the operator and value. The new value is stored within the variable. (Put value in quotations if using spaces)
GIVEBUFF [BuffName] [Time] [Value] [Infinite] [Visible] Give a specified buff to the player. Value can be separated by a comma for buffs which use multiple values (e.g. General Buff)
REMOVEBUFF [BuffName] Removes a specified buff from the player.
ADDTOGUILD [GuildName] Adds a player to the specified guild.
REMOVEFROMGUILD Removes the player from their guild.
REFRESHEFFECTS Refreshes level effects. To be used directly after setting a level effect to save relogging.
CHANGEHAIR [Value] Changes the players hair. Requires relogging.
CANGAINEXP [True/False] Sets if the player can get any more experience from monsters.
COMPOSEMAIL "[Message]" [Sender] Creates mail to the player from a specified sender. The message must be surrounded by quotations.
ADDMAILITEM [ItemName] [Count] Adds the specified amount of items to already created mail (Requires COMPOSEMAIL to be used first).
ADDMAILGOLD [Amount] Adds the specified amount of gold to already created mail (Requires COMPOSEMAIL to be used first).
SENDMAIL Sends any created mail to the player.
GROUPGOTO [PageName] Changes the NPC page to the specified page for the player and all group members.
ENTERMAP Used alongside the NEEDMOVE map attribute and MAPCOORD default npc command to allow a player to enter a map through specific coordinates.
GIVEPEARLS [Amount] Gives X amount of pearls to the player.
TAKEPEARLS [Amount] Removes X amount of pearls from the player.
MAKEWEDDINGRING Makes a relationship wedding ring based on the item in the players left ring slot.
FORCEDIVORCE Forces a relationship divorce between the player and their partner.
LOADVALUE [Variable] [Filename] [Group] [Key] Loads the value found in the designated group, key and filename in to the specified variable.
SAVEVALUE [Filename] [Group] [Key] [Value] Saves the specified value to the allocated filename under the designated group and key.
GIVECREDIT [Amount] Gives the player X amount of game shop credits.
TAKECREDIT [Amount] Takes X amount of game shop credits from the player.
CONQUESTGUARD [ConquestID] [GuardID] Bring the specified Conquest Guard back to life.
CONQUESTGATE [ConquestID] [GateID] Bring the specified Conquest Gate back to life.
CONQUESTWALL [ConquestID] [WallID] Bring the specified Conquest Wall back to life.
CONQUESTSIEGE
TAKECONQUESTGOLD [Amount] Withdraws the gold stored at the Conquest to the Guild Storage of the owning guild.
SETCONQUESTRATE [ConquestID] [Percent] Sets the percentage extra gold that will be charged on top of items at the Conquest Area.
STARTCONQUEST [ConquestID] Allows the Conquest to be forcefully started.
SCHEDULECONQUEST [ConquestID] Allows a guild to schedule a war to take the conquest
OPENGATE [ConquestID] [GateID] Opens gate.
CLOSEGATE [ConquestID] [GateID] Closes gate.

#SAY Commands

Command Function
<$OUTPUT(VAR)> Displays value stored in specified variable (e.g. A1).
<$NPCNAME> Displays current NPC name.
<$USERNAME> Displays players name.
<$MAP> Displays players current map filename.
<$X_COORD> Displays players current X Coordinate.
<$Y_COORD> Displays players current Y Coordinate.
<$GAMEGOLD> Displays players gold amount.
<$LEVEL> Displays players level.
<$CLASS> Displays players class.
<$DATE> Displays current date.
<$USERCOUNT> Displays server user count.
<$PKPOINT> Displays players PK point value.
<$GUILDWARTIME> Displays length of guild war in minutes.
<$GUILDWARFEE> Displays cost of guild war.
<$PARCELAMOUNT> Displays amount of parcels player has awaiting collection.
<$HP> Displays players current HP.
<$MAXHP> Displays players maximum HP.
<$MP> Displays players current MP.
<$MAXMP> Displays players maximum MP.
<$ARMOUR> Displays name of armour player is currently wearing.
<$WEAPON> Displays name of weapons players is current holding.
<$RING_L> Displays name of left ring player is currently wearing.
<$RING_R> Displays name of right ring player is currently wearing.
<$BRACELET_L> Displays name of left bracelet player is currently wearing.
<$BRACELET_R> Displays name of right bracelet player is currently wearing.
<$NECKLACE> Displays name of necklace player is currently wearing.
<$BELT> Displays name of belt player is currently wearing.
<$BOOTS> Displays name of boots player is currently wearing.
<$HELMET> Displays name of helmet player is currently wearing.
<$AMULET> Displays name of amulet player is currently holding.
<$STONE> Displays name of stone player is currently holding.
<$TORCH> Displays name of torch player is currently holding.
<$CREDIT> Displays players game shop credit amount.
<$CONQUESTOWNER(CONQUESTID)> Displays the current owner of the conquest.
<$CONQUESTGUARD(CONQUESTID,GUARDID)> Displays 'Guard Name - [Still Alive]' or 'Guard Name - [Repair Cost]'.
<$CONQUESTGATE(CONQUESTID,GATEID)> Displays 'Gate Name - [Still Alive]' or 'Gate Name - [Repair Cost]'.
<$CONQUESTWALL(CONQUESTID,WALLID)> Displays 'Wall Name - [Still Alive]' or 'Wall Name - [Repair Cost]'.
<$CONQUESTSIEGE(CONQUESTID,SIEGEID)> Displays 'Siege Name - [Still Alive]' or 'Siege Name - [Repair Cost]'.
<$CONQUESTGOLD(CONQUESTID)> Displays the gold in the Conquest Storage for Conquest.
<$CONQUESTRATE(CONQUESTID)> Displays the currently set interest rate on Conquest NPCs.
<$CONQUESTSCHEDULE(CONQUESTID)> Displays any scheduled wars set for Conquest.

Other

Chat Type
Normal
Announcement
Hint
Shout
System
System2
Guild
Group
WhisperIn
WhisperOut
Trainer
LevelUp
Relationship
Mentor

Buttons

Buttons are essential to any NPC as they provide navigation from one page to another. They can only be added within the #SAY block of a page and are outputted similar to normal text, except show up as yellow and will change state when you hover over or click on them.

<BUTTON NAME/@PAGENAME>

Variables

Variables are an essential feature for any complex NPC script. At their most basic they allow a single value to be stored within a variable, this can then be used across multiple pages within the same NPC, substituting a regular value. Variables are made up of a letter A-Z and a number 0-9, e.g. A0, B6, T9 etc.

When modifying the value inside the variable we write it as "A1", when reading the value inside the variable we write it as "%A1".

Variables have two main #ACT commands

#ACT
MOV A1 D100

This will store the value "D100" in to the variable A1.

#ACT
CALC B2 + 50

If there is an integer value (whole number) already stored in the variable B2, this command will increase its value by 50. If there is a string value already stored in the variable B2, this command will concatenate them together.

Variables also use a single #IF command

#IF
CHECKCALC %C3 > 100

Because we are now reading the variable C3 we add a "%" to the start. This command will check that the value stored in C3 is greater than 100. Any type of standard operator can be used in this command.

The variable can be substituted in to any standard NPC command.

#ACT
MOVE %D4

Variables can also have their stored value output in a #SAY block.

<$OUTPUT(E5)>

Arguments

Arguments allow you to pass one or multiple values from a button through to a single NPC page. This allows you to have efficient NPC scripts that can be easily updated and modified without have to use lots of duplicated text.

To initiate arguments we must add our chosen values as parameters in a button.

<BUTTON NAME/@PAGENAME(PARAM1,PARAM2,PARAM3)>

Here we would replace "PARAM1", "PARAM2", "PARAM3" as real values. You can add as little or as many parameters are you wish here.

For the @PAGENAME to be able to read these parameters we must added "()" on the end of the page name

[@PAGENAME()]

Now any values stored in the clicked button will be passed through to the page as arguments. These arguments can be used to substitute any parameter in an NPCs' #IF or #ACT command.

#ACT
INSTANCEMOVE %ARG(0) 1 %ARG(1) %ARG(2)

Coloured Text

Any normal text within a #SAY block can be displayed in a different colour, this excludes buttons. To change the colour of a word or sentence you need to add a "{" to the start, and "/COLOUR}" to the end of where you want the colour to be changed; replacing COLOUR with the desired colour.

This is normal text, {however this text will be another colour/PINK}.

If the different coloured text continues across multiple lines, this method must be applied to every line.

Include

This page command can be used anywhere within the NPC script. Primarily put as the very first line, it is used to include a section of text from another text file. Once included, the script parser will read it as if it were part of the same text file and process it normally.

The include line should be written as follows

#INCLUDE [FolderPath/DocumentName.txt] @SECTION_A

The folder path and document name is relative to the Envir/ folder.

The section page name relates to a page within the document. This page (unlike others) must start with "{" and end with "}".

[@SECTION_A]
{

[@PAGENAME]
#SAY
This page has been included from another file.

}

Input Request

You can ask for a players input by requesting a value to be entered. This is achieved by using two "@@" symbols instead of one in a button. Once the response is inputted it will be stored in the value %INPUTSTR for the remainder of the page.

[@MAIN]
#SAY
Q. How many classes are there in Mir?
<Answer Question/@@QUESTION>

[@@QUESTION]
#ACT
MOV A1 %INPUTSTR
LOCALMESSAGE "You entered <$OUTPUT(A1)>" Hint

Operators

Operators are used within many #IF and #ACT commands and are an efficient way to check if a value matches the desired result.

Operator Description
< Tests positive if left value is LESS than right value.
> Tests positive if left value is GREATER than right value.
<= Tests positive if left value is LESS than or EQUAL to right value.
>= Tests positive if left value is GREATER than or EQUAL to right value.
== Tests positive if left value is EQUAL to right value.
 != Tests positive if left value is NOT EQUAL to right value.

Default Page Names

All default page names are used within a special script file in the root NPC/ folder called "00default.txt". This script file cannot be renamed, and will be recreated on server launch if it cannot be found.

The list below details all the special page names used in this script file.

Command Parameters Function
[@_LOGIN] Called when the player logs in.
[@_USEITEM(PARAM1)] [ItemShape] Called when an item matching the correct shape is used (right click or double clicked).
[@_TRIGGER(PARAM1)] [Value] Called when "@TRIGGER PARAM1" or "@TRIGGER PLAYERNAME PARAM1" is entered in the chat window.
[@_MAPCOORD(PARAM1,PARAM2,PARAM3)] [MapNumber] [X_Coord] [Y_Coord] Called when a player stands on the specified map and coordinates.
[@_MAPENTER(PARAM1)] [MapNumber] Called when a player enters the specified map.
[@_DIE] Called when a player dies.
[@_LEVELUP] Called when a player levels up.
[@_CUSTOMCOMMAND(PARAM1)] [Value] Called when a player types "@PARAM1" in the chat window.
[@_ONACCEPTQUEST(PARAM1)] [QuestID] Called when the specified quest is taken.
[@_ONFINISHQUEST(PARAM1)] [QuestID] Called when the specified quest is completed.
[@_DAILY] Called the first time a player logs in that day within a 24 hour period. Reset time depends on when the server was started.

Monster Page Names

All monsters page names are used within a special script file in the root NPC/ folder called "00monster.txt". This script file cannot be renamed, and will be recreated on server launch if it cannot be found.

The list below details all the special page names used in this script file. The MonsterIDX parameter is the unique index of the monster found in the DB table.

Command Parameters Function
[@_SPAWN(PARAM1)] [MonsterIDX] Called when a monster is spawned.
[@_DIE(PARAM1)] [MonsterIDX] Called when a monster dies.