Controls API Reference

The controls module provides camera and object interaction controls.

Overview

import io.materia.controls.*

---

OrbitControls

Orbiting camera controls for rotating around a target.

Constructor

class OrbitControls(
    camera: Camera,
    domElement: HTMLElement  // or Window on JVM
)

Properties

Property	Type	Default	Description
enabled	Boolean	true	Enable controls
target	Vector3	(0,0,0)	Orbit target point
minDistance	Float	0	Minimum zoom distance
maxDistance	Float	Infinity	Maximum zoom distance
minZoom	Float	0	Minimum zoom (ortho)
maxZoom	Float	Infinity	Maximum zoom (ortho)
minPolarAngle	Float	0	Minimum vertical angle
maxPolarAngle	Float	PI	Maximum vertical angle
minAzimuthAngle	Float	-Infinity	Minimum horizontal angle
maxAzimuthAngle	Float	Infinity	Maximum horizontal angle
enableDamping	Boolean	false	Enable smooth motion
dampingFactor	Float	0.05	Damping amount
enableZoom	Boolean	true	Enable zooming
zoomSpeed	Float	1.0	Zoom sensitivity
enableRotate	Boolean	true	Enable rotation
rotateSpeed	Float	1.0	Rotation sensitivity
enablePan	Boolean	true	Enable panning
panSpeed	Float	1.0	Pan sensitivity
screenSpacePanning	Boolean	true	Pan in screen space
keyPanSpeed	Float	7.0	Keyboard pan speed
autoRotate	Boolean	false	Auto-rotate
autoRotateSpeed	Float	2.0	Auto-rotate speed
enableKeys	Boolean	true	Enable keyboard
keys	Keys	default	Key bindings
mouseButtons	MouseButtons	default	Mouse bindings
touches	Touches	default	Touch bindings

Key Bindings

data class Keys(
    val left: String = "ArrowLeft",
    val up: String = "ArrowUp",
    val right: String = "ArrowRight",
    val bottom: String = "ArrowDown"
)

Mouse Bindings

data class MouseButtons(
    val left: MouseAction = MouseAction.ROTATE,
    val middle: MouseAction = MouseAction.DOLLY,
    val right: MouseAction = MouseAction.PAN
)

enum class MouseAction {
    ROTATE, DOLLY, PAN, NONE
}

Methods

// Update controls (call each frame)
fun update(): Boolean

// Reset to initial state
fun reset()

// Save current state
fun saveState()

// Get polar angle
fun getPolarAngle(): Float

// Get azimuthal angle
fun getAzimuthalAngle(): Float

// Get distance to target
fun getDistance(): Float

// Listen to target changes
fun listenToKeyEvents(element: HTMLElement)

// Dispose event listeners
fun dispose()

Events

controls.addEventListener("change") {
    renderer.render(scene, camera)
}

controls.addEventListener("start") {
    // Interaction started
}

controls.addEventListener("end") {
    // Interaction ended
}

Example

val controls = OrbitControls(camera, renderer.domElement)
controls.enableDamping = true
controls.dampingFactor = 0.05f
controls.minDistance = 2f
controls.maxDistance = 50f
controls.maxPolarAngle = PI / 2  // Don't go below ground

// Animate
fun animate() {
    controls.update()  // Required for damping
    renderer.render(scene, camera)
}

// Focus on object
controls.target.copy(mesh.position)
controls.update()

---

MapControls

Extends OrbitControls for map-style navigation (pan with left mouse).

Constructor

class MapControls(
    camera: Camera,
    domElement: HTMLElement
)

Differences from OrbitControls

• Left mouse button pans
• Right mouse button rotates
• Good for top-down views

Example

val controls = MapControls(camera, renderer.domElement)
controls.enableDamping = true
controls.screenSpacePanning = false  // Pan parallel to ground
controls.maxPolarAngle = PI / 2

---

TrackballControls

Unconstrained rotation controls (no up direction).

Constructor

class TrackballControls(
    camera: Camera,
    domElement: HTMLElement
)

Properties

Property	Type	Default	Description
enabled	Boolean	true	Enable controls
rotateSpeed	Float	1.0	Rotation speed
zoomSpeed	Float	1.2	Zoom speed
panSpeed	Float	0.3	Pan speed
noRotate	Boolean	false	Disable rotation
noZoom	Boolean	false	Disable zoom
noPan	Boolean	false	Disable pan
staticMoving	Boolean	false	No inertia
dynamicDampingFactor	Float	0.2	Inertia damping
minDistance	Float	0	Min distance
maxDistance	Float	Infinity	Max distance

Methods

fun update()
fun reset()
fun dispose()

---

FlyControls

Flight simulator-style controls.

Constructor

class FlyControls(
    camera: Camera,
    domElement: HTMLElement
)

Properties

Property	Type	Default	Description
movementSpeed	Float	1.0	Movement speed
rollSpeed	Float	0.005	Roll speed
dragToLook	Boolean	false	Require drag to look
autoForward	Boolean	false	Always move forward

Methods

fun update(delta: Float)
fun dispose()

Example

val controls = FlyControls(camera, renderer.domElement)
controls.movementSpeed = 10f
controls.rollSpeed = PI / 24

fun animate(deltaTime: Float) {
    controls.update(deltaTime)
    renderer.render(scene, camera)
}

---

FirstPersonControls

First-person shooter-style controls.

Constructor

class FirstPersonControls(
    camera: Camera,
    domElement: HTMLElement
)

Properties

Property	Type	Default	Description
enabled	Boolean	true	Enable controls
movementSpeed	Float	1.0	Movement speed
lookSpeed	Float	0.005	Look sensitivity
lookVertical	Boolean	true	Allow vertical look
autoForward	Boolean	false	Auto move forward
activeLook	Boolean	true	Mouse look
heightSpeed	Boolean	false	Height affects speed
heightCoef	Float	1.0	Height coefficient
heightMin	Float	0	Minimum height
heightMax	Float	1.0	Maximum height
constrainVertical	Boolean	false	Limit vertical angle
verticalMin	Float	0	Min vertical angle
verticalMax	Float	PI	Max vertical angle

Methods

fun update(delta: Float)
fun lookAt(target: Vector3)
fun dispose()

---

PointerLockControls

First-person controls with pointer lock (mouse capture).

Constructor

class PointerLockControls(
    camera: Camera,
    domElement: HTMLElement
)

Properties

Property	Type	Default	Description
isLocked	Boolean	false	Is pointer locked
minPolarAngle	Float	0	Min vertical angle
maxPolarAngle	Float	PI	Max vertical angle

Methods

// Lock pointer
fun lock()

// Unlock pointer
fun unlock()

// Connect/disconnect events
fun connect()
fun disconnect()

// Get look direction
fun getDirection(target: Vector3): Vector3

// Movement
fun moveForward(distance: Float)
fun moveRight(distance: Float)

fun dispose()

Events

controls.addEventListener("lock") {
    instructions.style.display = "none"
}

controls.addEventListener("unlock") {
    instructions.style.display = "block"
}

Example

val controls = PointerLockControls(camera, document.body)
scene.add(controls.getObject())  // Add camera to scene

// Click to lock
document.body.addEventListener("click") {
    controls.lock()
}

// Movement
val velocity = Vector3()
val direction = Vector3()

var moveForward = false
var moveBackward = false
var moveLeft = false
var moveRight = false

document.addEventListener("keydown") { event ->
    when (event.code) {
        "KeyW" -> moveForward = true
        "KeyS" -> moveBackward = true
        "KeyA" -> moveLeft = true
        "KeyD" -> moveRight = true
    }
}

document.addEventListener("keyup") { event ->
    when (event.code) {
        "KeyW" -> moveForward = false
        "KeyS" -> moveBackward = false
        "KeyA" -> moveLeft = false
        "KeyD" -> moveRight = false
    }
}

fun animate(delta: Float) {
    if (controls.isLocked) {
        direction.z = (if (moveForward) 1 else 0) - (if (moveBackward) 1 else 0)
        direction.x = (if (moveRight) 1 else 0) - (if (moveLeft) 1 else 0)
        direction.normalize()
        
        velocity.x -= velocity.x * 10f * delta
        velocity.z -= velocity.z * 10f * delta
        
        if (moveForward || moveBackward) velocity.z -= direction.z * 400f * delta
        if (moveLeft || moveRight) velocity.x -= direction.x * 400f * delta
        
        controls.moveRight(-velocity.x * delta)
        controls.moveForward(-velocity.z * delta)
    }
    
    renderer.render(scene, camera)
}

---

TransformControls

Gizmo for translating, rotating, and scaling objects.

Constructor

class TransformControls(
    camera: Camera,
    domElement: HTMLElement
)

Properties

Property	Type	Default	Description
enabled	Boolean	true	Enable controls
mode	String	"translate"	Transform mode
space	String	"world"	Coordinate space
size	Float	1	Gizmo size
axis	String?	null	Active axis
showX	Boolean	true	Show X axis
showY	Boolean	true	Show Y axis
showZ	Boolean	true	Show Z axis
translationSnap	Float?	null	Translation snap
rotationSnap	Float?	null	Rotation snap
scaleSnap	Float?	null	Scale snap
dragging	Boolean	false	Is dragging

Modes

// Translation (move)
controls.setMode("translate")

// Rotation
controls.setMode("rotate")

// Scale
controls.setMode("scale")

Spaces

// World space
controls.setSpace("world")

// Local space (object-relative)
controls.setSpace("local")

Methods

// Attach to object
fun attach(object3d: Object3D): TransformControls

// Detach from object
fun detach(): TransformControls

// Set mode
fun setMode(mode: String)

// Set space
fun setSpace(space: String)

// Set size
fun setSize(size: Float)

// Get raycaster
fun getRaycaster(): Raycaster

fun dispose()

Events

controls.addEventListener("change") {
    renderer.render(scene, camera)
}

controls.addEventListener("dragging-changed") { event ->
    orbitControls.enabled = !event.value
}

controls.addEventListener("objectChange") {
    // Object was transformed
}

Example

val transformControls = TransformControls(camera, renderer.domElement)
scene.add(transformControls)

// Attach to selected object
transformControls.attach(selectedMesh)

// Keyboard shortcuts
document.addEventListener("keydown") { event ->
    when (event.key) {
        "g" -> transformControls.setMode("translate")
        "r" -> transformControls.setMode("rotate")
        "s" -> transformControls.setMode("scale")
        "x" -> transformControls.showX = !transformControls.showX
        "y" -> transformControls.showY = !transformControls.showY
        "z" -> transformControls.showZ = !transformControls.showZ
        " " -> transformControls.setSpace(
            if (transformControls.space == "local") "world" else "local"
        )
    }
}

// Disable orbit controls while transforming
transformControls.addEventListener("dragging-changed") { event ->
    orbitControls.enabled = !event.value
}

---

DragControls

Drag objects in the scene.

Constructor

class DragControls(
    objects: List<Object3D>,
    camera: Camera,
    domElement: HTMLElement
)

Properties

Property	Type	Default	Description
enabled	Boolean	true	Enable controls
transformGroup	Boolean	false	Transform group

Events

controls.addEventListener("dragstart") { event ->
    event.`object`.material.emissive.set(0xaaaaaa)
}

controls.addEventListener("drag") { event ->
    // Object being dragged
}

controls.addEventListener("dragend") { event ->
    event.`object`.material.emissive.set(0x000000)
}

controls.addEventListener("hoveron") { event ->
    // Hovering over object
}

controls.addEventListener("hoveroff") { event ->
    // No longer hovering
}

Example

val draggableObjects = listOf(cube1, cube2, cube3)
val dragControls = DragControls(draggableObjects, camera, renderer.domElement)

// Disable orbit while dragging
dragControls.addEventListener("dragstart") {
    orbitControls.enabled = false
}

dragControls.addEventListener("dragend") {
    orbitControls.enabled = true
}

---

ArcballControls

Arcball-style rotation controls.

Constructor

class ArcballControls(
    camera: Camera,
    domElement: HTMLElement,
    scene: Scene? = null
)

Properties

Similar to OrbitControls with additional:

Property	Type	Description
cursorZoom	Boolean	Zoom at cursor position
scaleFactor	Float	Zoom scale factor
focusAnimationTime	Float	Focus animation duration

---

See Also

• Camera API - Camera types
• Core API - Vector3, Raycaster
• Examples - Control examples