Basic Lua Scripting: Spawn Scripts

[Jabantiz]

I am doing these tutorials by request and in my free time that isn't long enough to work on the emu itself so I can't guarentee how fast they will come out. I would also like to link 2 great resources for information on lua scripting for the emu, the wiki and this sticky. These tutorials will assume a basic knowledge of lua, and will only focus on writing lua scripts. With that said lets jump into spawn scripts.

Spawn Scripts are used to bring your NPC's to life so that they are capable of more then just standing there and fighting. They can be used to give your NPC dialog, make them offer quests, or even spawn minions when their life drops below a certain amount. The first thing we should know is that the server will call certain functions when certain events occur. The following functions will be called by the server when the required event occurs:

spawn(NPC) is called when the NPC spawns for the first time. The parameter is the NPC this script is assigned to. This is where we state if this npc provides quests (more on that in the quests tutorial).

respawn(NPC) is called every time this NPC respawns (every spawn after the first one), it is mostly used to call spawn() again to register the quests to the npc again

attacked(NPC, Spawn) is called when the NPC is attacked, NPC is the spawn that this script belongs to, Spawn is the spawn attacking the NPC

targeted(NPC, Spawn) is called when the NPC is targeted, NPC is the spawn that this script belongs to, Spawn is the spawn that targeted the NPC

aggro(NPC, Spawn) is called when the NPC is aggro'd, NPC is the spawn that this script belongs to, Spawn is the spawn that aggro'd the NPC

healthchanged(NPC, Spawn) is called whenever the health of the NPC changes, NPC is the spawn that this script belongs to, Spawn is the spawn that caused the change in health

hailed (NPC, Spawn) is called when the NPC is hailed, NPC is the spawn this script belongs to, Spawn is the spawn that hailed the NPC

hailed_busy(NPC, Spawn) is called when the NPC is hailed and busy (in combat), NPC is the spawn that this script belongs to, Spawn is the spawn that hailed the NPC

killed(NPC, Spawn) is called when the NPC kills something, NPC is the spawn that this script belongs to, Spawn is the spawn that the NPC just killed

death(NPC, Spawn) is called when the NPC dies, NPC is the spawn that this script belongs to, Spawn is the spawn that killed the NPC

casted_on(NPC, Spawn, SpellName) is called when a spell is casted on the NPC, NPC is the spawn that this script belongs to, Spawn is the spawn that casted the spell, SpellName is the name of the spell that was casted

The following code block has all the functions that the server will call, while the ones you don't use don't need to be in your lua file this can be a good template for those of you new to spawn scripts.

Code: Select all

function spawn(NPC)
end

function respawn(NPC)
end

function hailed (NPC, Spawn)
end

function hailed_busy(NPC, Spawn)
end

function targeted(NPC, Spawn)
end

function attacked(NPC, Spawn)
end

function aggro(NPC, Spawn)
end

function healthchanged(NPC, Spawn)
end

function killed(NPC, Spawn)
end

function death(NPC, Spawn)
end

function casted_on(NPC, Spawn, SpellName)
end

The most common one used in a spawn script is hailed()

Code: Select all

function hailed(NPC, Spawn)

end

This function will be called every time the spawn is hailed, either by clicking on them or hitting 'H'. NPC is the spawn that is being hailed (the spawn this script is attached to) and Spawn is the spawn that hailed the NPC, usually a player.

When we hail an npc we expect it to turn to face us and say something, the first is easy we just call FaceTarget()

Code: Select all

FaceTarget(NPC, Spawn)

The first parameter of FaceTarget is the spawn we want to turn, in this case the NPC, the second parameter is the spawn we want the npc to turn to.

Now to get the npc to talk to us we have a few options, the first is for it to use /say, /shout, or /ooc, the other is for an actual dialog with chat bubbles and options for the player to select, we will cover the dialog later for now we will focus on the normal chat channels.

Code: Select all

Say(Spawn, message, player) 
Shout(Spawn, message, player) 
SayOOC(Spawn, message, player) 

These 3 commands all work the same, just for their respective chat channel. Spawn is the entity that will actually speak in the channel, message is what the entity will say, and player is optional but if included the message will only be sent to that player.

Code: Select all

Say(NPC, "Hello World!")

Putting this all together we would get the following

Code: Select all

function hailed(NPC, Spawn)
     FaceTarget(NPC, Spawn)
     Say(NPC, "Hello World!")
end

Now when you go up to the NPC that this script is assigned to and hail them they will turn to face you and say Hello World!

(the lua file attached to this npc contains only the code in the above code block)

Now that our NPC talks lets have him recognize the players name and race. With the help of the Get Functions this is a simple task. We will be using GetName(Spawn) and GetRaceName(Spawn), the only parameter these 2 functions need is the spawn we want to get the race/name of and they will return a string. Lets change the Say() function in the previous code block to utilize these 2 functions.

Code: Select all

function hailed(NPC, Spawn)
     FaceTarget(NPC, Spawn)
     Say(NPC, "Hello " .. GetName(Spawn) .. ", it is nice to see a " .. GetRaceName(Spawn) .. " around here!")
end

Now our NPC seems just a little bit more alive, but the player is still unable to really interact with him, that is where conversations come in. There are 3 things we need for conversations, first we must create a new conversation

Code: Select all

Conversation = CreateConversation()

Next we want to add the player choices, for that we use the following function

Code: Select all

AddConversationOption(conversation, string, function)

The first parameter is the conversation we just created, the second parameter is the text the player will see, the third parameter is the name of the function to call in this lua script if this option is selected, it can be named whatever you want and will recieve NPC and Spawn as parameters, it is optional and if left out the dialog will just close when the player selects that option. The function name also needs to be in quotes. AddConversation needs to be called for every option you want the player to have on this chat bubble.

Once you have all the players options set you can now set what the npc will say.

Code: Select all

StartConversation(conversation, NPC, Spawn, string)

The first parameter is the conversation we created, second is the NPC who will be talking, third is the player who the NPC is talking to, and finally the text to show. This is done last as this function will also cause the conversation to be sent, so if AddConversationOption() is called after this function it will not be shown to the player.

Lets use these functions to create a simple dialog, the npc will greet the player, using the players name, and ask how they are doing, the player will have 3 choices, 1 will exit the dialog the other 2 will lead to diffrent responces, both responces will have only 1 option for the player and that option will just exit the dialog. As this code is a bit longer I have added comments to explain the steps

Code: Select all

function hailed(NPC, Spawn)

	-- have the NPC face the player
     FaceTarget(NPC, Spawn)

	-- create the conversation
	conversation = CreateConversation()

	-- set the 3 player options
	AddConversationOption(conversation, "Good", "Choice1")
	AddConversationOption(conversation, "Not so good.", "Choice2")
	AddConversationOption(conversation, "I don't have time for this.")

	-- set the npc dialog and start the conversation
	StartConversation(conversation, NPC, Spawn, "Good to see you " .. GetName(Spawn) .. ", how are you today?")
end

-- This is the function called by the first choice
function Choice1(NPC, Spawn)

	-- face the target
	FaceTarget(NPC, Spawn)

	-- need to create another conversation
	conversation = CreateConversation()

	-- add the player option
	AddConversationOption(conversation, "Good Bye.")

	-- set NPC dialog and start the conversation
	StartConversation(conversation, NPC, Spawn, "That is good.")
end

-- This is the function called by the second choice
function Choice2(NPC, Spawn)

	-- face the target
	FaceTarget(NPC, Spawn)

	-- need to create another conversation
	conversation = CreateConversation()

	-- add the player option
	AddConversationOption(conversation, "Good Bye.")

	-- set NPC dialog and start the conversation
	StartConversation(conversation, NPC, Spawn, "That is to bad.")
end

(The code block above is the same script I used to get this picture)

With that we will end the first tutorial. I encourage you to read over the functions that are currently documented in the wiki and experiment some, using what you have learned here and with the SetModelType(Spawn, ModelID) you can create a npc to change the players model, or SetAdventureClass(Spawn, ClassID) to change the players class.

[John Adams]

Holy crap, Jab. This post rivals my own Nice work!

If I hear one more question about how to write a LUA script, I'm blocking IP addresses from this site