AddParticleEvent

Introduced

3.0

Description

Adds a Particle Event to a Particle Type or Obstacle extension property.

Note: This command uses output arguments. C# and some scripting languages (such as JScript, PerlScript and Python) don't support arguments passed by reference so you need to use the best workaround for your situation:

For scripting languages this command returns an ISIVTCollection which you can use to get the output arguments.

For C# you can use the XSIApplication.ExecuteCommand method to call this command. ExecuteCommand packs the output arguments into a C# System.Object containing an Array of the output arguments (see Calling Commands from C#).

Scripting Syntax

    AddParticleEvent( Target, Source, [Output] )

Parameters

Parameter | Type | Description
Target [in/out] | ParticleType or Property | Particle Type or Obstacle extension property on which the Particle Event will be added. Default Value: Selected Particle Types or Obstacle extension properties.
Source [in/out] | ParticleType | Particle Type the Particle Event will generate.
Output [out] | XSICollection of particle events (Property objects). | Particle Event generated.

Examples

1. VBScript Example

    '
    ' This example demonstrates how to set up a particle event script with a particle goal
    '

    NewScene , false

    ' Note: Since the CreateParticleCloud command returns the newly created ParticleCloud wrapped in
    ' an XSICollection, we can get a pointer to the new cloud by extracting just the first member
    set myParticleCloud = CreateParticleCloud()(0)

    set myParticleEmitter = ActiveSceneRoot.AddGeometry( "Sphere","MeshSurface", "ParticleEmitter" )
    AddParticleEmitter myParticleCloud, myParticleEmitter
    set myParticleGoal = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface", "ParticleGoal" )
    myParticleGoal.posx = 10.0
    myParticleGoal.posy = 15.0

    ' Note: The AddParticleGoal command uses an input/output type of parameter to specify which
    ' particle cloud object to use. Unfortunately, if you pass the actual ParticleCloud object
    ' for this parameter, the command will convert it to an XSICollection again, so avoid this
    ' by passing in only the name (SIObject.Name property) of the ParticleCloud object
    AddParticleGoal myParticleCloud.Name, myParticleGoal
    set myParticleCloudPrimitive = myParticleCloud.ActivePrimitive
    set oEventColl =  AddParticleEvent( myParticleCloudPrimitive.ParticleTypes(0))(0)

    ' Converting the event collection into a Property
    set oEvent = oEventColl(0)
    oEvent.Parameters("EventAction").value = 6             ' script
    oEvent.EventTrigger.Value =  3                         ' Every NFrame
    oEvent.TriggerValue.Value =  50                        ' Every 50 frames
    oEvent.ScriptContext.Value = 1                         ' Per particle
    oEvent.Script.Value = "for each oAttr in inParticle.Attributes " & vbCrLf & "" & vbTab & _
    "Application.LogMessage ""Reading "" & oAttr.Name" & vbCrLf & "next"

    PlayForwardsFromStart

    ' Expected results:
    'INFO : Reading Goal_0_UVWI
    'INFO : Reading Goal_0_Offset
    'INFO : Reading Goal_0_Weight
    ' ....
    'INFO : Reading Goal_0_UVWI
    'INFO : Reading Goal_0_Offset
    'INFO : Reading Goal_0_Weight

2. JScript Example

    /*
       This example demonstrates how to set up a particle event script with a particle goal
    */

    NewScene( null, false );

    // Note: Since the CreateParticleCloud command returns the newly created ParticleCloud wrapped in
    // an XSICollection, we can get a pointer to the new cloud by extracting just the first member
    var myParticleCloud = CreateParticleCloud()(0);

    var myParticleEmitter = ActiveSceneRoot.AddGeometry( "Sphere","MeshSurface", "ParticleEmitter" );
    AddParticleEmitter( myParticleCloud, myParticleEmitter );
    var myParticleGoal = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface", "ParticleGoal" );
    myParticleGoal.posx = 10.0;
    myParticleGoal.posy = 15.0;

    // Note: The AddParticleGoal command uses an input/output type of parameter to specify which
    // particle cloud object to use. Unfortunately, if you pass the actual ParticleCloud object
    // for this parameter, the command will convert it to an XSICollection again, so avoid this
    // by passing in only the name (SIObject.Name property) of the ParticleCloud object
    AddParticleGoal( myParticleCloud.Name, myParticleGoal );
    var myParticleCloudPrimitive = myParticleCloud.ActivePrimitive;
    var oEventColl =  AddParticleEvent( myParticleCloudPrimitive.ParticleTypes(0))(0);

    // Converting the event collection into a Property
    var oEvent = oEventColl(0);
    oEvent.Parameters("EventAction").Value = 6; // script
    oEvent.EventTrigger.Value =  3; // Every NFrame
    oEvent.TriggerValue.Value =  50; // Every 50 frames
    oEvent.ScriptContext.Value = 1; // Per particle
    oEvent.Script.Value = "for each oAttr in inParticle.Attributes "
       + "\n\tApplication.LogMessage \"Reading \" & oAttr.Name \nnext";

    PlayForwardsFromStart();

    // Expected results:
    //INFO : Reading Goal_0_UVWI
    //INFO : Reading Goal_0_Offset
    //INFO : Reading Goal_0_Weight
    //  ...
    //INFO : Reading Goal_0_UVWI
    //INFO : Reading Goal_0_Offset
    //INFO : Reading Goal_0_Weight

3. Python Example

    #
    # This example demonstrates how to set up a particle event script with a particle goal
    #

    Application.NewScene( "", 0 )

    # Note: Since the CreateParticleCloud command returns the newly created ParticleCloud wrapped in
    # an XSICollection, we can get a pointer to the new cloud by extracting just the first member
    myParticleCloud = Application.CreateParticleCloud()(0)

    myParticleEmitter = Application.ActiveSceneRoot.AddGeometry( "Sphere","MeshSurface", "ParticleEmitter" )
    Application.AddParticleEmitter( myParticleCloud, myParticleEmitter )
    myParticleGoal = Application.ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface", "ParticleGoal" )
    myParticleGoal.posx = 10.0
    myParticleGoal.posy = 15.0

    # Note: The AddParticleGoal command uses an input/output type of parameter to specify which
    # particle cloud object to use. Unfortunately, if you pass the actual ParticleCloud object
    # for this parameter, the command will convert it to an XSICollection again, so avoid this
    # by passing in only the name (SIObject.Name property) of the ParticleCloud object
    Application.AddParticleGoal( myParticleCloud.Name, myParticleGoal )
    myParticleCloudPrimitive = myParticleCloud.ActivePrimitive
    oEventColl =  Application.AddParticleEvent( myParticleCloudPrimitive.ParticleTypes(0))(0)

    # Converting the event collection into a Property
    oEvent = oEventColl(0)
    oEvent.Parameters("EventAction").Value = 6        # script
    oEvent.EventTrigger.Value =  3                    # Every NFrame
    oEvent.TriggerValue.Value =  50                   # Every 50 frames
    oEvent.ScriptContext.Value = 1                    # Per particle
    oEvent.Script.Value = "for each oAttr in inParticle.Attributes \n\tApplication.LogMessage \"Reading \" + oAttr.Name \nnext"

    Application.PlayForwardsFromStart()

    # Expected results:
    #INFO : Reading Goal_0_UVWI
    #INFO : Reading Goal_0_Offset
    #INFO : Reading Goal_0_Weight
    #INFO : Reading Goal_0_UVWI
    #INFO : Reading Goal_0_Offset
    #INFO : Reading Goal_0_Weight

See Also

AddParticleEmitter | AddParticleForce | AddParticleObstacle | ApplyParticleShader
CreateParticleCloud | CreateParticleType | SetParticleType | SIAddParticleEvent
Particle | ParticleCloud | ParticleCloudPrimitive | ParticleType

Autodesk Softimage v7.5