ArgScript - emd4600/SporeModder-FX GitHub Wiki

ArgScript is the most common file format in Spore modding. This page describes its main features.

ArgScript is a plain text format, consisting of multiple commands with parameters and options. By itself, ArgScript doesn't do anything: the available commands depend on the type of file that is being processed (is it an effect? a property list?)

An example of a .prop.prop_t file, which uses ArgScript:

key parent CreatureEditorTemplates!CreatureMouthCarnivoreTemplate
# This is a comment, this gets ignored

texts blockName
	"Canine Jaw"
end

int32 modelCapabilityVocalize 1
int32 modelCapabilityBite 3
int32 modelPrice 75

float modelMaxScale 2
float modelMinScale 0.5

key modelMeshLOD0 editor_rigblock~!ce_mouth_jaw_carnivore_02.rw4
key skinpaintDiffuseTexture skinPaint_texture~!ce_mouth_jaw_carnivore_02__diffuse.rw4
key skinpaintSpecBumpTexture skinPaint_texture~!ce_mouth_jaw_carnivore_02__specBump.rw4
key skinpaintTintMaskTexture skinPaint_texture~!ce_mouth_jaw_carnivore_02__tintMask.rw4

ArgScript is used in:

• Property Lists (.prop.prop_t)
• Effects (.pfx)
• Materials and Compiled States (.smt_t and .rw4)
• Shader Fragments (.vertex_fragment and .pixel_fragment)
• Animation Lists (.tlsa.tlsa_t)
• Part Capability Lists (.pctp.pctp_t)
• Animations (.animation.anim_t)
• .trigger

The basic building block in ArgScript are words. Words are separated by spaces. Words can have whitespaces inside if they are surrounded with () or ""

For example:model myEffect -scale 0.5 -pos (0, 3.0, 0) is detecting 6 different words: model, myEffect, -scale, 0.5, pos, (0, 3.0, 0)

A command (also property, attribute or instruction) is a single line of ArgScript. The first word of a command is called the keyword, and it's what identifies the command. Words starting with - are called options. The rest of words are arguments. For example:

yaw 0.4 0.67 0.9 -vary 1.0

The keyword is yaw; 0.4, 0.67 and 0.9 are the arguments; -vary is an option and 1.0 is the argument of the -vary option.

Like their names says, they are optional: you only have to write them if you want to use them. They are prefixed with a - and can have multiple arguments. A flag is an option that takes no arguments.

Blocks are special commands that can have other commands inside; a single end keyword is used to close the block. The first line of a block is just like other commands, so they can have arguments and options.

Some special blocks don't require keywords in the commands inside.

# This is a command
float modelScale 2.3

# This is a block with 2 commands inside, which do not use keywords
transform modelEffectTransforms
    -offset (-2, 0, 2)
    -offset (-3, 0, 3) -scale 0.5
end  # finish the block

Comments are parts of the text which are ignored. They will be lost when compiled, but they can be useful as notes to explain what something does, or when you want to disable a certain part of the file without deleting it. Everything after a # character is a comment.

There are some generic data types supported by ArgScript. These data types are used in the documentation to tell you which types of values are expected for every instruction.

• int: Integer values.
• uint: Unsigned (positive) integer values.
• float: Real numbers, decimals can be used.
• id: Either a name or a hexadecimal number (with 0x).
• string: Text. It's better to surround it with "", as in "my text".
• bool: A boolean: true or false.
• vector2: Two float numbers, in parenthesis (e.g. (0.3, 1))
• vector3: Three float numbers, in parenthesis (e.g. (0.3, 1, 0.0))
• vector4: Four float numbers, in parenthesis (e.g. (0.3, 1, 0.0, 1.0))
• colorRGB: Like vector3, but it represents a color
• colorRGBA: Like vector4, but it represents a color with alpha channel
• resourceID: Two values, separated by an exclamation sign !, that represent a group and an instance id. These IDs can either be hexadecimal integers (with 0x) or names; the group is optional. For example, MyModels!custom_background, 0x03472df3,...
• resourceKey: Similar to resourceID but with 3 values, in the format group!instance.type. For example: creature_parts~!ce_grob_eye.prop
• enum: Only certain values are accepted. Those values are specified in the documentation
• bitfield: Like an integer, but this is used to represent flags: that is, each bit represents a boolean value. For example, value 0x2003 has bits 0, 1, 13 enabled
• transform: A special type made by combining multiple options, more information in ArgScript Transforms.

In the color types, it's possible to edit them with a color picker; for more info, check ArgScript Colors.

In certain formats there can be other types specific to the format. For example, in effects the type particles is the name of a particles component, etc.

This might be the most important section. As we explained before, ArgScript is nothing by itself; it all depends on the type of file (.prop_t, .pfx, .anim_t, etc) being processed. For that reason, it is very important to be able to understand the documentation provided in this website, as it will tell you all the available commands, blocks and options for each type of file.

Basically, in the documentation we use <> to show the type of argument that is expected in that position, for example <float>. If it's between parenthesis, such as (<id>), then the value is optional. If ... is used, as in <int...> this means that it accepts more than one value. In certain cases, we also specify a name for that argument with :, for example <colorRGB: backgroundColor> means that the value will be used as background color, and it expects a colorRGB value.

Some examples of command documentation:

• scale <float>: This means the scale command requires a single argument, of type float. So for example we can do scale 2.0.

• life <float: minLife> (<float: maxLife>): This means the life command requires one argument, a float that the documentation calls minLife. It is possible to provide a second argument, maxLife, but it's optional (it's in parenthesis).

• alpha <float...> -vary <float>: This means the alpha command requires one or multiple float arguments. You can also use the option -vary with another float. So we can do alpha 1.0 0.3 0.5 0.9 -vary 0.15

It is possible to use mathematical expressions wherever an int or a float number is required. This is specially useful when combined with the variables explained before. These expressions accept the following operations:

• Addition: +
• Subtraction: -
• Multiplication: *
• Division: / (in integers, the result is floored)
• Modulo: %
• Power: ^

It's also possible to use functions. To use functions, type the function name, and then the parameters in parenthesis. The supported functions are:

• log(x): natural logarithm (base e) of x
• abs(x): absolute value of x (returns x in positive)
• floor(x): floor of x (rounded to closest smaller integer)
• ceil(x): ceil of x (rounded to closest larger integer)
• round(x): x rounded to the closest integer
• sqr(x): x squared

This function is exclusive for integers:

• hash(x): Return the hash of the name x. This is useful for referencing files. For example, hash(animations~) will return 0x00000000

It's possible to express an integer in hexadecimal by prefixing it with 0x.

These functions are exclusive for floats:

• sqrt(x): square root of x
• exp(x): e raised to the power of x
• sin(x): sine of angle x, in radians
• cos(x): cosine of angle x, in radians
• tan(x): tangent of angle x, in radians
• asin(x): arcsine of x, returns angle in radians
• acos(x): arccosine of x, returns angle in radians
• atan(x): arctangent of x, returns angle in radians
• atan2(x, y): arctangent of sides x and y, returns angle in radians
• sind(x): sine of angle x, in degrees
• cosd(x): cosine of angle x, in degrees
• tand(x): tangent of angle x, in degrees
• asind(x): arcsine of x, returns angle in degrees
• acosd(x): arccosine of x, returns angle in degrees
• atand(x): arctangent of x, returns angle in degrees
• atan2d(x, y): arctangent of sides x and y, returns angle in degrees

Floats also have two special words: pi and e It is possible to express floats in scientific notation: 3.4e4 is 3.4 * 10^4

Remember that mathematical expressions are a single word, and in ArgScript words are separated by spaces; therefore, if your expression contains whitespaces, you must surround it with parenthesis:

# This is not valid, it has a whitespace
3 + 4
# These are valid expressions
3+4
((3^2) * sin(0.5 * pi))
4*$radius

It is possible to use logical expressions when bool is required. Apart from everything supported in integer expressions, the following keywords are accepted:

• true, on, 1
• false, off, 0

Comparisons are also supported:

• >: greater than
• <: smaller than
• ==: equal to
• !=: not equal to

You can chain comparisons with:

• and
• or
• not

It's possible to specify "compile-time variables" that can be used in the file; they are similar to C macros. Keep in mind that these are NOT like variables in programming languages. These are processed and replaced when packing the mod, so they can't be modified on runtime. They are just replacements, a way to give a name to a certain value.

set my_var 4
float modelScale $my_var

It is possible to compile some sections of the file only if a certain criteria is met. This is usually combined with variables to easily enable/disable parts of the file. Conditions go in parenthesis; the keywordsif, elseif and else are used. End the conditional block with endif. For example:

if ($debug == true)
    float modelScale 2.5
endif