Crash Course: Scripting 101-B

Tue, 28 Jan 2014 13:16:00 +0000

I know it's been a while, but hopefully I'll be pushing these out more frequently. This is a continuation to Crash Course: Scripting 101-A, which I wrote back in November. Normally, I would have written it all in one huge post; however, due to complications with our forum software deleting my original post twice, I decided to break down the course in parts. This format should help me space out the time between posts, and focus more intensively on specific areas that might otherwise be undermined.

Anyway, let's get on with it, shall we?

III: Expressions
Logical expressions are often used in scripting to determine a set of rules or prerequisites for a specific event or scenario to happen. These expressions can be used to determine numerous things during gameplay, and can be regularly found in quest NPCs or anything that works around special conditions in order to operate.

Sample script:

mes "[Random Guy]";
mes "Hello there! What's your name?";
next;

input .@my_name$;

mes "[Random Guy]";
if (strcharinfo(0) != .@my_name$) {
	mes "Well, that's odd! Your nametag...hey, come back here!";
} else {
	mes "That's a nice name you've got there!";
}

close;

Here's a situation where some fellow is asking for a player's name. Players are prompted with the input command, storing their answer in a temporary NPC string variable called .@my_name$. In the script, we present the player with a logical expression that determines whether or not they told us the truth by comparing strcharinfo(0) against .@my_name$:

if (strcharinfo(0) != .@my_name$) {

If the if expression is found to be true, the script will proceed to include the code within the curly braces { } after the expression; otherwise, it will run the code in the curly braces after else in its place. However, no matter what message is displayed, a close will be executed afterwards, as it is impartial to the condition set by the if...else expression. Note that it is not required to use else, but it is useful when substituting text or code. Before we move onto the next section, here are some things you might find useful to know:

strcharinfo(0) returns the name of the attached player in a string format; if a player's name is Player A, the name will be returned as "Player A".
strings are any sequence of characters (letters, numbers, and symbols) that are enclosed in quotation marks.

IV: Concatenation
In formal language theory and computer programming, string concatenation is the operation of joining two character strings end-to-end; in English, this process is commonly known as "sequencing". In *Athena scripting, concatenation is used to piece words and information together dynamically - and by dynamically, I mean with the ability to change with little or no intervention from the scripter.

Sample script:

mes "[Random Guy]";
mes "Hello there! What's your name?";
next;

input .@my_name$;

mes "[Random Guy]";
if (strcharinfo(0) != .@my_name$) {
	mes "Well, that's odd! Your nametag doesn't say "+ .@my_name$ +"!";
} else {
	mes "That's a nice name you've got there, "+ strcharinfo(0) +"!";
}

close;

Let's use the script from earlier as an example. In order to concatenate a string, a plus sign + must trail a closing quotation mark, followed by the string you want to include. If the player input his name as Player B, .@my_name$ will be the equivalent of "Player B" - quotation marks included. Comparatively, the message in the if expression would say:

mes "Well, that's odd! Your nametag doesn't say "+ "Player A" +"!";

Think of concatenating as adding onto an existing string using variables or functions. In this example, strcharinfo(0), is being used to return the player's name as it is stored on the server; if the player's name is Player A, the function will return the string "Player A". Always keep in mind that you are concatenating strings, which must be enclosed in quotation marks to be read by the script parser properly.

Crash Course: Scripting 101-A

Tue, 12 Nov 2013 15:33:00 +0000

Prologue
When I first got into *Athena scripting, it would have been a great convenience to have a decent guide, teacher, or even a friend to learn with. Back then, the documentation for script commands wasn't very good (not that it's anything glamourous now), people didn't have the patience to sit down and go over the basics, and my friends who were into computers/gaming had no interest in anything remotely related to programming.

A lot has changed over the years, and it's been rather interesting to see myself push the limits of *Athena emulators through mere scripting; if you asked me to explain making source modifications for *Athena emulators, you'd hear me blabber things I learned in a C++ programming class I took over summer, and that's about as helpful as I can get - and *Athena emulators were written in C.

But enough about me; let's get back to why you're here.

I: Structure and Formatting
In this section, we'll cover basic script structure and formatting.

Sample script:

prontera,144,174,3	script	Test NPC#prt::testnpc	4_M_MOCASS2,{
 
	mes "[Test NPC]";
	mes "Text will be displayed here.";
	close;
	
}

Let's break this down, piece by piece:

prontera,144,174,3	script	Test NPC#prt::testnpc	4_M_MOCASS2,{

Location
Determine the location you would like your NPC to be on by moving to that area and typing '/where' in-game. If you would like your NPC to not have a physical location (known as a "floating" NPC), use a hyphen <->.

prontera - the name of the map which the NPC will be located
144 - the x-coordinate of the target cell the NPC will be placed upon
174 - the y-coordinate of the target cell the NPC will be placed upon
3 - the direction which the NPC will be facing

Think of numerical directions as though you were looking at this grid:

[1][0][7]
[2]   [6]
[3][4][5]

Object
Define the type of object you are writing, and its corresponding name(s).

script - defines the object as an NPC script
- other objects include duplicates, shops, warps, mapflags, etc. - but we'll get into that later
Test NPC - the visible part of an NPC's display name; if no other names are given, this defaults as the NPC's unique name as well
#prt - the hidden part of an NPC's display name, prefixed with a pound sign <#>; it serves as an identifier to distinguish duplicates
::testnpc - the NPC's unique name, prefixed with two colons <::>; it is the name used when duplicating, warping to, or unloading NPCs
4_M_MOCASS2 - the NPC's sprite name constant which will be displayed; before 9f32aa9, this was commonly just the sprite ID
- Sprite IDs are still acceptable to use; if you want your NPC to be invisible, use -1
- A complete list of constants can be found in db/const.txt
,{ - this is the opening brace (also known as a "curly"), prefixed with a comma <,>; it ends the header and indicates the beginning of the script
- A common mistake is to forget that comma - so don't forget!

Keep in mind that the whitespace in the header are actually tabs <TAB>, not spaces; the header will not be read properly if spaces are used.

Scripting

	mes "[Test NPC]";
	mes "Text will be displayed here.";
	close;

Let's tell our script what we want our NPC to do; write out your script commands! A complete list of script commands can be found in doc/script_commands.txt.

mes - tells the script parser that we want to display a message in a dialogue box
"[Test NPC]" - the NPC's name, enclosed in quotation marks <">; quotation marks won't be displayed
- This is simply a vanity; an NPC name is not required, but it looks nice
- Any text enclosed in quotation marks from a mes command will be displayed in a dialogue box
; - script commands MUST end with a semi-colon <;> to indicate the end of the command
close - creates a close button and terminates the script once encountered
- Don't forget that trailing semi-colon; close is a command too!

Indentation
Like our header, the whitespace used to indent sections of our script are tabs, not spaces. Make a habit of indenting your script (especially if its nested/enclosed) with one tab; this improves readability and makes it easier for others to understand different sections of your script.

End of Script

The last thing you'll need to remember is to close that brace we opened earlier, when we wrote the header.

} - the closing brace, which is complementary to the opening brace in the header; it encloses the script and indicates the end of the file

For the sake of practicing good scripting habits, always close your braces (and brackets, parentheses, etc.) first, before scripting anything; this will help prevent any enclosures from having stray/missing braces. Braces are also used in expressions, which is what we'll get into next.

II: Variables
As your scripts become more complex, you'll find yourself wanting ways to reduce repetitiveness and increase flexibility. Typing the same thing over and over again gets old fast; we can improve scripts by using variables to represent constant values within our script. Variables can also be used to represent temporary values within our script - or even permanent values that can be referred to by other scripts as well. Let's go over the various variable types and how we can use them. For the sake of shorthanding, let's name the example variable "var".

Types
There are two types of variables that determine what data can be stored in the variable.

Integer variables are not postfixed with anything, and can only store numerical values
```
var = 1;
```
String variables are postfixed with a dollar <$> sign, and can store various letters, symbols, numerical values in the form of strings
```
var$ = "Some string of letters (abc), symbols ($#) and numbers (123).";
```

Extent
Similar to a type, the extent of a variable indicates how long it can be used.

Temporary variables are prefixed with an at <@> sign, and only last as long as the variable's scope will allow
```
@var = 1;
```
Permanent variables are not prefixed with anything other than their scope's prefix, and will last indefinitely unless they are cleared
```
var = 1;
```

Scopes
Variables have different ranges that they can effect; known as "scopes", these determine what they can be used for. When a variable is "attached", it means that variable is stuck with its attachment wherever they go or are invoked.

NPC
NPC variables are prefixed with a period <.> and are attached to the invoking script; temporary NPC variables are cleared when the script ends

.var = 1; // Permanent NPC variable

.@var = 1; // Temporary NPC variable

Character
Character variables are prefixed with nothing and are attached to the invoking player; temporary character variables are cleared when the player logs out
```
var = 1; // Permanent character variable
```
```
@var = 1; // Temporary character variable
```
Account
Account variables are prefixed with a pound sign <#> and are attached to the invoking player's account; there is no temporary version of this scope
```
#var = 1; // Permanent account variable
```
Global Account
Global account variables are prefixed with two pound signs <##> and are stored in the login server; the only differentiation this scope has from normal account variables is that global variables can be accessed across multiple character servers
```
##var = 1; // Permanent global account variable
```
Global
Global variables are prefixed with a dollar sign <$> and can be accessed from any script; temporary global variables are cleared when the server is restarted
```
$var = 1; // Permanent global variable
```
```
$@var = 1; // Temporary global variable
```
Instance
Instance variables are prefixed with an apostrophe <'> and are attached to the invoking party's instance; there is no temporary version of this scope
```
'var = 1; // Permanent instance variable
```

Remember to only use variables in the scope in which they are needed. Review this section thoroughly until you no longer have to reference it; as we progressively move onto more complex scripts, you'll save much more time knowing the basics rather than having to review them constantly.

Mumbles' Mumbles

Crash Course: Scripting 101-B

Crash Course: Scripting 101-A