Basic Usages

From Computing and Software Wiki

---

Revision as of 18:55, 19 March 2008

The script editor is a bundle of functionalities provided by the game engine as well as custom created ones for the psychologists disposal. In effect, a script acts as a series of methods in a tree of nodes. Each node is a method that has a functionality. The C4Engine Wiki contains a very useful entry that explains the basic commands of the Script Editor. As such, it has been copied and pasted here for quicker reference.

The C4 Engine has the capability to execute scripted actions in response to some kind of trigger. A script in C4 does not require the use of any programming language, but is instead organized into a tree of actions called methods that can be edited with a tool that displays a graphical representation of the script.

The image to the right shows the Script Editor. A script can be assigned to any node in a scene and edited by attaching the script controller to it as follows.

1. In the World Editor, select the node to which you would like to assign a script.
2. Choose Get Info from the Node menu or just press Ctrl-I.
3. Click on the Controller tab in the Get Info dialog.
4. Select the Script controller from the list of available controllers.
5. Click on the Edit Script button that appears to open the Script Editor.

Contents 1 Creating a New Script 2 Editing a Script 3 Script Editor Tools 4 Script Execution 5 Standard Script Methods 6 Reference

Creating a New Script

The first time the Script Editor is opened for a particular node, it shows a single method in the script called “Root”. This method performs no action and only serves as the root of the script's method tree. A new method is added to a script by dragging it from the palette on the left side of the editor to the method that precedes it. Any number of methods can be dragged to the same parent method in the script tree. The first method added to a script will always be dragged to the root method.

When a method is selected (which happens automatically to new methods as they are inserted into the tree), its settings are displayed on the right side of the editor. Each type of method has different settings that control how it is executed. Many methods perform some kind of operation on a target node, and a popup menu labelled “Target node” appears when such a method is selected. The target node of the method may be any one of the following

• The target node of the script controller itself. This is the same node that the script is attached to.
• The trigger node that was activated and caused the script to execute.
• The node that activated the trigger node (the activator node).
• Any node that is connected to the target node of the controller.

(The trigger node or activator node may not exist. Any method that is executed for a nonexistant node behaves as a no-operation and completes immediately.)

Editing a Script

Once a method has been placed in the script tree, its settings can be changed by clicking on it. A method can be repositioned in the tree by selecting the Move tool at the bottom of the editor and using it to drag an existing method to a new parent method. When a method is moved, all of its descendants move with it. A method cannot be dragged to one of its descendants.

A method can be removed from the tree by selecting it and clicking the Delete Method button at the bottom of the editor. Pressing the Delete or Backspace key will also delete a selected method. When a method is deleted, its descendants are moved up to the parent of the deleted method. All of a method's descendants can be deleted by selecting the method and clicking the Delete Subtree button.

Script Editor Tools

There are four tool buttons at the bottom of the Script Editor window, and they have the following uses. In addition to clicking on the tool button, each of these tools can also be selected by pressing the shortcut number key as shown in the table. (The shortcuts were chosen to be the same as the corresponding tools in the World Editor.)

Icon	Shortcut	Function
	1	Select. Selects a method in a script.
	2	Move. Selects and moves methods around in a script.
	6	Pan. Pans the script tree viewport. Holding the Alt key (Option on the Mac) temporarily selects the pan tool.
	7	Zoom. Changes the scale of the script tree viewport. Using the mouse wheel with any other tool also zooms.

Script Execution

When a script is executed, all of the immediate descendants of the root method are first executed, and these all run simultaneously. When a particular method completes its execution, which could be immediately or could be after some amount of time dependending on the operation being performed, all of its immediate descendants are then executed at the same time. This process continues until all of the methods in the script have executed, at which time the script goes back into a non-executing state.

Standard Script Methods

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.

The following table describes the operation of the standard methods.

Method	Description
Call Function	This method calls a function of the controller attached to the method's target node. The specific settings depend on the purpose of the function itself. This method completes when the function indicates that is has finished what it's doing.
Change Settings	This method changes one or more settings for the object attached to the target node and completes immediately.
Activate Controller	This method 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, the script is executed. This method always completes immediately without waiting for the activated controller to signal completion.
Enable Node	This method enables its target node and completes immediately.
Disable Node	This method disables its target node and completes immediately.
Delete Node	This method deletes its target node and completes immediately. The node to which the script is attached, or any of its ancestors, cannot be deleted with this method.
Show Geometry	This method shows its target node (if it's a geometry node) and completes immediately.
Hide Geometry	This method hides its target node (if it's a geometry node) and completes immediately.
Delay	This method simply waits for a specified amount of time before completing.
Play Ambient Sound	This method plays a sound resource without 3D spatialization. The method completes when the sound has finished playing.
Play Sound Source	This method plays its target node (if it's 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	This method stops its target node (if it's a source node) and completes immediately.
Change Material Color	This method changes the color of one of the material attributes assigned to its target node (if it's a geometry node) and completes immediately. 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.
Sleep	This method puts a controller to sleep.
Wake	This method awakens a controller.

Reference

C4Engine Wiki Using the Script Editor