Scripting Fundamentals

[thefoof]

In this guide I'm going to layout some fundamentals to scripting on EQ2Emulator. The sections to this guide are going to be Parameter Types, Using Functions, Setting Scripts to the Database, and Equations and If Statements.

Writing this guide because we've had a couple new folks interested in content, and explaining this to everybody takes too much time .

Some of what is in this guide can be found all over the web, but it's usually bundled with a ton of information you don't "need" to script for the emu so it all becomes a bit confusing.

With this info, you should know enough about how EQ2emu scripts work to start learning how to write them.

[thefoof]

So, first off let's cover some basic knowledge you should have for almost any type of programming; data types. For EQ2Emu LUA scripts in general, the only types you need to understand are Strings, Pointers, and Variables.

1. Variables

A variable is just that - like in algebra, it's a term that holds a value. To create a variable you must do what is known as "declare" it. To do this you just either type the name of the variable followed by an equal sign and then put a value on the other side (assigning the value to that variable), or you may type local followed by the variable name (honestly I'm not sure the difference ). You may assign any type of data you wish to a variable. Examples:

Code: Select all

Zone = GetZone(NPC)
X = GetName(NPC)

I don't expect you to know all the details for these functions at this point, but you can probably guess by looking at them . Basically what these two statements have done is assign the variable Zone with the zone pointer for the zone NPC is in. More on pointers later, just trust me for now. The variable X ran the function GetName(NPC), which returns the string value of the NPC's name. X now holds the value of that NPC's name.


2. Strings

A string is basically some text that is treated as just that - text. All you need to do to treat some text as a string, is enclose it in either double quotes (") or single quotes ('). When using a string, everything you put into it is treated as one entity. In other words you can write words that would otherwise be considered a variable, without it using the value of that variable. Certain functions require strings specifically for certain parameters, we'll cover parameters in the next section.

What you need to keep in mind with strings, when you use the same type of quote you used to start the string, the string ends. In other words if your string contains either a single or double quote, you should start the string with the other type of quotation.

Let's say you have a rather complicated string that contains both inside the string, what you then need to do is what's known as Concatenation. All this means is combine two strings, and you do this by placing two periods between the strings, here's an example.

Code: Select all

"Hello there! It's so cold out! Can you teach me how to make a" .. '"snowman"?'

Which evaluates to the text Hello there! It's so cold out! Can you teach me how to make a "snowman"? (I'm not a wordsmith )

3. Pointers

A pointer is kind of like a shortcut. Every Spawn and Player, and other values inside the server have a reserved address in memory for them. A pointer is like a link that points to that address. Almost ALL functions will use a pointer of some kind, in at least one of the parameters. To get these pointers, you generally pass them from one function to another, or there are other functions you may use to get a pointer, and you can either use that function directly in another function, or save the pointer value to a variable.

[thefoof]

Equations are just checks to see whether a statement is true or false. These are typically used in If statements which you'll read about soon. You use operators to determine whether something is true or false, or use a variable you set manually as true or false at some other point of the script. Remember that if something evaluates to 0 it's always false. Here's a list of LUA operators you may use in equations:

> - greater than
< - less than
>= - greater than or equal to
<= - less than or equal to
== - equal to
~= - not equal to
and - means there's another statement following that must also be true for the statement to continue
or - means there's another statement following where if either the first statement or following is true, the if statement may continue

Another piece of almost universal programming knowledge: If statements. An if statement is just a statement to choose what to do between different scenarios. You typically write a statement, enter a newline and then move over a tab to the right past the if. You must end each statement with then, and each if with the word "end" on the next line after the if statement finishes. Example:

Code: Select all

if 57 < 56 then
    do this
elseif not 1 == 2 then
    do this
else
    do this
end

What this means, if the first statement is true, it will run everything inside the first tab. If the second statement is true, it runs everything inside the else if. If neither of the first two statements are true, it will run everything inside the else. (In this example the second statement will always execute.) You can run if statements inside of if statements and make things as complicated or simple as needed by the script you're writing. If you wish to continue a script under a false condition, you may either add == false after the condition, or put the word not before the condition.

[thefoof]

The emulator has many different functions, most of which you can find here: http://www.eq2emulator.net/phpBB3/viewt ... f=30&t=633 and posted throughout that forum. Different functions return different values, and use different parameters to determine those values. Some don't return anything at all and instead set a value in the server itself. You'll have to look at the syntax of each function individually to see what it does or what types of parameters it uses (I'm always open to questions shoot a pm.)

To declare that you are using a function in a script, or create a function that only works in that script you write on a newline outside of a function, the word "function" followed by FunctionName(param1, param2, ....). To close a function, you add the word "end" after the function. You may call other functions from inside of a function.

The emu has what I call "root" functions, and then "extension" functions. A "root" function is something that's called from within a certain thing happening in game. You must have a "root" function called or your script will do absolutely nothing. Extensions are called through root functions. Examples of root functions:

Code: Select all

function spawn(NPC) - this function is called when a spawn pops into the world. the game automatically passes the one parameter, which we write as NPC in scripts. (You may substitute NPC for a different variable name technically speaking, but for official scripts using NPC as the main spawn of the script is the standard, anywhere in the function you write NPC, NPC gets substituted with the spawn's pointer. This same principal applies to all functions.)

function respawn(NPC) - called when a spawn respawns.

function hailed(NPC, Spawn) -called when the spawn is hailed -  where NPC is the spawn hailed, and Spawn is the Player that hailed it. - Spawn is the standard word used for players in spawnscripts.

function death(NPC, Spawn) - called when a spawn dies - where NPC is the spawn that was killed, Spawn is the killer of that spawn.

function casted_on(NPC, Spawn, SpellName) - called when a spawn has a spell or entity command cast on it - where NPC is the spawn casted_on, Spawn is the caster of the spell, SpellName is the string value of the spell casted's name.

And many more. Just remember when writing your scripts, your script MUST contain at least one of these root functions, or nothing in your script will do anything!

The way parameters in LUA and most other programming languages are used is -- by the placement. Say that from the function hailed() we called the function Example() like this: Example(NPC, Spawn, "!")

Code: Select all

function Example(NPC, Spawn, exclamation)
    Say(NPC, "Hello there, " .. GetName(Spawn) .. exclamation)
end

We know the first parameter from hailed is the npc that was hailed, and the second is the spawn that hailed it. We also know the syntax for Say is Say(Spawn, "string"). We passed the parameter "NPC" from hailed, in the first position, and we again named it NPC in the function Example() (again it's not within our scripting standards for spawnscripts, but you can change the names of params.) So here, the NPC would use the Say chat channel to speak the string that has followed, you wouldn't normally pass a string that just contains an exclamation point, I just did it here to show how you can pass other things.

Remember that for functions you create yourself, you may use any parameters in any order you wish -- but hardcoded functions that interact with the game have preset syntaxes you must follow.[/b]

[thefoof]

So you wrote your first script, now how do you get it to work in-game? This is fairly easy.

All you need to do is go to your spawn_scripts table in your world database, enter your script path from where your EQ2World.exe is located into the lua_script field (example: SpawnScripts/Generic/movement_circle_small.lua), and then enter either the spawn_id, placement_id, or entry_id of that spawn. (I believe the order of which each field will overwrite the other is entry_id > location_id > spawn_id, someone correct me if I'm wrong)


That's the end of the guide, I hope it helps somebody. I'm no teacher so if I wasn't clear on something let me know.