BabylonJS-CharacterController

A 3rd person CharacterController for use in BabylonJS (a 3D HTML Webgl framework) applications.
It uses the collider and moveWithCollision() function to move the character around. It uses some of the physics kinematic equations to calculate movements like jump, fall, slide. It does not use any physics engine. It does not react to or apply forces.
For demo see
https://ssatguru.github.io/BabylonJS-CharacterController-Samples/demo/

About

It currently supports

It supports constraining avatar from traversing slopes inclined at certain angles.

It also supports camera “elasticity”. In other words if a mesh comes between the camera and avatar/player, the camera snaps to a position in front of the mesh. This way the avatar/player is always in view.

It can also enter first person view if the camera comes very close to the avatar/player

Breaking change with 0.2.0

Instead of “jump” animation it expects “idleJump” and “runJump” animations.

Version 0.2.0 converts the project from a plain vanilla JavaScript project to a module based JavaScript project.
With this change, the way to load the application has changed.
In JavaScript, instead of

var CharacterControl = org.ssatguru.babylonjs.component.CharacterController;
var characterControl = new CharacterControl(player,camera,scene);

now do

var characterControl = new CharacterController(player,camera,scene);

In TypeScript, instead of

import CharacterController = org.ssatguru.babylonjs.component.CharacterController;

now do

import {CharacterController} from "babaylonjs-charactercontroller";

See below for more details.

Quick start

1) add the following dependencies

<script src="https://cdn.babylonjs.com/babylon.js"></script>
<script src="CharacterController.js"></script>

See INSTALL below to find where you can get “CharacterController.js”.

2) a small javascript code snippet to get you up and running

  //------------------Character Controller -------------------------------------------------
    var cc = new CharacterController(player,camera,scene);
  cc.start();

see “BabylonJS-CharacterController-Samples” https://github.com/ssatguru/BabylonJS-CharacterController-Samples for a few simple samples to help you get going

INSTALL

You can get the “CharacterController.min.js” from its git repository “dist” folder or “releases” section
https://github.com/ssatguru/BabylonJS-CharacterController/tree/master/dist
https://github.com/ssatguru/BabylonJS-CharacterController/releases

You can also install it from npm

npm install babylonjs-charactercontroller 

Usage

This has been built as an UMD module which means you can use it as a CommonJS/NodeJS module, AMD module or as a global object loaded using the script tag.

Project “BabylonJS-CharacterController-Samples” https://github.com/ssatguru/BabylonJS-CharacterController-Samples has a collection of sample projects to show how to use this from TypeScript, NodeJs, AMD or plain vanilla JavaScript applications.

Below is a quick summary of how you can use this as different module types.

TypeScript

// TypeScript
import * as BABYLON from "babylonjs";
import {CharacterController} from "babylonjs-charactercontroller";
...
let engine = new BABYLON.Engine(canvas, true);
...
let cc = new CharacterController(player,camera,scene);

CommonJS/NodeJS Module

let BABYLON = require("babylonjs");
let CharacterController = require("babylonjs-CharacterController").CharacterController;
...
let engine = new BABYLON.Engine(canvas, true);
...
let characterController = new CharacterController(player,camera,scene);
...

AMD Module

<script src="./lib/require.js"></script>
<script>
	require.config({
		baseUrl: ".",
		paths: {
			"babylonjs": "./lib/babylon",
			"ec": "./lib/CharacterController"
		}
	});

	require(['babylonjs', 'cc'], function (BABYLON, cc) {
		let CharacterController = ec.CharacterController;
    ...
		let engine = new BABYLON.Engine(canvas, true);
		...
		let characterController = new CharacterController(player,camera,scene);
		...
	});
</script>

Global Module

<script src="./lib/babylon.js"></script>
<script src="./lib/CharacterController.js"></script>
<script>
  ...
	let engine = new BABYLON.Engine(canvas, true);
	...
	let characterController = new CharacterController(player,camera,scene);
	...
</script>

API

To Instantiate

// JavaScript
var cc = new CharacterController(player,camera,scene);
// TypeScript
import {CharacterController} from "babylonjs-charactercontroller";
let cc = new CharacterController(player,camera,scene);

Takes three parms

The player skeleton is expected to have the following animation ranges

If your animation range is named differently from those mentioned above then use the setWalkAnim(..),setWalkBackAnim(..) etc API to specify your animation range name.

To start/stop controller

cc.start();
cc.stop();

To change animation range name or other parameters

cc.setIdleAnim(rangeName: string,rate: number,loop: boolean);
cc.setIdleJumpAnim(rangeName: string,rate: number,loop: boolean);

cc.setWalkAnim(name :string, playback rate:number,loop:boolean);
cc.setWalkBackAnim(name :string, playback rate:number,loop:boolean);

cc.setRunAnim(name :string, playback rate:number,loop:boolean);
cc.setRunJumpAnim(rangeName: string,rate: number,loop: boolean)

cc.setFallAnim(name :string, playback rate:number,loop:boolean);

cc.setTurnRightAnim(name :string, playback rate:number,loop:boolean);
cc.setTurnLeftAnim(name :string, playback rate:number,loop:boolean);

cc.setStrafeRightAnim(name :string, playback rate:number,loop:boolean);
cc.setStrafeLeftAnim(name :string, playback rate:number,loop:boolean);

cc.setSlideBackAnim(name :string, playback rate:number,loop:boolean);

So lets say your walk animation is called “myWalk” and you want to play it at half speed and loop it continuoulsy then

cc.setWalkAnim("myWalk",0.5,true);

To change key binding

By default the controller uses WASDQE, space and arrow keys to controll your player/avatar.

To change these use

cc.setWalkKey(string:key); or cc.setWalkCode(number:keyCode);
cc.setWalkBackKey(string:key); or cc.setWalkBackCode(number:keyCode);
cc.setTurnLeftKey(string:key); or cc.setTurnLefttCode(number:keyCode);
cc.setTurnRightKey(string:key); or cc.setTurnRightCode(number:keyCode);
cc.setStrafeLeftKey(string:key); or cc.setStrafeLefttCode(number:keyCode);
cc.setStrafeRightKey(string:key); or cc.setStrafeRightCode(number:keyCode);
cc.setJumpKey(string:key); or cc.setJumpCode(number:keyCode);

You can specify both key or a keycode.

To change gravity or speed at which avatar/player is moved

Speed is specified in meters/second

setGravity(n: number);    //default 9.8 m/s^2  
setWalkSpeed(n: number);  //default 3 m/s
setRunSpeed(n: number);   //default 6 m/s
setBackSpeed(n: number);  //default 3 m/s
setJumpSpeed(n: number);  //default 6 m/s
setLeftSpeed(n: number);  //default 3 m/s
setRightSpeed(n: number); //default 3 m/s

To change the slope the avatar can traverse

setSlopeLimit(minSlopeLimit: number,maxSlopeLimit: number); //the slope is specified in degrees

Example

setSlopeLimit(45,55); 

Here if the avatar is on a slope with angle between 45 and 55 degrees then it will start sliding back when it stops moving.
If the slope is 55 or more then avatar will not be able to move up on it.

To change the height of steps the avatar can climb

setStepOffset(stepOffset: number); 

Example

setStepOffset(0.5); 

The avatar can only move up a step if the height of the step is less than or equal to the “stepOffset”.
By default the value is 0.25.

To change avatar or skeleton at

setAvatar(avatar: Mesh);
setAvatarSkeleton(skeleton: Skeleton);

To change camera behavior

By default the camera focuses on the avatar/player origin. To focus on a different position on the avatar/player use

setCameraTarget(v: Vector3);

Lets say your avatar origin is at its feet but instead of focusing on its feet you would like camera to focus on its head then, assuming the the head is 1.5m above ground, you would do

cc.setCameraTarget(new BABAYLON.Vector3(0,1.5,0);

By default the camera behaves “elastically”. In other words if something comes between the camera and avatar the camera snaps to a position in front of that something. This way the avatar/player is always in view. To turn this off use

setCameraElasticity(false);

You can use the arc rotate camera’s “lowerRadiusLimit” and “upperRadiusLimit” property to controll how close or how far away from the avatar the camera can get.
Example setting

camera.lowerRadiusLimit=2;
camera.upperRadiusLimit=20;

will restrict the camera between 2 and 20m from the avatar/player.
When the camera comes to the “lowerRadiusLimit” the controller switches to first person view. In other words it makes the avatar/player invisible and the camera collision is disabled. Pulling camera back restores the third person view. To prevent this use

setNoFirstPerson(true);

Build

If not already installed, install node js.
Switch to the project folder.
Run “npm install”, once, to install all the dependencies.
To build anytime
Run “npm build” - this will both compile, minify and store the build in “dist” folder. Use the “index.html” in “tst” folder to test your changes.