\n
Many people want to write games using three.js. This article\nwill hopefully give you some ideas on how to start.
\n
At least at the time I'm writing this article it's probably going to be the\nlongest article on this site. It's possible the code here is massively over\nengineered but as I wrote each new feature I'd run into a problem that needed a\nsolution I'm used to from other games I've written. In other words each new\nsolution seemed important so I'll try to show why. Of course the smaller your\ngame the less you might need some of the solutions shown here but this is a\npretty small game and yet with the complexities of 3D characters many things\ntake more organization than they might with 2D characters.
\n
As an example if you're making PacMan in 2D, when PacMan turns a corner\nthat happens instantly at 90 degrees. There is no in-between step. But\nin a 3D game often we need the character to rotate over several frames.\nThat simple change can add a bunch of complexity and require different\nsolutions.
\n
The majority of the code here will not really be three.js and\nthat's important to note, three.js is not a game engine.\nThree.js is a 3D library. It provides a scene graph\nand features for displaying 3D objects added to that scene graph\nbut it does not provide all the other things needed to make a game.\nNo collisions, no physics, no input systems, no path finding, etc, etc...\nSo, we'll have to provide those things ourselves.
\n
I ended up writing quite a bit of code to make this simple unfinished\ngame like thing and again, it's certainly possible I over engineered and there\nare simpler solutions but I feel like I actually didn't write\nenough code and hopefully I can explain what I think is missing.
\n
Many of the ideas here are heavily influenced by Unity.\nIf you're not familiar with Unity that probably does not matter.\nI only bring it up as 10s of 1000s of games have shipped using\nthese ideas.
\n
Let's start with the three.js parts. We need to load models for our game.
\n
At opengameart.org I found this animated knight\nmodel by quaternius
\n
\n\n
quaternius also made these animated animals.
\n
\n\n
These seem like good models to start with so the first thing we need to\ndo is load them.
\n
We covered loading glTF files before.\nThe difference this time is we need to load multiple models and\nwe can't start the game until all the models are loaded.
\n
Fortunately three.js provides the LoadingManager just for this purpose.\nWe create a LoadingManager and pass it to the other loaders. The\nLoadingManager provides both onProgress and\nonLoad properties we can attach callbacks to.\nThe onLoad callback will be called when\nall files have been loaded. The onProgress callback\nas called after each individual file arrives to give as a chance to show\nloading progress.
\n
Starting with the code from loading a glTF file I removed all\nthe code related to framing the scene and added this code to load all models.
\n
const manager = new THREE.LoadingManager();\nmanager.onLoad = init;\nconst models = {\n pig: { url: 'resources/models/animals/Pig.gltf' },\n cow: { url: 'resources/models/animals/Cow.gltf' },\n llama: { url: 'resources/models/animals/Llama.gltf' },\n pug: { url: 'resources/models/animals/Pug.gltf' },\n sheep: { url: 'resources/models/animals/Sheep.gltf' },\n zebra: { url: 'resources/models/animals/Zebra.gltf' },\n horse: { url: 'resources/models/animals/Horse.gltf' },\n knight: { url: 'resources/models/knight/KnightCharacter.gltf' },\n};\n{\n const gltfLoader = new GLTFLoader(manager);\n for (const model of Object.values(models)) {\n gltfLoader.load(model.url, (gltf) => {\n model.gltf = gltf;\n });\n }\n}\n\nfunction init() {\n // TBD\n}\n\n
This code will load all the models above and the LoadingManager will call\ninit when done. We'll use the models object later to let us access the\nloaded models so the GLTFLoader callback for each individual model attaches\nthe loaded data to that model's info.
\n
All the models with all their animation are currently about 6.6meg. That's a\npretty big download. Assuming your server supports compression (the server this\nsite runs on does) it's able to compress them to around 1.4meg. That's\ndefinitely better than 6.6meg bit it's still not a tiny amount of data. It would\nprobably be good if we added a progress bar so the user has some idea how much\nlonger they have to wait.
\n
So, let's add an onProgress callback. It will be\ncalled with 3 arguments, the url of the last loaded object and then the number\nof items loaded so far as well as the total number of items.
\n
Let's setup some HTML for a loading bar
\n
<body>\n <canvas id=\"c\"></canvas>\n+ <div id=\"loading\">\n+ <div>\n+ <div>...loading...</div>\n+ <div class=\"progress\"><div id=\"progressbar\"></div></div>\n+ </div>\n+ </div>\n</body>\n
\n
We'll look up the #progressbar div and we can set the width from 0% to 100%\nto show our progress. All we need to do is set that in our callback.
\n
const manager = new THREE.LoadingManager();\nmanager.onLoad = init;\n\n+const progressbarElem = document.querySelector('#progressbar');\n+manager.onProgress = (url, itemsLoaded, itemsTotal) => {\n+ progressbarElem.style.width = ${itemsLoaded / itemsTotal * 100 | 0}%;\n+};\n\n
We already setup init to be called when all the models are loaded so\nwe can turn off the progress bar by hiding the #loading element.
\n
function init() {\n+ // hide the loading bar\n+ const loadingElem = document.querySelector('#loading');\n+ loadingElem.style.display = 'none';\n}\n\n
Here's a bunch of CSS for styling the bar. The CSS makes the #loading <div>\nthe full size of the page and centers its children. The CSS makes a .progress\narea to contain the progress bar. The CSS also gives the progress bar\na CSS animation of diagonal stripes.
\n
#loading {\n position: absolute;\n left: 0;\n top: 0;\n width: 100%;\n height: 100%;\n display: flex;\n align-items: center;\n justify-content: center;\n text-align: center;\n font-size: xx-large;\n font-family: sans-serif;\n}\n#loading>div>div {\n padding: 2px;\n}\n.progress {\n width: 50vw;\n border: 1px solid black;\n}\n#progressbar {\n width: 0;\n transition: width ease-out .5s;\n height: 1em;\n background-color: #888;\n background-image: linear-gradient(\n -45deg,\n rgba(255, 255, 255, .5) 25%,\n transparent 25%,\n transparent 50%,\n rgba(255, 255, 255, .5) 50%,\n rgba(255, 255, 255, .5) 75%,\n transparent 75%,\n transparent\n );\n background-size: 50px 50px;\n animation: progressanim 2s linear infinite;\n}\n\n@keyframes progressanim {\n 0% {\n background-position: 50px 50px;\n }\n 100% {\n background-position: 0 0;\n }\n}\n\n
Now that we have a progress bar let's deal with the models. These models\nhave animations and we want to be able to access those animations.\nAnimations are stored in an array by default be we'd like to be able to\neasily access them by name so let's setup an animations property for\neach model to do that. Note of course this means animations must have unique names.
\n
+function prepModelsAndAnimations() {\n+ Object.values(models).forEach(model => {\n+ const animsByName = {};\n+ model.gltf.animations.forEach((clip) => {\n+ animsByName[clip.name] = clip;\n+ });\n+ model.animations = animsByName;\n+ });\n+}\n\nfunction init() {\n // hide the loading bar\n const loadingElem = document.querySelector('#loading');\n loadingElem.style.display = 'none';\n\n+ prepModelsAndAnimations();\n}\n\n
Let's display the animated models.
\n
Unlike the previous example of loading a glTF file\nThis time we probably want to be able to display more than one instance\nof each model. To do this, instead of adding\nthe loaded gltf scene directly like we did in the article on loading a glTF,\nwe instead want to clone the scene and in particular we want to clone\nit for skinned animated characters. Fortunately there's a utility function,\nSkeletonUtils.clone we can use to do this. So, first we need to include\nthe utils.
\n
import * as THREE from 'three';\nimport {OrbitControls} from 'three/addons/controls/OrbitControls.js';\nimport {GLTFLoader} from 'three/addons/loaders/GLTFLoader.js';\n+import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';\n\n
Then we can clone the models we just loaded
\n
function init() {\n // hide the loading bar\n const loadingElem = document.querySelector('#loading');\n loadingElem.style.display = 'none';\n\n prepModelsAndAnimations();\n\n+ Object.values(models).forEach((model, ndx) => {\n+ const clonedScene = SkeletonUtils.clone(model.gltf.scene);\n+ const root = new THREE.Object3D();\n+ root.add(clonedScene);\n+ scene.add(root);\n+ root.position.x = (ndx - 3) * 3;\n+ });\n}\n\n
Above, for each model, we clone the gltf.scene we loaded and we parent that\nto a new Object3D. We need to parent it to another object because when\nwe play animations the animation will apply animated positions to the nodes\nin the loaded scene which means we won't have control over those positions.
\n
To play the animations each model we clone needs an AnimationMixer.\nAn AnimationMixer contains 1 or more AnimationActions. An\nAnimationAction references an AnimationClip. AnimationActions\nhave all kinds of settings for playing then chaining to another\naction or cross fading between actions. Let's just get the first\nAnimationClip and create an action for it. The default is for\nan action to play its clip in a loop forever.
\n
+const mixers = [];\n\nfunction init() {\n // hide the loading bar\n const loadingElem = document.querySelector('#loading');\n loadingElem.style.display = 'none';\n\n prepModelsAndAnimations();\n\n Object.values(models).forEach((model, ndx) => {\n const clonedScene = SkeletonUtils.clone(model.gltf.scene);\n const root = new THREE.Object3D();\n root.add(clonedScene);\n scene.add(root);\n root.position.x = (ndx - 3) * 3;\n\n+ const mixer = new THREE.AnimationMixer(clonedScene);\n+ const firstClip = Object.values(model.animations)[0];\n+ const action = mixer.clipAction(firstClip);\n+ action.play();\n+ mixers.push(mixer);\n });\n}\n\n
We called play to start the action and stored\noff all the AnimationMixers in an array called mixers. Finally\nwe need to update each AnimationMixer in our render loop by computing\nthe time since the last frame and passing that to AnimationMixer.update.
\n
+let then = 0;\nfunction render(now) {\n+ now *= 0.001; // convert to seconds\n+ const deltaTime = now - then;\n+ then = now;\n\n if (resizeRendererToDisplaySize(renderer)) {\n const canvas = renderer.domElement;\n camera.aspect = canvas.clientWidth / canvas.clientHeight;\n camera.updateProjectionMatrix();\n }\n\n+ for (const mixer of mixers) {\n+ mixer.update(deltaTime);\n+ }\n\n renderer.render(scene, camera);\n\n requestAnimationFrame(render);\n}\n\n
And with that we should get each model loaded and playing its first animation.
\n
\n\n
\n
Let's make it so we can check all of the animations.\nWe'll add all of the clips as actions and then enable just one at\na time.
\n
-const mixers = [];\n+const mixerInfos = [];\n\nfunction init() {\n // hide the loading bar\n const loadingElem = document.querySelector('#loading');\n loadingElem.style.display = 'none';\n\n prepModelsAndAnimations();\n\n Object.values(models).forEach((model, ndx) => {\n const clonedScene = SkeletonUtils.clone(model.gltf.scene);\n const root = new THREE.Object3D();\n root.add(clonedScene);\n scene.add(root);\n root.position.x = (ndx - 3) * 3;\n\n const mixer = new THREE.AnimationMixer(clonedScene);\n- const firstClip = Object.values(model.animations)[0];\n- const action = mixer.clipAction(firstClip);\n- action.play();\n- mixers.push(mixer);\n+ const actions = Object.values(model.animations).map((clip) => {\n+ return mixer.clipAction(clip);\n+ });\n+ const mixerInfo = {\n+ mixer,\n+ actions,\n+ actionNdx: -1,\n+ };\n+ mixerInfos.push(mixerInfo);\n+ playNextAction(mixerInfo);\n });\n}\n\n+function playNextAction(mixerInfo) {\n+ const {actions, actionNdx} = mixerInfo;\n+ const nextActionNdx = (actionNdx + 1) % actions.length;\n+ mixerInfo.actionNdx = nextActionNdx;\n+ actions.forEach((action, ndx) => {\n+ const enabled = ndx === nextActionNdx;\n+ action.enabled = enabled;\n+ if (enabled) {\n+ action.play();\n+ }\n+ });\n+}\n\n
The code above makes an array of AnimationActions,\none for each AnimationClip. It makes an array of objects, mixerInfos,\nwith references to the AnimationMixer and all the AnimationActions\nfor each model. It then calls playNextAction which sets enabled on\nall but one action for that mixer.
\n
We need to update the render loop for the new array
\n
-for (const mixer of mixers) {\n+for (const {mixer} of mixerInfos) {\n mixer.update(deltaTime);\n}\n\n
Let's make it so pressing a key 1 to 8 will play the next animation\nfor each model
\n
window.addEventListener('keydown', (e) => {\n const mixerInfo = mixerInfos[e.keyCode - 49];\n if (!mixerInfo) {\n return;\n }\n playNextAction(mixerInfo);\n});\n\n
Now you should be able to click on the example and then press keys 1 through 8\nto cycle each of the models through their available animations.
\n
\n\n
\n
So that is arguably the sum-total of the three.js portion of this\narticle. We covered loading multiple files, cloning skinned models,\nand playing animations on them. In a real game you'd have to do a\nton more manipulation of AnimationAction objects.
\n
Let's start making a game infrastructure
\n
A common pattern for making a modern game is to use an\nEntity Component System.\nIn an Entity Component System an object in a game is called an entity that consists\nof a bunch of components. You build up entities by deciding which components to\nattach to them. So, let's make an Entity Component System.
\n
We'll call our entities GameObject. It's effectively just a collection\nof components and a three.js Object3D.
\n
function removeArrayElement(array, element) {\n const ndx = array.indexOf(element);\n if (ndx >= 0) {\n array.splice(ndx, 1);\n }\n}\n\nclass GameObject {\n constructor(parent, name) {\n this.name = name;\n this.components = [];\n this.transform = new THREE.Object3D();\n parent.add(this.transform);\n }\n addComponent(ComponentType, ...args) {\n const component = new ComponentType(this, ...args);\n this.components.push(component);\n return component;\n }\n removeComponent(component) {\n removeArrayElement(this.components, component);\n }\n getComponent(ComponentType) {\n return this.components.find(c => c instanceof ComponentType);\n }\n update() {\n for (const component of this.components) {\n component.update();\n }\n }\n}\n\n
Calling GameObject.update calls update on all the components.
\n
I included a name only to help in debugging so if I look at a GameObject\nin the debugger I can see a name to help identify it.
\n
Some things that might seem a little strange:
\n
GameObject.addComponent is used to create components. Whether or not\nthis a good idea or a bad idea I'm not sure. My thinking was it makes\nno sense for a component to exist outside of a gameobject so I thought\nit might be good if creating a component automatically added that component\nto the gameobject and passed the gameobject to the component's constructor.\nIn other words to add a component you do this
\n
const gameObject = new GameObject(scene, 'foo');\ngameObject.addComponent(TypeOfComponent);\n
\n
If I didn't do it this way you'd instead do something like this
\n
const gameObject = new GameObject(scene, 'foo');\nconst component = new TypeOfComponent(gameObject);\ngameObject.addComponent(component);\n
\n
Is it better that the first way is shorter and more automated or is it worse\nbecause it looks out of the ordinary? I don't know.
\n
GameObject.getComponent looks up components by type. That has\nthe implication that you can not have 2 components of the same\ntype on a single game object or at least if you do you can only\nlook up the first one without adding some other API.
\n
It's common for one component to look up another and when looking them up they\nhave to match by type otherwise you might get the wrong one. We could instead\ngive each component a name and you could look them up by name. That would be\nmore flexible in that you could have more than one component of the same type but it\nwould also be more tedious. Again, I'm not sure which is better.
\n
On to the components themselves. Here is their base class.
\n
// Base for all components\nclass Component {\n constructor(gameObject) {\n this.gameObject = gameObject;\n }\n update() {\n }\n}\n\n
Do components need a base class? JavaScript is not like most strictly\ntyped languages so effectively we could have no base class and just\nleave it up to each component to do whatever it wants in its constructor\nknowing that the first argument is always the component's gameobject.\nIf it doesn't care about gameobject it wouldn't store it. I kind of feel like this\ncommon base is good though. It means if you have a reference to a\ncomponent you know you can find its parent gameobject always and from its\nparent you can easily look up other components as well as look at its\ntransform.
\n
To manage the gameobjects we probably need some kind of gameobject manager. You\nmight think we could just keep an array of gameobjects but in a real game the\ncomponents of a gameobject might add and remove other gameobjects at runtime.\nFor example a gun gameobject might add a bullet gameobject every time the gun\nfires. A monster gameobject might remove itself if it has been killed. We then\nwould have an issue that we might have code like this
\n
for (const gameObject of globalArrayOfGameObjects) {\n gameObject.update();\n}\n\n
The loop above would fail or do un-expected things if\ngameobjects are added or removed from globalArrayOfGameObjects\nin the middle of the loop in some component's update function.
\n
To try to prevent that problem we need something a little safer.\nHere's one attempt.
\n
class SafeArray {\n constructor() {\n this.array = [];\n this.addQueue = [];\n this.removeQueue = new Set();\n }\n get isEmpty() {\n return this.addQueue.length + this.array.length > 0;\n }\n add(element) {\n this.addQueue.push(element);\n }\n remove(element) {\n this.removeQueue.add(element);\n }\n forEach(fn) {\n this._addQueued();\n this._removeQueued();\n for (const element of this.array) {\n if (this.removeQueue.has(element)) {\n continue;\n }\n fn(element);\n }\n this._removeQueued();\n }\n _addQueued() {\n if (this.addQueue.length) {\n this.array.splice(this.array.length, 0, ...this.addQueue);\n this.addQueue = [];\n }\n }\n _removeQueued() {\n if (this.removeQueue.size) {\n this.array = this.array.filter(element => !this.removeQueue.has(element));\n this.removeQueue.clear();\n }\n }\n}\n\n
The class above lets you add or remove elements from the SafeArray\nbut won't mess with the array itself while it's being iterated over. Instead\nnew elements get added to addQueue and removed elements to the removeQueue\nand then added or removed outside of the loop.
\n
Using that here is our class to manage gameobjects.
\n
class GameObjectManager {\n constructor() {\n this.gameObjects = new SafeArray();\n }\n createGameObject(parent, name) {\n const gameObject = new GameObject(parent, name);\n this.gameObjects.add(gameObject);\n return gameObject;\n }\n removeGameObject(gameObject) {\n this.gameObjects.remove(gameObject);\n }\n update() {\n this.gameObjects.forEach(gameObject => gameObject.update());\n }\n}\n\n
With all that now let's make our first component. This component\nwill just manage a skinned three.js object like the ones we just created.\nTo keep it simple it will just have one method, setAnimation that\ntakes the name of the animation to play and plays it.
\n
class SkinInstance extends Component {\n constructor(gameObject, model) {\n super(gameObject);\n this.model = model;\n this.animRoot = SkeletonUtils.clone(this.model.gltf.scene);\n this.mixer = new THREE.AnimationMixer(this.animRoot);\n gameObject.transform.add(this.animRoot);\n this.actions = {};\n }\n setAnimation(animName) {\n const clip = this.model.animations[animName];\n // turn off all current actions\n for (const action of Object.values(this.actions)) {\n action.enabled = false;\n }\n // get or create existing action for clip\n const action = this.mixer.clipAction(clip);\n action.enabled = true;\n action.reset();\n action.play();\n this.actions[animName] = action;\n }\n update() {\n this.mixer.update(globals.deltaTime);\n }\n}\n\n
You can see it's basically the code we had before that clones the scene we loaded,\nthen sets up an AnimationMixer. setAnimation adds a AnimationAction for a\nparticular AnimationClip if one does not already exist and disables all\nexisting actions.
\n
The code references globals.deltaTime. Let's make a globals object
\n
const globals = {\n time: 0,\n deltaTime: 0,\n};\n\n
And update it in the render loop
\n
let then = 0;\nfunction render(now) {\n // convert to seconds\n globals.time = now * 0.001;\n // make sure delta time isn't too big.\n globals.deltaTime = Math.min(globals.time - then, 1 / 20);\n then = globals.time;\n\n
The check above for making sure deltaTime is not more than 1/20th\nof a second is because otherwise we'd get a huge value for deltaTime\nif we hide the tab. We might hide it for seconds or minutes and then\nwhen our tab was brought to the front deltaTime would be huge\nand might teleport characters across our game world if we had code like
\n
position += velocity * deltaTime;\n
\n
By limiting the maximum deltaTime that issue is prevented.
\n
Now let's make a component for the player.
\n
class Player extends Component {\n constructor(gameObject) {\n super(gameObject);\n const model = models.knight;\n this.skinInstance = gameObject.addComponent(SkinInstance, model);\n this.skinInstance.setAnimation('Run');\n }\n}\n\n
The player calls setAnimation with 'Run'. To know which animations\nare available I modified our previous example to print out the names of\nthe animations
\n
function prepModelsAndAnimations() {\n Object.values(models).forEach(model => {\n+ console.log('------->:', model.url);\n const animsByName = {};\n model.gltf.animations.forEach((clip) => {\n animsByName[clip.name] = clip;\n+ console.log(' ', clip.name);\n });\n model.animations = animsByName;\n });\n}\n\n
And running it got this list in the JavaScript console.
\n
------->: resources/models/animals/Pig.gltf\n Idle\n Death\n WalkSlow\n Jump\n Walk\n ------->: resources/models/animals/Cow.gltf\n Walk\n Jump\n WalkSlow\n Death\n Idle\n ------->: resources/models/animals/Llama.gltf\n Jump\n Idle\n Walk\n Death\n WalkSlow\n ------->: resources/models/animals/Pug.gltf\n Jump\n Walk\n Idle\n WalkSlow\n Death\n ------->: resources/models/animals/Sheep.gltf\n WalkSlow\n Death\n Jump\n Walk\n Idle\n ------->: resources/models/animals/Zebra.gltf\n Jump\n Walk\n Death\n WalkSlow\n Idle\n ------->: resources/models/animals/Horse.gltf\n Jump\n WalkSlow\n Death\n Walk\n Idle\n ------->: resources/models/knight/KnightCharacter.gltf\n Run_swordRight\n Run\n Idle_swordLeft\n Roll_sword\n Idle\n Run_swordAttack\n
Fortunately the names of the animations for all the animals match\nwhich will come in handy later. For now we only care the that the\nplayer has an animation called Run.
\n
Let's use these components. Here's the updated init function.\nAll it does is create a GameObject and add a Player component to it.
\n
const globals = {\n time: 0,\n deltaTime: 0,\n};\n+const gameObjectManager = new GameObjectManager();\n\nfunction init() {\n // hide the loading bar\n const loadingElem = document.querySelector('#loading');\n loadingElem.style.display = 'none';\n\n prepModelsAndAnimations();\n\n+ {\n+ const gameObject = gameObjectManager.createGameObject(scene, 'player');\n+ gameObject.addComponent(Player);\n+ }\n}\n\n
And we need to call gameObjectManager.update in our render loop
\n
let then = 0;\nfunction render(now) {\n // convert to seconds\n globals.time = now * 0.001;\n // make sure delta time isn't too big.\n globals.deltaTime = Math.min(globals.time - then, 1 / 20);\n then = globals.time;\n\n if (resizeRendererToDisplaySize(renderer)) {\n const canvas = renderer.domElement;\n camera.aspect = canvas.clientWidth / canvas.clientHeight;\n camera.updateProjectionMatrix();\n }\n\n- for (const {mixer} of mixerInfos) {\n- mixer.update(deltaTime);\n- }\n+ gameObjectManager.update();\n\n renderer.render(scene, camera);\n\n requestAnimationFrame(render);\n}\n\n
and if we run that we get a single player.
\n
\n\n
\n
That was a lot of code just for an entity component system but\nit's infrastructure that most games need.
\n
Let's add an input system. Rather than read keys directly we'll\nmake a class that other parts of the code can check left or right.\nThat way we can assign multiple ways to input left or right etc..\nWe'll start with just keys
\n
// Keeps the state of keys/buttons\n//\n// You can check\n//\n// inputManager.keys.left.down\n//\n// to see if the left key is currently held down\n// and you can check\n//\n// inputManager.keys.left.justPressed\n//\n// To see if the left key was pressed this frame\n//\n// Keys are 'left', 'right', 'a', 'b', 'up', 'down'\nclass InputManager {\n constructor() {\n this.keys = {};\n const keyMap = new Map();\n\n const setKey = (keyName, pressed) => {\n const keyState = this.keys[keyName];\n keyState.justPressed = pressed && !keyState.down;\n keyState.down = pressed;\n };\n\n const addKey = (keyCode, name) => {\n this.keys[name] = { down: false, justPressed: false };\n keyMap.set(keyCode, name);\n };\n\n const setKeyFromKeyCode = (keyCode, pressed) => {\n const keyName = keyMap.get(keyCode);\n if (!keyName) {\n return;\n }\n setKey(keyName, pressed);\n };\n\n addKey(37, 'left');\n addKey(39, 'right');\n addKey(38, 'up');\n addKey(40, 'down');\n addKey(90, 'a');\n addKey(88, 'b');\n\n window.addEventListener('keydown', (e) => {\n setKeyFromKeyCode(e.keyCode, true);\n });\n window.addEventListener('keyup', (e) => {\n setKeyFromKeyCode(e.keyCode, false);\n });\n }\n update() {\n for (const keyState of Object.values(this.keys)) {\n if (keyState.justPressed) {\n keyState.justPressed = false;\n }\n }\n }\n}\n\n
The code above tracks whether keys are up or down and you can check\nif a key is currently pressed by checking for example\ninputManager.keys.left.down. It also has a justPressed property\nfor each key so that you can check the user just pressed the key.\nFor example a jump key you don't want to know if the button is being\nheld down, you want to know did the user press it now.
\n
Let's create an instance of InputManager
\n
const globals = {\n time: 0,\n deltaTime: 0,\n};\nconst gameObjectManager = new GameObjectManager();\n+const inputManager = new InputManager();\n\n
and update it in our render loop
\n
function render(now) {\n\n ...\n\n gameObjectManager.update();\n+ inputManager.update();\n\n ...\n}\n\n
It needs to be called after gameObjectManager.update otherwise\njustPressed would never be true inside a component's update function.
\n
Let's use it in the Player component
\n
+const kForward = new THREE.Vector3(0, 0, 1);\nconst globals = {\n time: 0,\n deltaTime: 0,\n+ moveSpeed: 16,\n};\n\nclass Player extends Component {\n constructor(gameObject) {\n super(gameObject);\n const model = models.knight;\n this.skinInstance = gameObject.addComponent(SkinInstance, model);\n this.skinInstance.setAnimation('Run');\n+ this.turnSpeed = globals.moveSpeed / 4;\n }\n+ update() {\n+ const {deltaTime, moveSpeed} = globals;\n+ const {transform} = this.gameObject;\n+ const delta = (inputManager.keys.left.down ? 1 : 0) +\n+ (inputManager.keys.right.down ? -1 : 0);\n+ transform.rotation.y += this.turnSpeed * delta * deltaTime;\n+ transform.translateOnAxis(kForward, moveSpeed * deltaTime);\n+ }\n}\n\n
The code above uses Object3D.transformOnAxis to move the player\nforward. Object3D.transformOnAxis works in local space so it only\nworks if the object in question is at the root of the scene, not if it's\nparented to something else
\n
We also added a global moveSpeed and based a turnSpeed on the move speed.\nThe turn speed is based on the move speed to try to make sure a character\ncan turn sharply enough to meet its target. If turnSpeed so too small\na character will turn around and around circling its target but never\nhitting it. I didn't bother to do the math to calculate the required\nturn speed for a given move speed. I just guessed.
\n
The code so far would work but if the player runs off the screen there's no\nway to find out where they are. Let's make it so if they are offscreen\nfor more than a certain time they get teleported back to the origin.\nWe can do that by using the three.js Frustum class to check if a point\nis inside the camera's view frustum.
\n
We need to build a frustum from the camera. We could do this in the Player\ncomponent but other objects might want to use this too so let's add another\ngameobject with a component to manage a frustum.
\n
class CameraInfo extends Component {\n constructor(gameObject) {\n super(gameObject);\n this.projScreenMatrix = new THREE.Matrix4();\n this.frustum = new THREE.Frustum();\n }\n update() {\n const {camera} = globals;\n this.projScreenMatrix.multiplyMatrices(\n camera.projectionMatrix,\n camera.matrixWorldInverse);\n this.frustum.setFromProjectionMatrix(this.projScreenMatrix);\n }\n}\n\n
Then let's setup another gameobject at init time.
\n
function init() {\n // hide the loading bar\n const loadingElem = document.querySelector('#loading');\n loadingElem.style.display = 'none';\n\n prepModelsAndAnimations();\n\n+ {\n+ const gameObject = gameObjectManager.createGameObject(camera, 'camera');\n+ globals.cameraInfo = gameObject.addComponent(CameraInfo);\n+ }\n\n {\n const gameObject = gameObjectManager.createGameObject(scene, 'player');\n gameObject.addComponent(Player);\n }\n}\n\n
and now we can use it in the Player component.
\n
class Player extends Component {\n constructor(gameObject) {\n super(gameObject);\n const model = models.knight;\n this.skinInstance = gameObject.addComponent(SkinInstance, model);\n this.skinInstance.setAnimation('Run');\n this.turnSpeed = globals.moveSpeed / 4;\n+ this.offscreenTimer = 0;\n+ this.maxTimeOffScreen = 3;\n }\n update() {\n- const {deltaTime, moveSpeed} = globals;\n+ const {deltaTime, moveSpeed, cameraInfo} = globals;\n const {transform} = this.gameObject;\n const delta = (inputManager.keys.left.down ? 1 : 0) +\n (inputManager.keys.right.down ? -1 : 0);\n transform.rotation.y += this.turnSpeed * delta * deltaTime;\n transform.translateOnAxis(kForward, moveSpeed * deltaTime);\n\n+ const {frustum} = cameraInfo;\n+ if (frustum.containsPoint(transform.position)) {\n+ this.offscreenTimer = 0;\n+ } else {\n+ this.offscreenTimer += deltaTime;\n+ if (this.offscreenTimer >= this.maxTimeOffScreen) {\n+ transform.position.set(0, 0, 0);\n+ }\n+ }\n }\n}\n\n
One more thing before we try it out, let's add touchscreen support\nfor mobile. First let's add some HTML to touch
\n
<body>\n <canvas id=\"c\"></canvas>\n+ <div id=\"ui\">\n+ <div id=\"left\"><img src=\"../resources/images/left.svg\"></div>\n+ <div style=\"flex: 0 0 40px;\"></div>\n+ <div id=\"right\"><img src=\"../resources/images/right.svg\"></div>\n+ </div>\n <div id=\"loading\">\n <div>\n <div>...loading...</div>\n <div class=\"progress\"><div id=\"progressbar\"></div></div>\n </div>\n </div>\n</body>\n
\n
and some CSS to style it
\n
#ui {\n position: absolute;\n left: 0;\n top: 0;\n width: 100%;\n height: 100%;\n display: flex;\n justify-items: center;\n align-content: stretch;\n}\n#ui>div {\n display: flex;\n align-items: flex-end;\n flex: 1 1 auto;\n}\n.bright {\n filter: brightness(2);\n}\n#left {\n justify-content: flex-end;\n}\n#right {\n justify-content: flex-start;\n}\n#ui img {\n padding: 10px;\n width: 80px;\n height: 80px;\n display: block;\n}\n\n
The idea here is there is one div, #ui, that\ncovers the entire page. Inside will be 2 divs, #left and #right\nboth of which are almost half the page wide and the entire screen tall.\nIn between there is a 40px separator. If the user slides their finger\nover the left or right side then we need up update keys.left and keys.right\nin the InputManager. This makes the entire screen sensitive to being touched\nwhich seemed better than just small arrows.
\n
class InputManager {\n constructor() {\n this.keys = {};\n const keyMap = new Map();\n\n const setKey = (keyName, pressed) => {\n const keyState = this.keys[keyName];\n keyState.justPressed = pressed && !keyState.down;\n keyState.down = pressed;\n };\n\n const addKey = (keyCode, name) => {\n this.keys[name] = { down: false, justPressed: false };\n keyMap.set(keyCode, name);\n };\n\n const setKeyFromKeyCode = (keyCode, pressed) => {\n const keyName = keyMap.get(keyCode);\n if (!keyName) {\n return;\n }\n setKey(keyName, pressed);\n };\n\n addKey(37, 'left');\n addKey(39, 'right');\n addKey(38, 'up');\n addKey(40, 'down');\n addKey(90, 'a');\n addKey(88, 'b');\n\n window.addEventListener('keydown', (e) => {\n setKeyFromKeyCode(e.keyCode, true);\n });\n window.addEventListener('keyup', (e) => {\n setKeyFromKeyCode(e.keyCode, false);\n });\n\n+ const sides = [\n+ { elem: document.querySelector('#left'), key: 'left' },\n+ { elem: document.querySelector('#right'), key: 'right' },\n+ ];\n+\n+ const clearKeys = () => {\n+ for (const {key} of sides) {\n+ setKey(key, false);\n+ }\n+ };\n+\n+ const handleMouseMove = (e) => {\n+ e.preventDefault();\n+ // this is needed because we call preventDefault();\n+ // we also gave the canvas a tabindex so it can\n+ // become the focus\n+ canvas.focus();\n+ window.addEventListener('pointermove', handleMouseMove);\n+ window.addEventListener('pointerup', handleMouseUp);\n+\n+ for (const {elem, key} of sides) {\n+ let pressed = false;\n+ const rect = elem.getBoundingClientRect();\n+ const x = e.clientX;\n+ const y = e.clientY;\n+ const inRect = x >= rect.left && x < rect.right &&\n+ y >= rect.top && y < rect.bottom;\n+ if (inRect) {\n+ pressed = true;\n+ }\n+ setKey(key, pressed);\n+ }\n+ };\n+\n+ function handleMouseUp() {\n+ clearKeys();\n+ window.removeEventListener('pointermove', handleMouseMove, {passive: false});\n+ window.removeEventListener('pointerup', handleMouseUp);\n+ }\n+\n+ const uiElem = document.querySelector('#ui');\n+ uiElem.addEventListener('pointerdown', handleMouseMove, {passive: false});\n+\n+ uiElem.addEventListener('touchstart', (e) => {\n+ // prevent scrolling\n+ e.preventDefault();\n+ }, {passive: false});\n }\n update() {\n for (const keyState of Object.values(this.keys)) {\n if (keyState.justPressed) {\n keyState.justPressed = false;\n }\n }\n }\n}\n\n
And now we should be able to control the character with the left and right\ncursor keys or with our fingers on a touchscreen
\n
\n\n
\n
Ideally we'd do something else if the player went off the screen like move\nthe camera or maybe offscreen = death but this article is already going to be\ntoo long so for now teleporting to the middle was the simplest thing.
\n
Lets add some animals. We can start it off similar to the Player by making\nan Animal component.
\n
class Animal extends Component {\n constructor(gameObject, model) {\n super(gameObject);\n const skinInstance = gameObject.addComponent(SkinInstance, model);\n skinInstance.mixer.timeScale = globals.moveSpeed / 4;\n skinInstance.setAnimation('Idle');\n }\n}\n\n
The code above sets the AnimationMixer.timeScale to set the playback\nspeed of the animations relative to the move speed. This way if we\nadjust the move speed the animation will speed up or slow down as well.
\n
To start we could setup one of each type of animal
\n
function init() {\n // hide the loading bar\n const loadingElem = document.querySelector('#loading');\n loadingElem.style.display = 'none';\n\n prepModelsAndAnimations();\n {\n const gameObject = gameObjectManager.createGameObject(camera, 'camera');\n globals.cameraInfo = gameObject.addComponent(CameraInfo);\n }\n\n {\n const gameObject = gameObjectManager.createGameObject(scene, 'player');\n globals.player = gameObject.addComponent(Player);\n globals.congaLine = [gameObject];\n }\n\n+ const animalModelNames = [\n+ 'pig',\n+ 'cow',\n+ 'llama',\n+ 'pug',\n+ 'sheep',\n+ 'zebra',\n+ 'horse',\n+ ];\n+ animalModelNames.forEach((name, ndx) => {\n+ const gameObject = gameObjectManager.createGameObject(scene, name);\n+ gameObject.addComponent(Animal, models[name]);\n+ gameObject.transform.position.x = (ndx + 1) * 5;\n+ });\n}\n\n
And that would get us animals standing on the screen but we want them to do\nsomething.
\n
Let's make them follow the player in a conga line but only if the player gets near enough.\nTo do this we need several states.
\n
\nIdle:
\nAnimal is waiting for player to get close
\nWait for End of Line:
\nAnimal was tagged by player but now needs to wait for the animal\nat the end of the line to come by so they can join the end of the line.
\nGo to Last:
\nAnimal needs to walk to where the animal they are following was, at the same time recording\na history of where the animal they are following is currently.
\nFollow
\nAnimal needs to keep recording a history of where the animal they are following is while\nmoving to where the animal they are following was before.
\n
\n
There are many ways to handle different states like this. A common one is to use\na Finite State Machine and\nto build some class to help us manage the state.
\n
So, let's do that.
\n
class FiniteStateMachine {\n constructor(states, initialState) {\n this.states = states;\n this.transition(initialState);\n }\n get state() {\n return this.currentState;\n }\n transition(state) {\n const oldState = this.states[this.currentState];\n if (oldState && oldState.exit) {\n oldState.exit.call(this);\n }\n this.currentState = state;\n const newState = this.states[state];\n if (newState.enter) {\n newState.enter.call(this);\n }\n }\n update() {\n const state = this.states[this.currentState];\n if (state.update) {\n state.update.call(this);\n }\n }\n}\n\n
Here's a simple class. We pass it an object with a bunch of states.\nEach state as 3 optional functions, enter, update, and exit.\nTo switch states we call FiniteStateMachine.transition and pass it\nthe name of the new state. If the current state has an exit function\nit's called. Then if the new state has an enter function it's called.\nFinally each frame FiniteStateMachine.update calls the update function\nof the current state.
\n
Let's use it to manage the states of the animals.
\n
// Returns true of obj1 and obj2 are close\nfunction isClose(obj1, obj1Radius, obj2, obj2Radius) {\n const minDist = obj1Radius + obj2Radius;\n const dist = obj1.position.distanceTo(obj2.position);\n return dist < minDist;\n}\n\n// keeps v between -min and +min\nfunction minMagnitude(v, min) {\n return Math.abs(v) > min\n ? min * Math.sign(v)\n : v;\n}\n\nconst aimTowardAndGetDistance = function() {\n const delta = new THREE.Vector3();\n\n return function aimTowardAndGetDistance(source, targetPos, maxTurn) {\n delta.subVectors(targetPos, source.position);\n // compute the direction we want to be facing\n const targetRot = Math.atan2(delta.x, delta.z) + Math.PI * 1.5;\n // rotate in the shortest direction\n const deltaRot = (targetRot - source.rotation.y + Math.PI * 1.5) % (Math.PI * 2) - Math.PI;\n // make sure we don't turn faster than maxTurn\n const deltaRotation = minMagnitude(deltaRot, maxTurn);\n // keep rotation between 0 and Math.PI * 2\n source.rotation.y = THREE.MathUtils.euclideanModulo(\n source.rotation.y + deltaRotation, Math.PI * 2);\n // return the distance to the target\n return delta.length();\n };\n}();\n\nclass Animal extends Component {\n constructor(gameObject, model) {\n super(gameObject);\n+ const hitRadius = model.size / 2;\n const skinInstance = gameObject.addComponent(SkinInstance, model);\n skinInstance.mixer.timeScale = globals.moveSpeed / 4;\n+ const transform = gameObject.transform;\n+ const playerTransform = globals.player.gameObject.transform;\n+ const maxTurnSpeed = Math.PI * (globals.moveSpeed / 4);\n+ const targetHistory = [];\n+ let targetNdx = 0;\n+\n+ function addHistory() {\n+ const targetGO = globals.congaLine[targetNdx];\n+ const newTargetPos = new THREE.Vector3();\n+ newTargetPos.copy(targetGO.transform.position);\n+ targetHistory.push(newTargetPos);\n+ }\n+\n+ this.fsm = new FiniteStateMachine({\n+ idle: {\n+ enter: () => {\n+ skinInstance.setAnimation('Idle');\n+ },\n+ update: () => {\n+ // check if player is near\n+ if (isClose(transform, hitRadius, playerTransform, globals.playerRadius)) {\n+ this.fsm.transition('waitForEnd');\n+ }\n+ },\n+ },\n+ waitForEnd: {\n+ enter: () => {\n+ skinInstance.setAnimation('Jump');\n+ },\n+ update: () => {\n+ // get the gameObject at the end of the conga line\n+ const lastGO = globals.congaLine[globals.congaLine.length - 1];\n+ const deltaTurnSpeed = maxTurnSpeed * globals.deltaTime;\n+ const targetPos = lastGO.transform.position;\n+ aimTowardAndGetDistance(transform, targetPos, deltaTurnSpeed);\n+ // check if last thing in conga line is near\n+ if (isClose(transform, hitRadius, lastGO.transform, globals.playerRadius)) {\n+ this.fsm.transition('goToLast');\n+ }\n+ },\n+ },\n+ goToLast: {\n+ enter: () => {\n+ // remember who we're following\n+ targetNdx = globals.congaLine.length - 1;\n+ // add ourselves to the conga line\n+ globals.congaLine.push(gameObject);\n+ skinInstance.setAnimation('Walk');\n+ },\n+ update: () => {\n+ addHistory();\n+ // walk to the oldest point in the history\n+ const targetPos = targetHistory[0];\n+ const maxVelocity = globals.moveSpeed * globals.deltaTime;\n+ const deltaTurnSpeed = maxTurnSpeed * globals.deltaTime;\n+ const distance = aimTowardAndGetDistance(transform, targetPos, deltaTurnSpeed);\n+ const velocity = distance;\n+ transform.translateOnAxis(kForward, Math.min(velocity, maxVelocity));\n+ if (distance <= maxVelocity) {\n+ this.fsm.transition('follow');\n+ }\n+ },\n+ },\n+ follow: {\n+ update: () => {\n+ addHistory();\n+ // remove the oldest history and just put ourselves there.\n+ const targetPos = targetHistory.shift();\n+ transform.position.copy(targetPos);\n+ const deltaTurnSpeed = maxTurnSpeed * globals.deltaTime;\n+ aimTowardAndGetDistance(transform, targetHistory[0], deltaTurnSpeed);\n+ },\n+ },\n+ }, 'idle');\n+ }\n+ update() {\n+ this.fsm.update();\n+ }\n}\n\n
That was big chunk of code but it does what was described above.\nHopefully of you walk through each state it will be clear.
\n
A few things we need to add. We need the player to add itself\nto the globals so the animals can find it and we need to start the\nconga line with the player's GameObject.
\n
function init() {\n\n ...\n\n {\n const gameObject = gameObjectManager.createGameObject(scene, 'player');\n+ globals.player = gameObject.addComponent(Player);\n+ globals.congaLine = [gameObject];\n }\n\n}\n\n
We also need to compute a size for each model
\n
function prepModelsAndAnimations() {\n+ const box = new THREE.Box3();\n+ const size = new THREE.Vector3();\n Object.values(models).forEach(model => {\n+ box.setFromObject(model.gltf.scene);\n+ box.getSize(size);\n+ model.size = size.length();\n const animsByName = {};\n model.gltf.animations.forEach((clip) => {\n animsByName[clip.name] = clip;\n // Should really fix this in .blend file\n if (clip.name === 'Walk') {\n clip.duration /= 2;\n }\n });\n model.animations = animsByName;\n });\n}\n\n
And we need the player to record their size
\n
class Player extends Component {\n constructor(gameObject) {\n super(gameObject);\n const model = models.knight;\n+ globals.playerRadius = model.size / 2;\n\n
Thinking about it now it would probably have been smarter\nfor the animals to just target the head of the conga line\ninstead of the player specifically. Maybe I'll come back\nand change that later.
\n
When I first started this I used just one radius for all animals\nbut of course that was no good as the pug is much smaller than the horse.\nSo I added the difference sizes but I wanted to be able to visualize\nthings. To do that I made a StateDisplayHelper component.
\n
I uses a PolarGridHelper to draw a circle around each character\nand it uses html elements to let each character show some status using\nthe techniques covered in the article on aligning html elements to 3D.
\n
First we need to add some HTML to host these elements
\n
<body>\n <canvas id=\"c\"></canvas>\n <div id=\"ui\">\n <div id=\"left\"><img src=\"../resources/images/left.svg\"></div>\n <div style=\"flex: 0 0 40px;\"></div>\n <div id=\"right\"><img src=\"../resources/images/right.svg\"></div>\n </div>\n <div id=\"loading\">\n <div>\n <div>...loading...</div>\n <div class=\"progress\"><div id=\"progressbar\"></div></div>\n </div>\n </div>\n+ <div id=\"labels\"></div>\n</body>\n
\n
And add some CSS for them
\n
#labels {\n position: absolute; /* let us position ourself inside the container */\n left: 0; /* make our position the top left of the container */\n top: 0;\n color: white;\n width: 100%;\n height: 100%;\n overflow: hidden;\n pointer-events: none;\n}\n#labels>div {\n position: absolute; /* let us position them inside the container */\n left: 0; /* make their default position the top left of the container */\n top: 0;\n font-size: large;\n font-family: monospace;\n user-select: none; /* don't let the text get selected */\n text-shadow: /* create a black outline */\n -1px -1px 0 #000,\n 0 -1px 0 #000,\n 1px -1px 0 #000,\n 1px 0 0 #000,\n 1px 1px 0 #000,\n 0 1px 0 #000,\n -1px 1px 0 #000,\n -1px 0 0 #000;\n}\n\n
Then here's the component
\n
const labelContainerElem = document.querySelector('#labels');\n\nclass StateDisplayHelper extends Component {\n constructor(gameObject, size) {\n super(gameObject);\n this.elem = document.createElement('div');\n labelContainerElem.appendChild(this.elem);\n this.pos = new THREE.Vector3();\n\n this.helper = new THREE.PolarGridHelper(size / 2, 1, 1, 16);\n gameObject.transform.add(this.helper);\n }\n setState(s) {\n this.elem.textContent = s;\n }\n setColor(cssColor) {\n this.elem.style.color = cssColor;\n this.helper.material.color.set(cssColor);\n }\n update() {\n const {pos} = this;\n const {transform} = this.gameObject;\n const {canvas} = globals;\n pos.copy(transform.position);\n\n // get the normalized screen coordinate of that position\n // x and y will be in the -1 to +1 range with x = -1 being\n // on the left and y = -1 being on the bottom\n pos.project(globals.camera);\n\n // convert the normalized position to CSS coordinates\n const x = (pos.x * .5 + .5) * canvas.clientWidth;\n const y = (pos.y * -.5 + .5) * canvas.clientHeight;\n\n // move the elem to that position\n this.elem.style.transform = translate(-50%, -50%) translate(${x}px,${y}px);\n }\n}\n\n
And we can then add them to the animals like this
\n
class Animal extends Component {\n constructor(gameObject, model) {\n super(gameObject);\n+ this.helper = gameObject.addComponent(StateDisplayHelper, model.size);\n\n ...\n\n }\n update() {\n this.fsm.update();\n+ const dir = THREE.MathUtils.radToDeg(this.gameObject.transform.rotation.y);\n+ this.helper.setState(${this.fsm.state}:${dir.toFixed(0)});\n }\n}\n\n
While we're at it lets make it so we can turn them on/off using lil-gui like\nwe've used else where
\n
import * as THREE from 'three';\nimport {OrbitControls} from 'three/addons/controls/OrbitControls.js';\nimport {GLTFLoader} from 'three/addons/loaders/GLTFLoader.js';\nimport * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';\n+import {GUI} from 'three/addons/libs/lil-gui.module.min.js';\n\n
+const gui = new GUI();\n+gui.add(globals, 'debug').onChange(showHideDebugInfo);\n+showHideDebugInfo();\n\nconst labelContainerElem = document.querySelector('#labels');\n+function showHideDebugInfo() {\n+ labelContainerElem.style.display = globals.debug ? '' : 'none';\n+}\n+showHideDebugInfo();\n\nclass StateDisplayHelper extends Component {\n\n ...\n\n update() {\n+ this.helper.visible = globals.debug;\n+ if (!globals.debug) {\n+ return;\n+ }\n\n ...\n }\n}\n\n
And with that we get the kind of start of a game
\n
\n\n
\n
Originally I set out to make a snake game\nwhere as you add animals to your line it gets harder because you need to avoid\ncrashing into them. I'd also have put some obstacles in the scene and maybe a fence or some\nbarrier around the perimeter.
\n
Unfortunately the animals are long and thin. From above here's the zebra.
\n
\n\n
The code so far is using circle collisions which means if we had obstacles like a fence\nthen this would be considered a collision
\n
\n\n
That's no good. Even animal to animal we'd have the same issue
\n
I thought about writing a 2D rectangle to rectangle collision system but I\nquickly realized it could really be a lot of code. Checking that 2 arbitrarily\noriented boxes overlap is not too much code and for our game with just a few\nobjects it might work but looking into it after a few objects you quickly start\nneeding to optimize the collision checking. First you might go through all\nobjects that can possibly collide with each other and check their bounding\nspheres or bounding circles or their axially aligned bounding boxes. Once you\nknow which objects might be colliding then you need to do more work to check if\nthey are actually colliding. Often even checking the bounding spheres is too\nmuch work and you need some kind of better spacial structure for the objects so\nyou can more quickly only check objects possibly near each other.
\n
Then, once you write the code to check if 2 objects collide you generally want\nto make a collision system rather than manually asking \"do I collide with these\nobjects\". A collision system emits events or calls callbacks in relation to\nthings colliding. The advantage is it can check all the collisions at once so no\nobjects get checked more than once where as if you manually call some \"am I\ncolliding\" function often objects will be checked more than once wasting time.
\n
Making that collision system would probably not be more than 100-300 lines of\ncode for just checking arbitrarily oriented rectangles but it's still a ton more\ncode so it seemed best to leave it out.
\n
Another solution would have been to try to find other characters that are\nmostly circular from the top. Other humanoid characters for example instead\nof animals in which case the circle checking might work animal to animal.\nIt would not work animal to fence, well we'd have to add circle to rectangle\nchecking. I thought about making the fence a fence of bushes or poles, something\ncircular but then I'd need probably 120 to 200 of them to surround the play area\nwhich would run into the optimization issues mentioned above.
\n
These are reasons many games use an existing solution. Often these solutions\nare part of a physics library. The physical library needs to know if objects\ncollide with each other so on top of providing physics they can also be used\nto detect collision.
\n
If you're looking for a solution some of the three.js examples use\nammo.js so that might be one.
\n
One other solution might have been to place the obstacles on a grid\nand try to make it so each animal and the player just need to look at\nthe grid. While that would be performant I felt that's best left as an exercise\nfor the reader 😜
\n
One more thing, many game systems have something called coroutines.\nCoroutines are routines that can pause while running and continue later.
\n
Let's make the main character emit musical notes like they are leading\nthe line by singing. There are many ways we could implement this but for now\nlet's do it using coroutines.
\n
First, here's a class to manage coroutines
\n
function* waitSeconds(duration) {\n while (duration > 0) {\n duration -= globals.deltaTime;\n yield;\n }\n}\n\nclass CoroutineRunner {\n constructor() {\n this.generatorStacks = [];\n this.addQueue = [];\n this.removeQueue = new Set();\n }\n isBusy() {\n return this.addQueue.length + this.generatorStacks.length > 0;\n }\n add(generator, delay = 0) {\n const genStack = [generator];\n if (delay) {\n genStack.push(waitSeconds(delay));\n }\n this.addQueue.push(genStack);\n }\n remove(generator) {\n this.removeQueue.add(generator);\n }\n update() {\n this._addQueued();\n this._removeQueued();\n for (const genStack of this.generatorStacks) {\n const main = genStack[0];\n // Handle if one coroutine removes another\n if (this.removeQueue.has(main)) {\n continue;\n }\n while (genStack.length) {\n const topGen = genStack[genStack.length - 1];\n const {value, done} = topGen.next();\n if (done) {\n if (genStack.length === 1) {\n this.removeQueue.add(topGen);\n break;\n }\n genStack.pop();\n } else if (value) {\n genStack.push(value);\n } else {\n break;\n }\n }\n }\n this._removeQueued();\n }\n _addQueued() {\n if (this.addQueue.length) {\n this.generatorStacks.splice(this.generatorStacks.length, 0, ...this.addQueue);\n this.addQueue = [];\n }\n }\n _removeQueued() {\n if (this.removeQueue.size) {\n this.generatorStacks = this.generatorStacks.filter(genStack => !this.removeQueue.has(genStack[0]));\n this.removeQueue.clear();\n }\n }\n}\n\n
It does things similar to SafeArray to make sure that it's safe to add or remove\ncoroutines while other coroutines are running. It also handles nested coroutines.
\n
To make a coroutine you make a JavaScript generator function.\nA generator function is preceded by the keyword function* (the asterisk is important!)
\n
Generator functions can yield. For example
\n
function* count0To9() {\n for (let i = 0; i < 10; ++i) {\n console.log(i);\n yield;\n }\n}\n\n
If we added this function to the CoroutineRunner above it would print\nout each number, 0 to 9, once per frame or rather once per time we called runner.update.
\n
const runner = new CoroutineRunner();\nrunner.add(count0To9);\nwhile(runner.isBusy()) {\n runner.update();\n}\n\n
Coroutines are removed automatically when they are finished.\nTo remove a coroutine early, before it reaches the end you need to keep\na reference to its generator like this
\n
const gen = count0To9();\nrunner.add(gen);\n\n// sometime later\n\nrunner.remove(gen);\n
\n
In any case, in the player let's use a coroutine to emit a note every half second to 1 second
\n
class Player extends Component {\n constructor(gameObject) {\n\n ...\n\n+ this.runner = new CoroutineRunner();\n+\n+ function* emitNotes() {\n+ for (;;) {\n+ yield waitSeconds(rand(0.5, 1));\n+ const noteGO = gameObjectManager.createGameObject(scene, 'note');\n+ noteGO.transform.position.copy(gameObject.transform.position);\n+ noteGO.transform.position.y += 5;\n+ noteGO.addComponent(Note);\n+ }\n+ }\n+\n+ this.runner.add(emitNotes());\n }\n update() {\n+ this.runner.update();\n\n ...\n\n }\n}\n\nfunction rand(min, max) {\n if (max === undefined) {\n max = min;\n min = 0;\n }\n return Math.random() * (max - min) + min;\n}\n\n
You can see we make a CoroutineRunner and we add an emitNotes coroutine.\nThat function will run forever, waiting 0.5 to 1 seconds and then creating a game object\nwith a Note component.
\n
For the Note component first lets make a texture with a note on it and\ninstead of loading a note image let's make one using a canvas like we covered in the article on canvas textures.
\n
function makeTextTexture(str) {\n const ctx = document.createElement('canvas').getContext('2d');\n ctx.canvas.width = 64;\n ctx.canvas.height = 64;\n ctx.font = '60px sans-serif';\n ctx.textAlign = 'center';\n ctx.textBaseline = 'middle';\n ctx.fillStyle = '#FFF';\n ctx.fillText(str, ctx.canvas.width / 2, ctx.canvas.height / 2);\n return new THREE.CanvasTexture(ctx.canvas);\n}\nconst noteTexture = makeTextTexture('♪');\n\n
The texture we create above is white each means when we use it\nwe can set the material's color and get a note of any color.
\n
Now that we have a noteTexture here's the Note component.\nIt uses SpriteMaterial and a Sprite like we covered in\nthe article on billboards
\n
class Note extends Component {\n constructor(gameObject) {\n super(gameObject);\n const {transform} = gameObject;\n const noteMaterial = new THREE.SpriteMaterial({\n color: new THREE.Color().setHSL(rand(1), 1, 0.5),\n map: noteTexture,\n side: THREE.DoubleSide,\n transparent: true,\n });\n const note = new THREE.Sprite(noteMaterial);\n note.scale.setScalar(3);\n transform.add(note);\n this.runner = new CoroutineRunner();\n const direction = new THREE.Vector3(rand(-0.2, 0.2), 1, rand(-0.2, 0.2));\n\n function* moveAndRemove() {\n for (let i = 0; i < 60; ++i) {\n transform.translateOnAxis(direction, globals.deltaTime * 10);\n noteMaterial.opacity = 1 - (i / 60);\n yield;\n }\n transform.parent.remove(transform);\n gameObjectManager.removeGameObject(gameObject);\n }\n\n this.runner.add(moveAndRemove());\n }\n update() {\n this.runner.update();\n }\n}\n\n
All it does is setup a Sprite, then pick a random velocity and move\nthe transform at that velocity for 60 frames while fading out the note\nby setting the material's opacity.\nAfter the loop it the removes the transform\nfrom the scene and the note itself from active gameobjects.
\n
One last thing, let's add a few more animals
\n
function init() {\n\n ...\n\n const animalModelNames = [\n 'pig',\n 'cow',\n 'llama',\n 'pug',\n 'sheep',\n 'zebra',\n 'horse',\n ];\n+ const base = new THREE.Object3D();\n+ const offset = new THREE.Object3D();\n+ base.add(offset);\n+\n+ // position animals in a spiral.\n+ const numAnimals = 28;\n+ const arc = 10;\n+ const b = 10 / (2 * Math.PI);\n+ let r = 10;\n+ let phi = r / b;\n+ for (let i = 0; i < numAnimals; ++i) {\n+ const name = animalModelNames[rand(animalModelNames.length) | 0];\n const gameObject = gameObjectManager.createGameObject(scene, name);\n gameObject.addComponent(Animal, models[name]);\n+ base.rotation.y = phi;\n+ offset.position.x = r;\n+ offset.updateWorldMatrix(true, false);\n+ offset.getWorldPosition(gameObject.transform.position);\n+ phi += arc / r;\n+ r = b * phi;\n }\n\n
\n\n
\n
You might be asking, why not use setTimeout? The problem with setTimeout\nis it's not related to the game clock. For example above we made the maximum\namount of time allowed to elapse between frames to be 1/20th of a second.\nOur coroutine system will respect that limit but setTimeout would not.
\n
Of course we could have made a simple timer ourselves
\n
class Player ... {\n update() {\n this.noteTimer -= globals.deltaTime;\n if (this.noteTimer <= 0) {\n // reset timer\n this.noteTimer = rand(0.5, 1);\n // create a gameobject with a note component\n }\n }\n\n
And for this particular case that might have been better but as you add\nmore and things you'll get more and more variables added to your classes\nwhere as with coroutines you can often just fire and forget.
\n
Given our animal's simple states we could also have implemented them\nwith a coroutine in the form of
\n
// pseudo code!\nfunction* animalCoroutine() {\n setAnimation('Idle');\n while(playerIsTooFar()) {\n yield;\n }\n const target = endOfLine;\n setAnimation('Jump');\n while(targetIsTooFar()) {\n aimAt(target);\n yield;\n }\n setAnimation('Walk')\n while(notAtOldestPositionOfTarget()) {\n addHistory();\n aimAt(target);\n yield;\n }\n for(;;) {\n addHistory();\n const pos = history.unshift();\n transform.position.copy(pos);\n aimAt(history[0]);\n yield;\n }\n}\n\n
This would have worked but of course as soon as our states were not so linear\nwe'd have had to switch to a FiniteStateMachine.
\n
It also wasn't clear to me if coroutines should run independently of their\ncomponents. We could have made a global CoroutineRunner and put all\ncoroutines on it. That would make cleaning them up harder. As it is now\nif the gameobject is removed all of its components are removed and\ntherefore the coroutine runners created are no longer called and it will\nall get garbage collected. If we had global runner then it would be\nthe responsibility of each component to remove any coroutines it added\nor else some other mechanism of registering coroutines with a particular\ncomponent or gameobject would be needed so that removing one removes the\nothers.
\n
There are lots more issues a\nnormal game engine would deal with. As it is there is no order to how\ngameobjects or their components are run. They are just run in the order added.\nMany game systems add a priority so the order can be set or changed.
\n
Another issue we ran into is the Note removing its gameobject's transform from the scene.\nThat seems like something that should happen in GameObject since it was GameObject\nthat added the transform in the first place. Maybe GameObject should have\na dispose method that is called by GameObjectManager.removeGameObject?
\n
Yet another is how we're manually calling gameObjectManager.update and inputManager.update.\nMaybe there should be a SystemManager which these global services can add themselves\nand each service will have its update function called. In this way if we added a new\nservice like CollisionManager we could just add it to the system manager and not\nhave to edit the render loop.
\n
I'll leave those kinds of issues up to you.\nI hope this article has given you some ideas for your own game engine.
\n
Maybe I should promote a game jam. If you click the jsfiddle or codepen buttons\nabove the last example they'll open in those sites ready to edit. Add some features,\nChange the game to a pug leading a bunch of knights. Use the knight's rolling animation\nas a bowling ball and make an animal bowling game. Make an animal relay race.\nIf you make a cool game post a link in the comments below.
\n\n
![\"\"](\"../resources/srgb_gamut.png\")
\n\t\t![](\"../resources/images/threejs-structure.svg\")
![](\"../resources/images/threejs-1cube-no-light-scene.svg\")
![](\"../resources/frustum-3d.svg\")
![](\"../resources/scene-down.svg\")
![](\"../resources/images/threejs-1cube-with-directionallight.svg\")
![](\"../resources/images/threejs-3cubes-scene.svg\")
![](\"../resources/images/resize-incorrect-aspect.png\")
![](\"../resources/images/resize-low-res.png\")
![](\"../resources/images/resize-correct-aspect.png\")
![](\"../resources/images/vscode-eslint-not-defined.png\")
![](\"../resources/images/vscode-eslint-not-a-constructor.png\")
![](\"../resources/images/vscode-eslint-var.png\")
![](\"../resources/images/vscode-eslint-let.png\")
![](\"../resources/servez.gif\")
\n![](\"../resources/servez-response.png\")
\n![](\"../resources/images/scenegraph-generic.svg\")
![](\"../resources/images/scenegraph-solarsystem.svg\")
![](\"../resources/images/scenegraph-sun-earth.svg\")
![](\"../resources/images/scenegraph-sun-earth-fixed.svg\")
![](\"../resources/images/scenegraph-sun-earth-moon.svg\")
![](\"../resources/images/scenegraph-car.svg\")
![](\"../resources/images/scenegraph-human.svg\")
![](\"../resources/images/scenegraph-tank.svg\")
![](\"../examples/resources/images/wall.jpg\")
\n![](\"../examples/resources/images/flower-1.jpg\")
\n ![](\"../examples/resources/images/flower-2.jpg\")
\n ![](\"../examples/resources/images/flower-3.jpg\")
\n ![](\"../examples/resources/images/flower-4.jpg\")
\n ![](\"../examples/resources/images/flower-5.jpg\")
\n ![](\"../examples/resources/images/flower-6.jpg\")
\n ![](\"../resources/images/compressed-but-large-wood-texture.jpg\")
![](\"../resources/images/mip-low-res-enlarged.png\")
![](\"../resources/images/mipmap-low-res-enlarged.png\")
![](\"../examples/resources/images/checker.png\")
\n![](\"../resources/images/z-fighting.png\")
![](\"../resources/images/quad-viewport.png\")
![](\"../examples/resources/images/roundshadow.png\")
![](\"../resources/images/low-res-shadow-map.png\")
![](\"../resources/threejs-attributes.svg\")
![](\"../resources/cube-faces-vertex.svg\")
![](\"../resources/images/standard-primitive-normals.jpg\")
![](\"../resources/images/standard-primitive-uvs.jpg\")
![](\"../resources/images/inspect-matrices.gif\")
![](\"../resources/images/screencapture-413x313.png\")
![](\"../examples/resources/images/world.jpg\")
![](\"../resources/images/bring-up-fps-meter.gif\")
![](\"../resources/images/fps-meter.gif\")
![](\"../resources/images/windmill-obj.jpg\")
![](\"../resources/images/windmill-export-as-obj.jpg\")
![](\"../resources/images/windmill-export-options.jpg\")
![](\"../resources/images/windmill-exported-files.png\")
![](\"../resources/images/windmill-export-textures.jpg\")
![](\"../resources/images/windmill-overwrite.jpg\")
![](\"../resources/images/windmill-exported-texture-files.png\")
![](\"../resources/images/windmill-exported-files-with-textures.png\")
![](\"../resources/images/windmill-missing-cloth.jpg\")
![](\"../resources/images/windmill-blocky.jpg\")
![](\"../examples/resources/models/windmill/windmill_001_base_NOR.jpg\")
![](\"../resources/images/windmill-obj-2.jpg\")
![](\"../resources/images/camera-inside-windmill.svg\")
![](\"../resources/images/camera-fit-scene.svg\")
![](\"../resources/images/field-of-view-camera.svg\")
![](\"../resources/images/computed-camera-position.svg\")
![](\"../resources/images/tiny-ground-plane.jpg\")
![](\"../resources/images/cartoon_lowpoly_small_city_free_pack.jpg\")
![](\"../resources/images/making-path-for-cars.jpg\")
![](\"../resources/images/blender-export-obj-write-nurbs.jpg\")
![](\"../resources/images/car-curves-before.png\")
![](\"../resources/images/car-curves-after.png\")
![](\"../resources/images/car-curves-too-small.png\")
![](\"../resources/images/cars-scale-0.01.png\")
![](\"../examples/resources/images/cubemaps/computer-history-museum/pos-x.jpg\")
\n ![](\"../examples/resources/images/cubemaps/computer-history-museum/neg-x.jpg\")
\n ![](\"../examples/resources/images/cubemaps/computer-history-museum/pos-y.jpg\")
\n![](\"../examples/resources/images/cubemaps/computer-history-museum/neg-y.jpg\")
\n ![](\"../examples/resources/images/cubemaps/computer-history-museum/pos-z.jpg\")
\n ![](\"../examples/resources/images/cubemaps/computer-history-museum/neg-z.jpg\")
\n![](\"../examples/resources/images/equirectangularmaps/tears_of_steel_bridge_2k.jpg\")
![](\"../resources/images/transparency-cubes-no-backs.png\"){kind=spacer}
![](\"../resources/images/transparency-cubes-some-backs.png\"){kind=spacer}
![](\"../resources/images/transparency-planes.png\"){kind=spacer}
![](\"../examples/resources/images/tree-01.png\")
![](\"../examples/resources/images/tree-02.png\")
![](\"../resources/images/transparency-alphatest-issues.png\"){kind=spacer}
![](\"../resources/images/multi-view-skew.gif\")
![](\"../resources/images/multi-view-fixed.gif\")
![](\"../examples/resources/images/frame.png\")
![](\"../resources/images/picking-transparent-issue.jpg\"){kind=spacer}
![](\"../resources/images/threejs-postprocessing.svg\")
![](\"../resources/images/shadertoy-skyline.png\")
![](\"../resources/images/cities-skylines.jpg\")
![](\"../resources/images/overlapping-labels.png\")
![](\"../resources/images/label-sorting-issue.png\")
![](\"../examples/resources/data/world/country-outlines-4k.png\")
![](\"../examples/resources/data/world/country-index-texture.png\")
![](\"../resources/images/7x7-indexed-face.png\")
![](\"../resources/images/billboard-label-z-issue.png\")
![](\"../examples/resources/images/minecraft/flourish-cc-by-nc-sa.png\")
![](\"../resources/images/knight.jpg\")
![](\"../resources/images/animals.jpg\")
![](\"../resources/images/zebra.png\")
![](\"../resources/images/zebra-collisions.svg\")
![](\"../resources/images/servez-https.png\")
![](\"../resources/images/https-warning.gif\")
![it is actually\n3024 x 3761 pixels in size](\"resources/images/compressed-but-large-wood-texture.jpg\"){kind=link}
![](\"resources/threejs-geometry.svg\"){kind=link}