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.

feat(gameplay): how much is left has one author going up as well as down

esenginede9fdd68ef02
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index e9dd89b2b..93491c3c8 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 91,
- "experimental": 1793,
+ "experimental": 1794,
"deprecated": 3
},
- "total": 1997,
+ "total": 1998,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index e36b831c7..80d632a6e 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1629 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1630 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -12705,6 +12705,11 @@ ReplicationPlugin
(assets: AssetsData | null | undefined, ref: string): ResolvedTileset | undefined
```
+## restoreToFull — function @experimental
+```
+(world: World, entity: Entity): void
+```
+
## rootMotionVelocity — function @experimental
```
(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 5dd2c6a82..1e5603e9d 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 89 beta · 1648 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1649 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -12948,6 +12948,11 @@ ReplicationPlugin
(assets: AssetsData | null | undefined, ref: string): ResolvedTileset | undefined
```
+## restoreToFull — function @experimental
+```
+(world: World, entity: Entity): void
+```
+
## rootMotionVelocity — function @experimental
```
(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index bd2671975..900c34f47 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 86 beta · 1628 experimental · 3 deprecated
+Symbols: 113 public · 86 beta · 1629 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -12710,6 +12710,11 @@ ReplicationPlugin
(assets: AssetsData | null | undefined, ref: string): ResolvedTileset | undefined
```
+## restoreToFull — function @experimental
+```
+(world: World, entity: Entity): void
+```
+
## rootMotionVelocity — function @experimental
```
(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 650dc65dc..9bc45fa6a 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1650 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1651 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -12967,6 +12967,11 @@ ReplicationPlugin
(assets: AssetsData | null | undefined, ref: string): ResolvedTileset | undefined
```
+## restoreToFull — function @experimental
+```
+(world: World, entity: Entity): void
+```
+
## rootMotionVelocity — function @experimental
```
(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 52b4354bf..c1efbee81 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1640 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1641 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -12733,6 +12733,11 @@ ReplicationPlugin
(assets: AssetsData | null | undefined, ref: string): ResolvedTileset | undefined
```
+## restoreToFull — function @experimental
+```
+(world: World, entity: Entity): void
+```
+
## rootMotionVelocity — function @experimental
```
(delta: { x: number; z: number; }, seconds: number): { x: number; z: number; }
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index dce0b373a..2f79c124b 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -936,6 +936,7 @@ export {
Health,
Damage,
applyDamage,
+ restoreToFull,
MeleeAttack,
MeleeAttacks,
resolveMeleeHits,
diff --git a/sdk/src/gameplay/Health.ts b/sdk/src/gameplay/Health.ts
index cb7ab52d8..b99bc1a41 100644
--- a/sdk/src/gameplay/Health.ts
+++ b/sdk/src/gameplay/Health.ts
@@ -11,6 +11,10 @@
* health bar (armour, invulnerability, a shield) has one seam to sit in
* rather than an inlined subtraction to be found and edited.
*
+ * Going back UP is the same author's other verb. A respawn that reset
+ * the field itself would be a second one, and then "how much is left"
+ * has two answers whenever they disagree.
+ *
* The bus is double buffered, so a blow sent this frame lands on the
* next. That is one frame between the animation's hit moment and the
* number changing, and it buys a combat system that never reaches into
@@ -76,6 +80,20 @@ export const Damage: EventDef<DamagePayload> = defineEvent<DamagePayload>('Damag
* Land every blow in `blows`. The ONLY writer of `Health` — a blow aimed at
* something that has none, or at something already down, is simply not applied.
*/
+/**
+ * Put an entity back to full. The other half of this seam: a respawn restores
+ * what a blow took, and neither reaches into the field itself.
+ *
+ * `max` is the whole policy — there is no second notion of "full" to invent, and
+ * a caller that wants some other number wants a rule this seam does not have.
+ *
+ * @experimental
+ */
+export function restoreToFull(world: World, entity: Entity): void {
+ if (!world.valid(entity) || !world.has(entity, Health)) return;
+ world.update(entity, Health, (h: HealthData) => { h.current = h.max; });
+}
+
export function applyDamage(world: World, blows: Iterable<DamagePayload>): void {
for (const blow of blows) {
if (!world.valid(blow.target) || !world.has(blow.target, Health)) continue;
diff --git a/sdk/src/gameplay/index.ts b/sdk/src/gameplay/index.ts
index 8513fbe39..bd0cf9d7d 100644
--- a/sdk/src/gameplay/index.ts
+++ b/sdk/src/gameplay/index.ts
@@ -44,6 +44,7 @@ export {
Health,
Damage,
applyDamage,
+ restoreToFull,
type HealthData,
type DamagePayload,
} from './Health';
diff --git a/sdk/tests/combat.test.ts b/sdk/tests/combat.test.ts
index 0ccd870fe..f7a446a0e 100644
--- a/sdk/tests/combat.test.ts
+++ b/sdk/tests/combat.test.ts
@@ -6,7 +6,7 @@
*/
import { describe, it, expect } from 'vitest';
import {
- Health, Damage, applyDamage, MeleeAttack, MeleeAttacks, resolveMeleeHits,
+ Health, Damage, applyDamage, restoreToFull, MeleeAttack, MeleeAttacks, resolveMeleeHits,
COMBAT_ATTACK_START, COMBAT_HIT, COMBAT_ATTACK_END,
type HealthData, type DamagePayload, type MeleeAttackData, type MeleeOverlapQuery,
} from '../src/gameplay';
@@ -130,6 +130,35 @@ describe('a blow lands in exactly one place', () => {
expect((world.get(NEAR, Health) as HealthData).current).toBe(0);
});
+ it('goes back up through the same seam it came down', () => {
+ const world = scene();
+ applyDamage(world, [{ target: NEAR, source: ATTACKER, amount: 35, x: 0, y: 0, z: 0 }]);
+ expect((world.get(NEAR, Health) as HealthData).current).toBe(65);
+ restoreToFull(world, NEAR);
+ expect((world.get(NEAR, Health) as HealthData).current).toBe(100);
+ });
+
+ it('restores something already down, which is what a respawn is', () => {
+ const world = scene();
+ applyDamage(world, [{ target: NEAR, source: ATTACKER, amount: 999, x: 0, y: 0, z: 0 }]);
+ expect((world.get(NEAR, Health) as HealthData).current).toBe(0);
+ restoreToFull(world, NEAR);
+ expect((world.get(NEAR, Health) as HealthData).current).toBe(100);
+ });
+
+ it('full is the entity\u2019s own max, not a number this seam decided', () => {
+ const world = scene();
+ world.update(NEAR, Health, (h: HealthData) => { h.max = 40; h.current = 3; });
+ restoreToFull(world, NEAR);
+ expect((world.get(NEAR, Health) as HealthData).current).toBe(40);
+ });
+
+ it('restoring what has no health is not an error', () => {
+ const world = scene();
+ expect(() => restoreToFull(world, FLOOR)).not.toThrow();
+ expect(world.has(FLOOR, Health)).toBe(false);
+ });
+
it('passes over anything that has no health to lose', () => {
const world = scene();
expect(() => applyDamage(
diff --git a/tools/check-health-authority.mjs b/tools/check-health-authority.mjs
new file mode 100644
index 000000000..df83be0b7
--- /dev/null
+++ b/tools/check-health-authority.mjs
@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-health-authority.mjs — how much is left has one author.
+ *
+ * `applyDamage` is the seam a blow lands in, and the reason is that a second
+ * subtraction somewhere else makes armour, invulnerability and shields
+ * unimplementable: there is no one place to put them. Going back up is the same
+ * argument — a respawn that assigned the field itself was the second author, and
+ * for as long as it was there "full" meant whatever each caller thought.
+ *
+ * So: nothing outside Health.ts writes `current`. A game restores through
+ * `restoreToFull` and damages through the `Damage` bus, and both land here.
+ *
+ * node tools/check-health-authority.mjs
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { listTrackedSources } from './lib/sourceRoots.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The seam itself, which is where the writes are supposed to be. */
+const SEAM = 'sdk/src/gameplay/Health.ts';
+
+/** Source with comments gone: a `//` must not be able to satisfy or trip this. */
+const stripComments = (text) =>
+ text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+
+/**
+ * Assignment to a health `current`. Deliberately shaped around the NAME rather
+ * than the type: a checker that resolved types would need the compiler, and the
+ * field is spelled the same way in every writer worth catching.
+ */
+const WRITES = [
+ /\bh(?:ealth|p)?\.current\s*(?:=[^=]|[-+*/]=|\+\+|--)/,
+ /\.current\s*=\s*[^=]/,
+];
+
+/** Which of those lines are about Health rather than some other `.current`. */
+const ABOUT_HEALTH = /\bhealth\b|\bHealth\b|\bhp\b/;
+
+/**
+ * Second authors that are known and not yet dealt with. Each carries WHY, the
+ * same bargain every other declared gap in this repo strikes — and each must
+ * still be found, or the note is bookkeeping about code that has moved.
+ */
+const DECLARED = {
+ 'examples/celestial-heights/src/systems/save.ts':
+ 'the flagship carries a health value ACROSS scenes and restores a saved one, '
+ + 'which is neither a blow nor a reset to full — it needs a verb this seam '
+ + 'does not have yet, and inventing one for it here would be designing a '
+ + 'save system from a gate',
+};
+
+const problems = [];
+const declaredHits = new Set();
+const { files } = listTrackedSources(['sdk/src', 'examples', 'templates', 'pipeline/src']);
+for (const file of files.filter((f) => /\.ts$/.test(f) && !f.endsWith('.d.ts'))) {
+ if (file === SEAM) continue;
+ const lines = stripComments(readFileSync(path.join(ROOT, file), 'utf8')).split('\n');
+ for (const [i, line] of lines.entries()) {
+ if (!WRITES.some((re) => re.test(line))) continue;
+ if (!ABOUT_HEALTH.test(line)) continue;
+ if (DECLARED[file]) { declaredHits.add(file); continue; }
+ problems.push(`${file}:${i + 1} writes a health value outside ${SEAM}`
+ + ' — damage goes through the Damage bus, a reset through restoreToFull');
+ }
+}
+
+// ---- 2. and the author of health authors nothing else --------------------
+// The seam writes Health. A restore that also cleared a death flag would own a
+// fact the game owns, leaving "am I dead" with two authors.
+const seamSrc = stripComments(readFileSync(path.join(ROOT, SEAM), 'utf8'));
+for (const m of seamSrc.matchAll(/world\.update\(\s*[^,]+,\s*([A-Za-z_]\w*)/g)) {
+ if (m[1] !== 'Health') {
+ problems.push(`${SEAM} writes ${m[1]} — this seam owns how much is left and nothing else`);
+ }
+}
+
+// A declaration that no longer names a real writer is a note about code that has
+// moved on, and the next reader trusts it.
+for (const file of Object.keys(DECLARED)) {
+ if (!declaredHits.has(file)) {
+ problems.push(`${file} is declared as a second author and writes nothing — drop the entry`);
+ }
+}
+
+for (const file of declaredHits) console.log(` declared: ${file} — ${DECLARED[file]}`);
+for (const p of problems) console.log(`✗ ${p}`);
+console.log(problems.length === 0
+ ? `check-health-authority: ${files.length} file(s) — Health.current is written only in ${SEAM}`
+ : `check-health-authority: ${problems.length} finding(s)`);
+process.exit(problems.length === 0 ? 0 : 1);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 014f4065b..b0ffceff7 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -145,6 +145,7 @@ export const GATES = [
{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs', needs: 'editor' },
{ id: 'component-fields', run: 'node tools/check-component-fields.mjs' },
{ id: 'animator-parameters', run: 'node tools/check-animator-parameters.mjs' },
+ { id: 'health-authority', run: 'node tools/check-health-authority.mjs' },
// A field declares that it carries an asset in one place; everything that acts
// on live assets has to read THAT rather than keep a list of components beside it.
{ id: 'live-asset-rebind', run: 'node tools/check-live-asset-rebind.mjs' },