Methods

From C4 Engine Wiki
Revision as of 12:02, 15 July 2023 by Eric Lengyel (talk | contribs) (Created page with "__NOTOC__ There are several types of script methods that are defined in the engine module. An application module can define any number of its own custom script methods as well, and they will show up in the palette on the left side of the script editor window. === Basic Methods === The following table describes the operation of the methods built into the engine that appear under the '''Basic''' in the Script Editor. {| {{Table}} {{Table...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

There are several types of script methods that are defined in the engine module. An application module can define any number of its own custom script methods as well, and they will show up in the palette on the left side of the script editor window.

Basic Methods

The following table describes the operation of the methods built into the engine that appear under the Basic in the Script Editor.

Method

Description

Duration

Null

Performs no operation. This method is useful for joining multiple fibers of execution at the end of a loop or as a starting node for the script when a loop begins at the first method that performs some action.

Completes immediately.

Evaluate Expression

Evaluates a text expression and outputs the result. For a description of expression syntax, see Expression Evaluation in Scripts. (If the expression contains a syntax error, then the method is colored bright yellow in the Script Editor.)

Completes immediately.

Call Controller Function

Calls a function of the controller attached to the method's target node. The specific settings depend on the purpose of the function itself.

Completes when the function indicates that is has finished what it's doing.

Change Settings

Changes one or more settings for the object referenced by the target node.

Completes immediately.

Activate Controller

Activates the controller attached to the method's target node. The effect depends on the controller being activated. In the case that the target node has a script controller attached to it, any scripts that handle the controller activate event are executed.

Completes immediately.

Deactivate Controller

Deactivates the controller attached to the method's target node. The effect depends on the controller being deactivated. In the case that the target node has a script controller attached to it, any scripts that handle the controller deactivate event are executed.

Completes immediately.

Set Color Value

Sets the red, green, blue, and alpha components of a color variable to specific values.

Completes immediately.

Set Vector Value

Sets the x, y, and z components of a vector or point variable to specific values.

Completes immediately.

Get External Variable

Retrieves the value of a specific variable belonging to the script controller attached to the target node of the method. This method is useful for reading values from other scripts in the world and storing them in variables local to the running script. If the variable being retrieved has object or controller scope, then its current value is returned, but if it has script scope, then its initial value is always returned.

Completes immediately.

Set External Variable

Sets the value of a specific variable belonging to the script controller attached to the target node of the method. This method is useful for copying values from variables local to the running script to object-scope or controller-scope variables of other scripts in the world. Only variables having object scope or controller scope can be modified using this method.

Completes immediately.

Get Script Time

Outputs the amount of time that has elapsed, as a floating-point value measured in seconds, since the script began running. The script time is updated once per frame. The time is guaranteed to be exactly 0.0 during the first frame in which the script is running.

Completes immediately.

Terminate External Script

Terminates all scripts running on the target node of the method. This method has no effect if the target node does not have a script controller attached to it. This method cannot be used to terminate the script containing the method itself, only scripts belonging to other nodes.

Completes immediately.

Standard Methods

The following table describes the operation of the methods built into the engine that appear under the Standard in the Script Editor.

Method

Description

Duration

Delay

Waits for a specified amount of time.

Completes after the specified time has elapsed.

Random Integer

Generates a random integer in a specified range and outputs the value. The boolean result is set to true if the value is not zero and false otherwise.

Completes immediately.

Random Float

Generates a random floating-point number in a specified range and outputs the value. The boolean result is set to true if the value is not zero and false otherwise. Note that in this case, a false result is extremely unlikely because the return value would have to be exactly 0.0.

Completes immediately.

Get String Length

Outputs the length of an input string.

Completes immediately.

Wake Controller

Awakens a controller.

Completes immediately.

Sleep Controller

Puts a controller to sleep.

Completes immediately.

Schedule Sleep

Tells a controller to go to sleep at the soonest convenient time. For most controllers, this method is equivalent to the Sleep Controller method. Some controllers may delay the sleep operation until a task has been completed, such as allowing an animation to finish playing.

Completes immediately.

Get Controller Wake State

Returns a boolean value indicating whether a controller is currently awake.

Completes immediately.

Enable Node

Enables its target node.

Completes immediately.

Disable Node

Disables its target node.

Completes immediately.

Get Node Enable State

Returns a boolean value indicating whether the target node is currently enabled.

Completes immediately.

Delete Node

Deletes its target node. It is possible to delete the node to which the script is attached (or any of its ancestors) with this method, but such a deletion is deferred until the end of the current frame.

Completes immediately.

Enable Interactivity

Enables interactivity for its target node.

Completes immediately.

Disable Interactivity

Disables interactivity for its target node.

Completes immediately.

Get Node Interactivity State

Returns a boolean value indicating whether the target node is currently interactive. If the target node does not possess the Interactivity property, then the return value is false.

Completes immediately.

Show Geometry

Shows the target node. Has no effect if the target is not a geometry node.

Completes immediately.

Hide Geometry

Hides the target node. Has no effect if the target is not a geometry node.

Completes immediately.

Get Geometry Visibility State

Returns a boolean value indicating whether the target node is visible. If the target node is not a geometry node, then the return value is false.

Completes immediately.

Activate Trigger

Activates a trigger. Has no effect if the target is not a trigger node. When a trigger node is activated, it searches for a controller to activate in the following order and performs exactly one of the following actions.

  1. If the trigger node itself has a controller, then that controller is activated.
  2. If the trigger object specifies an activation connector key, there is a node connected to the trigger through a connector having that key, and that node has a controller, then that controller is activated.
  3. If such a target node exists, but it does not have a controller, then its immediate subnodes are examined. Every controller belonging to that set of subnodes is activated.

Completes immediately.

Deactivate Trigger

Deactivates a trigger. Has no effect if the target is not a trigger node. When a trigger node is deactivated, it searches for a controller to deactivate in the following order and performs exactly one of the following actions.

  1. If the trigger node itself has a controller, then that controller is deactivated.
  2. If the trigger object specifies a deactivation connector key, there is a node connected to the trigger through a connector having that key, and that node has a controller, then that controller is deactivated.
  3. If such a target node exists, but it does not have a controller, then its immediate subnodes are examined. Every controller belonging to that set of subnodes is deactivated.

Completes immediately.

Break Joint

Breaks a joint. Has no effect if the target is not a joint node. If the joint node has a controller, then it is not activated as it would be if the joint were broken due to sufficient force being applied to it.

Completes immediately.

Remove Modifiers

Removes modifiers of a specific type, or all modifiers, from an instance node. Has no effect if the target is not an instance node. This method has no immediate effect, but the removed modifiers affect how the instanced world is loaded when a saved game is restored.

Completes immediately.

Get Object-Space Position

Returns a 3D point containing the object-space position of the target node.

Completes immediately.

Get World-Space Position

Returns a 3D point containing the world-space position of the target node.

Completes immediately.

Play Ambient Sound

Plays a sound resource without 3D spatialization.

Completes when the sound has finished playing.

Play Sound Source

Plays the target node. Has no effect if the target is not a source node.

If the source was already playing or the source is looping, then the method completes immediately. Otherwise, the method completes when the source finishes playing.

Stop Sound Source

Stops its target node. Has no effect if the target is not a source node.

Completes immediately.

Vary Source Volume

Varies the volume of its target node over a given amount of time. Has no effect if the target is not a source node.

Completes immediately.

Vary Source Frequency

Varies the frequency of its target node over a given amount of time. Has no effect if the target is not a source node.

Completes immediately.

Set Material Color

Changes the color of one of the material attributes assigned to its target node. Has no effect if the target is not a geometry node. Since materials are shared, all geometry nodes using the same material, not necessarily just the target, are affected. Thus, to change a material color for only one geometry node, it should use a unique material. This method can change any material attribute that includes a color, such as diffuse, specular, or emission. The mutable flag corresponding to the color must be checked under the Flags tab in the Material Editor.

Completes immediately.

Set Shader Scalar Parameter

Changes the value of a Constant Scalar process in the shader assigned to its target node. Has no effect if the target is not a geometry node or if no material assigned to the geometry uses a custom shader. Since materials are shared, all geometry nodes using the same material, not necessarily just the target, are affected. Thus, to change a scalar parameter for only one geometry node, it should use a unique material.

Completes immediately.

Set Shader Vector Parameter

Changes the value of a Constant Vector process in the shader assigned to its target node. Has no effect if the target is not a geometry node or if no material assigned to the geometry uses a custom shader. Since materials are shared, all geometry nodes using the same material, not necessarily just the target, are affected. Thus, to change a vector parameter for only one geometry node, it should use a unique material.

Completes immediately.

Set Shader Color Parameter

Changes the value of a Constant Color process in the shader assigned to its target node. Has no effect if the target is not a geometry node or if no material assigned to the geometry uses a custom shader. Since materials are shared, all geometry nodes using the same material, not necessarily just the target, are affected. Thus, to change a color parameter for only one geometry node, it should use a unique material.

Completes immediately.

Event Methods

The following table describes the special methods that appear under the Events in the Script Editor. These methods each return a boolean value indicating whether the specific type of event was the one that initiated script execution.

Method

Description

Duration

Controller Activate Event

Returns a boolean value indicating whether the script was run to handle a controller activate event. This event can only occur for scripts attached to nodes.

Completes immediately.

Controller Deactivate Event

Returns a boolean value indicating whether the script was run to handle a controller deactivate event. This event can only occur for scripts attached to nodes.

Completes immediately.

Widget Activate Event

Returns a boolean value indicating whether the script was run to handle a widget activate event. This event can only occur for scripts attached to widgets.

Completes immediately.

Widget Change Event

Returns a boolean value indicating whether the script was run to handle a widget change event. This event can only occur for scripts attached to widgets.

Completes immediately.

Widget Begin Hover Event

Returns a boolean value indicating whether the script was run to handle a widget begin hover event. This event can only occur for scripts attached to widgets.

Completes immediately.

Widget End Hover Event

Returns a boolean value indicating whether the script was run to handle a widget end hover event. This event can only occur for scripts attached to widgets.

Completes immediately.

Script First Execution Event

Returns a boolean value indicating whether this is the first time a script has been executed for a particular script controller.

Completes immediately.

See Also