ScriptSlave commands
 
These are the commands which control script slave entities: func_scriptobjects, func_scriptmodels and func_volumetric. Scriptslave entities are a subclass of trigger entities, they also respond to many trigger and entity commands (gameX86 source code reference: scriptslave.cpp).

ScriptSlave commands are colored in blue in my custom SinScript syntax coloring wordfile for UltraEdit32.


endpath
 
Function
 
This makes an object stop following or looping a path of info_splinepath nodes.

Syntax
 
$<object_name> endpath

Notes & examples
 

explode  
 
Function
 
This makes a scriptobject or scriptmodel spawn an explosion effect from the location of its origin. The scale of the explosion and the damage it inflicts can be set by including the optional command arguments.

Syntax
 
$<object_name> explode <damage_points> <scale>

Notes & examples
 
If the damage and scale arguments are omitted, the default values are based on the size of the object or model.


followpath
 
Function
 
This will make an object move along a path defined by a string of daisy-chained (target to targetname) info_splinepath nodes. By default, the object will gradually orient itself to the "angles" value of each splinepath node while moving toward it. Also, if the object was rotating prior to the command, it will stop all rotation movement before it starts following the path.

Syntax
 
$<object_name> followpath $<splinepath_node> <arg> loop

Notes & examples
 
The choices for the optional <arg> in the command line are:

normalangles:


ignoreangles:


follow the direction of the splinepath. IOW, the object or model will "look" in the same direction it is traveling.

will ignore the angle information stored in the spline or the forward vector of the movement generated by the spline.

Making objects follow a path:

The info_splinepath entities need to be daisy-chained together by matching the target-targetname keys to one another. When the followpath command is executed, the object will move to the splinepath node specified in the command argument and follow all the other splinepaths in the chain up to the last one in an open path. If the last splinepath node's "target" key points to the first splinepath node in the chain to create a closed path, the object will stop at the node that precedes the one where it started.

In order to make some sense out of this, first take a look at Figures 1 and 2 below to see the difference between an open path and a closed path:

Fig. 1
Fig. 2
Figure 1: Open path

Figure 2: Closed path

In Figure 1, there are 6 splinepath nodes with targetnames "sp1" to "sp6". The first node "sp1" targets "sp2", "sp2" targets "sp3" etc. all the way to the last node "sp6". But the last node "sp6" does not target the first node "sp1" and thus the path is open.

In Figure 2, there are 6 splinepath nodes with targetnames "sp1" to "sp6" connected together the same as in Figure1 except that here, the last node "sp6" does target the first node "sp1" and thus closes the path.

So what is the difference between making making an object follow an open path or a closed path? That all depends on which pathnode you make it start following the path. In the first example, I'll instruct a scriptobject (named "ob1") to start following on "sp1" on both the open and closed paths:

Fig. 3
Fig. 4
Figure 3: Following an open path

Figure 4: Following a closed path

            follow_openpath:
            $ob1 follow $sp1
            waitFor $object1
            end


            follow_closedpath:
            $ob1 follow $sp1
            waitFor $object1
            end


As you can see in Figures 3 and 4, there is no difference in the result when making "ob1" follow the open or closed paths. But the reason for this is that I instructed "ob1" to start following the path on the first node "sp1" of the open path. Here, the last node in the open path happens to be the same as the node that precedes the one where it started in the closed path: "sp6". So in both cases, "ob1" sees "sp6" as being the last node in the path.

Now let's see what happens if we make "ob1" start following the path on a node other than "sp1" in both cases. I chose "sp4" for this example:

Fig. 5
Fig. 6
Figure 5: Following an open path

Figure 6: Following a closed path

            follow_openpath:
            $ob1 follow $sp4
            waitFor $object1
            end


            follow_closedpath:
            $ob1 follow $sp4
            waitFor $object1
            end


Ah! Now this is where the difference between an open or closed path counts. As you can see in Figure 5, "ob1" will start following the open path at "sp4" and stop at "sp6" because "sp6" is the last node in the path. But in Figure 6, "ob1" will start following the path at "sp4" and stop at "sp3" because it's the node that precedes the one where it started in the closed path. In this case, "ob1" effectively sees "sp3" as the last node in the path.

By knowing the difference, you can choose whether you want to close the path or leave it open depending on where and how you want the object to move along the path.

Making objects follow a path and loop:

To make an object loop the path over and over, you must add the "loop" argument at the end of the command line. Here again, leaving the path open or closing it will make a difference depending on what node you instruct the object to start following the path. Also, when the "loop" argument is used, the object will start following the path at what it considers to be the last node in the chain instead of the first node (when loop is not used).

Note:
Setting the info_splinepath entity's "loop" key has absolutely no effect on func_scriptobjects or func_scriptmodels when instructed to follow or loop a path. The "loop" key only affects cameras (func_camera and func_securitycamera) instructed to orbit a path.


Let's use the same set of open and closed paths in the example above to see how this affects objects looping a path:

Fig. 7
Fig. 8
Figure 7: Looping an open path

Figure 8: Looping a closed path

            follow_openpath:
            $ob1 follow $sp1 loop
            waitFor $object1
            end


            follow_closedpath:
            $ob1 follow $sp1 loop
            waitFor $object1
            end


As you can see in Figures 7 and 8, there is no difference in the result when making "ob1" loop the open or closed paths. In both cases, "ob1" will start following at "sp6" and loop the entire path because in both the open and closed path examples, it considers "sp6" as the last node in the path.

Now let's see what happens if we make "ob1" start looping the path on a node other than "sp1" in both cases. I chose "sp4" for this example:

Fig. 9
Fig. 10
Figure 9: Looping an open path

Figure 10: Looping a closed path

            follow_openpath:
            $ob1 follow $sp4 loop
            waitFor $object1
            end


            follow_closedpath:
            $ob1 follow $sp4 loop
            waitFor $object1
            end


Here again, this is where the difference between an open or closed path counts. By observing where "ob1" starts following the path and which nodes it loops in Figure 9 and Figure 10, you can see that the result is not at all the same:

In Figure 9, "ob1" is instructed to follow the path starting at node "sp4". What happens first is that the object looks for all the nodes that can be "seen ahead of sp4" up to the last one in the path. Since the path is open, this happens to be "sp6" because that's where the path ends. Having found what it considers as the last node in the path, "ob1" jumps to it and starts looping the path:

sp6 -> sp4 -> sp5 -> sp6 -> sp4 ... etc.

In Figure 10, "ob1" is instructed to follow the path starting at node "sp4". What happens first is that the object looks for all the nodes that can be "seen ahead of sp4" up to the last one in the path. But in this case, since the path is closed, the object will "find" nodes beyond "sp6" all the way to "sp3". Remember that in a closed path, the node that precedes the one specified in the command is considered to be the last node in the path. Having found what it considers as the last node in the path, "ob1" jumps to it and starts looping the entire path:

sp3 -> sp4 -> sp5 -> sp6 -> sp1 -> sp2 -> sp3 -> sp4 ... etc.

Making an object loop predictably around a path seems more complicated because of this "start at last node" thing instead of just starting at the node specified in the command like for non-looping paths. But once you get the basic idea, it really isn't (it just makes it much harder to explain :P ).


jumpto
 
Function
 
Instantaneously moves an object from its present location to the location of an entity's origin or to an XYZ coordinate. This is independent of any previous speed or time commands and the object will simply "snap" to the designated location.

Syntax
 
$<object_name> jumpto $<entity_name>|"(<X Y Z>)"

Notes & examples
 
When using a coordinate as an argument, make sure you enclose the XYZ values in double-quotes and parentheses otherwise the command won't recognize the argument as valid. If you had previously stored the coordinates in a vector variable, you can use that variable's name as the command argument.

Note:
Do not confuse this command with the jumpto Actor command. It is an entirely different command with a different function even though it has the same name.



moveBackward
 
Function
 
Makes an object move backward by the number of map units specified in the command argument. The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.

Syntax
 
$<object_name> moveBackward <distance>

Notes & examples
 
For a scriptobject or scriptmodel, the forward, backward, left and right directions are relative to the current "angle" or "angles" setting of the entity: the direction in which it's pointing IOW. For example, if the scriptmodel has its "angle" key set to 90, forward is 90 degrees, backward is 270, right is 0 and left is 180.


moveDown
 
Function
 
Makes an object move down by the number of map units specified in the command argument. Down is toward the Z negative map coordinates.

Syntax
 
$<object_name> moveDown <distance>

Notes & examples
 
The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.


moveEast
 
Function
 
Makes an object move east by the number of map units specified in the command argument. East is toward the X positive map coordinates.

Syntax
 
$<object_name> moveEast <distance>

Notes & examples
 
The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.


moveForward
 
Function
 
Makes an object move forward by the number of map units specified in the command argument. The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.

Syntax
 
$<object_name> moveForward <distance>

Notes & examples
 
For a scriptobject or scriptmodel, the forward, backward, left and right directions are relative to the current "angle" or "angles" setting of the entity: the direction in which it's pointing IOW. For example, if the scriptmodel has its "angle" key set to 90, forward is 90 degrees, backward is 270, right is 0 and left is 180.


moveLeft
 
Function
 
Makes an object move left by the number of map units specified in the command argument. The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.

Syntax
 
$<object_name> moveLeft <distance>

Notes & examples
 
For a scriptobject or scriptmodel, the forward, backward, left and right directions are relative to the current "angle" or "angles" setting of the entity: the direction in which it's pointing IOW. For example, if the scriptmodel has its "angle" key set to 90, forward is 90 degrees, backward is 270, right is 0 and left is 180.


moveNorth
 
Function
 
Makes an object move north by the number of map units specified in the command argument. North is toward the Y positive map coordinates.

Syntax
 
$<object_name> moveNorth <distance>

Notes & examples
 
The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.


moveRight
 
Function
 
Makes an object move right by the number of map units specified in the command argument. The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.

Syntax
 
$<object_name> moveRight <distance>

Notes & examples
 
For a scriptobject or scriptmodel, the forward, backward, left and right directions are relative to the current "angle" or "angles" setting of the entity: the direction in which it's pointing IOW. For example, if the scriptmodel has its "angle" key set to 90, forward is 90 degrees, backward is 270, right is 0 and left is 180.


moveSouth
 
Function
 
Makes an object move south by the number of map units specified in the command argument. South is toward the Y negative map coordinates.

Syntax
 
$<object_name> moveSouth <distance>

Notes & examples
 
The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.


moveto
 
Function
 
This makes an object move from its present location to the location of an entity's origin or to an XYZ coordinate. The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.

Syntax
 
$<object_name> moveto $<entity_name>|"(<X Y Z>)"

Notes & examples
 
When using a coordinate as an argument, make sure you enclose the XYZ values in double-quotes and parentheses otherwise the command won't recognize the argument as valid. If you had previously stored the coordinates in a vector variable, you can use that variable's name as the command argument.

Note:
Do not confuse this command with the moveto Camera command. It is an entirely different command with a different function even though it has the same name and some similarities.



moveUp
 
Function
 
Makes an object move up by the number of map units specified in the command argument. Up is toward the Z positive map coordinates.

Syntax
 
$<object_name> moveUp <distance>

Notes & examples
 
The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.


moveWest
 
Function
 
Makes an object move west by the number of map units specified in the command argument. West is toward the X negative map coordinates.

Syntax
 
$<object_name> moveWest <distance>

Notes & examples
 
The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.


next  
 
Function
 
This makes a scriptobject or scriptmodel move to the next waypoint entity in a set of daisy-chained waypoints. The object must first be moved to a waypoint with the moveto or jumpto command before this command can be used.

Syntax
 
$<object_name> next

Notes & examples
 
The speed at which the object will move is determined by the last speed or time command. If neither speed or time were set beforehand, the object will move at the default speed.

This command can be used in a situation where you have many waypoints entities in a map and you want to make the object move in a straight line from one to the next. In order for this command to be used, the waypoints have to be daisy-chained to one another target-targetname wise.

You must first move the object to a waypoint (usually the first one in the chain):

$object moveto $waypoint1
waitFor $object


Then, if the waypoint named "waypoint1" targets the waypoint named "waypoint2", by using the command:

$object next
waitFor $object


This will make the object move to "waypoint2". Any additional "next" commands will move the object to the waypoint targeted by the one it is currently located at.


noblock
 
Function
 
This makes a scriptobject or scriptmodel ignore a blocking event until the next onblock command. This is typically used in a thread after the blocking event has occured and before the event processing commands.

Syntax
 
$<object_name> noblock

Notes & examples
 
A blocking event occurs when a moving scriptobject or scriptmodel's movement is blocked by the player or an actor. A blocking event can also be made to occur by using the doBlocked Entity command.

For an example on how to use this command, refer to the notes of the onblock command since both are closely related and typically used together in the same thread.


nodamage
 
Function
 
This makes a scriptobject or scriptmodel ignore a damage event until the next ondamage command. This is typically used in a thread after the damage event has occured and before the event processing commands.

Syntax
 
$<object_name> nodamage

Notes & examples
 
A damage event occurs when a scriptobject or scriptmodel is hurt by the player or an actor with a punch or weapon projectile. A damage event can also be made to occur by using the hurt Entity command.

For an example on how to use this command, refer to the notes of the ondamage command since both are closely related and typically used together in the same thread.


notouch
 
Function
 
This makes a scriptobject or scriptmodel ignore a touch event until the next ontouch command. This is typically used in a thread after the touch event has occured and before the event processing commands.

Syntax
 
$<object_name> notouch

Notes & examples
 
A touch event occurs when a scriptobject or scriptmodel is touched by the player. A touch event can also be made to occur by using the doTouch Entity command.

For an example on how to use this command, refer to the notes of the ontouch command since both are closely related and typically used together in the same thread.


notrigger
 
Function
 
This makes a scriptobject or scriptmodel ignore a trigger event until the next ontrigger command. This is typically used in a thread after the trigger event has occured and before the event processing commands.

Syntax
 
$<object_name> notrigger

Notes & examples
 
A trigger event occurs when a scriptobject or scriptmodel is triggered by an entity that targets it. A trigger event can also be made to occur by using the trigger Master command or the doActivate Entity command.

For an example on how to use this command, refer to the notes of the ontrigger command since both are closely related and typically used together in the same thread.


nouse
 
Function
 
This makes a scriptobject or scriptmodel ignore a use event until the next onuse command. This is typically used in a thread after the use event has occured and before the event processing commands.

Syntax
 
$<object_name> nouse

Notes & examples
 
A use event occurs when a scriptobject or scriptmodel is used by the player. A use event can also be made to occur by using the doUse Entity command.

For an example on how to use this command, refer to the notes of the onuse command since both are closely related and typically used together in the same thread.


onblock
 
Function
 
This makes a scriptobject or scriptmodel respond to a blocking event until the thread ends or until the next noblock command. The argument of the command is the name of the label to jump to when a blocking event is "sensed" by the object. Usually followed by a pause command.

Syntax
 
$<object_name> onblock <label_name>

Notes & examples
 
A blocking event occurs when a moving scriptobject or scriptmodel's movement is blocked by the player or an actor. A blocking event can also be made to occur by using the doBlocked Entity command.

Here's a typical example of the use of this command. Draw a simple 64 x 64 x 64 cube. Turn it into a func_scriptobject and give it a targetname of "object1". Then, place the cube's bottom face 128 units off the floor and write the following script:

thread object_move
thread monitor_blocking
end

object_move:
$object1 moveDown 128
waitFor $object1
$object1 moveUp 128
waitFor $object1
goto object_move
end

monitor_blocking:
$object1 onblock react_to_blocking
pause

react_to_blocking:
$object1 noblock
$object1 playsound impact/metal/drm2.wav 1 2
waitForSound impact/metal/drm2.wav
$object1 playsound impact/metal/drm3.wav 1 2
waitForSound impact/metal/drm3.wav
wait 2
goto monitor_blocking
end


Here, the object_move thread makes the cube move all the way down to the floor and back up to its original position continuously. In the monitor_blocking thread, the onblock command puts the object in "listen mode" for a blocking event and the pause command suspends execution of the thread until the event occurs. When the object's movement is blocked, the thread un-pauses and jumps to the react_to_blocking label.

Right after, the noblock command prevents the object from responding to additional blocking events while the following commands are executed. The 2 sounds will be played, the thread waits 2 seconds and jumps back to the monitor_blocking label at the top of the thread where it will be permitted to respond to blocking events again.

In practical terms, this means that if the player gets underneath the cube while it's moving downward and blocks its movement, the object will stop moving, play the 2 sounds, wait 2 seconds and check again if something's still blocking it. If the player is still blocking the object, the sounds will be played again and the object goes back to "listen mode" 2 seconds later. This will go on until the the player gets out of the way and stops blocking the object.

If the noblock command wasn't there, the commands after the react_to_blocking label would be started spuriously and continously without delay. The net result would be that the sounds may not even have time to finish playing and might overlap one another because the object would be incessantly reacting to successive blocking events (since the player keeps blocking the object).

The noblock command "de-sensitizes" the object to blocking events right after the react_to_blocking label to permit orderly execution of the thread without being "disturbed" by another blocking event that could occur during the execution of those commands.


ondamage
 
Function
 
This makes a scriptobject or scriptmodel respond to a damage event until the thread ends or until the next nodamage command. The argument of the command is the name of the label to jump to when a damage event is "sensed" by the object. Usually followed by a pause command.

Syntax
 
$<object_name> ondamage <label_name>

Notes & examples
 
A damage event occurs when a scriptobject or scriptmodel is hurt by the player or an actor with a punch or weapon projectile. A damage event can also be made to occur by using the hurt Entity command.

Please note that a scriptobject or scriptmodel is not destructible as such. This command does not make it destructible, it simply makes it react to being hurt.

Here's a typical example of the use of this command. Draw a simple 64 x 64 x 64 cube. Turn it into a func_scriptobject and give it a targetname of "object1". Then, write the following script:

thread monitor_damage
end

monitor_damage:
$object1 ondamage react_to_damage
pause

react_to_damage:
$object1 nodamage
$object1 playsound impact/metal/drm2.wav 1 2
waitForSound impact/metal/drm2.wav
$object1 playsound impact/metal/drm3.wav 1 2
waitForSound impact/metal/drm3.wav
wait 2
goto monitor_damage
end


In the monitor_damage thread, the ondamage command puts the object in "listen mode" for a damage event and the pause command suspends execution of the thread until the event occurs. When the object is hurt by a punch or projectile, the thread un-pauses and jumps to the react_to_damage label.

Right after, the nodamage command prevents the object from responding to additional damage events while the following commands are executed. The 2 sounds will be played, the thread waits 2 seconds and jumps back to the monitor_damage label at the top of the thread where it will be permitted to respond to damage events again.

In practical terms, this means that if the player shoots at the cube, it will play the 2 sounds, wait 2 seconds and check again if something's still hurting it. If the player is still shooting the object, the sounds will be played again and the object goes back to "listen mode" 2 seconds later. This will go on until the the player stops shooting at the object.

If the nodamage command wasn't there, the commands after the react_to_damage label would be started spuriously and continously without delay. The net result would be that the sounds may not even have time to finish playing and might overlap one another because the object would be incessantly reacting to successive damage events (since the player keeps shooting at the object). This would be especially bad if the player shoots at the object with a rapid-fire weapon like the Chaingun for example.

The nodamage command "de-sensitizes" the object to damage events right after the react_to_damage label to permit orderly execution of the thread without being "disturbed" by another damage event that could occur during the execution of those commands.

When a damage event occurs, a number of local variables implicit to the object are automatically created. These variables are local to the thread that handles the damage event. Here's the list:

local.damage:


local.inflictor:


local.attacker:


local.position:

local.direction:
the amount of damage inflicted to the object (integer so this is a number variable).

the name or sequence number of the entity that actually struck the object. This would typically be a projectile (string variable).

the name or sequence number of the spawner of the damage inflicting entity. IOW, the player or actor that fired that projectile (string variable).

the world space XYZ coordinate of the place that was hit (vector variable).

the normal of the plane of the polygon face that was hit (vector variable).


ontouch
 
Function
 
This makes a scriptobject or scriptmodel respond to a touch event until the thread ends or until the next notouch command. The argument of the command is the name of the label to jump to when a touch event is "sensed" by the object. Usually followed by a pause command.

Syntax
 
$<object_name> ontouch <label_name>

Notes & examples
 
A touch event occurs when a scriptobject or scriptmodel is touched by the player or a projectile (grenade, rocket, spider mine, spear, plasma ball, QD blast). A touch event can also be made to occur by using the doTouch Entity command.

Here's a typical example of the use of this command: a common touch activated elevator platform. Draw a simple 64 x 64 x 16 thick rectangular brush and place it flush with the floor. Turn it into a func_scriptobject and give it a targetname of "object1". Then, write the following script:

thread monitor_touch
end

monitor_touch:
$object1 ontouch react_to_touch
pause

react_to_touch:
$object1 notouch
$object1 time 2
wait 1
$object1 moveUp 128
waitfor $object1
wait 3
$object1 moveDown 128
waitfor $object1
goto monitor_touch
end


In the monitor_touch thread, the ontouch command puts the platform in "listen mode" for a touch event and the pause command suspends execution of the thread until the event occurs. When the platform is touched by the player, the thread un-pauses and jumps to the react_to_touch label.

Right after, the notouch command prevents the object from responding to additional touch events while the following commands are executed. The platform will wait 1 second before starting to rise (this gives the player enough time to step onto it) and will stay in the up position 3 seconds before going back down (which gives the player enough time to step off the platform). The command execution then jumps back to the monitor_touch label at the top of the thread where it will be permitted to respond to touch events again.

If the notouch command wasn't there, the commands after the react_to_touch label would be started spuriously and continously without delay. The net result would be that the platform would work erratically due to successive touch events (since the player stands on the platform and is continuously touching it).

The notouch command "de-sensitizes" the object to touch events right after the react_to_touch label to permit orderly execution of the thread without being "disturbed" by another touch event that could occur during the execution of those commands.


ontrigger
 
Function
 
This makes a scriptobject or scriptmodel respond to a trigger event until the thread ends or until the next notrigger command. The argument of the command is the name of the label to jump to when a trigger event is "sensed" by the object. Usually followed by a pause command.

Syntax
 
$<object_name> ontrigger <label_name>

Notes & examples
 
A trigger event occurs when a scriptobject or scriptmodel is triggered by an entity that targets it. A trigger event can also be made to occur by using the trigger Master command or the doActivate Entity command.

Here's a typical example of the use of this command: a trigger activated elevator platform. Draw a simple 64 x 64 x 16 thick rectangular brush and place it flush with the floor. Turn it into a func_scriptobject and give it a targetname of "object1". Draw another 64 x 64 x 64 brush, turn it into a trigger_multiple entity and set the "target" key to "object1". Then, write the following script:

thread monitor_trigger
end

monitor_trigger:
$object1 ontrigger react_to_trigger
pause

react_to_trigger:
$object1 notrigger
$object1 time 2
wait 1
$object1 moveUp 128
waitfor $object1
wait 3
$object1 moveDown 128
waitfor $object1
goto monitor_trigger
end


In the monitor_trigger thread, the ontrigger command puts the platform in "listen mode" for a trigger event and the pause command suspends execution of the thread until the event occurs. When the player stands in front of the platform and touches the trigger_multiple brush, the platform is triggered by the triger_multiple. Then the thread un-pauses and jumps to the react_to_trigger label.

Right after, the notrigger command prevents the object from responding to additional trigger events while the following commands are executed. The platform will wait 1 second before starting to rise (this gives the player enough time to step onto it) and will stay in the up position 3 seconds before going back down (which gives the player enough time to step off the platform). The command execution then jumps back to the monitor_trigger label at the top of the thread where it will be permitted to respond to trigger events again.

If the notrigger command wasn't there, the commands after the react_to_trigger label would be started spuriously and continously without delay. The net result would be that the platform would work erratically due to successive trigger events (since the player stands in front of the platform and is thus continuously touching the trigger_multiple entity).

The notrigger command "de-sensitizes" the object to trigger events right after the react_to_trigger label to permit orderly execution of the thread without being "disturbed" by another trigger event that could occur during the execution of those commands.


onuse
 
Function
 
This makes a scriptobject or scriptmodel respond to a use event until the thread ends or until the next nouse command. The argument of the command is the name of the label to jump to when a use event is "sensed" by the object. Usually followed by a pause command.

Syntax
 
$<object_name> onuse <label_name>

Notes & examples
 
A use event occurs when a scriptobject or scriptmodel is used by the player. A use event can also be made to occur by using the doUse Entity command.

When a use event occurs, a number of local variables implicit to the object are automatically created. These variables are local to the thread that handles the use event. Here's the list:

local.other:


local.key:

the name or sequence number of the entity that used the object. This would typically be a the player (string variable).

will be set if the object was assigned a "key" key/value pair (requires a certain item to be used). This would be the name of the required item: bluecard, coin, etc. (string variable).

If the object is "keyed" and you want it to take away the "key" item from the "user" (usually the player) after it was used, just use the following command:

local.other take local.key

A common example of this is a pay phone which requires a quarter to be used like the one in Ritual's Bank level. This would be done by drawing a brush, making it into a func_scriptobject and setting the "targetname" key to "phone" (for example) and the "key" key to "coin". Then, write the following script:

thread phone_init
end

phone_init:
$phone onuse phone_used
pause

phone_used:
$phone nouse
local.other take local.key 1
$phone playsound dialog/general/phone/phone1.wav 1 2 0
waitForSound dialog/general/phone/phone1.wav
goto phone_init
end


The player needs a coin to use the phone otherwise the scriptobject will ignore the use event and display the message "You need this item" and the icon of a coin on the screen. Let's say the player has 3 coins and uses the phone, the commands after the phone_used label will be executed: only one coin will be taken away from the player and the sound will be played.

Now this is where the nouse command's importance comes in. If the nouse command wasn't there, the commands after the phone_used label could be started before the commands after the label would have finished executing if the player used the object continously. The net result would be that the sound might restart continuously because the object would be reacting to successive use events (if the player keeps using the object rapidly). This would also take all 3 coins away from the player in one shot.

The nouse command prevents this and "de-sensitizes" the object to use events right after the phone_used label to permit orderly execution of the thread without being "disturbed" by another use event that could be initiated by the player during the execution of those commands.


rotatedownto
 
Function
 
Rotates an object counter-clockwise along the X, Y and Z rotation axes (as required) from its current orientation to the angles orientation specified in the command argument.

Syntax
 
$<object_name> rotatedownto "(<Xangle Yangle Zangle>)"

Notes & examples
 
The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

The argument's syntax is the standard vector notation in SinScript. A vector should always be enclosed between double quotes and parentheses. If the value of a vector was previously assigned to a vector variable, that variable can be used as the command argument instead.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateto
 
Function
 
Rotates an object along the X, Y and Z rotation axes (as required) from its current orientation to the angles orientation specified in the command argument. Depending on the object's current orientation and the orientation it is instructed to rotate to, the object will choose to rotate clockwise or counter-clockwise depending on which is the shortest way to get there.

Syntax
 
$<object_name> rotateto "(<Xangle Yangle Zangle>)"

Notes & examples
 
The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

The argument's syntax is the standard vector notation in SinScript. A vector should always be enclosed between double quotes and parentheses. If the value of a vector was previously assigned to a vector variable, that variable can be used as the command argument instead.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateupto
 
Function
 
Rotates an object clockwise along the X, Y and Z rotation axes (as required) from its current orientation to the angles orientation specified in the command argument.

Syntax
 
$<object_name> rotateupto "(<Xangle Yangle Zangle>)"

Notes & examples
 
The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

The argument's syntax is the standard vector notation in SinScript. A vector should always be enclosed between double quotes and parentheses. If the value of a vector was previously assigned to a vector variable, that variable can be used as the command argument instead.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateX
 
Function
 
Rotates an object along the X axis (pitch) at a constant angular speed in degrees per second.

Syntax
 
$<object_name> rotateX <degrees_per_second>

Notes & examples
 
Using a positive value in the <number_of_degrees> argument will make the object rotate clockwise when looking towards the positive direction of the X rotation axis. A negative value will make the object rotate counter-clockwise when looking towards the positive direction of the X rotation axis.

The argument is in degrees per second. So using the command:

$object rotateX 360

will make the object rotate clockwise along the X rotation axis by a 1 full turn every second.

To stop the object from rotating, use the following command:

$object rotateX 0

Note:
In Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused.


The following image shows the assignment of the rotation axes in Sin. Each is identified by a colored X, Y and Z letter. The large red arrows point toward the positive direction of each axis. The smaller blue lines which extend from each axis represent the coordinate axes and each is identified by a black text caption. The reason I superimposed the 2 sets of axes this way is to give you a visual reference as to the actual orientation of the rotation axes in space.


Rotation axes in SiN
Rotation axes in SiN

If you have trouble determining what rotation axis to use when you need to make an object rotate in a certain way, just use this simple analogy:

Just imagine that the rotation axis is a skewer and the object you want to rotate is a chicken you want to cook on the BBQ. If you impale the chicken with the skewer and roll the skewer between your fingers, the chicken will rotate along the length of the skewer. A rotation axis is exactly the same thing. Just determine how you want the object to rotate in relation to the map. Then it's just a matter of choosing the proper "skewer" :)


rotateXdown
 
Function
 
Rotates an object counter-clockwise along the X rotation axis from its current orientation by the number of degrees specified in the command argument.

Syntax
 
$<object_name> rotateXdown <number_of_degrees>

Notes & examples
 
Unlike the rotateXdownto command which rotates the object to an absolute orientation regardless of it's prior orientation, this will rotate the object incrementally from its current orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateXdownto
 
Function
 
Rotates an object counter-clockwise along the X rotation axis from its current orientation to the absolute angular orientation specified in the command argument.

Syntax
 
$<object_name> rotateXdownto <angle_orientation>

Notes & examples
 
Unlike the rotateXdown command which rotates the object incrementally from its current orientation, this will rotate the object to an absolute orientation regardless of it's prior orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateXup
 
Function
 
Rotates an object clockwise along the X rotation axis from its current orientation by the number of degrees specified in the command argument.

Syntax
 
$<object_name> rotateXup <number_of_degrees>

Notes & examples
 
Unlike the rotateXupto command which rotates the object to an absolute orientation regardless of it's prior orientation, this will rotate the object incrementally from its current orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateXupto
 
Function
 
Rotates an object clockwise along the X rotation axis from its current orientation to the absolute angular orientation specified in the command argument.

Syntax
 
$<object_name> rotateXupto <angle_orientation>

Notes & examples
 
Unlike the rotateXup command which rotates the object incrementally from its current orientation, this will rotate the object to an absolute orientation regardless of it's prior orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateY
 
Function
 
Rotates an object along the Y axis (yaw) at a constant angular speed in degrees per second.

Syntax
 
$<object_name> rotateY <degrees_per_second>

Notes & examples
 
Using a positive value in the <number_of_degrees> argument will make the object rotate clockwise when looking towards the positive direction of the Y axis. A negative value will make the object rotate counter-clockwise when looking towards the positive direction of the Y axis.

The argument is in degrees per second. So using the command:

$object rotateY 360

will make the object rotate clockwise along the Y rotation axis by a 1 full turn every second.

To stop the object from rotating, use the following command:

$object rotateY 0

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateYdown
 
Function
 
Rotates an object counter-clockwise along the Y rotation axis from its current orientation by the number of degrees specified in the command argument.

Syntax
 
$<object_name> rotateYdown <number_of_degrees>

Notes & examples
 
Unlike the rotateYdownto command which rotates the object to an absolute orientation regardless of it's prior orientation, this will rotate the object incrementally from its current orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateYdownto
 
Function
 
Rotates an object counter-clockwise along the Y rotation axis from its current orientation to the absolute angular orientation specified in the command argument.

Syntax
 
$<object_name> rotateYdownto <angle_orientation>

Notes & examples
 
Unlike the rotateYdown command which rotates the object incrementally from its current orientation, this will rotate the object to an absolute orientation regardless of it's prior orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateYup
 
Function
 
Rotates an object clockwise along the Y rotation axis from its current orientation by the number of degrees specified in the command argument.

Syntax
 
$<object_name> rotateYup <number_of_degrees>

Notes & examples
 
Unlike the rotateYupto command which rotates the object to an absolute orientation regardless of it's prior orientation, this will rotate the object incrementally from its current orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateYupto
 
Function
 
Rotates an object clockwise along the Y rotation axis from its current orientation to the absolute angular orientation specified in the command argument.

Syntax
 
$<object_name> rotateYupto <angle_orientation>

Notes & examples
 
Unlike the rotateYup command which rotates the object incrementally from its current orientation, this will rotate the object to an absolute orientation regardless of it's prior orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateZ
 
Function
 
Rotates an object along the Z axis (roll) at a constant angular speed in degrees per second.

Syntax
 
$<object_name> rotateZ <degrees_per_second>

Notes & examples
 
Using a positive value in the <number_of_degrees> argument will make the object rotate clockwise when looking towards the positive direction of the Z axis. A negative value will make the object rotate counter-clockwise when looking towards the positive direction of the Z axis.

The argument is in degrees per second. So using the command:

$object rotateZ 360

will make the object rotate clockwise along the Z rotation axis by a 1 full turn every second.

To stop the object from rotating, use the following command:

$object rotateZ 0

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateZdown
 
Function
 
Rotates an object counter-clockwise along the Z rotation axis from its current orientation by the number of degrees specified in the command argument.

Syntax
 
$<object_name> rotateZdown <number_of_degrees>

Notes & examples
 
Unlike the rotateZdownto command which rotates the object to an absolute orientation regardless of it's prior orientation, this will rotate the object incrementally from its current orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateZdownto
 
Function
 
Rotates an object counter-clockwise along the Z rotation axis from its current orientation to the absolute angular orientation specified in the command argument.

Syntax
 
$<object_name> rotateZdownto <angle_orientation>

Notes & examples
 
Unlike the rotateZdown command which rotates the object incrementally from its current orientation, this will rotate the object to an absolute orientation regardless of it's prior orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateZup
 
Function
 
Rotates an object clockwise along the Z rotation axis from its current orientation by the number of degrees specified in the command argument.

Syntax
 
$<object_name> rotateZup <number_of_degrees>

Notes & examples
 
Unlike the rotateZupto command which rotates the object to an absolute orientation regardless of it's prior orientation, this will rotate the object incrementally from its current orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



rotateZupto
 
Function
 
Rotates an object clockwise along the Z rotation axis from its current orientation to the absolute angular orientation specified in the command argument.

Syntax
 
$<object_name> rotateZupto <angle_orientation>

Notes & examples
 
Unlike the rotateZup command which rotates the object incrementally from its current orientation, this will rotate the object to an absolute orientation regardless of it's prior orientation.

The speed at which the object will rotate is determined by the last speed or time command. If neither speed or time were set beforehand, the object will rotate at the default speed.

Note:
It's important to remember that in Sin, the XYZ rotation axes mean pitch, yaw and roll. They are completely different from the map's XYZ coordinate axes for positioning and movement commands and those should not be confused. For detailed info on this, refer to the notes in the rotateX command.



setdamage
 
Function
 
This sets the amount of damage inflicted by a moving and/or rotating scriptobject/scriptmodel to a player or actor each time he blocks the object's movement or rotation. The default value is 1.

Syntax
 
$<object_name> setdamage <value>

Notes & examples
 
There is another command by the same name which is used to set the amount of damage inflicted by a trigger_hurt entity. It is the setdamage command which specifically applies to trigger_hurt entities only.


speed
 
Function
 
This sets the current moving or rotating speed of an object. Normally used before a movement or rotation command when a change of speed from the previous setting is required. The value is a multiplier factor that is applied to a normal speed value and not an absolute value as such.

Syntax
 
$<object_name> speed <factor>

Notes & examples
 
The speed value is a multipler factor: 1 is normal speed, 0.5 is half the normal speed, 2 is twice the normal speed, etc.

An object will always move or rotate at the speed set by the last speed command. IOW, an object will always "remember" its last speed setting. To reset the object speed to the default value, use the command:

$object speed 1

The speed at which an object moves or rotates can also be set by using the time command.

Note:
The speed parameter has no effect on an object instructed to follow or loop a path with the followpath command.



time
 
Function
 
This sets the amount of time in seconds that an object will take to complete a movement or rotation. Normally used before a translation or rotation command when a change of speed from the previous setting is required.

Syntax
 
$<object_name> time <value>

Notes & examples
 
The time command obviously affects the speed of movement or rotation of an object and is meant as an alternative to using the speed command when it is more convenient in that particular case. It will therefore override the default or previously set speed when the object executes its next translation or rotation movement.

An object will always move or rotate at a speed set by the last time command. IOW, an object will always "remember" its last time setting.

Note:
The time parameter has no effect on an object instructed to follow or loop a path with the followpath command.