User Tools

Site Tools


Scripting with StateAnimator

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


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:
    script {
        record model.thing.misc3 ()
            def onStateChange (animator, state)
                print "State changed:", animator.ID, state

    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 __init.ds__. 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:
    record model.thing.misc3 ()
        def onStateChange (animator, state)
            print "State changed:", animator.ID, state
  • The model asset's animation block can define named 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 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”).
__asset__ 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.
__thing__ Map object being animated (when the asset is a model.thing.*).
__player__ 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.

playingSequences ( )

startSequence ( sequence : Text, priority : Number, looping, node : Text = “” )

startTimeline ( name : Text )

stopTimeline ( name : Text )

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.

onInit ( animator : Render.StateAnimator )

onDamage ( animator : Render.StateAnimator, points : Number, inflictor : World.Thing )

onStateChange ( animator : Render.StateAnimator, state : Text )

This is only called if the state is in the animator's notifiedStates variable. For example, in the model definition, one could use:

notifiedStates <DEADARTI1, DORMANTARTI1>


assets/scripting_with_stateanimator.txt · Last modified: 2019-11-17 19:52 by skyjake