Scripting Tutorial: Scripts

From PBnWModdingWIKI

Contents 1 Getting Started 2 Scripts 2.1 Define Script 2.1.1 Parameters 2.2 Write Script 2.3 Run Script 2.3.1 Background Scripts 3 Author

Getting Started

Just a quick tutorial on how multiple scripts in the same file works. Mail Me if you need something added or expanded upon.

In this tutorial I am going to assume that you have read this: Getting Started

Scripts

I'm going to take you through 3 simple steps.

1. Defining the script.
2. Writing the script.
3. Running the script

Define Script

Before you can use a script you have to define it. To define a script you use "define script ScriptName". Script definitions should always be at the top of the file. If you followed the Getting Started tutorial you should now have something like this:

define script NewScript

run script WikiTutorialScript

begin script WikiTutorialScript
start
	disable load screen
	set fade in time 1
	wait until 1 != 1
end script WikiTutorialScript

Parameters

When you define a script you can also give that script a set of parameters. These can be expressions or objects that you want to use in the script. Now, the usefulness of this is that you can use the same script in many different instances. E.g. you can make a script that creates a creature in a specified town.

You define a script with parameters like this:

define script NewScript(nTown)

You can now use the variable nTown in your script, like you would any other variable.

// You also have to specify the used parameters when beginning the script.
begin script NewScript(nTown)
	// Instead of just getting Town 0, we can now use the same script to get any town we want.
	oTown = get town with id nTown
	nPlayer = get oTown player
	oPen = get building ABODE_NUMBER_CREATURE_PEN in oTown min built 1.0
	oCreature = 0
start
	oCreature = create SCRIPT_OBJECT_TYPE_CREATURE CREATURE_TYPE_WOLF at {oPen}
	set player nPlayer creature to oCreature
	release oCreature

// You don't have to include parameters when ending a script.
end script NewScript

The value of nTown is set when running the script. Let's say you want to create a creature in the player's town and one in the computer's town.

// This will create a creature in Town 0.
run script NewScript(0)

// This will create a creature in Town 1.
run script NewScript(1)

You can have more than one parameter. Each parameter is seperated by a comma. The definition of a slightly more advanced creature creation script could look like this:

define script CreateCreatureInTown(nTown, nCreatureType, nSize, nAlignment)

Write Script

All scripts start with "begin script ScriptName". After beginning a script you can define variables. Let's do something fun like creating a creature at the creature pen in the player's town and assigning that creature to the player.

// Begin Script.
begin script NewScript

// Get the player's town.
oTown = get town with id 0
// Get the creature pen in oTown.
oPen = get building ABODE_NUMBER_CREATURE_PEN in oTown min built 1.0
// Define and create the creature.
oCreature = create SCRIPT_OBJECT_TYPE_CREATURE CREATURE_TYPE_WOLF at {oPen}

// Here starts the body of the script.
start

	// Now, let's assign the creature we created to the player.
	set player 0 creature to oCreature
	// Creatures seem to behave more naturally if you release them from script.
	release oCreature

// End script.
end script NewScript

Run Script

Now that you have defined the script and written the script body you can execute it from the main script. To do that you use "run script ScriptName". You can call a script from the body of any other script.

define script NewScript

// Run main script.
run script WikiTutorialScript

begin script WikiTutorialScript
start
	disable load screen
	set fade in time 1

	// Execute your new script.
	run script NewScript

	wait until 1 != 1
end script WikiTutorialScript

// New scripts should be placed below the main script.
begin script NewScript

oTown = get town with id 0
oPen = get building ABODE_NUMBER_CREATURE_PEN in oTown min built 1.0
oCreature = create SCRIPT_OBJECT_TYPE_CREATURE CREATURE_TYPE_WOLF at {oPen} using only alignment good neutral

start
	set player 0 creature to oCreature

end script NewScript

Background Scripts

First we will have a look at "run script ScriptName".
From the documentation: "runs a script, and does not return control to the script which calls this statement until the called script is finished."

What this means is that if you have a script that calls another script with an infinite loop in it the first script will never finish. It is also good to keep in mind that long scripts takes time to execute.

In this example Moo2 will never return control to Moo1, so Moo1 will never get to DoStuff. Moo2, however, will forever DoMoreStuff. (Moo2 is such a bully ;).

define script Moo1
define script Moo2

begin script Moo1
start
	run script Moo2
	DoStuff

end script Moo1

begin script Moo2
start
	begin loop
		DoMoreStuff
	end loop

end script Moo2

Now, this is where background scripts enters the picture.
From the documentation: "Runs a script as a background task, and continues running the script which called it."

So if we run Moo2 as a background script instead, Moo1 will call Moo2 and then DoStuff.

define script Moo1
define script Moo2

begin script Moo1
start
	run background script Moo2
	DoStuff

end script Moo1

begin script Moo2
start
	begin loop
		DoMoreStuff
	end loop

end script Moo2

See? Moo1 will just tell Moo2 to do his thing and then continue with his own work.

Background scripts can also be used for scripts that will wait for certain conditions to be met before continuing.

Author

--Serdan 16:55, 12 March 2006 (PST)

e-mail/MSN: [email protected]
Website: http://aruiz.dfxwebs.com

Feedback is always appreciated. ^_^