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(net): interest as prepare-once, query-many
esengine9a833d4bb9c9
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 63015a999..cd024c2ec 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -6546,6 +6546,7 @@ inputOf: (connectionId: number) => ReplInputMsg | nullnetIds: NetIdssample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => void+setInterestProvider: (provider: InterestProvider | null) => voidtable: ReplicationTabletickInputOf: (connectionId: number) => ReplInputMsg | nullstatic new (world: World): ReplicationServerdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 35f7cfe9d..15a9fd397 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -6739,6 +6739,7 @@ inputOf: (connectionId: number) => ReplInputMsg | nullnetIds: NetIdssample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => void+setInterestProvider: (provider: InterestProvider | null) => voidtable: ReplicationTabletickInputOf: (connectionId: number) => ReplInputMsg | nullstatic new (world: World): ReplicationServerdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 1b2bdef01..70dedbcac 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -6541,6 +6541,7 @@ inputOf: (connectionId: number) => ReplInputMsg | nullnetIds: NetIdssample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => void+setInterestProvider: (provider: InterestProvider | null) => voidtable: ReplicationTabletickInputOf: (connectionId: number) => ReplInputMsg | nullstatic new (world: World): ReplicationServerdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex ac1ea3dec..807cbfa77 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -6787,6 +6787,7 @@ inputOf: (connectionId: number) => ReplInputMsg | nullnetIds: NetIdssample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => void+setInterestProvider: (provider: InterestProvider | null) => voidtable: ReplicationTabletickInputOf: (connectionId: number) => ReplInputMsg | nullstatic new (world: World): ReplicationServerdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 6032df9c2..6025e3419 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -6548,6 +6548,7 @@ inputOf: (connectionId: number) => ReplInputMsg | nullnetIds: NetIdssample: (tick: number) => voidsetInterestPolicy: (policy: InterestPolicy | null) => void+setInterestProvider: (provider: InterestProvider | null) => voidtable: ReplicationTabletickInputOf: (connectionId: number) => ReplInputMsg | nullstatic new (world: World): ReplicationServerdiff --git a/sdk/src/net/replication/index.ts b/sdk/src/net/replication/index.tsindex 973da1489..9d64c5716 100644--- a/sdk/src/net/replication/index.ts+++ b/sdk/src/net/replication/index.ts@@ -36,8 +36,13 @@ export {export { Replicated, NetGhost, type ReplicatedData } from './components';export {radiusInterest,+ radiusInterestProvider,type InterestPolicy,type InterestView,+ type InterestProvider,+ type InterestProviderPrepareView,+ type InterestProviderQueryView,+ type PreparedInterest,type RadiusInterestOptions,} from './interest';export { NetIds } from './NetIds';diff --git a/sdk/src/net/replication/interest.ts b/sdk/src/net/replication/interest.tsindex 005facb53..27dc1aedb 100644--- a/sdk/src/net/replication/interest.ts+++ b/sdk/src/net/replication/interest.ts@@ -38,6 +38,47 @@ export interface InterestView {*/export type InterestPolicy = (view: InterestView) => ReadonlySet<Entity> | 'all';+/**+ * What a provider is given to build one snapshot from.+ *+ * `entities` is an iterable, not an array: a provider that scans the population+ * may, but installing one must not itself cost an O(population) materialization.+ *+ * @experimental+ */+export interface InterestProviderPrepareView {+ readonly world: World;+ readonly entities: Iterable<Entity>;+ readonly entityCount: number;+}++/** What a prepared snapshot is asked about one connection. @experimental */+export interface InterestProviderQueryView {+ readonly connectionId: number;+ /** The entities this connection owns. The SERVER still forces them visible;+ * this is here so a provider can place its view. */+ readonly owned: readonly Entity[];+}++/** One snapshot, queried by every connection evaluated against it. @experimental */+export interface PreparedInterest {+ query(view: InterestProviderQueryView): ReadonlySet<Entity> | 'all';+}++/**+ * Relevance as prepare-once, query-many. A {@link InterestPolicy} is handed the+ * population per connection, so what it reads it reads C times; a provider+ * prepares one snapshot and answers every connection from it.+ *+ * @experimental+ */+export interface InterestProvider {+ prepare(view: InterestProviderPrepareView): PreparedInterest;+ /** Release anything held across samples. A provider that rebuilds owns+ * nothing; one that maintains an index between samples does. */+ dispose?(): void;+}+/** Where an entity is, for the distance a policy measures. `z` is optional so a* flat game's reader can keep answering in two. */export interface InterestPoint {@@ -108,3 +149,77 @@ function defaultPosition(world: World, entity: Entity): InterestPoint | null {const t = world.tryGet(entity, Transform) as { position?: { x: number; y: number; z?: number } } | null;return t?.position ? { x: t.position.x, y: t.position.y, z: t.position.z ?? 0 } : null;}++/**+ * {@link radiusInterest} as a provider: one pass over the population per sample,+ * then a local lookup per connection. Rebuilt every sample, so an arbitrary+ * `position` reader needs no invalidation contract and is evaluated once per+ * entity per snapshot. Keeps every rule the policy has.+ *+ * @experimental+ * @see radiusInterest+ */+export function radiusInterestProvider(+ radius: number,+ options: RadiusInterestOptions = {},+): InterestProvider {+ const r2 = radius * radius;+ const positionOf = options.position ?? defaultPosition;+ const cell = Math.max(radius, Number.EPSILON);+ const key = (x: number, y: number, z: number): string =>+ `${Math.floor(x / cell)},${Math.floor(y / cell)},${Math.floor(z / cell)}`;++ return {+ prepare({ world, entities }): PreparedInterest {+ const at = new Map<Entity, InterestPoint>();+ const placeless: Entity[] = [];+ const cells = new Map<string, Entity[]>();+ for (const e of entities) {+ const p = positionOf(world, e);+ if (!p) { placeless.push(e); continue; }+ at.set(e, p);+ const k = key(p.x, p.y, p.z ?? 0);+ const bucket = cells.get(k);+ if (bucket) bucket.push(e); else cells.set(k, [e]);+ }+ return {+ query({ owned }) {+ const anchors: InterestPoint[] = [];+ for (const e of owned) {+ const p = at.get(e);+ if (p) anchors.push(p);+ }+ // No place to look from: the same fail-open the policy has.+ if (anchors.length === 0) return 'all';++ const visible = new Set<Entity>(placeless);+ for (const a of anchors) {+ const cx = Math.floor(a.x / cell);+ const cy = Math.floor(a.y / cell);+ const cz = Math.floor((a.z ?? 0) / cell);+ for (let dx = -1; dx <= 1; dx++) {+ for (let dy = -1; dy <= 1; dy++) {+ for (let dz = -1; dz <= 1; dz++) {+ const bucket = cells.get(`${cx + dx},${cy + dy},${cz + dz}`);+ if (!bucket) continue;+ for (const e of bucket) {+ if (visible.has(e)) continue;+ const p = at.get(e)!;+ // A cell is a box and the rule is a+ // sphere: being in the neighbourhood is+ // not being in range.+ const ddx = p.x - a.x;+ const ddy = p.y - a.y;+ const ddz = (p.z ?? 0) - (a.z ?? 0);+ if (ddx * ddx + ddy * ddy + ddz * ddz <= r2) visible.add(e);+ }+ }+ }+ }+ }+ return visible;+ },+ };+ },+ };+}diff --git a/sdk/src/net/replication/server.ts b/sdk/src/net/replication/server.tsindex 2446b3b80..b1169781d 100644--- a/sdk/src/net/replication/server.ts+++ b/sdk/src/net/replication/server.ts@@ -35,7 +35,7 @@ import {} from './codec';import { Replicated, type ReplicatedData } from './components';import { NetIds } from './NetIds';-import type { InterestPolicy } from './interest';+import type { InterestPolicy, InterestProvider } from './interest';interface Connection {id: number;@@ -126,7 +126,14 @@ export class ReplicationServer {/** known entity → netId, owned by sampling. Survives the onDespawn hook* clearing netIds_, so a despawn can still broadcast its id. */private readonly knownNetIds_ = new Map<Entity, number>();- private policy_: InterestPolicy | null = null;+ /**+ * One interest slot, two shapes: a policy filters per connection, a provider+ * prepares once and answers each from it. Never both — "does the provider+ * run before the policy?" would quietly redefine what `candidates` means.+ */+ private interest_: { kind: 'policy'; value: InterestPolicy }+ | { kind: 'provider'; value: InterestProvider }+ | null = null;private tick_ = 0;private fixedDelta_ = 0;/** Removal-history claims, one per replicated component. */@@ -236,6 +243,8 @@ export class ReplicationServer {this.world_.disposeWriteReader(Replicated, this.ownerReader_);this.ownerReader_ = null;}+ if (this.interest_?.kind === 'provider') this.interest_.value.dispose?.();+ this.interest_ = null;this.offDespawn_();}@@ -274,8 +283,27 @@ export class ReplicationServer {* set against the new policy.*/setInterestPolicy(policy: InterestPolicy | null): void {- if (policy && !this.ownedByConnection_) this.installOwnerIndex_();- this.policy_ = policy;+ this.setInterest_(policy ? { kind: 'policy', value: policy } : null);+ }++ /**+ * Install a prepare-once/query-many provider. Shares the slot with+ * {@link setInterestPolicy}: the last non-null setter wins, and null on+ * either disables interest.+ *+ * @experimental+ */+ setInterestProvider(provider: InterestProvider | null): void {+ this.setInterest_(provider ? { kind: 'provider', value: provider } : null);+ }++ private setInterest_(next: typeof this.interest_): void {+ const previous = this.interest_;+ if (previous?.kind === 'provider' && previous.value !== (next as { value?: unknown })?.value) {+ previous.value.dispose?.();+ }+ if (next && !this.ownedByConnection_) this.installOwnerIndex_();+ this.interest_ = next;}/** Claim the write journal, then seed from what is already known — in that@@ -451,7 +479,7 @@ export class ReplicationServer {// Diff once against the shadow; frames below share the result.const sample = this.collectDirty_();- if (!this.policy_) {+ if (!this.interest_) {this.sampleBroadcast_(tick, spawnedEntities, despawned, sample);} else {this.sampleWithInterest_(tick, despawned, sample);@@ -533,7 +561,9 @@ export class ReplicationServer {{ dirty, removals }: DirtySample,): void {const despawnedNetIds = new Map(despawned.map((d) => [d.entity, d.netId]));- const candidates = [...this.known_];+ // One snapshot for every connection this sample: a provider prepares+ // here, and never on the per-connection path below.+ const visibleFor = this.resolveVisibility_();// Spawn payloads serialize once per entity per tick, however many// connections it enters.const payloads = new Map<Entity, ReplSpawnEntity>();@@ -548,7 +578,7 @@ export class ReplicationServer {for (const conn of [...this.connections_.values()]) {if (!conn.ready) continue;- const visible = this.visibleFor_(conn.id, candidates);+ const visible = visibleFor(conn.id);const enters: Entity[] = [];for (const e of visible) {@@ -591,12 +621,48 @@ export class ReplicationServer {}}+ /**+ * One snapshot of the interest source, and a function answering per+ * connection from it. A provider prepares ONCE — that is the whole reason+ * it exists — and never sees a materialized candidate array, which is the+ * other O(population) the policy shape forces.+ */+ private resolveVisibility_(): (connectionId: number) => Set<Entity> {+ const source = this.interest_;+ if (!source) {+ const all = [...this.known_];+ return () => new Set(all);+ }+ if (source.kind === 'provider') {+ const known = this.known_;+ const prepared = source.value.prepare({+ world: this.world_,+ // A wrapper, not the registry itself: a caller that casts the+ // iterable back to a Set could otherwise clear it.+ entities: { [Symbol.iterator]: () => known.values() },+ entityCount: known.size,+ });+ return (connectionId) => {+ const owned = this.ownedByConnection_?.get(connectionId);+ const ownedList = owned ? [...owned] : [];+ const result = prepared.query({ connectionId, owned: ownedList });+ const visible = result === 'all' ? new Set(this.known_) : new Set(result);+ for (const e of ownedList) visible.add(e);+ return visible;+ };+ }+ const candidates = [...this.known_];+ return (connectionId) => this.visibleFor_(connectionId, candidates);+ }+/** The policy's answer for one connection, with the server's invariant* applied on top: a connection always sees the entities it owns (input* routing and prediction anchor on them, so a policy cannot cull them). */private visibleFor_(connectionId: number, candidates: readonly Entity[]): Set<Entity> {const owned = this.ownedByConnection_?.get(connectionId);- const result = this.policy_!({+ const policy = this.interest_?.kind === 'policy' ? this.interest_.value : null;+ if (!policy) return new Set(candidates);+ const result = policy({connectionId, world: this.world_, candidates,owned: owned ? [...owned] : undefined,});@@ -845,8 +911,7 @@ export class ReplicationServer {if (!anyReady) this.rebaseRegistry_();// Everything relevant right now, full component payloads (current state// included — no separate baseline frame needed).- const candidates = [...this.known_];- const visible = this.policy_ ? this.visibleFor_(conn.id, candidates) : new Set(candidates);+ const visible = this.resolveVisibility_()(conn.id);const entities: ReplSpawnEntity[] = [];for (const e of visible) {const netId = this.knownNetIds_.get(e);diff --git a/sdk/tests/replication-interest-provider.test.ts b/sdk/tests/replication-interest-provider.test.tsnew file mode 100644index 000000000..5c7e5bebe--- /dev/null+++ b/sdk/tests/replication-interest-provider.test.ts@@ -0,0 +1,231 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Interest as prepare-once/query-many.+ *+ * A policy is handed the population per connection, so whatever it reads it+ * reads C times. A provider prepares one snapshot per sample and answers every+ * connection from it. The two cost fixtures here — a position read once per+ * entity, and one prepare per sample rather than one per connection — are the+ * reason the shape exists, so they are contracts rather than benchmark notes.+ */+import { describe, it, expect, beforeEach } from 'vitest';+import { App } from '../src/app/app';+import { clearUserComponents, defineComponent, Name } from '../src/ecs/component';+import { MemoryTransport } from '../src/net/MemoryTransport';+import {+ replicationPlugin, Net, Replicated, radiusInterest, radiusInterestProvider,+ type InterestProvider, type PreparedInterest,+} from '../src/net/replication';+import type { Entity } from '../src/types';+import type { World } from '../src/ecs/world';++const STEP = 1 / 60;+let NetPos: ReturnType<typeof defineComponent<{ x: number; y: number; z: number }>>;++beforeEach(() => {+ clearUserComponents();+ NetPos = defineComponent('NetPos', { x: 0, y: 0, z: 0 }, { replicatedFields: ['x', 'y', 'z'] });+});++const makeApp = (): App => { const a = App.new(); a.addPlugin(replicationPlugin); return a; };+const posOf = (world: World, e: Entity): { x: number; y: number; z: number } | null => {+ const p = world.tryGet(e, NetPos) as { x: number; y: number; z: number } | null;+ return p ? { x: p.x, y: p.y, z: p.z } : null;+};+const ghosts = (app: App): string[] =>+ app.world.getEntitiesWithComponents([Replicated])+ .map((e) => (app.world.tryGet(e, Name) as { value: string } | null)?.value ?? '')+ .sort();++async function serverWith(connections: number) {+ const serverApp = makeApp();+ const server = serverApp.getResource(Net).startServer();+ const clients: { app: App; id: number }[] = [];+ for (let i = 0; i < connections; i++) {+ const app = makeApp();+ const [ta, tb] = MemoryTransport.pair();+ const id = server.attachConnection(ta);+ await app.getResource(Net).connect(tb, { interpolationDelayTicks: 0 });+ clients.push({ app, id });+ }+ const step = async (n = 1) => {+ for (let i = 0; i < n; i++) {+ await serverApp.tick(STEP);+ for (const c of clients) await c.app.tick(STEP);+ }+ };+ const place = (name: string, x: number, owner = -1, y = 0): Entity => {+ const e = serverApp.world.spawn(name);+ serverApp.world.insert(e, Replicated, { owner });+ serverApp.world.insert(e, NetPos, { x, y, z: 0 });+ return e;+ };+ const placeless = (name: string, owner = -1): Entity => {+ const e = serverApp.world.spawn(name);+ serverApp.world.insert(e, Replicated, { owner });+ return e;+ };+ return { serverApp, server, clients, step, place, placeless };+}++describe('a radius provider answers what the radius policy answers', () => {+ it('agrees entity for entity across the interesting shapes', async () => {+ const shapes = async (useProvider: boolean): Promise<string[]> => {+ const h = await serverWith(1);+ const c = h.clients[0];+ h.place('anchor', 0, c.id);+ h.place('near', 10);+ h.place('far', 500);+ h.place('edge-in', 0, -1, 19);+ h.place('edge-out', 20, -1, 20);+ h.place('owned-far', 900, c.id);+ h.placeless('nowhere');+ if (useProvider) h.server.setInterestProvider(radiusInterestProvider(20, { position: posOf }));+ else h.server.setInterestPolicy(radiusInterest(20, { position: posOf }));+ await h.step(3);+ return ghosts(c.app);+ };++ const viaPolicy = await shapes(false);+ const viaProvider = await shapes(true);+ expect(viaProvider).toEqual(viaPolicy);+ expect(viaProvider).toEqual(['anchor', 'edge-in', 'near', 'nowhere', 'owned-far'].sort());+ });++ it('falls open to everything for a connection with no positioned anchor', async () => {+ const h = await serverWith(1);+ h.place('somewhere', 5000);+ h.placeless('nowhere');+ h.server.setInterestProvider(radiusInterestProvider(20, { position: posOf }));+ await h.step(3);+ expect(ghosts(h.clients[0].app)).toEqual(['nowhere', 'somewhere']);+ });++ it('sees from every anchor a connection owns', async () => {+ const h = await serverWith(1);+ const c = h.clients[0];+ h.place('a1', 0, c.id);+ h.place('a2', 1000, c.id);+ h.place('by-a1', 10);+ h.place('by-a2', 1010);+ h.place('between', 500);+ h.server.setInterestProvider(radiusInterestProvider(20, { position: posOf }));+ await h.step(3);+ expect(ghosts(c.app)).toEqual(['a1', 'a2', 'by-a1', 'by-a2']);+ });+});++describe('what a provider costs', () => {+ it('reads each position once per snapshot, not once per connection', async () => {+ const h = await serverWith(4);+ for (const c of h.clients) h.place(`pawn${c.id}`, c.id * 5, c.id);+ for (let i = 0; i < 20; i++) h.place(`e${i}`, i);+ await h.step();++ let reads = 0;+ h.server.setInterestProvider(radiusInterestProvider(50, {+ position: (world, e) => { reads++; return posOf(world, e); },+ }));+ reads = 0;+ await h.step();++ const population = h.serverApp.world.getEntitiesWithComponents([Replicated]).length;+ expect(reads).toBe(population);+ });++ it('prepares once per sample and queries once per connection', async () => {+ const h = await serverWith(4);+ for (const c of h.clients) h.place(`pawn${c.id}`, c.id * 5, c.id);+ await h.step();++ let prepares = 0;+ let queries = 0;+ const inner = radiusInterestProvider(50, { position: posOf });+ const counting: InterestProvider = {+ prepare(view) {+ prepares++;+ // Not an array: preparing may walk the population, installing+ // must not force it to be materialized first.+ expect(Array.isArray(view.entities)).toBe(false);+ expect(view.entityCount).toBeGreaterThan(0);+ const prepared = inner.prepare(view);+ return { query: (q) => { queries++; return prepared.query(q); } } as PreparedInterest;+ },+ };+ h.server.setInterestProvider(counting);+ prepares = 0; queries = 0;++ // One frame, one replication sample: one snapshot, four queries — not+ // one snapshot per connection, which is the whole point of the shape.+ await h.step(1);+ expect(prepares).toBe(1);+ expect(queries).toBe(4);++ await h.step(1);+ expect(prepares).toBe(2);+ expect(queries).toBe(8);+ });+});++describe('the interest slot holds one source', () => {+ it('switches between policy, provider and off, disposing what it drops', async () => {+ const h = await serverWith(1);+ const c = h.clients[0];+ h.place('anchor', 0, c.id);+ h.place('far', 500);+ h.server.setInterestPolicy(radiusInterest(20, { position: posOf }));+ await h.step(3);+ expect(ghosts(c.app)).toEqual(['anchor']);++ let disposed = 0;+ const wide = radiusInterestProvider(1000, { position: posOf });+ h.server.setInterestProvider({+ prepare: (v) => wide.prepare(v),+ dispose: () => { disposed++; },+ });+ await h.step(3);+ expect(ghosts(c.app)).toEqual(['anchor', 'far']);++ h.server.setInterestPolicy(radiusInterest(20, { position: posOf }));+ await h.step(3);+ expect(disposed).toBe(1);+ expect(ghosts(c.app)).toEqual(['anchor']);++ h.server.setInterestProvider(null);+ await h.step(3);+ expect(ghosts(c.app)).toEqual(['anchor', 'far']);+ expect(disposed).toBe(1);+ });++ it('disposes the installed provider when the server does', async () => {+ const h = await serverWith(1);+ let disposed = 0;+ const inner = radiusInterestProvider(20, { position: posOf });+ h.server.setInterestProvider({+ prepare: (v) => inner.prepare(v),+ dispose: () => { disposed++; },+ });+ h.serverApp.getResource(Net).stop();+ expect(disposed).toBe(1);+ });++ it('gives a joining client its own snapshot', async () => {+ const h = await serverWith(1);+ const c = h.clients[0];+ h.place('anchor', 0, c.id);+ h.place('far', 500);+ h.server.setInterestProvider(radiusInterestProvider(20, { position: posOf }));+ await h.step(3);++ const late = makeApp();+ const [ta, tb] = MemoryTransport.pair();+ const lateId = h.server.attachConnection(ta);+ await late.getResource(Net).connect(tb, { interpolationDelayTicks: 0 });+ await late.tick(STEP);++ // No positioned anchor of its own: it fails open and sees everything.+ expect(ghosts(late)).toEqual(['anchor', 'far']);+ expect(lateId).toBeGreaterThan(0);+ });+});