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(net): the rule reconciliation replays can be asked whether it replays

esenginef0fb04bf2934
diff --git a/sdk/src/net/replication/client.ts b/sdk/src/net/replication/client.ts
index d1b091f12..c7b25d9db 100644
--- a/sdk/src/net/replication/client.ts
+++ b/sdk/src/net/replication/client.ts
@@ -22,6 +22,7 @@
* snapshot interpolation entirely.
*/
import type { World } from '../../ecs/world';
+import { replay, type ReplayReport, type SpeculationScope } from '../../ecs/speculation';
import type { Entity } from '../../types';
import { getComponent } from '../../ecs/component';
import { ABI_LAYOUT_HASH } from '../../ecs/component.generated';
@@ -66,6 +67,28 @@ export interface PredictionOptions {
smoothing?: PredictionSmoothing;
}
+/**
+ * Ask whether an `apply` is what reconciliation needs it to be.
+ *
+ * The promise above is the one the rebuild rests on, and until now only a
+ * desync could report it broken. Runs the step twice from the same state and
+ * takes both back, so a game can ask in a test without paying for it in play.
+ *
+ * @experimental
+ */
+export function predictionReplays(
+ scope: SpeculationScope,
+ prediction: PredictionOptions,
+ entity: Entity,
+ actions: Record<string, unknown>,
+ dt: number,
+): ReplayReport {
+ return replay(scope, () => {
+ prediction.apply(scope.world, entity, actions, dt);
+ return 'commit';
+ });
+}
+
export interface PredictionSmoothing {
/** Seconds for the visual error to halve (typical: 0.05–0.15). */
halfLife: number;
diff --git a/sdk/src/net/replication/index.ts b/sdk/src/net/replication/index.ts
index 83e35b69d..214aff48a 100644
--- a/sdk/src/net/replication/index.ts
+++ b/sdk/src/net/replication/index.ts
@@ -53,6 +53,7 @@ export { NetIds } from './NetIds';
export { ReplicationServer } from './server';
export {
ReplicationClient,
+ predictionReplays,
type ReplicationClientOptions,
type PredictionOptions,
type PredictionSmoothing,
diff --git a/sdk/tests/replication-prediction.test.ts b/sdk/tests/replication-prediction.test.ts
index 04c04ef07..35e6d3b18 100644
--- a/sdk/tests/replication-prediction.test.ts
+++ b/sdk/tests/replication-prediction.test.ts
@@ -14,7 +14,8 @@ import { App } from '../src/app/app';
import { defineComponent, clearUserComponents } from '../src/ecs/component';
import { defineSystem, Schedule, GetWorld } from '../src/ecs/system';
import { MemoryTransport } from '../src/net/MemoryTransport';
-import { replicationPlugin, Net, Replicated, type ReplicationServer } from '../src/net/replication';
+import { replicationPlugin, Net, Replicated, predictionReplays, type ReplicationServer } from '../src/net/replication';
+import { ResourceStorage } from '../src/ecs/resource';
import type { Entity } from '../src/types';
import type { World } from '../src/ecs/world';
@@ -346,3 +347,46 @@ describe('per-tick input queue (tickInputOf)', () => {
expect(server.tickInputOf(connId)!.actions).toEqual({ n: 2 });
});
});
+
+// The promise `apply` carries — "must depend only on world state + actions +
+// dt (it re-runs during reconciliation)" — is what the rebuild rests on, and
+// until there was a machine for it only a desync could report it broken.
+describe('the rule reconciliation replays', () => {
+ it('is a function of the world, and the same one twice', () => {
+ const app = App.new();
+ const world = app.world;
+ const pawn = world.spawn();
+ world.insert(pawn, NetPos, { x: 0, y: 0 });
+
+ const report = predictionReplays(
+ { world, resources: new ResourceStorage() },
+ { apply: applyMove },
+ pawn,
+ { move: { x: 1, y: 0 } },
+ STEP,
+ );
+ expect(report).toEqual({ stable: true, why: '' });
+ // Asking moved nothing: both runs were taken back.
+ expect(world.get(pawn, NetPos).x).toBe(0);
+ });
+
+ it('and is reported when it is not', () => {
+ const app = App.new();
+ const world = app.world;
+ const pawn = world.spawn();
+ world.insert(pawn, NetPos, { x: 0, y: 0 });
+
+ const drifts = (w: World, e: Entity): void => {
+ w.set(e, NetPos, { x: Math.random(), y: 0 });
+ };
+ const report = predictionReplays(
+ { world, resources: new ResourceStorage() },
+ { apply: drifts },
+ pawn,
+ {},
+ STEP,
+ );
+ expect(report.stable).toBe(false);
+ expect(report.why).toMatch(/^values differed between runs/);
+ });
+});