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 MeleeAttack.ts
* @brief The swing: when the animation says it connects, what was in the way,
* and who is allowed to be hurt by it.
*
* @details Three facts, kept apart on purpose:
*
* an animation event ≠ a hit ≠ damage
*
* The clip says only that the swing reached its effective moment. What
* is in that space is the physics world's answer, and what that does to
* anyone is gameplay's. Collapsing any two of them is what makes a
* combat system that cannot be re-aimed, re-timed or re-balanced.
*
* So: the animator posts `hit` and knows nothing about damage; the
* query is asked at the ANIMATED anchor and knows nothing about health;
* the filtering (self, already-hit, damageable) lives here and nowhere
* in the physics layer.
*/
import { defineComponent, type ComponentDef } from '../ecs/component';
import { Transform, type TransformData } from '../ecs/component';
import type { World } from '../ecs/world';
import type { Entity } from '../types';
import type { Overlap3DHit } from '../physics3d/Physics3DQueries';
import type { AnimatorEventPayload } from '../animation/animatorEvent';
import { Health, type DamagePayload, type HealthData } from './Health';
import { COMBAT_ATTACK_START, COMBAT_HIT, COMBAT_ATTACK_END } from './vocabulary';
export { COMBAT_ATTACK_START, COMBAT_HIT, COMBAT_ATTACK_END } from './vocabulary';
/** The fields of the `MeleeAttack` component. @experimental */
export interface MeleeAttackData {
/** Radius of the sphere a `hit` tests, in world units. */
radius: number;
/** What a landed blow takes off. */
damage: number;
/** Physics layers the swing can reach; 0 is every layer. */
layers: number;
/**
* The entity whose WORLD placement the query is centred on — a socket under
* an animated joint, so where the swing reaches is what the animation did.
* 0 falls back to the attacker itself, which is a body slam, not a sword.
*/
anchor: Entity;
enabled: boolean;
/** Engine-written: the live swing, or 0 when none is running. */
attackId: number;
/** Engine-written: how many targets the live swing has landed on. */
hitCount: number;
}
/**
* A melee swing whose timing is the animation's and whose reach is the physics
* world's. Add it beside an `Animator` whose attack clip declares `attack-start`,
* `hit` and `attack-end`.
*
* @experimental
*/
export const MeleeAttack: ComponentDef<MeleeAttackData> =
defineComponent<MeleeAttackData>('MeleeAttack', {
radius: 60,
damage: 25,
layers: 0,
anchor: 0 as Entity,
enabled: true,
attackId: 0,
hitCount: 0,
}, {
// World lengths and speeds: written at 100 units a metre, scaled to the project (ecs/worldUnits.ts).
worldUnitFields: ['radius'],
entityFields: ['anchor'],
readonlyFields: ['attackId', 'hitCount'],
fields: {
radius: { min: 0 },
damage: { min: 0 },
layers: { min: 0, max: 15, step: 1, advanced: true },
anchor: { tooltip: 'The animated socket the swing reaches from.' },
attackId: { advanced: true },
hitCount: { advanced: true },
},
});
// =============================================================================
// Attack instances — what makes one swing land once
// =============================================================================
interface LiveAttack {
id: number;
/** Everything this swing has already landed on. */
hit: Set<Entity>;
}
/**
* The swings currently in the air, one per attacker: ONE swing lands on a target
* once, and the next one may land again. Leaning on "the event only fires once"
* is a contract the first multi-frame hit window breaks, and breaks silently —
* double damage reads as a balance problem, not a bug.
*/
export class MeleeAttacks {
private readonly live_ = new Map<Entity, LiveAttack>();
private nextId_ = 1;
/** Begin a swing, ending whatever this attacker had in the air. */
open(entity: Entity): number {
const id = this.nextId_++;
this.live_.set(entity, { id, hit: new Set() });
return id;
}
close(entity: Entity): void {
this.live_.delete(entity);
}
live(entity: Entity): { id: number; hits: number } | null {
const attack = this.live_.get(entity);
return attack ? { id: attack.id, hits: attack.hit.size } : null;
}
/**
* Record `target` as hit by this attacker's live swing. False when the swing
* already reached it, which is the whole point.
*/
record(entity: Entity, target: Entity): boolean {
const attack = this.live_.get(entity);
if (!attack || attack.hit.has(target)) return false;
attack.hit.add(target);
return true;
}
/** Drop an attacker's swing (wire to world.onDespawn). */
forget(entity: Entity): void {
this.live_.delete(entity);
}
clear(): void {
this.live_.clear();
}
}
// =============================================================================
// Resolution
// =============================================================================
/**
* The only thing a swing asks the physics world. Narrow on purpose: what is in
* this space is all physics can answer, and `Physics3DQueries` satisfies it
* without combat depending on the rest of that surface.
*/
export interface MeleeOverlapQuery {
overlapSphere(
centre: { x: number; y: number; z: number }, radius: number, layerMask?: number,
): readonly Overlap3DHit[];
}
/** Where a swing reaches from: the animated anchor, else the attacker itself. */
function anchorOf(world: World, attacker: Entity, attack: MeleeAttackData): Entity {
const anchor = attack.anchor;
return anchor && world.valid(anchor) && world.has(anchor, Transform) ? anchor : attacker;
}
/** Publish what the live swing is, for an inspector and for a driver to read. */
function publish(world: World, entity: Entity, attacks: MeleeAttacks): void {
const live = attacks.live(entity);
world.update(entity, MeleeAttack, (data: MeleeAttackData) => {
data.attackId = live?.id ?? 0;
data.hitCount = live?.hits ?? 0;
});
}
/**
* Turn the animation events an attacker posted into blows.
*
* Runs on LAST frame's events, before this frame's animator poses anything:
* the joints still hold the pose that produced the event, so the swing is asked
* about the space it was actually in.
*/
export function resolveMeleeHits(
world: World, attacks: MeleeAttacks, queries: MeleeOverlapQuery | null,
events: Iterable<AnimatorEventPayload>,
damage: { send(blow: DamagePayload): void },
): void {
for (const event of events) {
const attacker = event.entity;
if (!world.valid(attacker) || !world.has(attacker, MeleeAttack)) continue;
const attack = world.get(attacker, MeleeAttack) as MeleeAttackData;
if (!attack.enabled) continue;
// A swing already in the air when its owner went down lands on nobody:
// the animator keeps playing whatever it was playing, and "the attack
// stops" cannot be left to whoever remembers to switch this off.
if (world.has(attacker, Health)
&& (world.get(attacker, Health) as HealthData).current <= 0) continue;
if (event.name === COMBAT_ATTACK_START) {
attacks.open(attacker);
publish(world, attacker, attacks);
continue;
}
if (event.name === COMBAT_ATTACK_END) {
attacks.close(attacker);
publish(world, attacker, attacks);
continue;
}
if (event.name !== COMBAT_HIT) continue;
// A clip that says only `hit` still gets an instance, so its dedup holds;
// the ceremony is for clips with a window, not a requirement.
if (!attacks.live(attacker)) attacks.open(attacker);
const anchor = anchorOf(world, attacker, attack);
// The anchor hangs off an animated joint, so its world placement is
// composed rather than stored. O(1) when nothing moved.
world.ensureTransformsComposed();
const placement = world.get(anchor, Transform) as TransformData;
const centre = placement.worldPosition ?? placement.position;
for (const found of queries?.overlapSphere(centre, attack.radius, attack.layers) ?? []) {
// Gameplay's rules, none of them the physics world's to know.
if (found.entity === attacker) continue;
if (!world.valid(found.entity) || !world.has(found.entity, Health)) continue;
if (!attacks.record(attacker, found.entity)) continue;
damage.send({
target: found.entity, source: attacker, amount: attack.damage,
x: found.x, y: found.y, z: found.z,
});
}
publish(world, attacker, attacks);
}
}