A to Z Scripting: More scripting basics

From The DarkMod Wiki
Jump to navigationJump to search

Working tidily

Rule #1 is to keep your scripts tidy and well-commented so they're easy to follow. That includes making liberal use of the 'tab' key, which lets you quickly align your lines.


Comparison 1: script for reading spawnargs that the mapper has set on a func_mover entity 

//bad
vector mover_translate	= $wardrobe.getVectorKey("translate");
vector mover_rotate = $wardrobe.getVectorKey("rotate");
float mover_time = $wardrobe.getFloatKey("move_time");

//better
vector	mover_translate	= $wardrobe.getVectorKey("translate");
vector	mover_rotate	= $wardrobe.getVectorKey("rotate");
float	mover_time	= $wardrobe.getFloatKey("move_time");	//time taken to move


Comparison 2: script for constantly checking if an AI can see the player 

//bad
void watch_for_player()
{
while(1)
{
if($lord_marlow.canSee($player1))
{
$lord_marlow.bark("snd_i_see_you");
return;
}
sys.wait(0.5);
}
}

//better
void watch_for_player()
{
	while($player1.getLocation() == $master_bedroom)	//for as long as the player is in the master bedroom...
	{
		if($lord_marlow.canSee($player1)		//check if Lord Marlow can see the player
		{
			$lord_marlow.bark("snd_i_see_you");	//if yes, make Marlow say something to the player
			return;					//then end this script
		}
		sys.wait(0.5);					//wait 0.5s before checking again
	}
}


General tips

  • Scripting is case-sensitive.
  • The scripting engine reads from top to bottom. That makes the order in which scripts and variables are arranged quite important. You can't call a script or use a variable if the engine hasn't seen it defined yet.
  • The $ sign instructs the engine to look for an entity ingame with that name. If there's no $ sign, the engine will instead look for a variable with that name in the scripts.
  • Commenting can be done either by putting // in front of every line of comment, or by putting /* at the top and */ at the bottom. The latter is useful for multi-line comments or temporarily disabling a section of your script.


Data types

Data type indicates whether something is a text (string), number (float), vector etc. You will always want to be aware of this, since i.e. a script designed to apply a force vector won't work if you give it a string instead of a vector as input.

String A string of letters/numbers, in other words plain text. It must always have double quotation marks. Example: “Text message 123”
Float A float is a single number, decimals are allowed. Example: 15.2
Vector A vector consists of 3 numbers, often used for 3D movements (x y z) or colors (red green blue). It must always have single quotation marks. Example: '0 90 0'
Boolean Can be true or false. Easily replaced by floats (0 or 1). Example: TRUE
Void No type. Commonly used for scripts or script events that have no output.
Entity Indicates an entity, usually using the name as seen in DR. If it's a specific entity, instead of a variable, then a $ sign is required. Example: $player1
Subcategories of “entity” You can be more specific and define an entity as, for example, an ai, light or tdm_elevator. These are names of scriptobjects, and by defining an entity like this you gain access to that scriptobject's internal variables and scripts. For an "ai", useful internal variables are i.e. whether the AI is alerted or knocked out. (see A to Z Scripting: Scripting with... - "AI flags" for more)


Variables

Variables are an important part of scripting. Each variable stores a piece of data, such as an entity's name or a position, which can then be modified or used by a script event. They allow a single script to have various effects, depending on the values of the variables.


Creating new variables

The first time the engine finds a variable in a script it needs to be given a data type. Afterwards you use just the name. Example: 

vector teleportation_destination;			//create a new vector variable called "teleportation_destination"
...
$player1.setOrigin(teleportation_destination);


You may also want to assign an initial value. Otherwise, floats will default to 0, strings to "", vectors to '0 0 0', entities to $null_entity and booleans to false. Example: 

vector teleportation_destination = '44 68 122';


Another option is to create a variable using the output of a script event. 3 Examples: 

vector teleportation_destination	= $func_static_1.getOrigin();

float can_see				= $guard_westwing_1.canSee($player1);

float sound_duration 			= $entity1.startSound("snd_move", SND_CHANNEL_ANY, false);  //stores the duration of the sound that's been started


Where to create variables

It's important whether you create a variable inside of a script or outside.

If it's created inside of a script (locally), only that script can use it. Also, every time you run the script the variable will discard its old value because it gets recreated in the script. Example: 

void count_targets()		//counts how many targets there are on a relay entity
{
	float number_of_targets = $trigger_relay_1.getNumTargets();
}


If it's created outside of a script (globally), all scripts that come afterwards will be able to use it (remember that the engine reads from top to bottom). Note that you can't run script events outside of scripts. Example: 

vector target_position = '48 93 222';

void move_to_position()
{
	$func_mover_1.speed(30);
	$func_mover_1.moveToPos(target_position);
}

Example: puzzle with max 3 attempts

Say you wanted to give a player 3 attempts to solve an optional puzzle, with an option to reset his number of attempts: 

float attempts_left = 3;		//set the value of attempts_left to: 3. This is a float variable.

void attempt_failed()			//this script is called every time the player fails an attempt
{
	attempts_left	= attempts_left - 1; 			//new value of attempts_left is: current value - 1

	if (attempts_left == 0) $puzzle.setFrobable(0);		//if no more attempts, make the puzzle entity unfrobable
}

void reset_attempts()				//calling this script resets the player's attempts
{
	attempts_left = 3;

	$puzzle.setFrobable(1);			//also make sure the puzzle entity is frobable
}



Using the TDM Script Reference

The TDM Script Reference is an essential wiki resource for scripting, listing all available script events for the current version of TDM. All script events are listed twice: the first time they're sorted alphabetically, the second time they're grouped based on which kinds of entities they can be called on. By far not all script events have received manual descriptions, so sometimes you may need to experiment with them to properly figure them out.


Example: bob()

scriptEvent void bob(float speed, float phase, vector distance);

   Initiates a translation back and forth along the given vector with the given speed and phase.

   Spawnclasses responding to this event: idMover

Interpretation:

  • void means this script event has no output (unlike, for example, a script that checks the health of an AI)
  • the script event's name is bob
  • when you use this event, you need to put 3 things into the input brackets: 2 floats and a vector
    • all 3 have informative names to tell you what their purpose is. There's also a description on the next line.
  • This script event will only work on func_movers.


So, the below line would make a mover called func_mover_1 start bobbing with a speed of 10 units per second, in phase 0.2 (i.e. start at 20% of the way through the first movement cycle) and over a distance of 30 units: 

$func_mover_1.bob(10, 0.2, 30);


Example: canSee()

scriptEvent float canSee(entity ent);

    no description

    Spawnclasses responding to this event: idAI

Interpretation:

  • unlike the previous event, this one produces a float as output. canSee() is a yes or no question, so this float will probably return 0 if no or 1 if yes.
  • the input brackets require you to specify an entity, in addition to the one that the event is being called on. So the event checks if one entity can see another entity.

' no description in this case.

  • the script event only works if called on an AI (but you're probably allowed to check if an AI can see non-AI entities).


It might take some experimentation to figure out which entity the script event should be called on and which entity should go into the input brackets. In the end it could look something like this: 

$guard_westwing_1.canSee($player1);


You can store the result as a variable for later use: 

float	guard_sees_player = $guard_westwing_1.canSee($player1);


Next / previous article

Retrieved from "https://wiki.thedarkmod.com/index.php?title=A_to_Z_Scripting:_More_scripting_basics&oldid=27016"