Jazz Script Tutorial by Simoro
Of the three primary resources required for custom animations to work, the Jazz Scripts are one of the least understood. Compared to the mind-numbing work required to create the animations themselves and the brain-melting work of coding the custom interactions, Jazz Scripts are relatively easy and straight forward. However, it is still not clear what a hefty portion of the Jazz commands actually do. This tutorial is an attempt to break down each of the functions available and explain to the best extent possible what each one does. Some of this is based off of guess work and trial and error, and as more information becomes available, this information will be updated.
Most of the information here was gathered from the wiki: SmoothJazz Wiki
plus ample trial and error.
So lets begin playing some Jazz!
In order to create or modify Jazz scripts, you will need a Jazz editor. The only one I am aware of is SmoothJazz by TigerM and maintained by Peter Jones.
If you want to peek at the EA Jazz scripts, they are all located in JazzData.package in the \The Sims 3\Game\Bin\Jazz\ folder.
If you are starting from scratch, your Jazz script will need a State Machine name. This is the name that will be used in the Visual Studio code. If you are modifying an existing EA script in order to replace existing EA functionality without modifying the code behind it (such as replacing animations), the State Machine name should not be changed. DO NOT actually save changes to the original script. Simply duplicate it, edit it, and put the modded script into the .package file. It will automatically override the normal EA one of the same name. If this is a custom script, it is good to start the name with your Username, just to ensure it doesn't conflict with EAs or other custom scripts. It should also be named descriptively upon whatever the script does. For example, if I was scripting an exercise routine, the State Machine would be something like:
State Machine "Simoro_exercise"
{
}
The entire rest of the script will be listed inbetween the curly brackets.
Next are all of the settings that belong to the State Machine. Many of these are optional, depending on what the script needs to do. In the order they are normal found, they are: Priority, Properties, Actor, Parameters, and Assign Actor. Priority and Properties are often absent, especially for simple scripts. Here are the lists for the typical values:
Priority priority_level
-Default :-2
-Broadcast :-1
-Low :6000
-LowPlus :8000
-Normal :10000
-NormalPlus :15000
-FacialIdle :17500
-High :20000
-HighPlus :25000
-CarryRight :30000
-CarryRightPlus :35000
-CarryLeft :40000
-CarryLeftPlus :45000
-Ultra :50000
-UltraPlus :55000
-LookAt :60000
Properties property_list_separated_by_commas
-Default
-UnilateralActor
-PinAllResources
-BlendMotionAccumulation
-HoldAllPoses
Unfortunately, it is not entirely clear at this time how exactly these entries change how the script runs.
Actor is used to declare all of the objects involved in the animations. For an animation involving only a single object (like an alarm clock going off), this will be something like:
Actor "alarmclock"
On the other hand, if the animation involves two sims and a baseball, it would read like this:
Actor "x"
Actor "y"
Actor "baseball"
Every object that has an animation being used needs to be declared here, including props (like screwdrivers) and furniture objects (like beds)
Parameters are variables that will often be set by the code using the Jazz script. Declaring a parameter here not only lets the script know what to look for, but also sets the starting value of that parameter. Some common examples are:
Parameter "ProductVersion" = 0x20 //0x20 is the code for Late Night
Parameter "x:Age" = "adult"
Parameter "IsMirrored" = "no"
Parameters are very useful for complex interactions where different animations need to be played under different circumstances. These can be named anything you want, and you can certainly make up your own, as these are specifically called in the code running the script.
Assign Actor tells the script which animations go with which actor. The animation names here need a bit more explaining however. Say you have created some custom animations using common naming conventions called "a_Simoro_exercise_start_x", "a_Simoro_exercise_loop_x", and "a_Simoro_exercise_stop_x". This is how they would be listed using Assign Actor:
Assign Actor "a_Simoro_exercise_start.ma"."x" as "x"
Assign Actor "a_Simoro_exercise_loop.ma"."x" as "x"
Assign Actor "a_Simoro_exercise_stop.ma"."x" as "x"
But there is more! You could also just enter:
Assign Actor "a_Simoro_exercise_all.ma"."x" as "x"
There does not seem to be a list of available shortcuts, but I have seen other ones in some of the EA scripts. Also, for animations that children and teens can perform also, you will need to create and include the child and teen versions as an Assign Actor as well. The naming conventions for animations are important. Object animations must start with "o_", and sim animations must start with "a_" for adult, "c_" for child, "t_" for teen, "p_" for toddler, "b_" for babies, or "e_" for elder. Animations including multiple actors are a little different, and will start with things like "a2o_" for Adult to Object, "a2a_" for Adult to Adult, "a2c_" for Adult to Child. The child and teen animations need to have the same name as the coorsponding adult animation, with the exception that the name will start with "c_" or "t_" instead of "a_" EA scripts normally don't include regular teen animations, as they automatically convert adult animations for them, however custom animations can't do this, so teen animations will need to be included seperately.
So far a Jazz script would look something like this:
State Machine "Simoro_exercise"
{
Priority High
Property BlendMotionAccumulation
Actor "x"
Parameter "x:AthleticLevel" = 0
Assign Actor "a_Simoro_exercise_all.ma"."x" as "x"
}
Next are the State definitions. These play the animations, and inform the game which animations are next in the line up. A State declaration would look something like:
State "start_exercise"
{
}
The State name can be anything, though it pays to make it something descriptive.
All States can have a list of Properties. Here are the current State Properties available:
-Public
-Entry :The state is an entry state and can be explicitly set as the current state without using transitions
-Exit :The state is an exit state
-Loop :The state runs as a loop where the state machine will continually be coming back to it through transitions
-OneShot
-OneShotHold
-Synchronized
-Join
-Explicit
Under common naming conventions, there is usually a State "Enter", a State "Exit", and possibly a State "Join", which includes the Entry, Exit, and Join Properties, respectively. In many of the EA scripts these three States also have the Explicit Property, though it is not known (at least by me) what the Explicit Property does.
Next are listed the Transitions. These are the States that the script will go to when the current State is complete. If more than one Trasition is listed, it seems to pick one at random, with the exception that it will not go to a State which ultimately ends in a State with the Exit Property, until the code tells the script to go there. This is merely an observation on my part, but so far it has held true. Transitions are declared like:
Transitions to "exercise_loops"
These are always near the top of the State, usually just below the Properties. It is the scripts way of giving the State a heads up to what is coming next. Transitions are not directly calling the next state.
If the animation in question is simple, than the next line will likely be something like:
Play "a_Simoro_exercise_start_x" for "x"
This is the action statement that actually kicks off the animation. In the above example, "a_Simoro_exercise_start_x" is the actual animation name and "x" is the Actor which was assign in the code running the script. If there is a second sim taking part in a social interaction, than the line:
Play "a_Simoro_exercise_start_y" for "y"
Can be added. The same is true for props and other objects. IMPORTANT NOTE: for sim animations, even if the animation is designed only for a child or a teen, you will still use the "a_" or "a2a_" prefix on the animation name. The game will convert it for you.
There are additional options that you can add for a Play statement, and you do so by adding a set of curly brackets to it, such as:
Play "a_Simoro_exercise_loop1_x" for "x"
{
Flags AtEnd, LoopAsNeeded
Blend In 0.2
}
The two items listed above are the most common, but there are also more such as Track Mask, Priority1, and Stop Animation. These are uncommon to see, and to be honest, I am not sure how to use them or what they might do at this time. The Flags are a little better understood (only a little), and are as follows:
AtEnd
LoopAsNeeded :Animation will be repeated until the next animation begins
OverridePriority
Mirror, OverrideMirror
OverrideTiming0, TimingMaster :Both flags have the same value
OverrideTiming1, TimingSlave :Both flags have the same value
TimingIgnored :Shorthand for OverrideTiming0, OverrideTiming1
TimingNormal :Not listed in the wiki. Quite possibly same as TimingIgnored
Interruptible
ForceBlend
UseTimingPriority
UseTimingPriorityAsClockMaster
BaseClipIsSocial
BaseClipIsObjectOnly
AdditiveClipIsObjectOnly
HoldPose
BlendMotionAccumulation
If no Flags are listed, than AtEnd is used by default. Not sure exactly what AtEnd does, but every animation seems to use it. Blend In smooths the transitions between the currently playing animation and the next animation. In practice, if Blend In is removed, the animations seem to speed up and get really jerky. The value always seems to be between 0.0 and 1.0.
If there are multiple animations that could be played in a State, there are two ways to select the one that gets chosen. The first is:
Select Random
{
Flags AvoidRepeats
Weight 1
{
Play "a_Simoro_exercise_loop1_x" for "x"
}
Weight 1
{
Play "a_Simoro_exercise_loop2_x" for "x"
}
Weight 10
{
Play "a_Simoro_exercise_loop3_x" for "x"
}
}
In the above example, one of the three animations would be played randomly. The Weight value determines how likely the option will be chosen. In the above example the third choice would be ten times as likely to be select as the other ones. The line that reads "Flags AvoidRepeats" is optional, and if used a selection will not be repeated until all other options have been chosen. The other process to select an animation is:
Select on Parameter "x:Gender"
{
Value "Male"
{
Play "a_Simoro_exercise_manly_workout_x" for "x"
}
Value "Female"
{
Play "a_Simoro_exercise_girly_workout_x" for "x"
}
}
As stated in the Parameter section, you can name a parameter anything you want, and assign a value to it in the code.
The last commonly seen command is:
Next State "Finish_Workout"
When the game sees this command, it will transition immediately to the named State. If the State has more than one possible Transition, Next State can be used (usually in one of the two Select methods above) to tell the script where to go next. Whichever state you are calling with this command still needs to be listed in the Transition list.
There are a two other more technical commands available that might be useful in more advanced animations. The first is
Actor Operation SetMirror on "x"
{
Actor Operation SetMirror on "baseball"
}
Which will mirror all further animations for the named Actor, in this case "x" and "baseball". It may seem odd to next these commands like in the above example, but that is how the EA scripts do it. This mirroring action will be applied to every animation that the Actor does for the rest of the script, or until it is turned off with:
Actor Operation None on "x"
{
Actor Operation None on "baseball"
}
The other special command is:
Create Prop "OldCrappyBaseball" as "baseball"
{
Play "a2o_Simoro_exercise_juggle_start_x" for "x"
Play "a2o_Simoro_exercise_juggle_start_baseBall" for "baseball"
}
This is used when a prop object is needed, such as screwdrivers, hammers, etc. The Play commands are nested inside the brackets.
If you are ever looking at the EA scripts in the JazzData.package found in the Sims3 install directory, you may notice lines that say something like:
Unknown Value 0 = 0
What do these values mean you ask? Nobody knows. They may be leftover fragments from the original coders which aren't needed, or they may cause the firey death of all your sims if you change it. The fact is, nobody has any idea at this time. For the most part these values are mostly set to 0 and never seem to change, but there are exeptions. If you are modifying an EA script, just leave them be.
I am well aware that there are some blantly large holes in the information presented here. These scripts are not something that many people have fiddled with in depth, and even with trial and error, not all of the various flags and properties can be figured out easily. If you discover something new, let me know and I will research and add it to the tutorial.
Following is a down and dirty primer on Jazz script commands.
State Machine "state_machine_name"
{
Properties property_list_separated_by_commas
-Default
-UnilateralActor
-PinAllResources
-BlendMotionAccumulation
-HoldAllPoses
Priority priority_level
-Default :-2
-Broadcast :-1
-Low :6000
-LowPlus :8000
-Normal :10000
-NormalPlus :15000
-FacialIdle :17500
-High :20000
-HighPlus :25000
-CarryRight :30000
-CarryRightPlus :35000
-CarryLeft :40000
-CarryLeftPlus :45000
-Ultra :50000
-UltraPlus :55000
-LookAt :60000
Unknown Value 0 = 0
Actor "actor_name"
-"x"
-"y"
-"bed"
-"screwdriver"
-etc.
Parameter "parameter_name" = default_parameter_value
-"ProductVersion" = 0x20
-"x:Age" = "adult"
-"IsMirrored" = "no"
-etc.
Assign Actor "animation_group.ma"."actor_name" as "actor_name"
-"a_exercise_all.ma"."x" as "x"
State "state_name"
{
Properties property_list_separated_by_commas :Default = Properties 0
-Public
-Entry :The state is an entry state and can be explicitly set as the current state without using transitions
-Exit :The state is an exit state
-Loop :The state runs as a loop where the state machine will continually be coming back to it through transitions
-OneShot
-OneShotHold
-Synchronized
-Join
-Explicit
Transitions to "state_name"
Select on Parameter "parameter_name"
{
Value parameter_value
{
}
}
Select Random
{
Flags random_flag_list :Default = Flags None
-None :No flags
-AvoidRepeats :Pick options that have not been picked yet
Weight weight_value
{
}
}
Actor Operation operation_type On "actor_name"
-None :Clear all operations
-SetMirror :Mirror animations for this actor
Create Prop "prop_name" as "actor_name"
Play "animation_name" for "actor_name"
{
Track Mask "?"
Flags flag_list_separated_by_commas :Default = Flags AtEnd
-AtEnd
-LoopAsNeeded
-OverridePriority
-Mirror OverrideMirror
-OverrideTiming0, TimingMaster :Both flags have the same value
-OverrideTiming1, TimingSlave :Both flags have the same value
-TimingIgnored :Shorthand for OverrideTiming0, OverrideTiming1
-TimingNormal :Not listed in the wiki. Quite possibly same as TimingIgnored
-Interruptible
-ForceBlend
-UseTimingPriority
-UseTimingPriorityAsClockMaster
-BaseClipIsSocial
-BaseClipIsObjectOnly
-AdditiveClipIsObjectOnly
-HoldPose
-BlendMotionAccumulation
Priority1 priority_level
Blend In float_value :normally between 0.0 and 1.0
Stop Animation
{
Flags flag_list_separated_by_commas :Same as Play Flags
}
}
Next State "state_name"
}
}