Overview

This page documents the format of jazz data in packages. For information on creating/using jazz scripts, see Sims_3:Jazz.

Jazz data is a graph representing a Finite State Machine, which is processed by the SACS engine in The Sims 3 to handle animation events. A glimpse at a visual representation of the jazz data can be seen in The Sims 3 - Behind the Scenes (Hi-Def 720p) video. At 2:08, a Sim is seen performing the actions associated with the "deathreactions" state machine, traversing from the Enter state through the "Shocked" state into the "Evil" state. At 3:44 a toddler Sim is seen playing with a teddy bear as controlled by the "stuffedAnimal" state machine.

Format

Follows the RCOL format, with its own custom chunks. All data is aligned on DWORD boundries. These chunks have a lot of filler data(0xDEADBEEF) which is a "serialization sentinel" according to enum definitions. There are two types of chunks, definition chunks and decision graph node chunks. The definition chunks form a simple structure with data about the state machine. Decision graph nodes form a recursive data structure. References to decision graph node indexes can validly refer to any decision graph node.

Many (all?) of the "hash" values here can be looked up in the _KEY resource for the package.

Definition Chunks

S_SM - State Machine Definition

DWORD 'S_SM'
DWORD Version    // 0x202
DWORD Name       // Hashed state machine name (Typically same as filename w/o path or extension)
DWORD count1     // Actor definitions
REP count1
  DWORD [S_AD index]
DWORD count2     // Property definitions
REP count2
  DWORD [S_PD index]
DWORD count3     // States
REP count3
  DWORD [S_St index]
REP count4
  DWORD filename //Hash of a source filename with extension
  DWORD actor1   //hash of actor name in animations with above extension
  DWORD actor2   //hash of actor name in jazz script
DWORD 0xDEADBEEF
DWORD Properties // State machine properties
DWORD Priority   // Automation priority
DWORD Overlay    // ThoughtBubble, OverlayFace, OverlayHead, OverlayBothArms, OverlayUpperbody, OverlayNone, Unset (0-6, unset is rarely used)
DWORD Empty
DWORD Empty
DWORD Empty
DWORD Empty

S_St - State Definition

DWORD 'S_St'
DWORD version        // 0x101
DWORD Name           // Hashed state name
DWORD Flags          // State Flags
DWORD [S_DG index]   // State decision graph
DWORD count          // State transitions
REP count
  DWORD [S_St index] // Valid transitions out
DWORD Overlay        // Awareness Overlay override: ThoughtBubble, OverlayFace, OverlayHead, OverlayBothArms, OverlayUpperbody, OverlayNone, Unset (0-6)

S_PD - Parameter Definition

DWORD 'S_PD'
DWORD version // 0x100
DWORD hash    // Hashed parameter name
DWORD hash    // Default value

S_AD - Actor Definition

DWORD 'S_AD'
DWORD version // 0x100
DWORD Name    //hashed actor parameter name
DWORD Empty   //null in all JazzData.package cases

S_DG - Decision Graph

DWORD 'S_DG'
DWORD version         // 0x101
DWORD blank           // In all cases in JazzData.package
DWORD count1
REP count1
    DWORD [DGN index] // List of all decision graph nodes descendant from this S_DG
DWORD count2
REP count2
    DWORD [DGN index] // Root of the decision graph
DWORD (DEADBEEF filler)

Decision Graph Node Chunks

SoPn - Select on Parameter Node

DWORD 'SoPn'
DWORD version             // 0x101
DWORD index               // Parameter to select on
DWORD count               // Possible cases to select
REP count
    DWORD Value           //hashed value to compare
    DWORD indexcount
    REP indexcount
        DWORD [DGN index] // Action to take on match
4BYTE filler(DEADBEEF)
DWORD '/DGN'

SNSN - Next State Node

DWORD 'SNSN'
DWORD version             // 0x101
DWORD S_St index          // Next state
DWORD '/DGN' (end entry)

Rand - Random Node

DWORD 'Rand'
DWORD version             // 0x101
DWORD count               // Possible outcomes
REP count
    FLOAT                 // Random weight
    DWORD subcount
    REP subcount
        DWORD [DGN index] // Action on selection
DWORD - DEADBEEF
DWORD flags               // Random node flags
DWORD '/DGN'

Play - Play Animation Node

If the string value below is defined, it a UTF-16 value null terminated, padded to the next DWORD boundry after the null termination. If the string length is 0, there is no data at all for the string, including no null termination.

When the animation name string is set, the CLIP and TkMk resource references are set to 00000000:00000000:6b20c4f302d5df12 and the string is hashed to get the animation ID after parameter substitution. Parameters are the named parameters defined by S_PD, and a substitution inside the string is indicated by enclosing a parameter name between curly braces ("{" and "}").

DWORD 'Play'
DWORD version     // 0x105
I64 T G (CLIP)
I64 T G (TkMk)
DWORD count1
3 DWORDS blank     // Blank in all existing jazzdata.package entries
REP count1
  DWORD Empty      // 0 in all 1 entry this count is non-zero in
  DWORD Empty      // 0 in all 1 entry this count is non-zero in
  DWORD Actor      // Hashed actor parameter name
  DWORD Slot       // Hashed slot name (Only one instance of this in jazzdata.package)
DWORD count2
REP count2
  DWORD actor      // Hashed actor name
  DWORD suffix     // Hashed parameter name for IkSuffix
DWORD filler(DEADBEEF)
I64 T G (CLIP)     // Additive Clip Key (unused in external sacs scripts)
DWORD len          // Length of the following string - a value of 0 indicates no data
WSTRING animation  // Animation name to play.  See above notes on this value.
VAR WCHAR (0) pad  // As needed for string (If len > 0) - see above note on string padding
DWORD len          // Length of the following string - a value of 0 indicates no data
WSTRING additive   // Name of the additive animation to play on top of the main one.  See above notes on this value.
VAR WCHAR (0) pad  // As needed for string (If len > 0) - see above note on string padding
DWORD filler(DEADBEEF)
DWORD Flags        // Animation node flags
DWORD Priority     // Animation Priroity
FLOAT              // Always 0
FLOAT Duration     // Animation blend-in duration, in seconds (Assuming normal speed)
FLOAT              // Animation blend-out duration
FLOAT              // Always 0
FLOAT Speed        // 1.0 = normal speed
DWORD [S_AD Index] // Actor to animate
DWORD Priority     // Animation Priroity
DWORD              // Always 16
5 DWORDS Empty
DWORD filler(DEADBEEF)

MulticastDecisionGraphNode Footer

DWORD count
REP count
  DWORD [DGN Index] // Additional actions (On animation complete?)
DWORD '/DGN'

Prop - Create Prop Node

The catalog resource ID references type 0x139f7591 (CatalogObjectResourceID) which does not exist in any packages. Internally, the type is changed to 0x2dc343f before instantiation

Current speculation is that the blank values may be object create parameters, since the prop is created with no script intervention. However, none of the values are set in existing jazz data. As of the Showtime version of the CSHostWrap.dll that comes with The Create A World Tool, these four blank values are unused and always zero.

DWORD 'Prop' 
DWORD version       // 0x100
DWORD [S_Ad Index]  // Prop actor to create
DWORD [S_Pd Index]  // Prop Parameter
// Catalog reference of prop to create, group is always 0
QWORD instance
DWORD type
DWORD group
4 DWORDS blank // Currently unused

MulticastDecisionGraphNode Footer

DWORD count
REP count
  DWORD [DGN index]
DWORD '/DGN'

AcOp - Actor Operation Node

DWORD 'AcOp'  // Signature
DWORD 0x100   // Version
DWORD Target  // Index of actor to operate on
DWORD 0 or 1  // Actor Operation (0 = None; 1 = SetMirror) Note that it would generally be a moot point for the operation to be zero
DWORD 0 or 1  // Operand to the operation (for a SetMirror operation, this is a boolean variable that sets the Mirror attribute to true or false)
3 DWORDS blank

MulticastDecisionGraphNode Footer

DWORD count
REP count
  DWORD [DGN index]
DWORD '/DGN'

Stop - Stop Animation Node

The fields in a Stop node are structurally identical to the end part of a Play node.

DWORD 'Stop'
DWORD version      // 0x104
DWORD Flags        // Animation node flags
DWORD Priority     // Animation Priroity
FLOAT              // Always 0
FLOAT Duration     // Animation blend-in duration, in seconds (Assuming normal speed)
FLOAT              // Animation blend-out duration
FLOAT              // Always 0
FLOAT Speed        // 1.0 = normal speed
DWORD [S_AD Index] // Actor to animate
DWORD Priority     // Animation Priroity
DWORD              // Always 16
5 DWORDS Empty
DWORD filler(DEADBEEF)

MulticastDecisionGraphNode Footer

DWORD count
REP count
  DWORD [DGN index]
DWORD '/DGN'