Introduction to Event Scripting

Goal of this tutorial

To understand the principles RoR script events work on by showing the existing uses.

Oil well Example

this simple example will create an oil depot that reacts on trucks that drive into it.

Prerequisites

• move nhelens.zip to the "My Documents/Rigs of Rods/terrains" folder and unpack all its files to a new directory "nhelens"
• remove the old nhelens.zip to prevent collisions
• Enable "Debug Collision Meshes" in your RoR configurator ('Settings'>'Debug'>'Debug Collision Meshes') to be able to see the debug visualization for events
• get an oil-well mesh and a fitting .odef file: http://forumold.rigsofrods.com/index.php?topic=28551.msg355869#msg355869

creating an event box

Method 1

• create an additional event box in blender:

• export this mesh with the same Origin Points as the rest of the mesh as "oil-well-eventcube.mesh" for this example.

• improve the .odef file to include this new event box. Add a new beginmesh to the .odef:
  • virtual : specifies that this mesh is an event mesh
  • event trigger truck: event <eventName> <eventType>
    • eventName : the name of the box that the script will get when being notified
    • eventType : valid eventTypes that trigger this: avatar, truck, airplane, delete

beginmesh
mesh oil-well-eventcube.mesh
virtual
event trigger truck
endmesh

Method 2

You can also create an event box without using blender by adding the following code to your .odef file:

beginbox
boxcoords 0.0, 20.0, 0.0, 5.0, -4.5, -0.5
virtual
event trigger truck
endbox

boxcoords defines the size and position of the box, relatively to the position of the object. The virtual and event lines are explained in method 1.

program the AngelScript file

• create a file named <filename>.terrn.as, so in our case the file should be called "a1da0UID-nhelens.terrn.as" when the terrain we use is called "a1da0UID-nhelens.terrn"

// Always include the base.as file!
#include "base.as"

string calledLast="";

void main()
{
	// spawn an oil-well
	game.spawnObject("oil-well", "my-oil-well-1", vector3(1119.44f, 33.933f, 924.982f), vector3(0, 0, 0), "myCallBack", false);
}

void myCallBack(int trigger_type, string inst, string box, int nodeid)
{
	if(calledLast == inst) return; // already triggered, discard

	// we log a message to the logfile
	log(inst + " event triggered");

	// We show a message ingame
	game.flashMessage(inst + " event triggered", 3, -1);

	calledLast = inst;
}

Test-Run

you should see this:

note: We're only interested in the pink boxes here, as they represent event boxes. Light pink boxes do not call back an AngelScript function, while dark pink boxes do call back an AngelScript function when triggered (~when you drive into them). More information about what the other colors mean can be found here.

if you do not see an oil loader, check the AngelScript.log file for errors. With no errors the log could read like this:

17:31:04: ScriptEngine initialized
17:31:04: ScriptEngine (SE) initializing ...
17:31:04: Type registrations done. If you see no error above everything should be working
17:31:05: ScriptEngine running
17:31:14: saving script bytecode to file c:\users\jeroen\docume~1\rigs of rods 0.38\cache\script_a1da0UID-nhelens.terrn.asc
17:31:14: Executing main()
17:31:14: The script finished successfully.

Result

What happens if you drive a truck into the pink event box:

look at your AngelScript.log:

02:55:05: SE| my-oil-well-1 event triggered

you can download the results of this example there: ScriptingTutorial1.zip

TODO: The event box of the file above is upside down (~under the ground) :/

Whats next

you could:

• check if the correct oil tanker trailer is in the spawn box
• direct the user to the oil unloading station after "loading the oil" (sleeping) for some time
• increase the node weight of a certain node inside of the tanker trailer to simulate the loaded oil.

Advanced Examples

for example this script will create two oil rigs and will redirect the user to collect and drop oil between them:

#include "base.as"

float timer = 0;
int timerSet = 0;

int state = 0;

vector3 pos_oil1(1099, 33.933, 924.982);
vector3 pos_oil2(1030, 33.4509, 1125.37);

void main()
{
	// spawn some oil-wells
	game.spawnObject("oil-well", "my-oil-well-1", pos_oil1, vector3(0, 0, 0), "callBackOilWellOne", false);
	game.spawnObject("oil-well", "my-oil-well-2", pos_oil2, vector3(0, 0, 0), "callBackOilWellTwo", false);
}

void frameStep(float dt)
{
	// count down the timer
	if(timer > 0)
		timer -= dt;
}

void callBackOilWellOne(int trigger_type, string inst, string box, int nodeid)
{
	//if(trigger_type != 1)  return; // we only want to trigger on events where the full truck is in the event box (doesn't work at the moment)
	if(state != 0) return; // only process this if state is valid
	
	if(timerSet == 0)
	{
		// set timer
		timerSet = 1;
		timer = 5;
		game.flashMessage("Loading oil ...", timer, -1);
		return;
	}
	
	if(timerSet == 1 && timer < 0)
	{
		// timer ran out, do something
		game.setDirectionArrow("unload oil", pos_oil2);
		state = 1;
		timerSet=0;
	}
}

void callBackOilWellTwo(int trigger_type, string inst, string box, int nodeid)
{
	//if(trigger_type != 1)  return; // we only want to trigger on events where the full truck is in the event box (doesn't work at the moment)
	if(state != 1) return; // only process this if state is valid
	
	if(timerSet == 0)
	{
		// set timer
		timerSet = 1;
		timer = 5;
		game.flashMessage("Unloading oil ...", timer, -1);
		return;
	}
	
	if(timerSet == 1 && timer < 0)
	{
		// timer ran out, do something
		game.setDirectionArrow("load some new oil", pos_oil1);
		state = 0;
		timerSet=0;
	}
}