Actor definition file, MS3D format (deprecated)

NOTE: 3D actors in MS3D format are now deprecated and provided for backward compatibility only.

Similarly to the ordinary actors, you define 3D actors by creating a simple definition files. These files use the .act3d extension and use the same syntax as other WME files. This is an example of a 3D actor definition file:

ACTOR3D
{
  NAME = "trinity"
  CAPTION = "Trinity"
  INTERACTIVE = TRUE
  SCRIPT = "actors\trinity\trinity.script"

  SCALE = 180

  ;--- velocities
  VELOCITY = 70.0
  ANGULAR_VELOCITY = 400.0

  ;--- external data
  MODEL = "actors\trinity\trinity.ms3d"
  FONT = "fonts\outline_red.font"  
  CURSOR = "sprites\arrow.sprite"

  SHADOW = TRUE
  SIMPLE_SHADOW = TRUE

  ; real-time shadow settings
  LIGHT_POSITION { -40, 200, -40 }
  SHADOW_COLOR { 0, 0, 0, 128 }

  ; simple shadow settings
  SHADOW_SIZE = 12.0
  SHADOW_IMAGE = "actors\trinity\shadow.png"
  



  ANIMATION
  {
    NAME="walk"
    LOOPING=TRUE
    START_FRAME=1
    END_FRAME=25

    EVENT
    {
      FRAME = 4
      NAME = "footstep"
    }

    EVENT
    {
      FRAME = 16
      NAME = "footstep"
    }
  }


  ANIMATION
  {
    MODEL = "actors\trinity\trinity2.ms3d"
    NAME="idle"
    LOOPING=TRUE
    START_FRAME=26
    END_FRAME=65
  }
}

Most of these properties are optional. WME tries to use reasonable default values for them.

The first block defines the usual properties, name, caption, interactivity and script assignment. You should already know these. If not, take a look at the Actors chapter.

The SCALE property affects the overall scale of the character. You will typically use this property if your character model uses different scale than your scene models, but the scaling can also be changed dynamically at runtime to achieve some game effects (shrinking characters, dwarfs etc.). This property also automatically modifies the walking velocity.

Speaking of velocity, it's defined by the following two properties. The VELOCITY property specifies the walking speed, while ANGULAR_VELOCITY specifies how fast the character turns.

Following section defines references to external files, FONT and CURSOR properties are standard ones, MODEL property is new to 3D characters. It should point to a MilkShape file (.ms3d).

The next few properties are dealing with character shadows. WME supports two types of shadows, simple and real-time. Simple shadow is a black "blob" below the character; real-time shadow is calculated at runtime and looks more realistic. You can choose whether to use shadows at all (the SHADOW property) and which type of shadow to use (the SIMPLE_SHADOW property). Note that some older video cards don't support real-time shadows. In that case WME fill automatically fall back to simple shadows regardless this setting.

If you use real-time shadows, you can define the color of the shadow (this is usually unnecessary) and more importantly the position of the light source (LIGHT_POSITION). This position is defined relatively to characters position and defines how long the shadow is and to which direction it's being cast. The property is defined by X, Y and Z coordinates of the light which casts the shadow. See the picture below for an example:



If you use simple shadows, you will need the following two properties. The SHADOW_SIZE property defines the size of that black blob, while using the SHADOW_IMAGE you can change its appearance. If you don't specify the shadow image, WME will use a default one.


The last large section of the file defines all the animations the character provides. This is a big difference compared to 2D characters. Instead of several small animation files all the animations are predefined in the MS3D files and made accessible via this actor definition file. Each animation is defined by an ANIMATION block which contains several nested properties.

The animation properties start with name of the animation (NAME). By using this name you can reference the animations later from game scripts when calling the PlayAnim method. There are few special names for animations, namely "walk", "idle" and "talk". These animations are used by the engine automatically.

The next property is called LOOPING. It specifies whether this animation loops or plays only once.

The START_FRAME and END_FRAME define the actual placement of this particular animation within the MilkShape file. You can have several animations in one file, and using these properties you can tell WME where does each animation start and end.

The second animation block in the example above contains an optional MODEL property. You can have various animations spread into several MilkShape files. In that case you have to specify in which file this particular animation is stored. Please note that only the bone animations are taken from these additional files, not the actual character model. Therefore you should use exactly the same skeleton in all files or you will get unpredictable results.

You can see the first animation block above contains two nested blocks named EVENT. Using these blocks you can trigger a script event whenever a certain frame of animation is played. Experienced WME users already know this from ordinary sprites. The example above specifies that frames 4 and 16 trigger a script event called "footstep". You can use these animation-triggered events in a script for various animation-dependent actions.