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
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.jsonindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsnew file mode 100644index 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.mjsindex 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' },