direct.actor.Actor

from direct.actor.Actor import Actor

Actor module: contains the Actor class.

See the Loading Actors and Animations page in the Programming Guide to learn more about loading animated models.

Inheritance diagram

Inheritance diagram of direct.actor.Actor

class Actor(models=None, anims=None, other=None, copy=True, lodNode=None, flattenable=True, setFinal=False, mergeLODBundles=None, allowAsyncBind=None, okMissing=None)[source]

Bases: DirectObject, NodePath

Actor class: Contains methods for creating, manipulating and playing animations on characters

class AnimDef(filename=None, animBundle=None)[source]

Bases: object

Instances of this class are stored within the AnimControlDict to track all of the animations associated with the Actor. This includes animations that have already been bound (these have a valid AnimControl) as well as those that have not yet been bound (for these, self.animControl is None).

There is a different AnimDef for each different part or sub-part, times each different animation in the AnimDict.

__init__(self, filename=None, animBundle=None)[source]
makeCopy(self)[source]
class PartDef(partBundleNP, partBundleHandle, partModel)[source]

Bases: object

Instances of this class are stored within the PartBundleDict to track all of the individual PartBundles associated with the Actor. In general, each separately loaded model file is a different PartBundle. This can include the multiple different LOD’s, as well as the multiple different pieces of a multipart Actor.

__init__(self, partBundleNP, partBundleHandle, partModel)[source]
getBundle(self)[source]
class SubpartDef(truePartName, subset=PartSubset, empty)[source]

Bases: object

Instances of this class are stored within the SubpartDict to track the existance of arbitrary sub-parts. These are designed to appear to the user to be identical to true “part” of a multi-part Actor, but in fact each subpart represents a subset of the joints of an existing part (which is accessible via a different name).

__init__(self, truePartName, subset=PartSubset, empty)[source]
makeCopy(self)[source]
__init__(self, models=None, anims=None, other=None, copy=True, lodNode=None, flattenable=True, setFinal=False, mergeLODBundles=None, allowAsyncBind=None, okMissing=None)[source]

Actor constructor: can be used to create single or multipart actors. If another Actor is supplied as an argument this method acts like a copy constructor. Single part actors are created by calling with a model and animation dictionary (animName:animPath{}) as follows:

a = Actor("panda-3k.egg", {"walk":"panda-walk.egg",
                           "run":"panda-run.egg"})

This could be displayed and animated as such:

a.reparentTo(render)
a.loop("walk")
a.stop()

Multipart actors expect a dictionary of parts and a dictionary of animation dictionaries (partName:(animName:animPath{}){}) as below:

a = Actor(

    # part dictionary
    {"head": "char/dogMM/dogMM_Shorts-head-mod",
     "torso": "char/dogMM/dogMM_Shorts-torso-mod",
     "legs": "char/dogMM/dogMM_Shorts-legs-mod"},

    # dictionary of anim dictionaries
    {"head":{"walk": "char/dogMM/dogMM_Shorts-head-walk",
             "run": "char/dogMM/dogMM_Shorts-head-run"},
     "torso":{"walk": "char/dogMM/dogMM_Shorts-torso-walk",
              "run": "char/dogMM/dogMM_Shorts-torso-run"},
     "legs":{"walk": "char/dogMM/dogMM_Shorts-legs-walk",
             "run": "char/dogMM/dogMM_Shorts-legs-run"}
     })

In addition multipart actor parts need to be connected together in a meaningful fashion:

a.attach("head", "torso", "joint-head")
a.attach("torso", "legs", "joint-hips")

# # ADD LOD COMMENT HERE! #

Other useful Actor class functions:

#fix actor eye rendering
a.drawInFront("joint-pupil?", "eyes*")

#fix bounding volumes - this must be done after drawing
#the actor for a few frames, otherwise it has no effect
a.fixBounds()
actorInterval(self, *args, **kw)[source]
addLOD(self, string)[source]

Add a named node under the LODNode to parent all geometry of a specific LOD under.

allowAsyncBind = 1
animLoaderOptions = LoaderOptions(LF_search | LF_report_errors | LF_convert_anim, TF_preload)
animPanel(self)[source]
Actor.attach(self, string, string, string, key="lodRoot")[source]

Attach one actor part to another at a joint called jointName

bindAllAnims(self, allowAsyncBind=False)[source]

Loads and binds all animations that have been defined for the Actor.

bindAnim(self, animName, partName=None, lodName=None, allowAsyncBind=False)[source]

Binds the named animation to the named part and/or lod. If allowAsyncBind is False, this guarantees that the animation is bound immediately–the animation is never bound in a sub-thread; it will be loaded and bound in the main thread, so it will be available by the time this method returns.

The parameters are the same as that for getAnimControls(). In fact, this method is a thin wrapper around that other method.

Use this method if you need to ensure that an animation is available before you start to play it, and you don’t mind holding up the render for a frame or two until the animation is available.

cleanup(self)[source]

This method should be called when intending to destroy the Actor, and cleans up any additional resources stored on the Actor class before removing the underlying node using removeNode().

Note that removeNode() itself is not sufficient to destroy actors, which is why this method exists.

clearLODAnimation(self)[source]

Description: Undoes the effect of a recent call to set_lod_animation(). Henceforth, the character will animate every frame, regardless of its distance from the camera.

clearPythonData(self)[source]
controlJoint(self, node, partName, jointName, lodName='lodRoot')[source]

The converse of exposeJoint: this associates the joint with the indicated node, so that the joint transform will be copied from the node to the joint each frame. This can be used for programmer animation of a particular joint at runtime.

The parameter node should be the NodePath for the node whose transform will animate the joint. If node is None, a new node will automatically be created and loaded with the joint’s initial transform. In either case, the node used will be returned.

It used to be necessary to call this before any animations have been loaded and bound, but that is no longer so.

copyActor(self, other, overwrite=False)[source]
delete(self)[source]
disableBlend(self, partName=None)[source]

Restores normal one-animation-at-a-time operation after a previous call to enableBlend().

This method is deprecated. You should use setBlend() instead.

Actor.drawInFront(self, string, int, string=None, key=None)[source]

Arrange geometry so the frontPart(s) are drawn in front of backPart.

If mode == -1, the geometry is simply arranged to be drawn in the correct order, assuming it is already under a direct-render scene graph (like the DirectGui system). That is, frontPart is reparented to backPart, and backPart is reordered to appear first among its siblings.

If mode == -2, the geometry is arranged to be drawn in the correct order, and depth test/write is turned off for frontPart.

If mode == -3, frontPart is drawn as a decal onto backPart. This assumes that frontPart is mostly coplanar with and does not extend beyond backPart, and that backPart is mostly flat (not self-occluding).

If mode > 0, the frontPart geometry is placed in the ‘fixed’ bin, with the indicated drawing order. This will cause it to be drawn after almost all other geometry. In this case, the backPartName is actually unused.

Takes an optional argument root as the start of the search for the given parts. Also takes optional lod name to refine search for the named parts. If root and lod are defined, we search for the given root under the given lod.

enableBlend(self, blendType=1, partName=None)[source]

Enables blending of multiple animations simultaneously. After this is called, you may call play(), loop(), or pose() on multiple animations and have all of them contribute to the final pose each frame.

With blending in effect, starting a particular animation with play(), loop(), or pose() does not implicitly make the animation visible; you must also call setControlEffect() for each animation you wish to use to indicate how much each animation contributes to the final pose.

This method is deprecated. You should use setBlend() instead.

Actor.exposeJoint(self, NodePath, string, string, key="lodRoot")[source]

Starts the joint animating the indicated node. As the joint animates, it will transform the node by the corresponding amount. This will replace whatever matrix is on the node each frame. The default is to expose the net transform from the root, but if localTransform is true, only the node’s local transform from its parent is exposed.

faceAwayFromViewer(self)[source]
faceTowardsViewer(self)[source]
fixBounds(self, partName=None)[source]
fixBounds_old(self, part=None)[source]

fixBounds(self, nodePath=None) Force recomputation of bounding spheres for all geoms in a given part. If no part specified, fix all geoms in this actor

flush(self)[source]

Actor flush function. Used by cleanup().

freezeJoint(self, partName, jointName, transform=None, pos=LVector3f(0, 0, 0), hpr=LVector3f(0, 0, 0), scale=LVector3f(1, 1, 1))[source]

Similar to controlJoint, but the transform assigned is static, and may not be animated at runtime (without another subsequent call to freezeJoint). This is slightly more optimal than controlJoint() for cases in which the transform is not intended to be animated during the lifetime of the Actor.

getActorInfo(self)[source]

Utility function to create a list of information about an actor. Useful for iterating over details of an actor.

getAnimBlends(self, animName=None, partName=None, lodName=None)[source]

Returns a list of the form:

[ (lodName, [(animName, [(partName, effect), (partName, effect), ...]),
             (animName, [(partName, effect), (partName, effect), ...]),
             ...]),
  (lodName, [(animName, [(partName, effect), (partName, effect), ...]),
             (animName, [(partName, effect), (partName, effect), ...]),
             ...]),
   ... ]

This list reports the non-zero control effects for each partName within a particular animation and LOD.

Actor.getAnimControl(self, string, string, string="lodRoot")[source]

Search the animControl dictionary indicated by lodName for a given anim and part. If none specified, try the first part and lod. Return the animControl if present, or None otherwise.

getAnimControlDict(self)[source]
Actor.getAnimControls(self, string, string=None, string=None)[source]

Returns a list of the AnimControls that represent the given animation for the given part and the given lod.

If animName is None or omitted, the currently-playing animation (or all currently-playing animations) is returned. If animName is True, all animations are returned. If animName is a single string name, that particular animation is returned. If animName is a list of string names, all of the names animations are returned.

If partName is None or omitted, all parts are returned (or possibly the one overall Actor part, according to the subpartsComplete flag).

If lodName is None or omitted, all LOD’s are returned.

getAnimFilename(self, animName)[source]

return the animFilename given the animName

getAnimNames(self)[source]
Actor.getBaseFrameRate(self, string, string=None)[source]

Return frame rate of given anim name and given part, unmodified by any play rate in effect.

getCurrentAnim(self, partName=None)[source]

Return the anim currently playing on the actor. If part not specified return current anim of an arbitrary part in dictionary. NOTE: only returns info for an arbitrary LOD

getCurrentFrame(self, animName=None, partName=None)[source]

Return the current frame number of the named anim, or if no anim is specified, then the anim current playing on the actor. If part not specified return current anim of first part in dictionary. NOTE: only returns info for an arbitrary LOD

getDuration(self, animName=None, partName=None, fromFrame=None, toFrame=None)[source]

Return duration of given anim name and given part. If no anim specified, use the currently playing anim. If no part specified, return anim duration of first part. NOTE: returns info for arbitrary LOD

Actor.getFrameRate(self, string, string=None)[source]

Return actual frame rate of given anim name and given part. If no anim specified, use the currently playing anim. If no part specified, return anim durations of first part. NOTE: returns info only for an arbitrary LOD

getFrameTime(self, anim, frame, partName=None)[source]
getGeomNode(self)[source]

Return the node that contains all actor geometry

getJointTransform(self, partName, jointName, lodName='lodRoot')[source]
getJointTransformState(self, partName, jointName, lodName='lodRoot')[source]
getJoints(self, partName=None, jointName='*', lodName=None)[source]

Returns the list of all joints, from the named part or from all parts, that match the indicated jointName. The jointName may include pattern characters like *.

getLOD(self, string)[source]

Get the named node under the LOD to which we parent all LOD specific geometry to. Returns ‘None’ if not found

getLODIndex(self)[source]

safe method (but expensive) for retrieving the child index

getLODNames(self)[source]

Return list of Actor LOD names. If not an LOD actor, returns ‘lodRoot’ Caution - this returns a reference to the list - not your own copy

getLODNode(self)[source]

Return the node that switches actor geometry in and out

getNumFrames(self, animName=None, partName=None)[source]
getOverlappingJoints(self, partNameA, partNameB, jointName='*', lodName=None)[source]

Returns the set of joints, matching jointName, that are shared between partNameA and partNameB.

getPart(self, partName, lodName='lodRoot')[source]

Find the named part in the optional named lod and return it, or return None if not present

getPartBundle(self, partName, lodName='lodRoot')[source]

Find the named part in the optional named lod and return its associated PartBundle, or return None if not present

getPartBundleDict(self)[source]
getPartBundles(self, partName=None)[source]

Returns a list of PartBundle objects for the entire Actor, or for the indicated part only.

getPartNames(self)[source]

Return list of Actor part names. If not an multipart actor, returns ‘modelRoot’ NOTE: returns parts of arbitrary LOD

getPlayRate(self, animName=None, partName=None)[source]

Return the play rate of given anim for a given part. If no part is given, assume first part in dictionary. If no anim is given, find the current anim for the part. NOTE: Returns info only for an arbitrary LOD

getSubpartsComplete(self)[source]

See setSubpartsComplete().

hasLOD(self)[source]

Return 1 if the actor has LODs, 0 otherwise

hideAllBounds(self)[source]

Hide the bounds of all actor geoms

hidePart(self, partName, lodName='lodRoot')[source]

Make the given part of the optionally given lod not render, even though still in the tree. NOTE: this will affect child geometry

initAnimsOnAllLODs(self, partNames)[source]
Actor.instance(self, NodePath, string, string, key="lodRoot")[source]

Instance a nodePath to an actor part at a joint called jointName

listJoints(self, partName='modelRoot', lodName='lodRoot')[source]

Handy utility function to list the joint hierarchy of the actor.

loadAnims(self, anims, partName='modelRoot', lodName='lodRoot')[source]

loadAnims(self, string:string{}, string=’modelRoot’, string=’lodRoot’) Actor anim loader. Takes an optional partName (defaults to ‘modelRoot’ for non-multipart actors) and lodName (defaults to ‘lodRoot’ for non-LOD actors) and dict of corresponding anims in the form animName:animPath{}

loadAnimsOnAllLODs(self, anims, partName='modelRoot')[source]

loadAnims(self, string:string{}, string=’modelRoot’, string=’lodRoot’) Actor anim loader. Takes an optional partName (defaults to ‘modelRoot’ for non-multipart actors) and lodName (defaults to ‘lodRoot’ for non-LOD actors) and dict of corresponding anims in the form animName:animPath{}

loadModel(self, modelPath, partName='modelRoot', lodName='lodRoot', copy=True, okMissing=None, autoBindAnims=True)[source]

Actor model loader. Takes a model name (ie file path), a part name(defaults to “modelRoot”) and an lod name(defaults to “lodRoot”).

Actor.loop(self, string, int=1, string=None)[source]

Loop the given animation on the given part of the actor, restarting at zero frame if requested. If no part name is given then try to loop on all parts. NOTE: loops on all LOD’s

makeSubpart(self, partName, includeJoints, excludeJoints=[], parent='modelRoot', overlapping=False)[source]

Defines a new “part” of the Actor that corresponds to the same geometry as the named parent part, but animates only a certain subset of the joints. This can be used for partial-body animations, for instance to animate a hand waving while the rest of the body continues to play its walking animation.

includeJoints is a list of joint names that are to be animated by the subpart. Each name can include globbing characters like ‘?’ or ‘*’, which will match one or any number of characters, respectively. Including a joint by naming it in includeJoints implicitly includes all of the descendents of that joint as well, except for excludeJoints, below.

excludeJoints is a list of joint names that are not to be animated by the subpart. As in includeJoints, each name can include globbing characters. If a joint is named by excludeJoints, it will not be included (and neither will any of its descendents), even if a parent joint was named by includeJoints.

if overlapping is False, an error is raised (in the dev build) if this subpart shares joints with any other subparts. If overlapping is True, no such error is raised.

parent is the actual partName that this subpart is based on.

mergeLODBundles = 1
modelLoaderOptions = LoaderOptions(LF_search | LF_report_errors | LF_convert_skeleton, TF_preload)
notify = <direct.directnotify.Notifier.Notifier object>
osdAnimBlends(self, animName=None, partName=None, lodName=None)[source]
partPrefix = '__Actor_'
Actor.pingpong(self, string, int=1, string=None)[source]

Loop the given animation on the given part of the actor, restarting at zero frame if requested. If no part name is given then try to loop on all parts. NOTE: loops on all LOD’s

Actor.play(self, string, string=None)[source]

Play the given animation on the given part of the actor. If no part is specified, try to play on all parts. NOTE: plays over ALL LODs

Actor.pose(self, string, int, string=None)[source]

Pose the actor in position found at given frame in the specified animation for the specified part. If no part is specified attempt to apply pose to all parts.

postFlatten(self)[source]

Call this after performing an aggressive flatten operation, such as flattenStrong(), that involves the Actor. This is especially necessary when mergeLODBundles is true, since this kind of actor may be broken after a flatten operation; this method should restore proper Actor functionality.

pprint(self)[source]

Pretty print actor’s details

printAnimBlends(self, animName=None, partName=None, lodName=None)[source]
printLOD(self)[source]
releaseJoint(self, partName, jointName)[source]

Undoes a previous call to controlJoint() or freezeJoint() and restores the named joint to its normal animation.

removeAnimControlDict(self)[source]
removeNode(self)[source]

You should call cleanup() for Actor objects instead, since removeNode() is not sufficient for completely destroying Actor objects.

removePart(self, partName, lodName='lodRoot')[source]

Remove the geometry and animations of the named part of the optional named lod if present. NOTE: this will remove child geometry also!

renamePartBundles(self, partName, newBundleName)[source]
resetLOD(self)[source]

Restore all switch distance info (usually after a useLOD call)

setBlend(self, animBlend=None, frameBlend=None, blendType=None, partName=None)[source]

Changes the way the Actor handles blending of multiple different animations, and/or interpolation between consecutive frames.

The animBlend and frameBlend parameters are boolean flags. You may set either or both to True or False. If you do not specify them, they do not change from the previous value.

When animBlend is True, multiple different animations may simultaneously be playing on the Actor. This means you may call play(), loop(), or pose() on multiple animations and have all of them contribute to the final pose each frame.

In this mode (that is, when animBlend is True), starting a particular animation with play(), loop(), or pose() does not implicitly make the animation visible; you must also call setControlEffect() for each animation you wish to use to indicate how much each animation contributes to the final pose.

The frameBlend flag is unrelated to playing multiple animations. It controls whether the Actor smoothly interpolates between consecutive frames of its animation (when the flag is True) or holds each frame until the next one is ready (when the flag is False). The default value of frameBlend is controlled by the interpolate-frames Config.prc variable.

In either case, you may also specify blendType, which controls the precise algorithm used to blend two or more different matrix values into a final result. Different skeleton hierarchies may benefit from different algorithms. The default blendType is controlled by the anim-blend-type Config.prc variable.

setCenter(self, center)[source]
setControlEffect(self, animName, effect, partName=None, lodName=None)[source]

Sets the amount by which the named animation contributes to the overall pose. This controls blending of multiple animations; it only makes sense to call this after a previous call to setBlend(animBlend = True).

setGeomNode(self, node)[source]

Set the node that contains all actor geometry

setLOD(self, string)[source]

Set the switch distance for given LOD

setLODAnimation(self, farDistance, nearDistance, delayFactor)[source]

Activates a special mode in which the Actor animates less frequently as it gets further from the camera. This is intended as a simple optimization to minimize the effort of computing animation for lots of characters that may not necessarily be very important to animate every frame.

If the character is closer to the camera than near_distance, then it is animated its normal rate, every frame. If the character is exactly far_distance away, it is animated only every delay_factor seconds (which should be a number greater than 0). If the character is between near_distance and far_distance, its animation rate is linearly interpolated according to its distance between the two. The interpolation function continues beyond far_distance, so that the character is animated increasingly less frequently as it gets farther away.

setLODNode(self, node=None)[source]

Set the node that switches actor geometry in and out. If one is not supplied as an argument, make one

Actor.setPlayRate(self, float, string, string=None)[source]

Set the play rate of given anim for a given part. If no part is given, set for all parts in dictionary.

It used to be legal to let the animName default to the currently-playing anim, but this was confusing and could lead to the wrong anim’s play rate getting set. Better to insist on this parameter. NOTE: sets play rate on all LODs

setSubpartsComplete(self, flag)[source]

Sets the subpartsComplete flag. This affects the behavior of play(), loop(), stop(), etc., when no explicit parts are specified.

When this flag is False (the default), play() with no parts means to play the animation on the overall Actor, which is a separate part that overlaps each of the subparts. If you then play a different animation on a subpart, it may stop the overall animation (in non-blend mode) or blend with it (in blend mode).

When this flag is True, play() with no parts means to play the animation on each of the subparts–instead of on the overall Actor. In this case, you may then play a different animation on a subpart, which replaces only that subpart’s animation.

It makes sense to set this True when the union of all of your subparts completely defines the entire Actor.

showAllBounds(self)[source]

Show the bounds of all actor geoms

showAllParts(self, partName, lodName='lodRoot')[source]

Make the given part and all its children render while in the tree. NOTE: this will affect child geometry

showPart(self, partName, lodName='lodRoot')[source]

Make the given part render while in the tree. NOTE: this will affect child geometry

Actor.stop(self, string=None, string=None)[source]

Stop named animation on the given part of the actor. If no name specified then stop all animations on the actor. NOTE: stops all LODs

Actor.stopJoint(self, string, string, key="lodRoot")[source]

Stops the joint from animating external nodes. If the joint is animating a transform on a node, this will permanently stop it. However, this does not affect vertex animations.

unloadAnims(self, anims=None, partName=None, lodName=None)[source]

unloadAnims(self, string:string{}, string=’modelRoot’, string=’lodRoot’) Actor anim unloader. Takes an optional partName (defaults to ‘modelRoot’ for non-multipart actors) and lodName (defaults to ‘lodRoot’ for non-LOD actors) and list of animation names. Deletes the anim control for the given animation and parts/lods.

If any parameter is None or omitted, it means all of them.

update(self, lod=0, partName=None, lodName=None, force=False)[source]

Updates all of the Actor’s joints in the indicated LOD. The LOD may be specified by name, or by number, where 0 is the highest level of detail, 1 is the next highest, and so on.

If force is True, this will update every joint, even if we don’t believe it’s necessary.

Returns True if any joint has changed as a result of this, False otherwise.

useLOD(self, lodName)[source]

Make the Actor ONLY display the given LOD

validateSubparts = 1
verifySubpartsComplete(self, partName=None, lodName=None)[source]

Ensures that each joint is defined by at least one subPart. Prints a warning if this is not the case.

waitPending(self, partName=None)[source]

Blocks until all asynchronously pending animations (that are currently playing) have been loaded and bound the the Actor. Call this after calling play() if you are using asynchronous binds, but you need this particular animation to be loaded immediately.