====== Scripting with StateAnimator ======

This page describes how [[model|3D model assets]] can be manipulated via Doomsday Script.

===== Introduction =====

The objects involved in 3D model rendering are:

  * **A map object.** Any mobj in the map can be represented by a 3D model.
  * **3D model asset.** An asset definition in the Info file of a package. Specifies the model file path, materials, rendering parameters, animation triggers, and any custom script functions.
  * **StateAnimator.** Each mobj has its own animator instance. This allows many objects to share the same 3D model asset but each still have their unique animation state. When a StateAnimator is created, its initial state is set up as defined in the model asset. 
  * **ModelLoader.** The model loader ensures that the 3D model asset is in memory when it is needed. It also reads the asset definitions and passes on the information to the mobj when it is being initialized.

StateAnimator supports scripting via the following:

  * In the package Info file, one can append a ''script'' block. The script is executed when the package metadata is parsed. For example, in a model asset called "model.thing.misc3", it could look like this:<code>
script {
    record model.thing.misc3 ()
        def onStateChange (animator, state)
            print "State changed:", animator.ID, state
            animator.startTimeline("off")
        end
    end
}</code> This will add a method called ''onStateChange'' into the model asset. The StateAnimator instance calling the method is passed in as the first argument.
  * The package can optionally have a file called ''<nowiki>__init.ds__</nowiki>''. This is assumed to be a Doomsday Script module and will be executed immediately after the package metadata has been parsed. The contents of the file could look like this:<code>record model.thing.misc3 ()
    def onStateChange (animator, state)
        print "State changed:", animator.ID, state
        animator.startTimeline("off")
    end
end</code>
  * The model asset's ''animation'' block can define named [[model#timelines|script timelines]]. These can be started when a model animation sequence starts, or separately using [[#StateAnimator methods]].
  * Any state sequence trigger defined in the model asset can have an embedded [[model#timelines|script timeline]].
===== StateAnimator variables =====

StateAnimator is the central object for model scripting purposes.

The StateAnimator variables automatically available in timeline scripts are:

^ Variable^ Description |
| ''ID''| Text string with the asset identifier (e.g., "model.thing.possessed"). |
| ''<nowiki>__asset__</nowiki>''| Asset metadata, providing read access to the ''animation'' and ''render'' blocks, and any other data specified inside the ''asset'' block. Changing these values has no effect on already initialized objects, because the definitions are only checked when the model is first being prepared for an object. |
| ''<nowiki>__thing__</nowiki>''| Map object being animated (when the asset is a ''model.thing.*''). |
| ''<nowiki>__player__</nowiki>'' | Player whose weapon is being animated (when the asset is ''model.weapon.*''). |
| ''material'' | Material to use when drawing, unless a rendering pass specifies another one. |
| ''notifiedStates'' | Name of the mobj state, or an array of mobj state names, that cause state change notification callbacks to be made to the ''onStateChange'' method. |
| (shader variable)| Shader variables declared in the ''render'' block (e.g., ''uEmission'' above). |
| (pass).(variable)| Shader variables declared in rendering passes (e.g., ''body.uEmission''). |
| (pass).''enabled''| Other pass variables in the pass records (e.g., ''body.enabled''). |
| (pass).''material''| Material to use when drawing a rendering pass (if declared in the definition). |


===== StateAnimator methods =====

Objects of the Render.StateAnimator class have the following methods.

#@Identifier_HTML~playingSequences~@# ( )

#@Identifier_HTML~startSequence~@# (
 #@Arg_HTML~Text,sequence~@#, 
 #@Arg_HTML~Number,priority~@#, 
 #@UArg_HTML~looping~@#, 
 #@Arg_HTML~Text,node~@# = "" )

#@Identifier_HTML~startTimeline~@# ( #@Arg_HTML~Text,name~@# )

#@Identifier_HTML~stopTimeline~@# ( #@Arg_HTML~Text,name~@# )

#@Identifier_HTML~thing~@# ( ) 

Returns a World.Thing representing the mobj that the animator belongs to.

===== Asset callbacks =====

StateAnimator will call methods defined in the model asset when certain events occur.

#@Identifier_HTML~onInit~@# (
 #@Arg_HTML~Render.StateAnimator,animator~@# )

#@Identifier_HTML~onDamage~@# (
 #@Arg_HTML~Render.StateAnimator,animator~@#, 
 #@Arg_HTML~Number,points~@#, 
 #@Arg_HTML~World.Thing,inflictor~@# )

#@Identifier_HTML~onStateChange~@# (
 #@Arg_HTML~Render.StateAnimator,animator~@#, 
 #@Arg_HTML~Text,state~@# ) 

This is only called if the state is in the animator's ''notifiedStates'' variable. For example, in the model definition, one could use:
<code>
notifiedStates <DEADARTI1, DORMANTARTI1>
</code>

===== Examples =====