[Guide] NPC Scripting Tutorial

krazydann · 06/05/2010, 20:36

I did not in anyway create, modify or help with this guide i just thought it was good so i am posting it here

Quote:
Originally Posted by henki133
Have you ever wanted to script your own NPC?
Did you fail?
Well take a look at this Tutorial!

Check attachment for downloadable guide. It's just a copy/paste text file for now. I will make it better later.

Tutorial 1 [The base of NPC scripting]
Tutorial 2 [How to fix the NPC if you got a problem with it]
Tutorial 3 [The NPC commands]
Tutorial 4 [The Text commands]
Nice JavaScript Editors

TUTORIAL 1 [The basics of NPC scripting]
Spoiler
So you want to learn the basics?
Okay! Here we go.
We will make a simple NPC and teach you on the way.
To begin with. You should download a JavaScript editor below at the Javascript editor downloads.
When you have done that, you are ready to start!
Open the program. Go to file and open and then go to your servers main folder and then you go to scripts folder--> NPC folder. If you dont know how to do that, then you should not have a private server at all because its just to go to the NPC folder inside scripts folder in your Server folder. Ok?
When you have got that far, choose a npc to edit.
Click open (remember we are still using the script editor!).
Now, (if you haven't made an new empty NPCID.js) it should get up some weird text.
(It may look weird to you if you are a beginner at this)
Do not panic.(Lol)
All you have to do is to delete the text. (Hotkey - CTRL + A and then delete)
Now you can start scripting!

To begin with, type this at the top:

Code:

[COLOR="DarkOrchid"]var status = 0;[/COLOR]

Explanation:

Spoiler

This is the variable to the status that we will get into later. Ignore the = 0 part. It doesn't really matter. the function start will make it -1 anyways. If you want to add a new variable you always have to make a var [Name]; at the top or the variable might not work.

When you have added that script, your first variable is set. Under this variable, you can set more variables.
That depends on what you will use them for but we will go into that later.

Now, you have to add the string that actually makes your NPC work.

Code:

[COLOR="DarkOrchid"]function start() { status = -1; action(1, 0, 0); } [/COLOR]

Explanation:

Spoiler

This makes the script actually work. You may notice that because of the function_start(). This has to be included in every npc script you are making.

Now you can go in game and talk to your NPC!... JOKES! The npc is not done yet..
Now you will have to add a string for the ACTIONS to work. Still, the above string is the base of the script. Did you notice that action(1, 0, 0); ? Well I did.
What do that variable do? We will come into that now.
Add this string to the script:

Code:

[COLOR="DarkOrchid"]function action(mode, type, selection) { [/COLOR]

Explanation:

Spoiler

This means that action is a function that has 3 variables. mode, type and selection. So the action(1, 0, 0) from before will be in the order as this one. So mode is 1, type is 0 and selection is 0.

Now we can add our modes.

Code:

[COLOR="DarkOrchid"] if (mode == -1) cm.sendOk("Goodbye then!"); cm.dispose(); else { if (mode == 0 && status == 1) { cm.dispose(); return; }[/COLOR]

Explanation:

Spoiler

The mode variable, actually takes care of if you have clicked End Chat or finished talking to a NPC. The mode == -1 checks if you have clicked a negative button like, No. The mode == 0 and status == 1 checks the status assigned for choices. The status == 1 should be changed if you have a question in another status. We will not talk about that cm.sendOK in this tut. Please check out Tutorial 3 if you want to knwo about it.

There is ONE more mode that we will add.. It is the one that checks if we did go backwards or forwards in the script.

Code:

[COLOR="DarkOrchid"] if (mode == 1) status++; else status--;[/COLOR]

Explanation:

Spoiler

You should now knwo about what the modes do. Yes, they take care of the status's actions. Now lets explain what the status++; actually does. Did you remember the status == -1; variable under function_start()? Now you may have noticed what I mean? It is actually adding +1 when you are going to next window(in-game)/status(in-script). The status--; is subtracting -1 when you are going to previous window(in-game)/status(in-script).

Now are we done? The answer is both no and yes. If you want the npc to not say anything, yes. If you want the npc to actually do anything, no. The script will wonder "Hey! What to do with the statuses then? It's useless!". It isn't useless if you add this if statement:

Code:

[COLOR="DarkOrchid"] if (status == 0) {[/COLOR]

Explanation:

Spoiler

This is a npc window(in-game)/status(in-script). If you are gonna add more statuses, You wil?l have to add +1 to the number all the time. For example: If you have status ==1, and want to add a new status, that status will have to be status == 2. But it won't do anything if you leave without the commands (Tutorial 3).

Now you have your first NPC window! Gratz! Now we will add a simple cm.sendNext(""); into it.

Code:

[COLOR="DarkOrchid"] cm.sendNext("Hello there! My name is Henki! I want to teach you how to script NPCs!");[/COLOR]

Youn will find explanation at Tutorial 3.

Now we will add a new status. This time it has to be "else" because if its not status 0 = if the mode added +1 to the variable "status" it will be 1.

Code:

[COLOR="DarkOrchid"] } else if (status == 1) {[/COLOR]

You won't need a explanation for this. The explanation is in the status == 0 explanation.

Now we will make the player choose between two choices.

Code:

[COLOR="DarkOrchid"] cm.sendSimple("So, why are you talking to me? \r\n #L0##bI want to learn NPC scripting#k#l /r/n #L1##bNevermind#k#l");[/COLOR]

Tutorial 3/4 for explanation.

Now we will add the 3rd status

Code:

[COLOR="DarkOrchid"] } else if (status == 2) {[/COLOR]

Same as status == 0/1

Now I'm gonna explain some of the cm.sendSimple. The L0 and L1 you see, is selection text commands and for them to take you somewhere when you click one, we have to add selections.

Code:

[COLOR="DarkOrchid"] if (selection == 0) {[/COLOR]

Explanation:

Spoiler

When you have clicked a selection at the sendSimple, you will be taken to this strings. the selections L0 = selection == 0, L1 = selection == 1 and so on..

Now when we click the first choice, we will be taken to selection 0. But now we will make that one do something.

Code:

[COLOR="DarkOrchid"] cm.sendOk("Then you have to go to ******** and find my tutorial. Cya in ********!");[/COLOR]

Tutorial 3 still. :P

Now we want to add a selection for the second choice.

Code:

[COLOR="DarkOrchid"] } else if (selection == 1) {[/COLOR]

and because the second choice says "Nevermind" we want the npc to quit the conversation.

Code:

[COLOR="DarkOrchid"] cm.dispose();[/COLOR]

Tutorial 3....

Now we will add some end branches and another dispose and were done!
This is the final result:

Code:

[COLOR="DarkOrchid"]var status = 0; function start() { status = -1; action(1, 0, 0); } function action(mode, type, selection) { if (mode == -1) { cm.dispose(); } else { if (mode == 0 && status == 1) { cm.dispose(); return; } if (mode == 1) status++; else status--; if (status == 0) { cm.sendNext("Hello there! My name is Henki! I want to teach you how to script NPCs!"); } else if (status == 1) { cm.sendSimple("So, why are you talking to me? \r\n #L0##bI want to learn NPC scripting#k#l \r\n #L1##bNevermind#k#l"); } else if (status == 2) { if (selection == 0) { cm.sendOk("Then you have to go to ******** and find my tutorial. Cya in ********!"); } else if (selection == 1) { cm.dispose(); } } } } [/COLOR]

Now press file->Save and you can try out the new made npc!

EXTRA INFO:

EXTRA NPC SCRIPT TEMPLATES:
TUTORIAL 2 [How to fix a NPC if you got a problem with it]
Spoiler
Fixing the npc..
Have your npc never started to talk?
Or do you DC after talking to it?
Maybe the npc stops talking when you click a button in the conversation window?
I will tell you how to fix those problems. It's easy.

We will look into: "Have your npc never started to talk?"

Open up your javascript editor and open the npc script from there or make a new javascript tab and paste in the script itself. Or if you dont want to download the JS Editors in this tut, open up the npc script manually with notepad.

If you are using a JS Editor, simply click the check for errors button (if there is any. AJAX JS Editor has one.) The normal error of the npc isn't working is syntax errors. The syntax errors is when you for example have forgot any " in for example,

Code:

[COLOR="DarkOrchid"]cm.sendOk("hello);[/COLOR]

This is a normal mistake and can easily be fixed because of that.
But if you are using notepad, (not notepad++) you have to search the errors manually and that is not recommended.

Another syntax error can be following:

You have forgotten any } or { anywhere or made an extra } or { anywhere.
Add/Delete at the place it should be/is on.

And another one:

You are using this:

Code:

[COLOR="DarkOrchid"]cm.sendOk("hello!";[/COLOR]

You noticed you forgot one )? Yeah, thats a syntax error too.
Or you maybe added an extra ) or (? that will be syntax error too.

Now on to the next part!

"Do you DC after talking to the npc or clicking a button in the npc's conversation window?"

It may be a simple syntax error with the cm.gainItem.
Lets say you wanted it to be like this:

Code:

[COLOR="DarkOrchid"]} else if (status == 1) { cm.gainItem(1049200); cm.sendOk("Here you go! A random item!"); cm.dispose(); }[/COLOR]

The NPC is actually dumb at this moment. He does not know how many items he shall give. So you have to add this instead of the old one:

Code:

[COLOR="DarkOrchid"] cm.gainItem(1049200, 1);[/COLOR]

or

Code:

[COLOR="DarkOrchid"] cm.gainItem(1049200,1);[/COLOR]

Doesn't matter..

There is one more thing that may cause this error. ( This error will not occour in the newest versions. )
Let's say you typed:

Code:

[COLOR="DarkOrchid"]cm.sendNext("Hello! Pick a category: \r\n \r\n #L0##bI WANNA GO HOME#l \r\n #L1##bNevermind#k#l");[/COLOR]

This will create a window with a next button and make a selection window at the same time. That will not work.
You have to type like this all the time for a simple selection window.

Code:

[COLOR="DarkOrchid"]cm.sendSimple("Hello! Pick a category: \r\n \r\n #L0##bI WANNA GO HOME#l \r\n #L1##bNevermind#k#l");[/COLOR]

Got it? Yes? Good!

Now onto the next part.

"The npc stops talking when you click the button?"

There is 2 things that can lead to this error. The first is:

LAG! Seriously. It can be because of lag or you might have to reload the map.

The second is:

You do not have any text dialog command like cm.sendOk("");...
Well. This is not a problem if you are adding some items/etc. commands in there.
TUTORIAL 3 [The NPC commands]
Spoiler
Spoiler

cm.dispose(); - Ends chat
cm.sendNext("text"); - shows a conversation window with a next button.
cm.sendPrev("text"); - shows a conversation window with a prev button.
cm.sendNextPrev("text"); - shows a conversation window with a next and a prev button.
cm.sendOk("text"); - shows a conversation window with a OK button.
cm.sendYesNo("text"); - shows a conversation window with a yes and no button.
cm.sendAcceptDecline("text"); - shows a conversation window with a accept and
decline button.
cm.sendSimple("text"); - shows a conversation window without buttons.
cm.sendGetNumber("text", defammount, minammount, maxammount) - It makes the player choose a number between minammount and maxammount.
cm.sendGetText("text") - It makes the player be able to type in a text box.
cm.setGetText("text") - It sets the text in a players NPC text box.
cm.getText() - It gets the text typed in the text box.
cm.openShop(SHOPID) - opens a shop by SHOPID
cm.openNpc(NPCID) - starts a new npc conversation with NPCID
cm.changeJob(JOBID) - changes the job of the player to JOBID
cm.getJob() - gets the job of the player
cm.startQuest(QUESTID) - starts a quest by QUESTID
cm.completeQuest(QUESTID) - completes a quest by QUESTID
cm.forfeitQuest(QUESTID) - forfeits a quest by QUESTID
cm.getMeso() - gets the meso of the player
cm.gainMeso(NUMBER) - gives mesos to the player by NUMBER
cm.gainExp(NUMBER) - gives EXP to the player by NUMBER
cm.getNpc() - gets the current npc
cm.getFileName() - probably gets a filename.
cm.getLevel() - gets the level of the player
cm.unequipEverything() - makes the player unequip everything in equipment
cm.teachSkill(SKILLID, SKILLLEVEL, MASTERLEVEL) - teaches the player a skill by SKILLID
cm.getSkill() - gets a skill of the player
cm.clearSkills() - clears the skills of the player
cm.getPlayer() - gets the player
cm.getC() - gets the client
cm.rechargeStars() - recharges the players stars
cm.getEventManager(String event) - probably gets an event manager..
cm.showEffect(String effect) - shows an effect by ID
cm.playSound(String sound) - plays a sound by ID
cm.updateBuddyCapacity(ammount) - uodates the buddy capacity to ammount
cm.getBuddyCapacity() - gets the buddy capacity of a player
cm.setHair(ID) - sets the hair of a player by ID
cm.setFace(ID) - sets the face of a player by ID
cm.setSkin(ID) - sets the skin of a player by ID
cm.warpParty(MAPID) - warps the party to mapID (good for instances)
cm.warpRandom(MAPID) - warps to a random portal by MAPID
cm.itemQuantity(itemid) - gets quanity of itemid
cm.createMapleSquad(MapleSquadType) - creates a maplesquad by MapleSquadType
cm.getSquadMember(MapleSquadType, number) - gets squadmember by number in MapleSquadType
cm.getSquadState(MapleSquadType) - gets the state of MapleSquadType
cm.setSquadState(MapleSquadType, state) - sets the state of MapleSquadType
cm.checkSquadLeader(MapleSquadType) - checks the leader of MapleSquadType
cm.removeMapleSquad(MapleSquadType) - removes the maplesquad, MapleSquadType
cm.numSquadMembers(MapleSquadType) - gets the number of squadmembers in MapleSquadType
cm.isSquadMember(MapleSquadType) - checks wether a player is a squadmember or not in MapleSquadType
cm.addSquadMember(MapleSquadType) - adds a squadmember to MapleSquadType
cm.removeSquadMember(MapleSquadType, Char) - removes squadmember from MapleSquadType
cm.removeSquadMember(MapleSquadType, Char, ban) - removes squadmember from MapleSquadType with ban
cm.canAddSquadMember(MapleSquadType) - checks if it can add another squadmember into
cm.removeSquadMember(MapleSquadType, Char) - removes squadmember from MapleSquadType
cm.warpSquadMembers(MapleSquadType, mapId) - warps squadmembers of MapleSquadType to mapId
cm.searchItem(ItemName) - searches for ItemName
cm.makeRing(partner, ringId) - makes a ring to you and your partner bt ringId
cm.resetReactors() - resets the reactors
cm.displayGuildRanks() - displays the guild ranks
cm.sendMessage(Player, Message) - sends a message to player
cm.gainFame(amount) - gives/takes fame from player by ammount
cm.maxSkills() - maxes players skills
cm.getSkillLevel(skillid) - gets skill level by skillid from player
cm.giveBuff(skillid) - gives a player the buff of skillid
cm.partyMembersInMap() - checks for the partymembers in the map.
cm.modifyNx(amount) - modifies the nx of the player
cm.getTime(type) - get the time of type. type = h/m/s
cm.addBuddyCapacity(number) - adds the buddycapacity of number
cm.clearKeys() - sets the keys to deafult
cm.scheduleWarp(delay, mapid) - warps to mapid in delay
cm.startClock(limit, endMap) - starts a clock that will go down to 0 from limit and then warps to endmap
cm.getCharByName(name) - gets char by name
cm.warpAllInMap(mapid, portal) - warps all in the map to mapid to portal
cm.createMarriage(partner) - creates marriage with partner
cm.createEngagement(partner) - creates engagement with partner
cm.divorceMarriage() - divorces from partner
cm.changeKeyBinding(key, type, action) - changes key by type by action...
cm.getEquipById(id) - gets equip by id
cm.getNpcTalkTimes() - gets how many times som1 have talked to this npc
cm.setNpcTalkTimes(amount) - sets how many times players have talked to npc by ammount
cm.makeProItem(ITEMID, NUMBER) - makes an item by ITEMID with NUMBER to each stat (xotic)
cm.isGuest() - checks wether a player is guest or not
cm.broadcastMessage(type, message) - broadcasts message by type
cm.setClan(ClanName) - makes player enter ClanName
cm.getAllOnlineNamesFromClan(ClanName) - gets all online members names from clan
cm.getAllOfflineNamesFromClan(ClanName) - gets all offline members names from clan
cm.getOfflineClanCount(ClanName) - counts how many offline in ClanName
cm.getJobById(id) - gets job by id
cm.getPartyMembers() - gets the partymembers in a party
cm.getSender() - gets the sender of ex. a message
cm.removeHiredMerchantItem(id) - removes id from hired merchant
cm.getHiredMerchantMesos() - gets hired merchants mesos
cm.setHiredMerchantMesos(Number) - sets hired merchants mesos by number
cm.getHiredMerchantItems() - gets hired merchants items
cm.sendKeymap(KEY) - sends ? to keymap
cm.removeAll(ItemID) - Removes all of ItemID

If Statements:

Jobs terms that will be used for above statement:

Spoiler

BEGINNER
WARRIOR
FIGHTER
CRUSADER
HERO
PAGE
WHITEKNIGHT
PALADIN
SPEARMAN
DRAGONKNIGHT
DARKKNIGHT
MAGICIAN
FP_WIZARD
FP_MAGE
FP_ARCHMAGE
IL_WIZARD
IL_MAGE
IL_ARCHMAGE
CLERIC
PRIEST
BISHOP
BOWMAN
HUNTER
RANGER
BOWMASTER
CROSSBOWMAN
SNIPER
CROSSBOWMASTER
THIEF
ASSASSIN
HERMIT
NIGHTLORD
BANDIT
CHIEFBANDIT
SHADOWER
GM
SUPERGM
(source: get3127's guide)

The commands in the spoiler actually makes the npc do what the commands is used for. Some of these commands do need a variable to work.
Like this one:
First, set a var at the top.

Code:

[COLOR="DarkOrchid"]var text;[/COLOR]

Second make the actions.

Code:

[COLOR="DarkOrchid"]if (status == 0) { cm.sendGetText("Tell me, what is 1+1?"); } else if (status == 1) { text = cm.getText(); cm.sendYesNo("So, your answer is #b" + text + " #keh?"); } else if (status == 2) { if (text = "2") { cm.gainMesos(1000000); cm.sendOk("yay! you did it! Here you get 1 mill mesos."); cm.dispose(); } else { cm.sendOk("Sry but thats the wrong answer. Try again next time!"); cm.dispose(); } }[/COLOR]

The npc asks a character for the answer of 1+1=. The player will be able to type in the answer in a box. If its the right answer, the player will be awarded 1 mill, otherwise the player will get none and be told to try again.

Also, some of these npc commands is IF commands. Let's get an example of, cm.isGuest()
This command checks wether a player is a guest or not. For it to work, we want to do this:

Code:

[COLOR="DarkOrchid"]if (cm.getPlayer().isGuest() == 1) {[/COLOR]

This checks if the character is a guest and then do actions.

There is commands that needs to get the player before being used too. Like this one:

Code:

[COLOR="DarkOrchid"]cm.giveSkill(SKILLID); cm.getPlayer().sendKeymap(KEY);[/COLOR]

This sends SKILLID to KEY

There is more, like:

Code:

[COLOR="DarkOrchid"]cm.getPlayer().gainExp(AMMOUNT);[/COLOR]

This gives AMMOUNT of exp to the player.

Please ask if you need to learn more cm.getPlayer(). commands.
TUTORIAL 4 [The Text commands]
Spoiler
Spoiler

#b = Blue text.
#c[itemid]# Shows how many [itemid] the player has in their inventory.
#d = Purple text.
#e = Bold text.
#f[imagelocation]# - Shows an image inside the .wz files.
#g = Green text.
#h # - Shows the name of the player.
#i[itemid]# - Shows a picture of the item.
#k = Black text.
#l - Selection close.
#m[mapid]# - Shows the name of the map.
#n = Normal text (removes bold).
#o[mobid]# - Shows the name of the mob.
#p[npcid]# - Shows the name of the NPC.
#q[skillid]# - Shows the name of the skill.
#r = Red text.
#s[skillid]# - Shows the image of the skill.
#t[itemid]# - Shows the name of the item.
#v[itemid]# - Shows a picture of the item.
#x - Returns "0%".
#z[itemid]# - Shows the name of the item.
#B[%]# - Shows a 'progress' bar.
#F[imagelocation]# - Shows an image inside the .wz files.
#L[number]# Selection open.
\r\n - Moves down a line.

Text commands is used inside quotes("text"). They will give the text a bit more features than just typing in some text.

Code:

[COLOR="DarkOrchid"]#r Hello. My name is Paul.[/COLOR]

Now we want this text to only have the "Hello." part red. Do the following:

Code:

[COLOR="DarkOrchid"]#r Hello. #k My name is Paul.[/COLOR]

It will first go into red text and then to normal again.

Now I will teach you about the cm.sendSimple(""); command.

Code:

[COLOR="DarkOrchid"]cm.sendSimple("Hello. What do you want? \r\n \r\n #L0##bCan I get meso?#k#l \r\n #L1##bGoodbye#k#l");[/COLOR]

This command will ask "Hello. What do you want?" and then a player can choose between "Can I get meso?" or "Goodbye". The #b is blue text and you already know what #k is right? But you don't know what "\r\n" is? It actually moves down a line. "\r\n \r\n" is two lines.

Just tell me if you need more explanation in text commands.
JavaScript Editors

Spoiler

Read Me:

Spoiler

Why I made this guide:

-Less spam in the forum
-Beginners get a bit more skilled
-Usual people dont tell you all of the npc commands. I will put new in there as fast as I find new ones.
-I am kind

I will update this TuT as much as I can.
Please tell me if you want any more tutorials into this topic. Has to be related to the NPC JavaScripting!

Do not PM me anything like, "HEY HENKI CAN AI GET LIKE A SO AWESUM SCRIPT LAHRX".. I will not answer but feel free to post your failed scripts. I will try to fix them as soon as I can.

DO NOT POST THIS TOPIC ANYWHERE ELSE WITHOUT GIVING THE PEOPLE BELOW FULL CREDIT! AND YOU HAVE TO ASK ME FOR PERMISSION OFCOURSE.

Credits goes to:

Henki133 - Everything
bboy242 - Inspiration

Credits go to XiuzSu from ********

daimon761 · 08/25/2010, 06:53

I know how to write an NPC Script, but how do I get it to work for Maplestory? I mean like how do you enter he script into the game? I would like a response from anyone please!

dono45 · 05/07/2012, 20:41

well u have to add the NPC to ur wz files, i mean ur data base, add I think you know what to do from there

~~TuPac'~~ · 05/07/2012, 21:01

As you can see the guy posted it one year ago.
I think he no longer need it.