Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

7.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ThirdPersonController.ts
 * @brief   Input to a walking character, and the character's real motion back
 *          out to its animator.
 *
 * @details It decides what the player WANTS - a direction in the camera's ground
 *          plane, a speed to reach it at, a jump - and asks
 *          CharacterController3D for it. What actually happens is the physics
 *          world's answer, and that answer, not the request, is what reaches the
 *          animator: a character shoving a wall has a full stick and no motion,
 *          and it must not be running on the spot.
 *
 *          It solves no collision, owns no gravity (the character controller
 *          carries the vertical component), and names no animation clip.
 */

import { defineComponent, type ComponentDef } from '../ecs/component';
import type { Entity } from '../types';
import type { Vec3 } from '../types';

// The names authored content reaches this through live on `esengine`; the
// runtime does not, so they are declared apart from it.
export {
    TPC_SPEED, TPC_GROUNDED, TPC_JUMP, TPC_DODGE, TPC_ATTACK, DODGE_KEY, ATTACK_KEY,
} from './vocabulary';

/** The fields of the `ThirdPersonController` component. @experimental */
export interface ThirdPersonControllerData {
    /** Top speed on the ground, world units per second. */
    moveSpeed: number;
    /** How fast it reaches that speed, units per second squared. */
    acceleration: number;
    /** How fast it sheds it when the stick centres. */
    deceleration: number;
    /** How fast it turns to face where it is going, degrees per second. */
    rotationSpeed: number;
    /** Upward speed a jump starts with; 0 disables jumping. */
    jumpSpeed: number;
    /** How much of `acceleration` applies while off the ground, 0..1. */
    airControl: number;
    /** Read the stick in the camera's ground plane rather than the world's. */
    cameraRelative: boolean;
    /** The camera that defines "forward". 0 = the first ThirdPersonCamera found. */
    camera: Entity;
    /** Speed under which the animator is told the character is standing still. */
    idleThreshold: number;
    enabled: boolean;
}

/**
 * Drives a CharacterController3D from player input, and reports what the
 * character actually did to its Animator.
 *
 * @experimental
 */
export const ThirdPersonController: ComponentDef<ThirdPersonControllerData> =
    defineComponent<ThirdPersonControllerData>('ThirdPersonController', {
        moveSpeed: 320,
        acceleration: 2400,
        deceleration: 3200,
        rotationSpeed: 720,
        jumpSpeed: 0,
        airControl: 0.3,
        cameraRelative: true,
        camera: 0 as Entity,
        idleThreshold: 8,
        enabled: true,
    }, {
    // World lengths and speeds: written at 100 units a metre, scaled to the project (ecs/worldUnits.ts).
    worldUnitFields: ['moveSpeed', 'acceleration', 'deceleration', 'jumpSpeed', 'idleThreshold'],
        entityFields: ['camera'],
        fields: {
            camera: { tooltip: 'Whose forward the stick is read against.' },
            rotationSpeed: { unit: '°/s' },
            airControl: { min: 0, max: 1, step: 0.05, advanced: true },
            idleThreshold: { min: 0, step: 0.05, advanced: true },
            jumpSpeed: { min: 0, tooltip: 'Upward speed a jump starts with. 0 = cannot jump.' },
        },
    });

// =============================================================================
// The decisions, as pure functions
// =============================================================================

const DEG2RAD = Math.PI / 180;
const RAD2DEG = 180 / Math.PI;

/** A basis to read the stick against: two ground-plane axes. */
export interface MoveBasis {
    forward: Vec3;
    right: Vec3;
}

/** The world basis, for a controller reading its stick without a camera. */
export const WORLD_BASIS: MoveBasis = {
    forward: { x: 0, y: 0, z: -1 },
    right: { x: 1, y: 0, z: 0 },
};

/**
 * Where the player is asking to go, as a unit vector on the ground plane.
 * Zero-length when the stick is centred, which is a stop rather than a
 * direction. `input.y` is forward on the stick, `input.x` is right.
 */
export function desiredDirection(
    input: { x: number; y: number }, basis: MoveBasis,
): Vec3 {
    const x = basis.forward.x * input.y + basis.right.x * input.x;
    const z = basis.forward.z * input.y + basis.right.z * input.x;
    const length = Math.hypot(x, z);
    if (length < 1e-6) return { x: 0, y: 0, z: 0 };
    return { x: x / length, y: 0, z: z / length };
}

/**
 * Move a horizontal velocity toward what was asked for. Accelerating and
 * stopping are separate rates because a character that coasts to a halt as
 * slowly as it gets going feels like it is on ice.
 */
export function approachVelocity(
    current: { x: number; z: number }, target: { x: number; z: number },
    acceleration: number, deceleration: number, dt: number,
): { x: number; z: number } {
    const dx = target.x - current.x;
    const dz = target.z - current.z;
    const gap = Math.hypot(dx, dz);
    if (gap < 1e-6) return { x: target.x, z: target.z };

    const slowing = Math.hypot(target.x, target.z) < Math.hypot(current.x, current.z);
    const step = (slowing ? deceleration : acceleration) * dt;
    if (step >= gap) return { x: target.x, z: target.z };
    return { x: current.x + (dx / gap) * step, z: current.z + (dz / gap) * step };
}

/** The heading, in degrees about world up, that a ground direction points at. */
export function facingYaw(direction: Vec3): number {
    return Math.atan2(-direction.x, -direction.z) * RAD2DEG;
}

/** The signed shortest way from `from` to `to`, in degrees. */
export function shortestAngleDelta(from: number, to: number): number {
    let delta = (to - from) % 360;
    if (delta > 180) delta -= 360;
    if (delta < -180) delta += 360;
    return delta;
}

/**
 * The velocity a root-motion request comes to over the seconds it covers. A RATE,
 * because the animator states one per rendered frame while the character steps on
 * its own clock: adding the displacement moves twice on a frame with two steps.
 */
export function rootMotionVelocity(
    delta: { x: number; z: number }, seconds: number,
): { x: number; z: number } {
    if (seconds <= 0) return { x: 0, z: 0 };
    return { x: delta.x / seconds, z: delta.z / seconds };
}

/**
 * Turn `from` toward `to` at a rate. The shortest way round, so a character
 * crossing the -180/180 seam does not spin the long way to get there.
 */
export function turnToward(from: number, to: number, degreesPerSecond: number, dt: number): number {
    const delta = shortestAngleDelta(from, to);
    if (degreesPerSecond <= 0) return to;
    const step = degreesPerSecond * dt;
    if (Math.abs(delta) <= step) return to;
    return from + Math.sign(delta) * step;
}

/** A yaw in degrees as the rotation quaternion about world up. */
export function yawQuaternion(yawDeg: number): { w: number; x: number; y: number; z: number } {
    const half = yawDeg * DEG2RAD * 0.5;
    return { w: Math.cos(half), x: 0, y: Math.sin(half), z: 0 };
}

/** The yaw a rotation about world up carries, in degrees. */
export function yawOfQuaternion(q: { w: number; y: number }): number {
    return 2 * Math.atan2(q.y, q.w) * RAD2DEG;
}