three.js game extension for ratmahatta md2 character

bower install threex.md2character



threex.md2character is a three.js game extension which provides a model of a monster. His name is 'ratmahatta' and is from quake era. It is animated, can hold a weapon, skin may be changed. Pretty sweet. you got 12 weapons to choose from, 5 different skins and 16 distinct animations. Pretty complete! It is easy to include in your game, maybe in a cave or a dungeon :) It is from webgl_morphtargets_md2.html three.js example. The model is make by Brian Collins and converted by @oosmoxiecode's MD2 converter.

Show Don't Tell

A Screenshot


How To Install It

You can install it via script tag

<script src='threex.md2character.js'></script>

Or you can install with bower, as you wish.

bower install threex.md2character

How To Use It


You typically create a ratamahatta like this

var ratamahatta = new THREEx.MD2CharacterRatmahatta()

Don't forget to update it when you render with ratamahatta.update(delta).Internally, it create a character and a controls. You can use them directly.

  • ratamahatta.character instance of THREEx.MD2Character
  • ratamahatta.controls instance of THREEx.MD2CharacterControls

It has simple functions to set the skin, weapon and animations.

  • ratamahatta.skinNames is the names of available skins. It has 5 different skins ["ratamahatta", "ctf_b", "ctf_r", "dead", "gearwhore"]
  • ratamahatta.setSkinName(skinName) set the skin based on its name
  • ratamahatta.weaponsNames is the names of available weapons. It has 12 animation ["none", "weapon", "w_bfg", "w_blaster", "w_chaingun", "w_glauncher", "w_hyperblaster", "w_machinegun", "w_railgun", "w_rlauncher", "w_shotgun", "w_sshotgun"]
  • ratamahatta.setWeaponName(weaponName) set the weapon based on its name
  • ratamahatta.animationNames is the names of available animation. It has 16 animations ["stand", "run", "attack", "pain", "jump", "flip", "salute", "taunt", "wave", "point", "crstand", "crwalk", "crattack", "crpain", "crdeath", "death"]
  • ratamahatta.setAnimationName(animationName) set the animation based on its name


First you create controls for your character like this

var controls    = new THREEx.MD2CharacterControls(character.object3d)

Dont forget to update it when you render with controls.update(delta, now). The character is controlled by controls.inputs properties. You just have to set them to fit your need.

  • control.inputs.right is true if the character must go right
  • control.inputs.left is true if the character must go left
  • control.inputs.up is true if the character must go forward
  • control.inputs.down is true if the character must go backward


It provide the base to play with the model. It is a modified version of MD2Character.js from this webgl_morphtargets_md2.html three.js example.

First you create it.

var character   = new THREEx.MD2Character()

Dont forget to update it at every frame with a character.update(delta)

  • character.object3d is the THREE.Object3D container
  • character.setWireframe(boolean) set the model in wireframe.
  • character.setWeapon(weaponIndex) add a weapon in the character hand. weaponIndex is between 0 and 11. if -1, it removes the weapon.
  • character.setSkin(skinIndex) set the skin of the character. skinIndex is between 0 and 4
  • character.setAnimation(animationName) set the animation for the character. The name is one of ["stand", "run", "attack", "pain", "jump", "flip", "salute", "taunt", "wave", "point", "crstand", "crwalk", "crattack", "crpain", "crdeath", "death"].
  • character.setPlaybackRate(rate) set the playback rate of the animation.
  • character.load(config) loads the characters
    • character.addEventListener('loaded', function(){}) to be notified when the model is loaded
    • character.isLoaded() is true if the model is loaded, false otherwise

Possible improvements

  • make the skin cachable
  • make a demo with LOTS of characters all doing something differents-
    • maybe a simple maze with rock skin
    • what about some localized sound on each
    • some low altitude camera fly
    • many runing in a maze
    • some small angle directional lights to get long shadows casting
  • see if there are other characters in three.js
    • i remember a superman from alteredqueue
    • and a fat ogre
    • find reference on it and put it here
    • make a 'possible enhancement' with those link