You should keep this reference available when writing skelescript code. It can be very useful to have a printout of this document as well as a printout of layout commands when working with skelescript. If you have suggestions on how to improve this documentation (including reports of typos and other mistakes), please post these suggestions at the skelescript message board.Commands:
Often, the best way to learn new parts of skelescript is to find something in this reference that is of interest and experiment with its usage in Skelescript Preview.
AddPosition number x, number y, number zFunctions:
Moves the currently selected item relatively by the specified amount in meters. Use the feet_to_meters function to convert a specified amount in feet to the appropriate amount in meters. This command is affected by flip_left_x and flip_right_x and will flip the relative positions when appropriate.AddRotation number add_heading, number add_pitch, number add_bank
; Moves item to the left 3 feet and up 4 meters. AddPosition feet_to_meters(-3), 4, 0
Affects the currently selected item's rotation relatively by the specified heading, pitch, and bank amount. This command is affected by flip_left_* and flip_right_* global states like flip_left_heading and flip_right_pitch and will flip the relative angles (changing them from positive to negative) when appropriate.AddScale number add_x, number add_y, number add_z
For a fun little animation of an item spinning 360 degrees, try running this code in Skelescript Preview for a given item:
select me int x, 0 while (post_inc(x) < 180) {AddRotation 2, 0, 0}
Affects the currently selected item's scale relatively by the specified x, y, and z amount.Position number x, number y, number z
Moves the currently selected item to the specified position in meters.MoveToItem item_id target_item, number add_x = 0, number add_y = 0, number add_z = 0
Position 0, 0, 0 ; Moves item to position (0, 0, 0).
Moves the currently selected item a the position relative to the specified item's position.move_to_ground item_id item = selected
; Moves the selected item two meters left of the current skelescript bone. MoveToItem me, -2, 0, 0
Moves the specified item so that it's y position is 0. This is handy for creating controls that need to be aligned with the ground, such as foot controls for the heel and toe.lock_all_channels item_id item = selected
Locks all the channels available for the active transformation tool. For instance, if the move tool is active, the x/y/z channels will be locked. If the rotate tool is active, the heading/pitch/bank channels will be locked.lock_movement item_id item = selected
Locks all the movement channels (x/y/z) for the specified item.lock_rotation item_id item = selected
Locks all the rotational channels (heading/pitch/bank) for the specified item.lock_scaling item_id item = selected
Locks all the scale channels (scale x/y/z) for the specified item.create_target string null_name = concat(name, "_target"), number add_x = 0, number add_y = 0, number add_z = 0
Creates a null object with the specified name at the specified relative position (in meters, relative to the currently selected object's position) to be used as the target item for the currently selected object.create_oriented_target string null_name = concat(name, "_target"), number add_x = 0, number add_y = 0, number add_z = 0
If no name is specified, it will default to the currently selected item's name with the suffix, "_target", added to it.
; selects the current skelescript bone. Let's assume it's a ; bone called "b_head". select me ; creates a null to be used as a target. We won't specify a name or relative ; position for the null, instead allowing the default values to be used. create_target msg name(target) ; displays "b_head_target"Here is another example:
; selects the parent of the currently selected bone. select parent ; creates a null to be used as a target that is 1 unit to the left of the ; selected item (x offset of -1). This time, we'll specify the name to be ; "foo". create_target "foo", -1, 0, 0
This is almost the same as the create_target command above. However, it adds the property of creating target nulls that match the orientation of the selected item.create_goal bool full_time = true, string null_name = concat(name, "_goal"), number add_x = 0, number add_y = 0, number add_z = 0
Creates a null object with the specified name at the specified relative position (in meters, relative to the currently selected object's position) to be used as the goal item for the currently selected object. If full_time is specified to true, the full-time IK option will be turned on.create_oriented_goal bool full_time = true, string null_name = concat(name, "_goal"), number add_x = 0, number add_y = 0, number add_z = 0
By default, full_time will be set to true. If no name is specified, it defaults to the currently selected item's name with the suffix, "_goal", added to it.
; selects the current skelescript bone. Let's assume it's a ; bone on the left side for a character's wrist. select me ; creates a null to be used as a full-time goal with the name, ; "left_arm_goal", that is positioned at the upper tip of the ; current wrist bone. create_goal true, (side & "_arm_goal")If the wrist bone was on the right side, the above line of code would have created a null with the name, "right_arm_goal", because of the use of the side function. This keeps the code portable among different bones by requiring minimal (if any) changes.
This is almost the same as the create_goal command above. However, it adds the property of creating goal nulls that match the orientation of the selected item.AutoConfirm bool value
This command overrides the native lightwave command that specifies whether auto-confirm should be on or off.FramesPerSecond int fps
AutoConfirm true ; turns on auto-confirm. AutoConfirm false ; turns off auto-confirm.
This command overrides the native lightwave command used to specified the global FPS setting. This is done for internal tracking reasons, but also adds type safety to the command (makes sure that the value specified is a valid integer).select item_id id
Note that the set procedure for the 'fps' property accomplishes the same thing, and is generally more intuitive to use. This command is provided only because it is a native part of the layout command set.
; set the current fps to 30 FramesPerSecond 30 ; this does the same thing using the skelescript way: set fps, 30
Selects the specified item. This is basically the same as the native SelectByItem command but is conveniently shorter to type and also checks the specified item ID to make sure that it is valid.deselect_all
select parent ; Selects the parent of the currently selected item. select me ; Selects the current skelescript bone.
Deselects all but one item. Layout does not allow less than one item to be selected except immediately after clearing an item or when no items of the current type are available.store_selection
Stores the currently selected items to a stack to be recalled later. Call restore_selection to pop off of the stack and restore the selection.restore_selection
Restores the the most recent stored selection by popping it off of the selection stack.delete item_id item = selected
Deletes the specified item (or the first selected item if no item is specified) without prompting the user.relative_limits int angle_type, number min, number max
; Delete the current skelescript bone. delete me
relative_hlimits number min, number max
relative_plimits number min, number max
relative_blimits number min, number max
Allows you to set rotational limits for the currently selected item with angles relative to the current orientation instead of with absolute angles. This command is also affected by flip_left_* and flip_right_* flags and will swap the min and max angles if necessary. This allows for a more flexible and generally more intuitive solution than using the native HLimits, PLimits, and BLimits commands.msg any message
For the relative_limits command, you can specify whether to use heading, pitch, or bank by specifying angle_heading, angle_pitch, or angle_bank. The relative_plimits, relative_hlimits, and relative_blimits are shorthands.
; sets the current item's heading limits to allow it to rotate -20 degrees ; backwards and 30 degrees forwards. relative_limits angle_heading, -20, 30 ; sets the current item's pitch limits to allow it to rotate -60 degrees ; backwards and 10 degrees forwards. relative_plimits -60, 10
Displays the specified message to the screen in a message box.splash string title, string image_file, string button_label = "Continue"
; displays 'hello world!' to the screen. msg "hello world!" ; displays the coordinates of the currently selected item to the screen. msg ("Position: (" & world_x & ", " & world_y & ", " & world_z & ")" )
Displays a splash window with an image. Currently, the only types of images supported are 8-bit, 24-bit, and 32-bit Truevision TGA image files. The image should be contained in the same directory as the skelescript object. If not, the specified path must be relative to that directory.add_item_shape item_id item = selected,
int shape = shape_ball, number scale = 0.2, bool filled = false, number opacity = 1.0, int axis = axis_y,
collection selected_color = empty_collection, collection unselected_color = empty_collection, collection text_color = empty_collection,
string label = empty_string, int justify = justify_center, item_id draw_to_item = null_item
Adds an Item Shape custom object plugin to the specified object. The values you can pass to shape are: shape_standard, shape_box, shape_ball, shape_pyramid, shape_diamond, shape_tetra, shape_ring, shape_grid, and shape_none. selected_color, unselected_color, and text_color will be disabled if an empty collection is passed to them. Otherwise, you can pass an rgb collection constructed using the 'rgb' function to set these colors.add_simple_follower item_id item = selected, bool after_ik = false,
; set the appearance of the selected item so that it's a 65mm ball ; (no modifications to color). add_item_shape selected, shape_ball, .065 ; set the appearance of the selected item so that it's a slightly ; translucent (75% opaque) blue box that appears brighter when ; selected. add_item_shape selected, shape_box, .065, true, .75, axis_y, rgb(0, 128, 255), rgb(0, 96, 192) ; set the appearance of the selected item so that it's a pyramid ; (no custom selected or unselected color) with a yellow label that ; reads, "blargh!". add_item_shape selected, shape_pyramid, .065, true, .75, axis_y, empty_collection, empty_collection, rgb(255, 255, 0), "blargh!"
bool heading_active = true, bool pitch_active = true, bool bank_active = true,
item_id item1 = null_item, number heading1 = 0.0, number pitch1 = 0.0, number bank1 = 0.0,
item_id item2 = null_item, number heading2 = 0.0, number pitch2 = 0.0, number bank2 = 0.0
Adds the Simple Follower motion modifier to the specified object. Simple Follower is a custom plugin by Christopher Lutz. It is available with SimpleRigger at http://www.animationsnippets.com/plugins/simplerigger/index.html. I just added this command to show that any sort of item plugin can be added through skelescript.add_gravity item_id item = selected, int start_frame = 1, int end_frame = 60,
number ground_level = 0.0, number strength = 1.0, number elasticity = 0.25, int axis = axis_y
Adds the gravity motion modifier to the specified object.assert bool expr, string fail_message = "Assertion failed."
The assert command is strictly a debugging tool which makes sure that a given condition is true before continuing. If the condition is false, the interpreter deliberately comes to a halt and displays an error message telling the programmer that the assertion failed and where the failure occurred.assert_selection string error_message = "One or more items must be selected.""
Let's say you have a script which is designed specifically for a character's left arm. To be on the left side, the X position of the skelegon should be less than 0. To make sure that the script is properly used for a bone on the left side, you can use a quick assertion like this:
; select the current skelescript bone. select me ; make sure that the bone is on the left side. If it is not, the ; script will come to a halt and the fail message will be displayed. assert (world_x < 0, "The item needs to be on the left side.")
Like the assert command, this one makes sure that the selection is not empty.assert_valid_angle_type int angle_type
Like the assert command, this one makes sure that the specified angle_type value is valid. Unless you are defining new procedures that deal with angle_types, you should never have need for this command. Beginners definitely should not worry about this one.error any message
Stops processing the script and all following scripts and displays the specified error message.end
Stops processing the script and all following scripts, prematurely ending the code. No error message is displayed, unlike the error command.run any ignored_expression
For intermediate to advanced scripters, this allows you to simply write an expression which is ignored. This is useful when you want to call one or more function without running any commands which use the return values.execute string command_line
; Inserts the integer, 123, into collection c. The return value ; of collection_insert is ignored. run collection_insert(c, 123)
execute_for_item item_id item, string command_line
Treats the specified command_line string as though it contained a valid group of commands. Basically, it allows you to execute the contents of a string that contains script code. Use the escape code, "\n", or the concat_lines function to write multiple lines of code.local int data_type, identifier name, any value
The execute_for_item command is basically the same except it temporarily selects the specified item before executing the command(s).
; Displays a message box which displays "hello world!" followed by ; another message box that displays "the end." execute "msg \"hello world!\" \n msg \"the end.\" " ; Does the same thing as the above code, but uses the concat_lines ; function instead (this is easier to read and manage). execute concat_lines("msg \"hello world!\"", "msg \"the end.\"")
Defines a local variable whose lifetime is limited to the current block.const int data_type, identifier name, any value
; Defines a local integer variable named 'foo' with the initial ; value of 123. local int foo, 123 ; Changes the value contained in foo to 456. set foo, 456
Defines a local constant (a read-only named value) whose lifetime is limited to the current block.global int data_type, identifier name, any value
; Defines a local constant named 'foo' with the initial ; value of 123. local int foo, 123 ; Trying to change the value of foo from above like this will result in ; an error since foo is not a variable. set foo, 123 ; error
Defines a global variable (one that is accessible from anywhere) whose lifetime remains until all skelescripts are finished being processed.global_const int data_type, identifier name, any value
; Defines a global string variable named 'bar' with the initial ; value of "hello world!". global string bar, "hello world!" ; Displays "hello world!" in a message box. msg bar ; Changes the string contained in bar to "blah." set bar, "blah" ; Displays "blah" in a message box. msg bar
Defines a global constant (a read-only named value that is accessible from anywhere) whose lifetime remains until all skelescripts are finished being processed.any identifier name, any value = 0
; Defines a global string constant named 'bar' with the initial ; value of "hello world!". global string bar, "hello world!" ; Displays "hello world!" in a message box. msg bar ; Trying to change the value of bar results in an error. set bar, "blah" ; error
bool identifier name, bool value = false
collection identifier name, collection value = create_collection
identifier identifier name, identifier value
int identifier name, int value = 0
item_id identifier name, item_id value = selected
number identifier name, number value = 0.0
string identifier name, string value = """
Shorthands for declaring local variables of various types. Using these is encouraged unless there is a specific reason you want to specify the data type separately using local.const_any identifier name, any value = 0
; Declares a local integer named foo with the initial value of 123. local int foo, 123 ; Does the same thing as above with less code. int foo, 123
const_bool identifier name, bool value = false
const_collection identifier name, collection value = create_collection
const_identifier identifier name, identifier value
const_int identifier name, int value = 0
const_item_id identifier name, item_id value = selected
const_number identifier name, number value = 0.0
const_string identifier name, string value = """
Shorthands for declaring local constants of various types. Using these is encouraged unless there is a specific reason you want to specify the data type separately using const.global_any identifier name, any value = 0
global_bool identifier name, bool value = false
global_collection identifier name, collection value = create_collection
global_identifier identifier name, identifier value
global_int identifier name, int value = 0
global_item_id identifier name, item_id value = selected
global_number identifier name, number value = 0.0
global_string identifier name, string value = """
Shorthands for declaring global variables of various types. Using these is encouraged unless there is a specific reason you want to specify the data type separately using global.global_const_any identifier name, any value = 0
global_const_bool identifier name, bool value = false
global_const_collection identifier name, collection value = create_collection
global_const_identifier identifier name, identifier value
global_const_int identifier name, int value = 0
global_const_item_id identifier name, item_id value = selected
global_const_number identifier name, number value = 0.0
global_const_string identifier name, string value = """
Shorthands for declaring global constants of various types. Using these is encouraged unless there is a specific reason you want to specify the data type separately using global_const.if expression expr
else_if expression expr
else
These commands are for intermediate to advanced programmers. They are used for selecting among one or more bodies of code based on specified conditions. Each of these commands must be followed by a block contained in braces (unlike C/C++, the braces are required even if there is only one statement defining the body of code).while expression expr
The 'if' command must be used before 'else_if' or 'else' commands. If the expression specified following the 'if' command evaluates to true (a non-zero value), the body of code in the block following the command will be executed and all following 'else_if' and 'else' commands will be ignored. Otherwise, the body of code will be skipped.
One or more 'else_if' commands can optionally follow the 'if' command. Like the 'if' command, if the condition following the 'else_if' command evaluates to true, the body of code following the 'else_if' command will be executed and all 'else_if' and 'else' commands that follow will be ignored. Otherwise, the body of code will be skipped.
Optionally, following the last 'else_if' command (or the 'if' command if no 'else_if' commands are used), an 'else' command can be specified. The else command takes no arguments. If the conditions specified the the preceding 'if' and 'else_if' commands all evaluated to false, the 'else' command's following body of code will be executed.
int foo, 456 ; The following code results in a message box displaying "456". if (foo == 123) {msg "123" } else if (foo == 456) {msg "456" } else { msg "the number was..." msg "something other than 123 or 456." } ; If foo was initialized to 123 instead, the above code would ; display "123". ; If foo was initialized to anything other than 123 or 456, the ; above code would first display a message box which reads, ; "the number was...", then it would display another message ; box with the message, "something other than 123 or 456."
The while loop command allows you to run a body of code repeatedly so long as a specified condition remains true.for_each collection c, identifier element_name = "element"
int x, 0 ; repeats the following code so long as x is less than 10. ; the code effectively displays "blah" in a message box ; 10 times in a row. while (x < 10) { msg "blah!" inc x ; add one to x }You can write the above code more conveniently using the post_inc function like this:
int x, 0 while (post_inc(x) < 10) {msg "blah!" }
The for_each loop command allows you to run a body of code repeatedly for every element in a collection.break
collection c, create_collection(string, "foo", "bar", "baz") for_each c, message {msg message}The code above will display three messages: "foo", "bar", and "baz".
Use the break command to prematurely break out of a loop.dec number& source, number amount = 1
int x, 0 while (post_inc(x) < 10) { if (x == 5) {break} msg "blah!" }The above code will display 5 messages instead of 10 because of the premature break when x is equivalent to 5.
inc number& source, number amount = 1
div number& lhs, number rhs
mul number& lhs, number rhs
Mathematical functions used to change the value of the specified variable.define_command identifier name, parameter_list parameters
The inc command increments a variable on the left-hand side by the specified amount on the right-hand side. The dec command decrements a variable by the specified amount. The mul command multiplies the variable's value by the specified value. The div command divides the variable's value by the specied divisor.
Allows you to define your own commands. This is useful for intermediate to advanced users who want to group multiple existing commands into a single command for convenience. The command must be followed by a block of code (in braces) used to define the body of code executed for the new command.define_function int type, identifier name, parameter_list parameters
The parameter_list is an optional group of parameters (separated by commas) consisting of a data type and an identifier. The list must be contained in parentheses.
The format of a parameter is like this (the brackets indicate optional parts):
data_type parameter_name[&] [=] [value]
Some examples follow:
int x_position
string error_message = "Cannot find item."
bool& return_state
The ampersand (&) is an optional character used to specify that the parameter is an out parameter. An out parameter is a parameter which, when receiving a variable as an argument, will write back its value to that variable when the procedure has finished processing. When used with commands, out parmeters allow a command to act like a multiple value-returning function by being able to modify existing variables passed to it. Experienced programmers should be familiar with out parameters or reference parameters. Reference parameters are slightly different as they are basically virtual instances of the same variable - they refer to the same location in memory (though some old compilers have actually used the out parameter approach to implement reference parameters). Out parameters form separate instances, but their values are copied back to the original variable at the end of the procedure. In most cases, this makes no difference to the programmer. The main thing to keep in mind is that they allow changes made in a procedure to be reflected back to the original variables passed to the procedure.
The format of a parameter list is like this:
(data_type arg1[&] [=] [value], data_type arg2[&] [=] [value], etc)
An example would be:
(string name, number x = 0, number y = 0, number z = 0)
define_command display_coordinates (item_id item = selected) { ; Displays the position of the specified item (defaults to ; the return value of the selected function, which is ; the first selected item). string message, "Position of " concat message, item concat message, ": (" concat message, world_x(item) concat message, ", " concat message, world_y(item) concat message, ", " concat message, world_z(item) concat message, ")" msg message }See the skelescript internal library for more examples of how to define commands and other procedures.
Allows you to define a value-returning function. See define_command for a detailed explanation of how to specify the parameter_list.define_get int type, identifier name, parameter_list parameters
Unlike commands, functions return a value, so the data type of the return value must be specified in front of the function name.
define_function bool odd_number(int num) { ; Returns true if num is odd, false if it's even. return (num % 2 == 1) }
Allows you to define the readable portion of a property. If no 'set' procedure for the property exists, a new read-only property will be created. If the 'set' procedure for the property already exists, defining the 'get' procedure will make it both readable and writable.define_set int type, identifier name, parameter_list parameters
A read-only property is syntactically the same thing as a value-returning function. The difference is that a read-only property can be adapted to become a writable property as well, unlike functions, which must always be read-only. Think of a function as a read-only property which is sealed against writability.
define_get item_id grandparent(item_id item = selected) { return parent(parent(item) ) }Here's another example to retrieve the X position of an item directly in feet:
define_get number world_x_in_feet(item_id item = selected) { ; Returns the world_x position for the specified item ; (or the currently selected item if no item is specified) ; in feet rather than in meters. return meters_to_feet(world_x(item) ) } ; Displays the world_x position in feet of the current ; skelescript bone. msg ("World X in feet: " & world_x_in_feet(me) )See define_set below for the 'set' versions of these procedures that will adapt them into writable properties.
Allows you to define the writable portion of a property. If no 'get' procedure for the property exists, a new write-only property will be created. If the 'get' procedure for the property already exists, defining the 'set' procedure will make it both readable and writable.return any return_value = nothing
A write-only property is syntactically similar to a variable. The difference is that it can take arguments. The only way to invoke a 'set' procedure for a property is with the 'set' command or the 'set' function.
When a 'set' procedure is invoked for a property, the value that the user is trying to assign to the property will be passed to the 'set' procedure as a local variable named 'value.'
define_set item_id grandparent(item_id item = selected) { set parent(parent(item) ), value }Here's another example to set the X position of an item directly in feet:
define_set number world_x_in_feet(item_id item = selected) { ; Allows you to set the world_x position in feet ; rather than meters. set world_x, feet_to_meters(value) } ; Set the world_x position to -10 feet. set world_x_in_feet, -10See define_get above for the 'get' version of these procedures that will adapt them into readable properties.
This command allows you to break out of a procedure at any point. For functions and get procedures of properties, this command is the only legal way to return out of these procedures.concat identifier source, any value
For commands and set procedures of properties, you cannot specify any arguments with return since these types of procedures cannot not return a value.
For functions and get procedures of properties, a return value must be specified.
Concatenates (adds by linking) extra text to the end of a string variable.swap any& value1, any& value2
string str, "foo" ; declare a string variable initialized to "foo" concat str, "bar" ; add "bar" to the end of the variable concat str, "baz" ; add "baz" to the end of the variable msg str ; displays "foobarbaz"You can also concatenate variables in other ways, including the use of the set command with the string concatenation operator (&) or the concat function like this:
string str, "foo" ; declare a string variable initialized to "foo" set str, (str & "bar") ; add "bar" to the end of the variable set str, concat(str, "baz") ; add "baz" to the end of the variable msg str ; displays "foobarbaz"However, this second approach is less efficient since it requires forming a new string and assigning it to the variable rather than concatenating the string directly into the variable's contents.
Swaps the values of two variables.set identifier name, any value
int foo, 456 int bar, 123 ; this will cause foo to get the value of 123 and bar to get ; the value of 456. swap foo, bar
Sets the value of a variable or a writable property. If a local variable is available with the same name as a global variable or property, the local variable takes precedence. Likewise, if local variables are defined in inner blocks with the same name as local variables in outer blocks, the local variable defined in the innermost block takes precedence takes precedence over the outer ones.pop collection c
; declare an integer variable named foo with the initial value of 123. int foo, 123 ; change the value of foo to 456 set foo, 456 ; create a new block { msg foo ; displays 456 int foo, 789 msg foo ; displays 789 } msg foo ; displays 456 ; this causes an error because foo has already been defined in this ; block on the first line with: int foo, 123 int foo, 123456789
Removes an element from the end of a collection.push collection c, any element
collection c, create_collection(int, 123, 456, 789) pop c ; removes the last element, 789. msg c ; displays '(123, 456)'
Adds an element to the end of a collection. This is practically the same as collection_insert (without the ability to specify separate keys), but it can be more convenient to write and also more intuitive when working with stacks.__AddRotation_impl item_id item, number add_heading, number add_pitch, number add_bank
collection c, create_collection(int, 1, 2, 3, 4) push c, 5 ; adds the element, 5, to the end of the collection. msg c ; displays '(1, 2, 3, 4, 5)'
__error_invalid_angle_type int angle_type
__export_list bool formatted = true, string file_name = "script_globals.html"
__global bool constant, int type, string identifier_string, any value
__init_internals
__local bool constant, int type, string identifier_string, any value, int block_offset = 0
__native_command string native_command_line
__swap_relative_limits_if_necessary item_id item, int angle_type, number& min, number& max
__swap_relative_limits number& min, number& max
These are system commands used by the internal library script. Only the most advanced users should use these. See the internal library code for examples of usage.
item_id create_null (string name, number x = 0, number y = 0, number z = 0)
Creates a null object with the specified name at the specified absolute position and returns its ID.item_id create_null_at (item_id item, string name, number add_x = 0, number add_y = 0, number add_z = 0)
Creates a null object with the specified name at the specified position relative to the position of the specified item and returns its ID.item_id create_oriented_null_at (item_id item, string name, number add_x = 0, number add_y = 0, number add_z = 0)
This is like the create_null_at function above, but has the additional property of creating a null that matches the orientation of the specified item.item_id create_goal (bool full_time = true, string null_name = concat(name, "_goal"), number add_x = 0, number add_y = 0, number add_z = 0)
item_id create_target (string null_name = concat(name, "_target"), number add_x = 0, number add_y = 0, number add_z = 0)
item_id create_oriented_goal (bool full_time = true, string null_name = concat(name, "_goal"), number add_x = 0, number add_y = 0, number add_z = 0)
item_id create_oriented_target (string null_name = concat(name, "_target"), number add_x = 0, number add_y = 0, number add_z = 0)
See the command versions of these functions. These functions perform the same operation as their command counterparts. The only difference is that these functions return the ID of the newly created goal/target null for convenience.item_id me
Returns the item ID of the current skelescript bone.item_id selected (int index = 0)
Returns the item ID of one of the selected item based on the index. The index starts at 0, meaning that the first element has an index 0, the second has an index of 1, and so forth. If no index is supplied, the ID of the first selected item will be returned. The function returns null_item if there is no selected item for the specified index.bool no_selection
; Displays the name of the first selected item. msg name(selected) ; This also displays the name of the first selected item. msg name(selected(0) ) ; This displays the name of the third selected item. msg name(selected(2) )
Returns true if selection is empty, or false if there are items selected.int num_selected
Returns the number of items selected.collection get_selected_items
Returns a new collection containing all the selected items.int item_type (item_id item = selected)
Returns a value indicating the type of the specified item (if no item is specified, the first selected item will be used by default). Valid return values are: item_type_object, item_type_bone, item_type_camera, item_type_light, and item_type_invalid if the specified ID is invalid.string name (item_id item = selected)
Returns the name of the specified item (if no item is specified, the first selected item will be used by default).item_id child (int index = 0, item_id item = selected)
Returns the child at the specified index for the specified item. Indices start from 0. If no child exists for the specified index, the function returns null_item.bool has_geometry (item_id item = selected)
Returns true if the specified item has geometry. The function will return true for nulls, cameras, lights, and bones.bool is_null_item (item_id item = selected)
Returns true if the specified item is a null object.number heading (item_id item = selected)
number pitch (item_id item = selected)
number bank (item_id item = selected)
number local_x (item_id item = selected)
number local_y (item_id item = selected)
number local_z (item_id item = selected)
number world_x (item_id item = selected)
number world_y (item_id item = selected)
number world_z (item_id item = selected)
number scale_x (item_id item = selected)
number scale_y (item_id item = selected)
number scale_z (item_id item = selected)
number pivot_heading (item_id item = selected)
number pivot_pitch (item_id item = selected)
number pivot_bank (item_id item = selected)
number pivot_x (item_id item = selected)
number pivot_y (item_id item = selected)
number pivot_z (item_id item = selected)
These functions return item parameters for the specified item (or the first selected item if no item ID is specified). The parameters should be self-explanatory based on the names.number relative_x (item_id item, number add_x)
The difference between the world_* functions and the local_* functions is that the world_* functions return absolute positions in the world after parenting, while local_* functions return relative item positions before parenting. Both the world_* and local_* positions are in meters. You can use conversion functions like meters_to_feet to convert the return values.
number relative_y (item_id item, number add_y)
number relative_z (item_id item, number add_z)
These functions return the absolute position relative to an item with a given offset. For example, the relative_x function with an item with the X position of 30 will return 20 if the offset is -10. Moreover, the functions accomodate for position flipping, so if flip_right_x is on, the function will return 40 instead of 20 since it'll flip the -10 offset into 10 since an X position of 30 means that the item is on the right side.string side (item_id item = selected, string left_str = left_side_name, string middle_str = middle_side_name, string right_str = right_side_name)
These functions should be useful for intermediate to advanced scripters whenever they want to calculate relative positions.
This function returns a string describing whether the specified item is to the left (negative X position), to the right (positive X position), or in the middle (an X position of 0).string scene_name
This function returns the name of the current scene or "(unnamed)" if the scene has not yet been saved.string scene_file_name
This function returns the name of the current scene's file name or "(unnamed)" if the scene has not yet been saved.number degrees_to_radians (number degrees)
number radians_to_degrees (number radians)
number feet_to_meters (number feet)
number meters_to_feet (number meters)
These functions convert values from one unit to another, returning the converted result.number add (number lhs, ~number remaining)
number sub (number lhs, ~number remaining)
number div (number lhs, ~number remaining)
number mul (number lhs, ~number remaining)
int mod (int lhs, ~int remaining)
number fmod (number lhs, ~number remaining)
These are mathematical functions which return the result of an arithmetical operation.number abs (number value)
The add function returns the sum of two or more numbers.
The sub function returns the difference of two or more numbers.
The div function returns the quotient after dividing the left-hand value by one or more divisors.
The mul function returns the product of two or more values.
The mod function returns the remainder (as an integer) after dividing an integer into another.
The fmod returns the remainder (as a floating-point decimal number) after dividing a number into another.
Note: beginners should not try to specify more than two arguments for mod and fmod functions as the results may confuse them. They do not return the final remainder after two or more divisions. Instead, they calculate the remainder after each division and use the remainder as a result for the next division.
int round (number value)
bool not (bool value)
number sqrt (number arg)
number sin (number theta)
number cos (number theta)
number tan (number theta)
number asin (number arg)
number acos (number arg)
number atan (number arg)
These are unary mathematical functions which convert a single value.int bitwise_and (int lhs, int rhs)
The abs function returns the absolute value (distance from zero, always positive) of the specified number.
The round function rounds a number to the nearest integer.
The not function negates a true/false boolean value. If true, not will convert it to false. If false, not will convert it to true.
sqrt returns the square root of a number.
sin, cos, tan, asin, acos, and atan are trigonometric functions that return the sine, cosine, tangent, arc sine, arc cosine, and arc tangent of the specified value.
int bitwise_or (int lhs, int rhs)
int bitwise_xor (int lhs, int rhs)
Performs bitwise operations. Inexperienced programmers can forget about these, as they are needed only for system commands. For experienced programmers, these functions can be useful for combining, extracting, and toggling bit flags.any choose (bool selector, expression true_result, expression false_result)
Chooses between two values based on whether the specified selector value is true or false. If true, the second argument is returned. If false, the third argument is returned.any choose_index (int index, ~expression choices)
int x, 15 ; Displays "x is greater than or equal to 10" since (x < 10) ; evaluates to false. msg choose(x < 10, "x is less than 10", "x is greater than or equal to 10")
Like the choose function above, but instead of choosing between 2 values, choose_index can choose among 2 or more values based on an index value starting at 0. If the index is 0, the function will the second argument (the first one following the index). If the index is 1, the function will return the third argument (second following the index), and so forth.number inc (number& source, number amount = 1)
number dec (number& source, number amount = 1)
number post_dec (number& source, number amount = 1)
number post_inc (number& source, number amount = 1)
These functions increment and decrement a variable by the specified amount (1 by default).any set (identifier variable, any value)
The inc and dec functions increment/decrement the variable and return the resulting value.
The post_inc and post_dec functions increment/decrement the variable and return the original value before the variable was incremented/decremented.
int x, 15 msg inc(x, 2) ; sets x to 17 and displays 17. int y, 10 msg post_dec(y) ; sets y from 10 to 9 and displays 10. msg y ; displays 9
Same as the set command, but returns the resulting value.string angle_type_name (int angle_type)
int x msg set(x, 123) ; sets x to 123 and displays 123.
Returns a string describing the angle type value. The return string will be one of the following: "heading", "pitch", or "bank" based on whether angle_heading, angle_pitch, or angle_bank is passed.int length (string str)
msg angle_type_name(angle_pitch) ; displays "pitch"
Returns the length (number of characters) of the specified string.string concat (string lhs, ~any remaining)
Returns a new string that is a combination of two or more strings.string concat_lines (string lhs, ~any remaining)
Returns a new string that is a combination of two or more lines of text.string substr (string str, int start_position, int length = -1)
Returns the portion of the specified string starting from the given position with the given number of characters (length). If no length is specified, the portion of the string from the position to the end of the string will be returned.bool str_equal (string str1, string str2)
string str, "foobar" msg substr(str, 3) ; displays "bar" msg substr(str, 3, 1) ; displays "b"
Returns true if two strings are identical (same exact characters). You can also use the == operator, which may be more familiar for experienced programmers but less intuitive for beginners.string toupper (string str)
string tolower (string str)
Returns the upper / lower case versions of a string.string tostring (any value)
msg tolower("HELLO thErE!") ; displays "hello there!" msg toupper("HELLO thErE!") ; displays "HELLO THERE!"
Converts a non-string value to a string. For strings, this function has no effect at all.collection collection_create (int data_type = any, ~any elements)
int x, 123 ; sets x to the integer, 123. string str, tostring(x) ; sets str to the string, "123"
collection create_collection (int data_type = any, ~any elements)
Creates a new collection and returns it. The data_type specified applies to all elements in the collection.bool collection_clear (collection c)
Both create_collection and collection_create perform the same functionality. Which one you choose is up to you. The identical collection_create function is provided for people who want consistency in the prefix-based form of working with collections.
collection c, create_collection(int, 1, 2, 3, 4, 5)All collections in skelescript are referenced through variables. This means that if you create a variable that is associated with a collection and assign this variable's value to a second variable, the second variable will refer to the same collection in memory (rather than a copy).
For experienced programmers who are interested, collections are automatically garbage-collected by skelescript using a reference-counted system. A collection is deallocated from memory when variables no longer refer to it at all.
collection c1, create_collection(int, 1, 2, 3, 4, 5) ; creates a new variable, c2, which refers to the same collection ; referred to by c1. collection c2, c ; insert element 6 into the collection referred to by c1 (and c2). run collection_insert(c1, 6) msg c2 ; displays (1, 2, 3, 4, 5, 6)
Removes all the elements in a collection, causing it to become empty. The function returns true if the operation succeeds.bool collection_contains (collection c, any key)
Returns true if the collection contains an item with the specified key.bool collection_empty (collection c)
Returns true if the collection is empty (contains no elements at all).bool collection_erase (collection c, any key)
Removes an element from the collection with the following key (or index). If the key is an integer, it will be assumed to be an index. If the key is a string, it will be treated as an actual key that is associated with the element. The function returns true/false based on whether the element was erased successfully.bool collection_insert (collection c, any element, any key = nothing)
Inserts an element into the specified collection. The optional key parameter allows you to specify a key to be associated with the element. The key is used for searching through the collection. For instance, in a collection of phone numbers, the key might be the person's name. You can use then use the person's name to look up the phone number. The function returns true if it is successful.int collection_size (collection c)
Returns the number of elements in a collection.any pop (collection c)
Removes the last element in the collection and returns its value.any clone (any data)
Returns a copy of an existing collection as a new collection.any eval (expression expr)
Evaluates a string's contents as though it were an expression. This has the same effect as the evaluation operator, #.string command_line (string command, ~any remaining)
msg eval("(1 + 2) * 3") ; displays 9 string foo, "bar" string bar, "baz" string baz, "1 + 2" ; Using the eval function: msg foo ; displays "bar" msg eval("foo") ; displays "bar" msg eval(foo) ; displays "baz" msg eval(bar) ; displays "1 + 2" msg eval(baz) ; displays 3 msg eval(eval(eval(foo)) ) ; displays 3 ; Using the string evaluation operator: msg (foo) ; displays "bar" msg (#foo) ; displays "baz" msg (##foo) ; displays "1 + 2" msg (###foo) ; displays 3
Returns a command line string formed from the specified command and each of the remaining arguments, each separated by spaces. This is useful for use with the execute command which executes a command line string as though it were a regular command line.bool is_boolean (any expression)
msg command_line("foo", 1, 2, 3) ; displays "foo 1 2 3"
bool is_collection (any expression)
bool is_integer (any expression)
bool is_item_id (any expression)
bool is_number (any expression)
bool is_only_item_selected (item_id item)
bool is_string (any expression)
These functions allow you to check whether a value matches a specified data type. They return true if the value is compatible with the type.int find_element (any c, any search_element)
msg is_string(123) ; returns false msg is_number(123) ; returns true collection c msg is_collection(c) ; returns true
Searches a collection/string for the specified element/character and returns the index of the first occurrence if found. Otherwise, the function returns -1.string collection_text (collection c, string separator = ", "", string empty_text = "empty"", string inner_prefix = "("", string inner_suffix = ") "")
collection c, create_collection(int, 123, 456, 789) msg find_element(c, 789) ; displays 2 msg find_element(c, 123) ; displays 0 msg find_element(c, 456) ; displays 1 msg find_element(c, 15) ; displays -1 msg find_element("HELLO", "L") ; displays 2
Converts a collection to a string which specifies its elements. Unlike the tostring function, this function gives you control over how to output the collection.collection empty_collection
Returns a new, empty collection.collection rgb (int red, int green, int blue)
Creates and returns a collection of color components in the range from 0 to 255. Use this function to create color collections for functions that require RGB values.collection rgb_to_float (collection c)
Returns a new collection from the specified collection which contains floating-point values ranging from 0.0 to 1.0 instead of 0 to 255.string __collection_text_impl (int j, collection c, string separator = ", "", string empty_text = "empty"", string inner_prefix = "("", string inner_suffix = ")"")
collection __server_collection (item_id item, string plugin_class)
string __server (item_id item, string class, int index)
item_id __child (int index, item_id item)
int __controller (item_id item, int angle_type)
int<