Custom Arms Scripting: Introduction

Glossary:
Throughout these pages, a few key terms will be used quite often. This is a quick explanation of what they mean

• Action: An action is something triggered by the user. Combo attacks, drawing, sheathing, specials, and taunts, are all examples of actions. An action has a number of commands associated with it. An action starts when the user does whatever input is required, like pressing a special key, and ends when all of the commands associated with it are finished.
• CAS: Short for Custom Arms Scripting, the language used to write animsets for Custom Arms
• Command: An order passed to CAS. A command consists of four values, seperated by commas. Those are in order, the time of the command, the function that the command calls, the first argument for that function, and the second argument for that function.
• Function: A block of code which does something, and takes inputs to modify how it does that. All functions in CAS are represented by integers which are used in the second field of a command, to call them.
• Integer: An integer is a whole number. with "nothing after the point" 1 is an integer. -34 is an integer. 4.32 is not.
• Line: A single notecard line within an animset, usually containing several commands. It's possible for an action to have more than one line associated with it.

This is a tutorial for basic users who have done little or no programming before. Note that some basic building and object editing skills are still required. This tutorial will teach you the basic concepts of the Custom Arms Scripting language

To begin with, custom arms scripting is done in notecards, not actual scripts. Each line of the notecard can contain data of various types, which the scripts will read and store, to later use as commands. Each line is in CSV format. That stands for Comma Seperated Values. It means that individual parts of the data are seperated by a comma --> ,

Usually when you see a comma in a custom arms script, it is seperating one part of data, or element, from another.
Each line which has commands, has the first two elements devoted to extra information, like what type of line it is, and then the rest of the elements are commands, in groups of 4.

Here's an example line from the Hyper animset:

C,hyper_1_1,-1,61,1_1,0,\\-1,25,0,0,\\0.43,11,40,5,\\0.95,51,0,0

This line is for the first attack on the W key, which makes you slash overhead.
You'll notice that it contains \\ several times. This is a seperator, which is used only to visually seperate commands. In this line, where you see a \\ is the space between one command, and another.

It is important to remember that these slashes are only for the user (ie, you) to understand things better. The scripts will not use them at all, and will completely ignore them. So for the purposes of learning, we will pretend that they're not there. And work with this line:

C,hyper_1_1,-1,61,1_1,0,-1,25,0,0,0.43,11,40,5,0.95,51,0,0

Which is just the same, but with the slashes removed.
As mentioned, CAS uses CSV. Every bit of information between two commas is something significant. Let's split it up:

C
hyper_1_1
-1
61
1_1
0
-1
25
0
0
0.43
11
40
5
0.95
51
0
0

This is how our line looks, if we split it at the commas. It still appears to be just a bunch of numbers, but this illustrates how it should be divided to begin with.
As mentioned, the first two elements (C and hyper_1_1) are used for extra information. Here, C tells us the type of line this is. C stands for Combo attack. Also useable are S for special, U for utility (draw/sheath) and T for taunts

The second element, in this case 'hyper_1_1' is the name of this action. What is here DOES NOT MATTER. It could say monkey cheese, or blue bananas, and it would work just as well. This element is only read by the user (you) to remind you of what a particular line is for. The scripts in the core will ignore this element entirely.

After the first two, the core will read the line in blocks of 4 elements. For example, it would be split something like this:
C,hyper_1_1
-1,61,1_1,0
-1,25,0,0
0.43,11,40,5
0.95,51,0,0

Here, the first two elements are split off by themself, and the rest are in groups of 4, seperated by commas. Now I'll explain what each of these groups does:

-1,61,1_1,0

These four elements all have their own meaning. The combination of them together, gives an order to the core, to do something, at a certain time.

The first element, is the time. Here it is -1. In CAS, a time of -1 basically means "as soon as possible". So having -1 here will cause the core to run this command right away, when the appropriate action (first W combo attack) is triggered.

The second element, which says 61, is the function. All functions in CAS have a number like this associated with them, and you can find a big table near the end of this tutorial which will explain what all the functions are. Don't worry, you're not expected to remember them. I don't even remember them, and I wrote the system. I just check my function table constantly while writing.
In this case, 61 is the Animation function. This function starts an animation on the avatar, and is very important to Custom Arms in general.

The third element, which says 1_1, is the first argument. An argument is data which a function takes in, to tell it exactly how to do it's job. In this case for example, 61 tells the core to start an animation, and this element tells it WHAT animation to start. Note that the animset name and _ is prepended to the value here. Since this is in the hyper animset, and the value here is 1_1. Running this command would play the animation 'hyper_1_1'

The fourth element, is argument2. This is very similar to argument1, except that it just contains more additional data to tell the function how to behave. You can never have too much data! For this particular function, the second element is not being used, and so it has a value of 0, which does nothing at all.


Let's look at another example. The second set of commands:
-1,25,0,0

Again, the first element here is -1. So again, it runs as soon as possible. Now, this can't run as soon as the action starts, because the previous command will be running then, and only one command can work at a time. So by putting a time of -1 here, this command will run as soon as the previous one finishes. Don't worry, it doesn't actually take long. the first command we looked at will finish in a fraction of a second, probably too fast to notice. So in practice it will seem like these commands are happening at the same time.

The second element here is 25. Again, this is a function number. The number 25 corresponds to the Trail function. This function turns on the weapon's trails, if it has any.

The third element, 0, is actually very important. Sometimes 0 is actually meaningful. In this case, a command of 0 means turn on the first trail, which in most cases will be the one opposite the leading edge of a sword. This value could also be 1, which would turn on the second trail. If it were -1, it would turn OFF all trails. And if it were -2, it would allow us to change the colour of the trails (for this action only)

The fourth element is also 0. This time, it has no meaning, it's just nothing. But if the third element had contained -2, there would be a colour here, telling which colour to change the trail to.

UNFINISHED
PLEASE COME BACK SOON FOR THE REST

Advanced Intro
--------------------------
For a tutorial oriented towards advanced users, see here:




This is a tutorial for advanced users with experience in LSL, as a quick introduction to the CAS language. It assumes familiary with the concepts of variables, functions, CSV, comments.

Overview
----------
Custom Arms Scripting is a small language which is written in notecards, and read by an lsl interpreter. It contains only input and has no logic structures, so is perhaps more similar to XML than any "real" language.

A CAS script is divided into lines, with each line being a CSV of functions and arguments. Due to memory limitations, the interpreter has to be simple, and so some formatting is strictly enforced. The c++ comment style of using // is also in use here. Everything after that on a line is ignored by the interpreter. Whitespace is somewhat significant, blank lines are entirely ignored, but as the script is stored in strings, putting unnecessary spaces in the CSV is not recommended.

The Entire CAS script, except for name elements, and comment lines, is read and stored inside the core as strings. The bigger or more complex an animset is, the more memory it will use. If you go overboard, this can result in crashing the core. For this reason, it is recommended to make animsets only as complex as they need to be. Also see Optimisation farther below.

Syntax
-----------
CAS lines are interpreted from left to right, and all function calls must be in the correct order that you wish them to trigger.
The first two elements of every line, are an identifier, and a name. The Identifier determines what type of line it is (combo, special attack, taunt, etc). The name is irrelevant and discarded by the interpreter. It's purpose is only for formatting and readability within the notecard.
Everything after the first two elements, for most identifiers, is pure CAS functions. Every function call uses exactly four of the CSV elements in the line, no more and no less. These elements are, in order:

• Time: Takes a float value. This is the time into the action, that this function will be called. Alternatively, you can put -1 which will trigger this function immediately after the previous one ends. If -1 is used for the first function, that function is called as soon as the action is triggered.
• Function: An integer constant is used here, to determine which function you wish to call. See the CAS reference for a list of functions.
• Argument1, argument2: The last two elements are arguments. These take any input for the function. see the CAS reference for a list of functions and their arguments.

Lists:
Some functions take a list as an input. To write lists in CAS, the format used is a CSV encapsulated with pointed brackets. For example:
<1,2,red,blue,<0.1,2.3,3.1>,45.0>

Lists can contain vectors without problems, but they cannot contain strings which have < or > in them. Any such strings will be treated internally as vectors.


All strings used such as animation names, must not contain any of the following characters:
\,/|<>
The above are in use by the system for various parsing, seperating, and commenting purposes. Using them WILL break your animset. Any string containing < or > may be treated as a vector.
In addition, the following characters are in use in some places, and are not advised for use where possible.
|#!'"_

Strings do not need to be encapsulated or escaped in any way.
For best results, use only alphanumeric characters a-z, A-Z, 0-9

Identifiers
-----------
The following strings are valid identifiers in CAS. An identifier takes the first CSV element of a line, and tells the core what kind of information this line holds, so it knows where to store it and when to call it.

C: Denotes a combo attack.
S: Denotes a special attack
T: Denotes a taunt
U: Short for utility. This is currently used for draw and sheath commands. In that order.
SET: Denotes an animset setting. This is a special case that does not use CAS. Only one setting is currently recnognised, direction, which determines the grip direction for the weapon. 0 = normal, 1 = reversed. This identifier still uses the second field as a name.
PRE: Short for Preload Textures. This is a special case that does not use CAS. Each line holds the UUID of a texture to preload for this animset. These textures are automatically preloaded when the animset is loaded. This is the ONLY identifier where order is not relevant.


With the exception of PRE, all identifiers are very specific about their interrelational order. That is, all lines with a given identifier must be in a certain order, usually ascending. For example, special 1 must be before special 2. The absolute location of these in the notecard is irrelevant, and so is their order relative to lines with a different identifier.

So an order like

special 1
combo 1_1
special 2
taunt 1
combo 1_2
taunt 2

etc, is fine.


Nevertheless, it is recommended for readability, to gather all lines with the same identifier into one block.

For combo attacks, the order is ascending direction, then ascending combo level. For example:
1_1
1_2
1_3
1_4
2_1
2_2
2_3
2_4

The above is a correct order.
And this, is not:
1_1
2_1
3_1
4_1
1_2
2_2
3_2
4_2

For Utility, the order is Draw, Sheath.
For technical reasons, it is adviseable to put Utility commands near the top of the notecard. This is not required though.
-------------------------------------------------------------------------------

Optimisation
----------------
The entire animset is read and stored as strings, which is taxing to memory. Bear in mind that a few things are different with strings, "1.0000" is not the same as "1". Although they have the same numerical value when typecast to float, the latter one uses far less memory than the former. It is therefore far better to use the latter where possible. The same principle can be applied almost anywhere. For example, the vector:
<0.123000, 12.000000, 0.000000>
Can be written as
<.123,12,0>
Notice that the leading 0 on the first value is removed. Trailing zeroes on all values are removed, and spaces between them are removed.
Any values which have nothing after the point, can have their decimal point entirely removed
The result is a value which means exactly the same thing, but takes far less memory to store.

Another trick is default values. Mainly for floats and vectors. The default vector is <0.000000, 0.000000, 0.000000>. This is of course very messy and long, and you could write it much simpler as: <0,0,0>
However, there's an even easier way. When a string which has no numerical value is typecast to a type like vector, it's value becomes the default value for the type. This means you can put in any non numeric string, even a single character, that will be equivilant to the zero vector. For internal consistency, it is recommended to use @ as this value, but that's optional.

Note that there is a big catch here. This default value trick cannot be used in the list input for function 26 (params). That function relies on visible cues in the text, like the pointy brackets around vectors and rotations, to determine what type things need to be. When writing input for that function, vectors must be written as <0,0,0> at a minimum. Similar for rotations. they have to be a valid value

This is useful on rotations too, which have a default value of <0.0, 0.0, 0.0, 1.0>. It is not useful on floats or integers as those can be easily written as 0.

CAS Functions
--------------
For a quick listing of the functions in CAS for experienced users, see the reference:<LINK GOES HERE>
This section is for those who are new to CAS, and need to learn roughly what each function does and how it should be used.

All functions have an integer constant associated with them. That is, a number which represents them. These integers are arranged in groups corresponding loosely to what they do. Each group will be explained here one at a time.



1x Attacks
------------
In CAS, you can insert an attack command anywhere. What this actually does, is triggers the weapon's hit detection method. Either by sensor or projectile. The system will handle everything from there, triggering sounds and particle effects as appropriate.

The attack command is not actually needed to do damage in most combat systems. The majority of systems do damage between themselves, and the weapon is merely a fancy visual on top of that. Currently the only system that the attack command is needed for, is Linden Damage. It is primarily used for the hit sounds/effects.

Types:
Attacks come in different types. Currently, three types are supported. Each type of attack has a hit soundgroup and a hit particle effect associated with it. Currently, customisation of attack types is not supported, one of the very few areas of Custom Arms that cannot be customised. This will probably change in the future, as I will look towards making attack types more customiseable down the line.

There is one command for each type. Starting at 11 and working upwards:

11 Slash: A slash with a bladed weapon. eg, sword, knife, claw
12 unarmed: A strike with a nonmetallic blunt object, baseball bat, fist, foot, tentacle, etc
13 Blunt: A strike with a blunt metal object. eg, metal staff, mace, etc.

to specify an attack call, use a value between 11 and 13 in the second element of a command. Try to choose the most appropriate attack type.
Note that every attack type, in addition to it's normal hit sound, also has a critical hit sound. The critical sound will be triggered automatically instead of the normal one, if the attack has a Damage value of 6 or higher. See below for more info

Damage and Power:

in addition to a type, each attack also has a damage, and a power value.

The damage value determines how much damage the attack does. Currently, only Linden Damage respects this value. Other combat systems work out their attack damage on their own. An applicable value is between 0 and 9, with 0 being no damage, and 9 a massive hit. Note that trying to insert a value higher than 9 or lower than 0 will not work

The power value determines how much the attack pushes the target. A value of 0 means no push, and 9, the highest, will send someone flying 50m or so away. Using push is only recommended for a few select attacks, like big roundhouse kicks, and specials. It is not advised to use push on every attack, though there are no technical limitations on doing so. Abusing the push feature is likely to get you banned from roleplay sims. Magotek is not responsible for this.


Attack Direction:

The attack direction is a value which tells the system what way you are swinging the weapon. It orients damage projectiles accordingly, so that the effects are directional. For example, uyou can make blood spray in the direction you swing a sword.

The following chart lists the directions. Only one is useable per attack

Projectile Direction Constants
1 up
2 Up/Left
3 Left
4 Down/Left
5 Down
6 Down/Right
7 Right
8 Up/Right
9 Forward (away)
10 Back (towards self)



Using

All attacks take the following arguments
1: Damage and Power concatenated into one integer
2: Attack direction. a value from 1-10. See list above.

The function that you call determines the type.
To put this all together. If you want to create a command for a bladed slash to the right, with moderate damage, you would use something like

1.0,11,40,7

Those values are:

1.0: a random time picked for an example. Use the appropriate time for your command.
11: The function call for a bladed attack
40: 4 and 0 put together. That's 4 damage, 0 power (no push)
7: The attack direction of right. Will make the blood spray to the right from this attack.















2x Utility
------------
21 Hide Weapon: Turns the Held weapon invisible.
22 Show Weapon: Turns held weapon visible. No arguments

These two functions will make the weapon visible or invisible. What might you use this for? There are several possible uses. For example, you could make a thrown weapon, that disappears from your hand (by turning invisible) when you throw it. And returns to your hand by turning visible again.

Another good use for this is in weapon-specific sheath/draw commands. See the Weapon Settings thread for more info here: <LINK GOES HERE>

.................................

23 Sheath Weapon: Sets weapon status to 0, updates the sheath, and turns held weapon invisible (if weapon settings allow). no Arguments
24 Draw Weapon: Sets weapon status to 1, updates the sheath, and turns held weapon visible(if weapon settings allow). no arguments

These functions draw and sheath the weapon. More specifically, they:
1. Change the internal weapon status value between 1(drawn) and 0(sheathed)
2. Send a linkmessage out on the weapon status channel (weapon_status_channel = 457473663). This number has the weapon status (0 or 1) in the str field.
3. Turns the held weapon invisible (when sheathing) or visible (when drawing). Note that weapon settings can prevent this. See the Weapon Settings thread for more info.
4. Sends a chat message out on the weapon status chanel. Has weapon status as message. The sheath usually listens on this channel, and uses this to do it's own visual work.

These functions do not trigger any animations. All that they do, is the internal gruntwork to make the weapon switch between sheathed and drawn. It is adviseable to use them at the precise point in the draw/sheath anim that the weapon is released. For example with a sword, it would be after the sword is fully sheathed, and just before the user lets go and draws their hand away.

............................................

25 Trails Show weapon trails. Argument1 number of trail, or -1 to disable. -2 for color setting, in which case the argument2 is the color. <-1, -1, -1> sets it back to system color, and is auto reverted on event end.

The trails function gives an animset control over the weapon trails.

The first thing it can do, is turn a trail on. the trails are always there, but hidden, by default. This can be used to make a trail visible for one attack. To do this, use the number of the trail you want to activate as Argument1, and no argument2.

Second thing, is turning trails off. There is no function to turn off specific trails, only to turn them all off. To do this, use -1 as argument1, and no argument2
Note that trails will automatically be turned off at the end of each attack. This usage is only needed when you have need to turn a trail on, and then back off, within the same action. For example, a sword combo that slashes once, moves around, then slashes again. you'd want to turn off the trail for the moving around part.

The third and final use, is changing the trail color. There is no function to set the color of individual trails, only to change them all. To do this, use -2 as argument1, and a color vector as argument2. Using <-1, -1, -1> sets it back to system color, and it will automatically revert to system colour at the end of the action.

.............................................

26 Params

This function allows you to execute the native LSL function, llSetLinkPrimitiveParams, through CAS. This tutorial will only cover how this is implemented in CAS, not the entire workings of llSetLinkPrimitiveParams. For info on that, read the lsl wikis: http://wiki.secondlife.com/wiki/LlSetPrimitiveParams
http://lslwiki.net/lslwiki/wakka.php?wa ... tiveParams

The first implementation detail is the targeting. You can either pass a linknumber as argument1 like primparams normally behaves, and all params will be applied to that prim. Or you can put in a name. The core will search the whole object for prims with that name, and apply all parameters to every one that matches. The latter method is more powerful in some cases, but requires the object to be properly setup.

Secondly, the list. You simply need to put down the entire params list you want to use, in the notecard, as the second argument. Remember that lists in CAS must be a CSV with <> around them. There are some important points to note:

-You can't use integer constants like PRIM_SIZE or LINK_SET in a string. Instead, use the integer that they represent. The integer for each param flag can be found on the wiki.
-Remember to trim unecessary extra zeroes from floats and vectors, to reduce the data size.
-Any strings used in this function cannot contain <>
-Prims named with numbers will not work, like "26". Only use numbers for targeting a specific link.
-This is the slowest function in CAS. It can take significant time to apply, and is slowed farther by delays.
The list of params has to be parsed and cast into the appropriate data types. How long this takes will depend on the size of your list. Expect an initial delay of 0.03 seconds per list element.
For each prim that is changing, add another 0.2 seconds, the delay on the primparams functions.
Searching the linkset for named prims will also add it's own overhead.

Argument1: Name or linknumber of target
Argument2: List of params. <> encapsulated CSV.
.............................

27 Message Sends an arbitrary linkmessage. Argument 1 is num, argument2 is <string>|<id> . The components of argument2 MUST be encapsulated in <> and seperated with |

This function sends a linkmessage to the LINK_SET, via llMessageLinked. For more info on that: https://wiki.secondlife.com/wiki/LlMessageLinked
Argument1 is the Num field.
Argument2 <string>|<id> . The components of argument2 MUST be encapsulated in <> and seperated with |

.........................................................









3x Audio
------------
31 Sound: Plays a sound type. Takes a sound type as argument.
32 Voice: Plays a voice type. Takes a voice type as argument.

Sounds and voices in CAS are organised into types, with each type being assigned a number. For example, 0 is miss sounds, 1 is slashy sounds, and so on.
These commands interact with the random sound system, by taking a type to play as argument1, and playing a sound randomly of that type from all available. The only difference between the two is that 31 plays sounds from the soundset currently loaded, and 32 plays from the current voiceset.
Note that if a set of the appropriate type is not loaded, or if there are no sounds in the specified group, this call will silently fail and the action will continue without any error.
....................
33 Arbitrary: Plays any arbitrary sound. Takes a sound UUID as argument, or a sound name (asset must be in inventory

An alternative method of doing sounds, this one takes a sound UUID as argument1. Or alternatively, you can place the sound aseet inside the weapon system, and then call it by name.







4x Weapon Motion
------------------
41 Spin: Spins the weapon around using llTargetOmega. Argument is spin speed
42 Stop spin: Stops a spinning weapon.

These two functions control weapon spin. Spinning is on a preset axis, you simply specify the spin speed (float) as argument1. For reference, 20 is a good speed. 0 is no spinning. Negative numbers will spin the opposite direction

function 42 when called, will stop spin if the weapon is currently spinning. Spinning will automatically stop at the end of an action.


43 Direction

Calling this function will set the weapon's direction, either in normal, or reverse grip. Call with 0 for normal, 1 for reversed
Will automatically revert back to the animset default. If you want a weapon to always be held in reverse grip, specify it in the animset settings. This function is to be used to set the direction for a single attack only.





5x Misc
----------------
51 Stop:
Immediately ends the current action. If there are any farther commands after a stop command, they will not be executed. No input
It is recommended to use this command to delay the end of your action until the appropriate time, by having it as the last action. Use of this is not necessary to end an action, it will automatically end if it runs out of commands to process.




6x Animation
----------------
61 Play Anim
62 Play Anim (unoptimised)

Perhaps the most important CAS functions of all. A weapon is nothing without animations. This function is the main gateway through which you control them.

Function 61 takes two arguments. The first is the prefix-stripped name of the animation. That is, the name of an anim with the animset name removed from the top. For example, if you are using the animset hyper, and you want to call the animation 'hyper_1_1', you would use just '1_1' as the argument1 for this function. The animset name is automatically added to the start.

This means that animations are required to follow a specific naming convention. They must always be named in the format <animsetname>_<namehere>

The second argument is a boolean value, telling whether or not to record this animation. If 1 is supplied as argument2, the animation will be recorded in a list internally. This allows it to be stopped later, with the next function. The main usage of this is for looped animations, which once started, never stop on their own. Always use Argument2 of 1 with looped anims.

Function 62 is an unoptimised version. When playing an animation with this function, it takes the exact name of the anim. This means no naming convention is needed. Note that 61 is generally better for script memory and should be used where possible. 62 is provided for the occasional case where you want to use an animation which is no-modify and cannot be renamed.
..............................

63 Stop Anim: Stops animations. Argument 1 is a type to stop: 0 = single, 1 = list, 2 = all. Argument2 is an animation name, only relevant if A1 is 0.

This function stops animations. It is only occasionally useful.
It has three modes of operation, which can be used by passing an argument1 of 0, 1, or 2
0: Stop single animation mode. The second argument should be the name or UUID of the animation to stop.
1: Stop listed animation mode. No second argument is needed. This call will stop every animation in the internal anim list, and then clear it. This is only useful if you are making animations add themselves to the list (see function 61). Also note that the anim list is automatically stopped at the end of an action, so only use this if you need them to stop before the end.
2. All animation mode. This call will stop every single animation currently playing on your avatar, including animations from any other object or outside source, and the default linden animations.

-----------------------------------

64 Move Av to:
This CAS function calls the native LSL function, llMoveToTarget, with some supplied parameters. For those not aware, when called from the root prim of a worn attachment, this function will move the avatar. Therefore, this function is designed to move the avatar around to where you want them. This is especially useful for things like running forward during an animation, or leaping into the air.

The first parameter takes an offset vector of where to move to. That is, xyz. Note that the offset you enter will automatically be localised to the avatar's rotation. For reference, the X axis is backwards (negative) and forward (positive). The Y axis is Left (Negative) and right (positive). The Z axis is Down (negative) and Up (positive). So for example if you want the avatar to leap 2m forward, you would use a parameter1 of <2.0,0.,0.>


7x Effects
-----------------------
71 Rez Object: rezzes an object. Argument1 is a string containint "name,offset,rotation,start param". Argument 2 is a list of 2 values, specifing whether the position and rotation are global (or not)


All strings used such as animset names, must not contain any of the following characters:
\,_/|#!<>'"
The above are in use by the system for various parsing, seperating, and commenting purposes. Using them WILL break your animset.
For best results, use only alphanumeric characters a-z, A-Z, 0-9

All Lists such as primparams input should be in csv format and encapsulated with pointed brackets < >