Three.js Mobile On-Screen Character Controller
A complete beginner-friendly tutorial for building a touch joystick that walks and rotates an animated 3D character in the browser — with a following camera and idle/walk animation blending. Drag the glowing joystick on the scene above to try it, then copy the full code below.
Quick Answer: How Do You Build a Mobile Character Controller in Three.js?
- Draw an on-screen joystick with HTML/CSS and set
touch-action: noneon it. - On touch or mouse drag, turn the stick offset into a normalized
(x, y)direction. - Each frame, rotate the character with
Math.atan2(x, y)and move it forward byspeed × delta. - Cross-fade
idleandwalkclips with anAnimationMixer. - Keep the camera behind the character with a fixed offset and
camera.lookAt()every frame.
Works with one code path on phones, tablets and desktop. Full copy-paste code is below.
What You'll Build
- A full-screen Three.js scene with lights, fog, a ground plane and a grid.
- An animated knight loaded from a GLB file and auto-scaled to about 1.8 units tall.
- A round on-screen joystick at the bottom center that works with a finger or a mouse.
- Smooth cross-fades between the idle and walking animations.
- Movement that faces the drag direction, plus a camera that follows behind the character.
Frequently Asked Questions
How do you make an on-screen joystick for mobile games in Three.js?
Create an outer circle and a draggable inner circle with HTML and CSS, then listen for touchstart/touchmove (and mousedown/mousemove on desktop). On each move, measure the drag position relative to the joystick center and convert it into a normalized direction vector between -1 and 1. Use that vector to rotate and move your 3D character. Set touch-action: none so the page does not scroll while dragging.
How do you move and rotate a 3D character with a joystick vector?
Turn the joystick's (x, y) vector into a heading angle with Math.atan2(x, y). Set the model's rotation.y to that angle so it faces the drag direction, then step it forward along that heading using sin and cos of the angle, scaled by the frame delta so movement is frame-rate independent.
How do you blend idle and walk animations in Three.js?
Load a rigged GLB model with GLTFLoader and create an AnimationMixer. Get a clipAction for each clip (idle, walk). Play idle at rest, and when the joystick is active call walkAction.reset().fadeIn(0.2).play() while fading out idle. On release, fade back to idle. Call mixer.update(delta) every frame in the animation loop.
How do you make the camera follow the character?
Each frame, set the camera position to the character's position plus a fixed offset (in this code 0, 3.5, 7), then call camera.lookAt() on a point about 1 unit above the character's feet. This keeps the character centered as it walks around the scene.
Does this Three.js character controller work on both mobile and desktop?
Yes. The joystick listens for touch events on mobile and mouse events on desktop, so the same code drives the character with a finger or a mouse. Because the movement is delta-scaled, it runs smoothly across different frame rates and devices.
Why doesn't the page scroll while I drag the joystick on my phone?
The joystick element uses CSS touch-action: none, which tells the mobile browser not to treat that drag as a page scroll or pinch-zoom. Touches outside the joystick still scroll the page normally.
How many animated characters can Three.js render on a phone?
Dozens of skinned characters run smoothly on modern phones if you cap the renderer pixel ratio at 2, reuse one loaded GLB with SkeletonUtils.clone, and share materials and textures between clones. For hundreds, bake the walk pose into an InstancedMesh.
Can I use my own character model with this controller?
Yes. Export any rigged character as a GLB with clips named idle and walk (Mixamo works well), host it next to the HTML file, and change MODEL_URL. If your clips use other names, update the findByName lookups.
How the Mobile Character Controller Works
Scroll up and drag the glowing joystick to walk the character around. The controller works by
drawing an on-screen joystick (an outer circle with a draggable inner circle), reading the drag
direction as a normalized vector, rotating the 3D model to face that direction, and playing a
walk animation through a Three.js AnimationMixer. On desktop it responds to the mouse;
on mobile it responds to touch. The showcase above adds sound, model swapping and extra buttons,
but the six steps below are everything you need to move an animated character.
Step-by-Step Code Breakdown
Every excerpt below is copied exactly from the full code further down. Follow the steps in order, or jump straight to the full code and launch it.
1. Set up the scene, camera and lights
In plain words: we create the 3D world, a camera that will sit behind and above the character, and a renderer that draws it all. A hemisphere light and a sun light the model, and a big plane with a grid gives you a floor so you can see the character moving. The pixel ratio is capped at 2 so high-DPI phones stay fast.
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x05101c);
scene.fog = new THREE.Fog(0x05101c, 15, 60);
const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.1, 500);
const cameraOffset = new THREE.Vector3(0, 3.5, 7); // camera sits behind and above the character
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
scene.add(new THREE.HemisphereLight(0xdfe9ff, 0x1a2230, 1.6));
const sun = new THREE.DirectionalLight(0xffffff, 2);
sun.position.set(5, 10, 7);
scene.add(sun);
const ground = new THREE.Mesh(
new THREE.PlaneGeometry(200, 200),
new THREE.MeshStandardMaterial({ color: 0x0e2233 }));
ground.rotation.x = -Math.PI / 2;
scene.add(ground);
scene.add(new THREE.GridHelper(200, 100, 0x2ad1d6, 0x16384d));
2. Load the animated character
GLTFLoader downloads the knight .glb from shanebrumback.com scales it to about 1.8 units tall with Box3 and adds it to the scene. Then we create an AnimationMixer and turn the idle and walking clips into actions. Idle starts playing right away.
const MODEL_URL = 'https://www.shanebrumback.com/models/glb/knight-animations.glb';
let model = null, mixer = null, idleAction = null, walkAction = null;
new GLTFLoader().load(MODEL_URL, (gltf) => {
model = gltf.scene;
// Auto-fit: scale the model to about 1.8 units tall
const size = new THREE.Box3().setFromObject(model).getSize(new THREE.Vector3());
model.scale.setScalar(1.8 / (size.y || 1));
model.position.y -= new THREE.Box3().setFromObject(model).min.y; // feet on the floor
scene.add(model);
mixer = new THREE.AnimationMixer(model);
const clips = gltf.animations;
const idle = THREE.AnimationClip.findByName(clips, 'idle') || clips[0];
const walk = THREE.AnimationClip.findByName(clips, 'walking') || clips[1] || clips[0];
idleAction = mixer.clipAction(idle);
walkAction = mixer.clipAction(walk);
idleAction.play();
});
3. Draw the on-screen joystick
The joystick is plain HTML and CSS: an outer circle fixed near the bottom of the screen and an inner #stick you drag. touch-action: none tells phones not to scroll the page while your thumb is on the joystick.
/* On-screen joystick: outer ring + draggable inner stick */
#joystick {
position: fixed; bottom: 6%; left: 50%; transform: translateX(-50%);
width: 22vw; height: 22vw; max-width: 110px; max-height: 110px;
border-radius: 50%; background: rgba(255,255,255,0.25);
box-shadow: 0 0 9px 4px #747DE8; z-index: 10;
touch-action: none; user-select: none; -webkit-user-select: none;
}
#stick {
position: absolute; top: 50%; left: 50%;
width: 60%; height: 60%; border-radius: 50%;
transform: translate(-50%, -50%); cursor: pointer; pointer-events: none;
background: radial-gradient(circle at 50% 120%, rgba(129,232,246,0.95), rgba(5,81,148,0.85) 80%);
}
4. Read the drag direction as a vector
setDirection() measures where your finger or mouse is compared with the joystick center and turns it into a direction between -1 and 1 on each axis. If you drag past the edge it is clamped to length 1. The same numbers nudge the visible stick so you can see what you are pressing.
const joystick = document.getElementById('joystick');
const stick = document.getElementById('stick');
let moveX = 0, moveZ = 0, active = false;
function setDirection(clientX, clientY) {
const r = joystick.getBoundingClientRect();
const cx = r.left + r.width / 2;
const cy = r.top + r.height / 2;
// Normalized -1..1 direction from the joystick center
let dx = (clientX - cx) / (r.width / 2);
let dy = (clientY - cy) / (r.height / 2);
const len = Math.hypot(dx, dy);
if (len > 1) { dx /= len; dy /= len; }
moveX = dx; moveZ = dy;
stick.style.left = (50 + dx * 30) + '%';
stick.style.top = (50 + dy * 30) + '%';
}
5. Blend idle and walk on press and release
When you press the joystick, startMove() fades the idle animation out and the walk animation in over 0.2 seconds, so the pose blends instead of snapping. endMove() does the reverse and re-centers the stick. Mouse events cover desktop and touch events cover phones, so one code path works everywhere.
function startMove(x, y) {
active = true;
if (walkAction) { idleAction.fadeOut(0.2); walkAction.reset().fadeIn(0.2).play(); }
setDirection(x, y);
}
function endMove() {
if (!active) return;
active = false;
moveX = moveZ = 0;
stick.style.left = '50%';
stick.style.top = '50%';
if (walkAction) { walkAction.fadeOut(0.2); idleAction.reset().fadeIn(0.2).play(); }
}
// Mouse
joystick.addEventListener('mousedown', (e) => { e.preventDefault(); startMove(e.clientX, e.clientY); });
window.addEventListener('mousemove', (e) => { if (active) setDirection(e.clientX, e.clientY); });
window.addEventListener('mouseup', endMove);
// Touch (passive: false so preventDefault stops the page from scrolling)
joystick.addEventListener('touchstart', (e) => { e.preventDefault(); startMove(e.touches[0].clientX, e.touches[0].clientY); }, { passive: false });
window.addEventListener('touchmove', (e) => { if (active) { e.preventDefault(); setDirection(e.touches[0].clientX, e.touches[0].clientY); } }, { passive: false });
window.addEventListener('touchend', endMove);
window.addEventListener('touchcancel', endMove);
6. Move the character and follow it with the camera
Every frame, Math.atan2(moveX, moveZ) turns the joystick vector into a facing angle. The model turns to that angle and steps forward along it, multiplied by delta so the speed is the same at 30, 60 or 120 fps. The camera then copies the character position plus a fixed offset and looks at its chest, so the player always stays in view.
const clock = new THREE.Clock();
const speed = 3; // units per second
function animate() {
requestAnimationFrame(animate);
const delta = Math.min(clock.getDelta(), 0.1);
if (mixer) mixer.update(delta);
if (model) {
if (active && (moveX || moveZ)) {
// Face the joystick direction and step forward along it
const angle = Math.atan2(moveX, moveZ);
model.rotation.y = angle;
model.position.x += Math.sin(angle) * speed * delta;
model.position.z += Math.cos(angle) * speed * delta;
}
// Follow camera: keep a fixed offset and look at the character's chest
camera.position.set(model.position.x, model.position.y, model.position.z).add(cameraOffset);
camera.lookAt(model.position.x, model.position.y + 1, model.position.z);
} else {
camera.position.copy(cameraOffset);
camera.lookAt(0, 1, 0);
}
renderer.render(scene, camera);
}
The Full Code
Paste this into a file named index.html and open it from any web server. It is completely self-contained: Three.js 0.160.0 loads from a CDN through an import map and the knight model loads from shanebrumback.com. Launch Full Code opens this exact code as a standalone page in a new window.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Three.js Mobile Character Controller</title>
<style>
html, body { margin: 0; height: 100%; overflow: hidden; background: #05101c; }
/* On-screen joystick: outer ring + draggable inner stick */
#joystick {
position: fixed; bottom: 6%; left: 50%; transform: translateX(-50%);
width: 22vw; height: 22vw; max-width: 110px; max-height: 110px;
border-radius: 50%; background: rgba(255,255,255,0.25);
box-shadow: 0 0 9px 4px #747DE8; z-index: 10;
touch-action: none; user-select: none; -webkit-user-select: none;
}
#stick {
position: absolute; top: 50%; left: 50%;
width: 60%; height: 60%; border-radius: 50%;
transform: translate(-50%, -50%); cursor: pointer; pointer-events: none;
background: radial-gradient(circle at 50% 120%, rgba(129,232,246,0.95), rgba(5,81,148,0.85) 80%);
}
#hint { position: fixed; top: 14px; left: 0; right: 0; text-align: center; color: #9fdfff; font: 600 14px system-ui, sans-serif; }
</style>
<script type="importmap">
{ "imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/"
} }
</script>
</head>
<body>
<div id="hint">Drag the joystick to walk</div>
<div id="joystick"><div id="stick"></div></div>
<script type="module">
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
// --- Step 1: scene, camera, renderer, lights and ground ---
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x05101c);
scene.fog = new THREE.Fog(0x05101c, 15, 60);
const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.1, 500);
const cameraOffset = new THREE.Vector3(0, 3.5, 7); // camera sits behind and above the character
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
scene.add(new THREE.HemisphereLight(0xdfe9ff, 0x1a2230, 1.6));
const sun = new THREE.DirectionalLight(0xffffff, 2);
sun.position.set(5, 10, 7);
scene.add(sun);
const ground = new THREE.Mesh(
new THREE.PlaneGeometry(200, 200),
new THREE.MeshStandardMaterial({ color: 0x0e2233 }));
ground.rotation.x = -Math.PI / 2;
scene.add(ground);
scene.add(new THREE.GridHelper(200, 100, 0x2ad1d6, 0x16384d));
// --- Step 2: load the animated character ---
const MODEL_URL = 'https://www.shanebrumback.com/models/glb/knight-animations.glb';
let model = null, mixer = null, idleAction = null, walkAction = null;
new GLTFLoader().load(MODEL_URL, (gltf) => {
model = gltf.scene;
// Auto-fit: scale the model to about 1.8 units tall
const size = new THREE.Box3().setFromObject(model).getSize(new THREE.Vector3());
model.scale.setScalar(1.8 / (size.y || 1));
model.position.y -= new THREE.Box3().setFromObject(model).min.y; // feet on the floor
scene.add(model);
mixer = new THREE.AnimationMixer(model);
const clips = gltf.animations;
const idle = THREE.AnimationClip.findByName(clips, 'idle') || clips[0];
const walk = THREE.AnimationClip.findByName(clips, 'walking') || clips[1] || clips[0];
idleAction = mixer.clipAction(idle);
walkAction = mixer.clipAction(walk);
idleAction.play();
});
// --- Step 3: read the joystick as a direction vector ---
const joystick = document.getElementById('joystick');
const stick = document.getElementById('stick');
let moveX = 0, moveZ = 0, active = false;
function setDirection(clientX, clientY) {
const r = joystick.getBoundingClientRect();
const cx = r.left + r.width / 2;
const cy = r.top + r.height / 2;
// Normalized -1..1 direction from the joystick center
let dx = (clientX - cx) / (r.width / 2);
let dy = (clientY - cy) / (r.height / 2);
const len = Math.hypot(dx, dy);
if (len > 1) { dx /= len; dy /= len; }
moveX = dx; moveZ = dy;
stick.style.left = (50 + dx * 30) + '%';
stick.style.top = (50 + dy * 30) + '%';
}
// --- Step 4: blend idle and walk when you press and release ---
function startMove(x, y) {
active = true;
if (walkAction) { idleAction.fadeOut(0.2); walkAction.reset().fadeIn(0.2).play(); }
setDirection(x, y);
}
function endMove() {
if (!active) return;
active = false;
moveX = moveZ = 0;
stick.style.left = '50%';
stick.style.top = '50%';
if (walkAction) { walkAction.fadeOut(0.2); idleAction.reset().fadeIn(0.2).play(); }
}
// Mouse
joystick.addEventListener('mousedown', (e) => { e.preventDefault(); startMove(e.clientX, e.clientY); });
window.addEventListener('mousemove', (e) => { if (active) setDirection(e.clientX, e.clientY); });
window.addEventListener('mouseup', endMove);
// Touch (passive: false so preventDefault stops the page from scrolling)
joystick.addEventListener('touchstart', (e) => { e.preventDefault(); startMove(e.touches[0].clientX, e.touches[0].clientY); }, { passive: false });
window.addEventListener('touchmove', (e) => { if (active) { e.preventDefault(); setDirection(e.touches[0].clientX, e.touches[0].clientY); } }, { passive: false });
window.addEventListener('touchend', endMove);
window.addEventListener('touchcancel', endMove);
// --- Step 5: rotate, move and follow with the camera every frame ---
const clock = new THREE.Clock();
const speed = 3; // units per second
function animate() {
requestAnimationFrame(animate);
const delta = Math.min(clock.getDelta(), 0.1);
if (mixer) mixer.update(delta);
if (model) {
if (active && (moveX || moveZ)) {
// Face the joystick direction and step forward along it
const angle = Math.atan2(moveX, moveZ);
model.rotation.y = angle;
model.position.x += Math.sin(angle) * speed * delta;
model.position.z += Math.cos(angle) * speed * delta;
}
// Follow camera: keep a fixed offset and look at the character's chest
camera.position.set(model.position.x, model.position.y, model.position.z).add(cameraOffset);
camera.lookAt(model.position.x, model.position.y + 1, model.position.z);
} else {
camera.position.copy(cameraOffset);
camera.lookAt(0, 1, 0);
}
renderer.render(scene, camera);
}
animate();
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
});
</script>
</body>
</html>
Mobile Performance Tips
- Cap pixel ratio:
renderer.setPixelRatio(Math.min(devicePixelRatio, 2))keeps high-DPI phones fast. - Load once, clone many: load the GLB a single time and use
SkeletonUtils.clonefor crowds. - Use
deltatime: scale movement by the frame delta so speed is the same at 30, 60 or 120 fps. - Lock to landscape for play: wide screens give the joystick and buttons room without covering the character.
Common Mistakes to Avoid
- Forgetting
touch-action: none, so the page scrolls instead of the character moving. - Calling
mixer.update()without a delta, which freezes or speeds up animations. - Rotating with Euler math on the wrong axis; for top-down movement only
rotation.yshould change.
Next Steps
Add shooting and first-person look with the Three.js FPS Game Starter, or learn desktop mouse look in the Three.js FPS Controls (PointerLockControls) tutorial.
More character tutorials: Rigged Super Soldier, Animating 3D GLTF Models, Xbox Controller Character Animation, Keyboard Inputs for 3D Games, Make One Object Follow Another.