Scripting support

The 3D characters support brings several new scripting methods and attributes. You will find a complete listing in the scripting reference section of this manual, but let's take a quick look into some of the most commonly used methods.

Creation and basics

To load a 3D actor use either Game.LoadActor3D() method or Scene.LoadActor3D() methods. They work exactly the same as their original counterparts (LoadActor()). These methods create a new 3D actor object, which provides a set of methods and attributes fairly similar to those provided by 2D actors. Besides the original TurnTo() method which turns the actor into one of eight directions, 3D actors also provide a TurnToAngle() method, which can be used to turn the character to any angle.


Animations work very differently than in case of 2D actors. Instead of lots of separate files, all the animations are part of the model files and they are then listed in the actor definition file. The PlayAnim() method only accepts the name of the animation to be played. In addition, you can play several animations at one time. Each animation can affect only some of the bones, therefore you can combine several animations into one; for example the actor can walk while making some gesture with their arm (the arm animation only modifies arm bones thus partially overrides the walking animation). Use the PlayAnimChannel() method to achieve this. There are 10 independent animation channels available, numbered from 0 to 9. The 0 channel is used internally by the engine for standard animations, such as walking, talking and standing.

Speaking of which, the engine recognizes these standard animation by their name, which means your actor definition file should contain animations named "walk", "idle" and "talk". You can override those names using the WalkAnimName, IdleAnimName and TalkAnimName attributes. What is this good for? Well, for example if you want to temporarily change walking to running, set the WalkAnimName to "run" and the actor will use the "run" animation for walking (providing animation with this name exists).

It is possible to load new actor animations at runtime. The 3D actor provides a MergeAnims() method, which will load animations from an external X model file. If you need to specify additional animations options (looping animation or animation events), you will need to create a definition file pairing the X model. For example, let's say you want to load an animation called "throw", which is stored in file "trinity_throw.x". To specify animation options, create a new file called "trinity_throw.anim" in the same directory where the X file is located. This definition file will contain one or more ANIMATION sections, using exactly the same syntax as the actor definition file. WME will automatically use the trinity_throw.anim file when loading trinity_throw.x model.

To release animation which is no longer needed from memory, use the UnloadAnim() method.


WME allows you to attach 3D models to 3D actors. This can be used for various purposes, such as the actor holding an item in their hand, a hat on their heads etc. The attachment can be created using the AddAttachment() method, and removed using the RemoveAttachment() method. To query an existing attachment, use the GetAttachment() method. It returns an attachment object, which provides its own set of scripting methods and properties.

Direct control

Among the primary point'n'click interface, WME also provides a set of methods for direct keyboard control for 3D characters. These include DirectWalk(), DirectWalkBack(), DirectWalkStop(), DirectTurnLeft(), DirectTurnRight() and DirectTurnStop(). The WME 3D characters demo already contains a script which demonstrates the use of those methods (scripts\direct_control.script).

There are more methods available, see the scripting reference for details.


You can change model textures at runtime using the SetTexture() method. Since your model can be using several textures you have to specify which one you're changing by specifying material name. Material name defaults to the name of the original texture assigned to your model, without extension. For example, if you assigned texture called "path\some_texture.png" in the 3D modeling software, you reference the material by name "some_texture".

The new texture can be either a static image or WME sprite, which means you can have animated textures. But note that only the images and frame delays are imported from the sprite, all the additional sprite properties used for 2D graphics are ignored when using a sprite as an animated texture for 3D models.

Video textures

You can even use Theora videos as 3D model textures using the SetTheoraTexture() method. The use is exactly the same as the SetTexture() method (see above). Keep in mind the video dimensions must be powers of two (2, 4, 8, 16, 32, 64, 128...). Keep the video textures as small as possible not to degrade game performance needlessly.

Meshes - MS3D format only (deprecated)

You can also modify the appearance of the actors. There is set of methods working with "meshes". A mesh is part of the model; usually the model is separated into multiple meshes based on different materials. You can hide or show individual parts of the model using the HideMesh() and ShowMesh() methods.

You can also load a new mesh from a separate file. This is useful if you want - for example - make the actors hold an item in their hands. A new mesh can be loaded using the AddMesh() method. This method accepts filename of another MS3D file, the name of the mesh and the name of the bone you want this new mesh attach to. This way you can for example attach a hat model to character's head, or insert some object into his hand. The new mesh is "glued" to the given bone and inherits all its movements and rotations.

Last of the methods dealing with individual meshes is RemoveMesh(). It permanently removes one mesh from the model.