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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file GameplayPlugin.ts
* @brief Wires the third-person character and its camera into the frame.
*
* @details Three systems, and WHERE they sit is the design. The controller asks
* before the physics step and observes after it, so what reaches the
* animator is the motion the world allowed rather than the motion the
* player asked for. The camera runs once a frame, after everything has
* moved, because it follows and is never followed.
*/
import type { App, Plugin } from '../app/app';
import { defineSystem, Schedule } from '../ecs/system';
import { Res, Time, type TimeData } from '../ecs/resource';
import { playModeOnly } from '../ecs/env';
import { Input, type InputState } from '../input/input';
import { Transform, type TransformData } from '../ecs/component';
import { CharacterController3D, type CharacterController3DData } from '../physics3d/Physics3DComponents';
import { Physics3D, Physics3DRuntime } from '../physics3d/Physics3DPlugin';
import type { Physics3DQueries } from '../physics3d/Physics3DQueries';
import { Animator, AnimatorController, type AnimatorControllerAPI } from '../animation/Animator';
import {
AnimatorRootMotion, type AnimatorRootMotionData,
} from '../animation/animatorRootMotion';
import { AnimatorEvent, type AnimatorEventPayload } from '../animation/animatorEvent';
import { EventReader, EventWriter, type EventWriterInstance } from '../ecs/event';
import { Damage, applyDamage, type DamagePayload } from './Health';
import { MeleeAttacks, resolveMeleeHits } from './MeleeAttack';
import { huntTargets } from './Hunter';
import { q } from '../math/quat';
import { look as lookFirstPerson, move as moveFirstPerson, installViewModels, TouchLook } from './firstPersonSystems';
import type { World } from '../ecs/world';
import type { Entity } from '../types';
import { Playthrough } from '../runtime/playthrough';
import {
ThirdPersonController, type ThirdPersonControllerData,
desiredDirection, approachVelocity, facingYaw, turnToward, rootMotionVelocity,
yawQuaternion, yawOfQuaternion, WORLD_BASIS, DODGE_KEY, ATTACK_KEY,
TPC_SPEED, TPC_GROUNDED, TPC_DODGE, TPC_ATTACK, TPC_JUMP, type MoveBasis,
} from './ThirdPersonController';
import {
ThirdPersonCamera, type ThirdPersonCameraData,
orbitOffset, cameraGroundBasis, dampFactor, clampPitch,
} from './ThirdPersonCamera';
/**
* What the animation is asking this character to do, or null when nothing is.
* Presence of the component is the opt-in and `active` is the switch — "the
* delta is non-zero" is not, being false in the still moment inside a dodge.
*/
function rootMotionRequest(world: World, entity: Entity): AnimatorRootMotionData | null {
if (!world.has(entity, AnimatorRootMotion)) return null;
const data = world.get(entity, AnimatorRootMotion) as AnimatorRootMotionData;
return data.active ? data : null;
}
/** The stick, from the keys a keyboard stands in for one with. */
function readStick(input: InputState): { x: number; y: number } {
const x = (input.isKeyDown('KeyD') ? 1 : 0) - (input.isKeyDown('KeyA') ? 1 : 0);
const y = (input.isKeyDown('KeyW') ? 1 : 0) - (input.isKeyDown('KeyS') ? 1 : 0);
const length = Math.hypot(x, y);
return length > 1 ? { x: x / length, y: y / length } : { x, y };
}
/** The camera a controller reads forward from: the one it names, else any. */
function basisFor(world: World, data: ThirdPersonControllerData): MoveBasis {
if (!data.cameraRelative) return WORLD_BASIS;
const named = data.camera && world.has(data.camera, ThirdPersonCamera)
? data.camera
: world.getEntitiesWithComponents([ThirdPersonCamera])[0];
if (named === undefined) return WORLD_BASIS;
return cameraGroundBasis((world.get(named, ThirdPersonCamera) as ThirdPersonCameraData).yaw);
}
/**
* Ask for motion: the stick, in the camera's ground plane, as a velocity the
* character controller will try to honour. The vertical component is left alone
* unless a jump starts one, because the character controller carries it.
*/
export function requestMotion(
world: World, input: InputState, dt: number,
animator: AnimatorControllerAPI | null = null,
): void {
for (const entity of world.getEntitiesWithComponents([ThirdPersonController, CharacterController3D])) {
const data = world.get(entity, ThirdPersonController) as ThirdPersonControllerData;
if (!data.enabled) continue;
if (animator && world.has(entity, Animator)) {
// A press asks for the ACTION; which clip that is, and whether this
// character has one at all, stays the animator graph's answer.
if (input.isKeyPressed(DODGE_KEY)) animator.setTrigger(entity, TPC_DODGE);
if (input.isKeyPressed(ATTACK_KEY)) animator.setTrigger(entity, TPC_ATTACK);
}
const character = world.get(entity, CharacterController3D) as CharacterController3DData;
// Which of the two states the character's movement: the stick, or the
// animation that declared itself in charge. Chosen HERE and not by the
// animator, which states a request and never a position.
const driven = rootMotionRequest(world, entity);
let next: { x: number; z: number };
if (driven) {
next = rootMotionVelocity(driven.deltaPosition, driven.deltaTime);
} else {
const direction = desiredDirection(readStick(input), basisFor(world, data));
const target = {
x: direction.x * data.moveSpeed,
z: direction.z * data.moveSpeed,
};
// Off the ground the player has only as much say as airControl allows.
const authority = character.isOnFloor ? 1 : Math.max(0, Math.min(1, data.airControl));
next = approachVelocity(
{ x: character.velocity.x, z: character.velocity.z }, target,
data.acceleration * authority, data.deceleration * authority, dt,
);
}
// A jump is the one time the vertical is ours to set; every other frame
// it stays 0, which the character controller reads as "walk". Not while an
// animation is driving: two things setting the vertical is one too many.
const jumping = !driven && data.jumpSpeed > 0 && character.isOnFloor
&& (input.isKeyPressed('Space') || input.isKeyDown('Space'));
world.update(entity, CharacterController3D, (c: CharacterController3DData) => {
c.velocity.x = next.x;
c.velocity.z = next.z;
c.velocity.y = jumping ? data.jumpSpeed : 0;
});
// The jump that was APPLIED, not the key that asked for one. An edge
// rather than a level: this runs on the fixed clock and the animator on
// the frame's, so a whole arc can pass between two of its samples.
if (jumping && animator && world.has(entity, Animator)) {
animator.setTrigger(entity, TPC_JUMP);
}
}
}
/**
* Observe what happened. The animator is told the speed the character REACHED,
* so walking into a wall reads as standing still, and the character turns to
* face where it actually went.
*/
export function observeMotion(world: World, animator: AnimatorControllerAPI | null, dt: number): void {
for (const entity of world.getEntitiesWithComponents([ThirdPersonController, CharacterController3D])) {
const data = world.get(entity, ThirdPersonController) as ThirdPersonControllerData;
if (!data.enabled) continue;
const character = world.get(entity, CharacterController3D) as CharacterController3DData;
const moved = character.realVelocity;
const speed = Math.hypot(moved.x, moved.z);
if (animator && world.has(entity, Animator)) {
animator.setFloat(entity, TPC_SPEED, speed < data.idleThreshold ? 0 : speed);
animator.setBool(entity, TPC_GROUNDED, character.isOnFloor);
}
if (!world.has(entity, Transform)) continue;
// While an animation is driving, the heading is the animation's too —
// turning to face the motion as well would be a second author of the
// yaw, and the two disagree the moment a dodge goes sideways.
const driven = rootMotionRequest(world, entity);
if (driven) {
if (driven.deltaTime <= 0) continue;
// This step's share of the frame's turn: the animator states one per
// rendered frame, and this runs once per fixed step inside it.
const step = q.scaled(driven.deltaRotation, Math.min(dt / driven.deltaTime, 1));
world.update(entity, Transform, (t: TransformData) => {
const turned = q.normalize(q.mul(t.rotation, step));
t.rotation.w = turned.w; t.rotation.x = turned.x;
t.rotation.y = turned.y; t.rotation.z = turned.z;
});
continue;
}
// Face where it is going, not where it was asked to go - and hold the
// last heading when it stops, rather than snapping back to world forward.
if (speed < data.idleThreshold) continue;
const wanted = facingYaw({ x: moved.x, y: 0, z: moved.z });
world.update(entity, Transform, (t: TransformData) => {
const turned = turnToward(yawOfQuaternion(t.rotation), wanted, data.rotationSpeed, dt);
const yaw = yawQuaternion(turned);
t.rotation.w = yaw.w; t.rotation.x = yaw.x; t.rotation.y = yaw.y; t.rotation.z = yaw.z;
});
}
}
/** Per-camera pointer state, so a delta exists without the input layer keeping one. */
const lastPointer = new Map<Entity, { x: number; y: number }>();
/**
* How far back the eye may sit before something solid is in the way. The probe
* is a sphere so the eye stops short of a wall rather than touching it.
*/
function clearDistance(
queries: Physics3DQueries | null, data: ThirdPersonCameraData,
pivot: { x: number; y: number; z: number }, offset: { x: number; y: number; z: number },
): number {
if (!data.obstruction || !queries || data.distance <= 0) return data.distance;
const hit = queries.sphereCast(
pivot, data.obstructionRadius,
{ x: offset.x * data.distance, y: offset.y * data.distance, z: offset.z * data.distance },
data.obstructionLayers,
);
if (!hit) return data.distance;
// The hit is a FRACTION of the sweep, and the sweep was the full distance.
return Math.max(0, Math.min(data.distance, hit.fraction * data.distance));
}
export function updateCameras(
world: World, input: InputState, queries: Physics3DQueries | null, dt: number,
): void {
for (const entity of world.getEntitiesWithComponents([ThirdPersonCamera, Transform])) {
const data = world.get(entity, ThirdPersonCamera) as ThirdPersonCameraData;
if (!data.enabled || !data.target || !world.has(data.target, Transform)) continue;
const pointer = input.getMousePosition();
const previous = lastPointer.get(entity);
lastPointer.set(entity, { x: pointer.x, y: pointer.y });
// Only while a button is held: a free pointer over the window is not
// someone turning the camera.
const dragging = input.isMouseButtonDown(0) || input.isMouseButtonDown(2);
let { yaw, pitch } = data;
if (previous && dragging) {
yaw -= (pointer.x - previous.x) * data.sensitivity;
pitch = clampPitch(pitch + (pointer.y - previous.y) * data.sensitivity,
data.minPitch, data.maxPitch);
}
if (yaw !== data.yaw || pitch !== data.pitch) {
world.update(entity, ThirdPersonCamera, (c: ThirdPersonCameraData) => {
c.yaw = yaw; c.pitch = pitch;
});
}
const targetTransform = world.get(data.target, Transform) as TransformData;
const pivot = {
x: targetTransform.position.x + data.targetOffset.x,
y: targetTransform.position.y + data.targetOffset.y,
z: targetTransform.position.z + data.targetOffset.z,
};
const offset = orbitOffset(yaw, pitch);
const distance = clearDistance(queries, data, pivot, offset);
const wanted = {
x: pivot.x + offset.x * distance,
y: pivot.y + offset.y * distance,
z: pivot.z + offset.z * distance,
};
const k = dampFactor(data.followDamping, dt);
world.update(entity, Transform, (t: TransformData) => {
t.position.x += (wanted.x - t.position.x) * k;
t.position.y += (wanted.y - t.position.y) * k;
t.position.z += (wanted.z - t.position.z) * k;
// Looking back down the offset it sits along: pitch tips the eye
// down when the camera is above, which is the negative turn about X.
const half = { p: -pitch * Math.PI / 360, y: yaw * Math.PI / 360 };
const cp = Math.cos(half.p), sp = Math.sin(half.p);
const cy = Math.cos(half.y), sy = Math.sin(half.y);
t.rotation.w = cp * cy;
t.rotation.x = sp * cy;
t.rotation.y = cp * sy;
t.rotation.z = -sp * sy;
});
}
}
export class GameplayPlugin implements Plugin {
name = 'gameplay';
private offDespawn_: (() => void) | null = null;
private offViewModels_: (() => void) | null = null;
/** Per App, not per module: two Apps in one process must not share swings. */
private readonly attacks_ = new MeleeAttacks();
build(app: App): void {
const world = app.world;
// Always present, empty until a game states something. Absent, a driver
// cannot tell "this game publishes nothing" from "the seam is broken".
app.insertResource(Playthrough, { facts: {} });
const attacks = this.attacks_;
this.offDespawn_ = world.onDespawn((entity: Entity) => {
lastPointer.delete(entity);
attacks.forget(entity);
});
// BEFORE this frame's animator: the events are last frame's, and the
// joints still hold the pose that posted them. Running after would ask
// the query about a swing that has already moved on.
app.addSystemToSchedule(Schedule.PreUpdate, defineSystem(
[EventReader(AnimatorEvent), EventWriter(Damage)],
(
events: Iterable<AnimatorEventPayload>,
damage: EventWriterInstance<DamagePayload>,
) => {
const queries = app.hasResource(Physics3D) ? app.getResource(Physics3D) : null;
resolveMeleeHits(world, attacks, queries, events, damage);
},
{ name: 'MeleeAttackSystem' },
), { runIf: playModeOnly });
// The only writer of Health, and it reads a request rather than being
// called by whatever swung.
app.addSystemToSchedule(Schedule.PreUpdate, defineSystem(
[EventReader(Damage)],
(blows: Iterable<DamagePayload>) => { applyDamage(world, blows); },
{ name: 'DamageSystem' },
), { runIf: playModeOnly });
// Perception wrote what each hunter can see this frame; navigation plans
// in Update. Deciding between the two is what makes a destination set
// here the one planned on the same frame it was chosen.
app.addSystemToSchedule(Schedule.PreUpdate, defineSystem(
[Res(Time)],
(time: TimeData) => {
const animator = app.hasResource(AnimatorController)
? app.getResource(AnimatorController) : null;
huntTargets(world, animator, TPC_ATTACK, time.delta);
},
{ name: 'HunterSystem' },
), { runAfter: ['PerceptionSystem'], runIf: playModeOnly });
// Before the physics step: what the player is asking for.
app.addSystemToSchedule(Schedule.FixedPreUpdate, defineSystem(
[Res(Time), Res(Input)],
(time: TimeData, input: InputState) => {
const animator = app.hasResource(AnimatorController)
? app.getResource(AnimatorController) : null;
requestMotion(world, input, time.fixedDelta, animator);
},
{ name: 'ThirdPersonControllerSystem' },
), { runIf: playModeOnly });
// Looking is a per-frame thing (the pointer moves between steps); walking is asked of the character on the fixed clock, like the third-person layer.
const touchLook = new TouchLook();
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(Input)],
(time: TimeData, input: InputState) => { lookFirstPerson(world, input, time.delta, touchLook); },
{ name: 'FirstPersonLookSystem' },
), { runIf: playModeOnly });
app.addSystemToSchedule(Schedule.FixedPreUpdate, defineSystem(
[Res(Time), Res(Input)],
(time: TimeData, input: InputState) => {
const queries = app.hasResource(Physics3D) ? app.getResource(Physics3D) : null;
// The world's gravity in world units per second squared, for a player whose own differs from it.
const config = app.hasResource(Physics3DRuntime) ? app.getResource(Physics3DRuntime).config : null;
moveFirstPerson(world, input, queries, time.fixedDelta, config ? config.gravity.y * config.pixelsPerUnit : 0);
},
{ name: 'FirstPersonControllerSystem' },
), { runIf: playModeOnly });
this.offViewModels_ = installViewModels(app);
// After it: what the world allowed. The animator hears this one.
app.addSystemToSchedule(Schedule.FixedPostUpdate, defineSystem(
[Res(Time)],
(time: TimeData) => {
const animator = app.hasResource(AnimatorController)
? app.getResource(AnimatorController) : null;
observeMotion(world, animator, time.fixedDelta);
},
{ name: 'ThirdPersonObserveSystem' },
), { runIf: playModeOnly });
// Once a frame, after everything it follows has moved.
app.addSystemToSchedule(Schedule.PostUpdate, defineSystem(
[Res(Time), Res(Input)],
(time: TimeData, input: InputState) => {
const queries = app.hasResource(Physics3D) ? app.getResource(Physics3D) : null;
updateCameras(world, input, queries, time.delta);
},
{ name: 'ThirdPersonCameraSystem' },
), { runIf: playModeOnly });
}
cleanup(): void {
this.offDespawn_?.();
this.offDespawn_ = null;
this.offViewModels_?.();
this.offViewModels_ = null;
lastPointer.clear();
this.attacks_.clear();
}
}
export const gameplayPlugin = new GameplayPlugin();