@replicast/core 1.0.0-rc.7 → 1.0.0-rc.9

package/dist/entity/replicator.js

@@ -0,0 +1,82 @@
+import { snapshotFields, diffFields, ownerIdField } from './fields.js';
+import { isEntityVisible } from './visibility.js';
+/**
+ * Tracks, per client, which entities that client has been sent and the fields it last saw, and turns
+ * the current world into that client's `{ enter, update, leave }` delta.
+ *
+ * Cost is O(clients x entities) per flush — deliberate for now; a spatial index hook comes later.
+ */
+export class EntityReplicator {
+    /** playerId → entityId → last-sent field snapshot. */
+    views = new Map();
+    /** True when `playerId` currently has `id` in their set (i.e. as of the last flush). */
+    hasInView(playerId, id) {
+        return this.views.get(playerId)?.has(id) ?? false;
+    }
+    /** The clients that currently see `id` — the audience for a `@Multicast`. */
+    viewersOf(id) {
+        const viewers = [];
+        for (const [playerId, view] of this.views) {
+            if (view.has(id))
+                viewers.push(playerId);
+        }
+        return viewers;
+    }
+    /** Forget a disconnected client so they re-enter from scratch on reconnect. */
+    dropViewer(playerId) {
+        this.views.delete(playerId);
+    }
+    /**
+     * Records `id` as already sent to `playerId` with `fields`, without waiting for the next flush —
+     * for a caller that must guarantee delivery order (an `@Client`/`@Multicast` send that needs the
+     * recipient's mirror to exist before the rpc arrives). The next real `flush()` then sees this id
+     * already in `view` and sends only a diff, never a duplicate `enter`.
+     */
+    recordEnter(playerId, id, fields) {
+        let view = this.views.get(playerId);
+        if (!view) {
+            view = new Map();
+            this.views.set(playerId, view);
+        }
+        view.set(id, fields);
+    }
+    /**
+     * Builds one client's delta and records it as sent. An entity is visible when the client owns it
+     * (owners always see their own entities) or the type's `visibleTo` hook allows it.
+     */
+    computeSync(playerId, entries, world) {
+        let view = this.views.get(playerId);
+        if (!view) {
+            view = new Map();
+            this.views.set(playerId, view);
+        }
+        const sync = { enter: [], update: [], leave: [] };
+        const stillVisible = new Set();
+        for (const { id, entity, type, plan, visibleTo } of entries) {
+            const isOwner = entity[ownerIdField] === playerId;
+            if (!isEntityVisible(isOwner, playerId, entity, visibleTo, world))
+                continue;
+            stillVisible.add(id);
+            const fields = snapshotFields(entity, plan, isOwner);
+            const previous = view.get(id);
+            if (previous === undefined) {
+                sync.enter.push({ type, id, fields });
+                view.set(id, fields);
+                continue;
+            }
+            const patch = diffFields(previous, fields);
+            if (Object.keys(patch).length > 0) {
+                sync.update.push({ id, fields: patch });
+                view.set(id, fields);
+            }
+        }
+        for (const id of view.keys()) {
+            if (!stillVisible.has(id)) {
+                sync.leave.push(id);
+                view.delete(id);
+            }
+        }
+        return sync;
+    }
+}
+//# sourceMappingURL=replicator.js.map

package/dist/entity/replicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replicator.js","sourceRoot":"","sources":["../../src/entity/replicator.ts"],"names":[],"mappings":"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"}

package/dist/entity/types.d.ts

@@ -0,0 +1,29 @@
+/** Server-assigned entity id. Numeric so it stays compact on the msgpack wire. */
+export type EntityId = number;
+/** Any class usable as a replicated entity type: it must be constructible with no arguments. */
+export type EntityConstructor<T extends object = object> = new () => T;
+/** Read-only view of the server world handed to `visibleTo` / `canCall` hooks. */
+export interface EntityWorldView {
+    get(id: EntityId): object | undefined;
+    byType<T extends object>(Type: EntityConstructor<T>): T[];
+    all(): object[];
+}
+/** One entity entering a client's view: the full replicated field set for that client. */
+export interface EntityEnter {
+    type: string;
+    id: EntityId;
+    fields: Record<string, unknown>;
+}
+/** One entity already in view whose replicated fields changed. */
+export interface EntityUpdate {
+    id: EntityId;
+    fields: Record<string, unknown>;
+}
+/** A single client's per-flush entity delta. */
+export interface EntitySync {
+    enter: EntityEnter[];
+    update: EntityUpdate[];
+    leave: EntityId[];
+}
+export declare function isEmptySync(sync: EntitySync): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/entity/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entity/types.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAA;AAE7B,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,UAAU,CAAC,CAAA;AAEtE,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAA;IACrC,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAA;IACzD,GAAG,IAAI,MAAM,EAAE,CAAA;CAChB;AAED,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,QAAQ,CAAA;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,QAAQ,CAAA;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,MAAM,EAAE,YAAY,EAAE,CAAA;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAA;CAClB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAErD"}

package/dist/entity/types.js

@@ -0,0 +1,4 @@
+export function isEmptySync(sync) {
+    return sync.enter.length === 0 && sync.update.length === 0 && sync.leave.length === 0;
+}
+//# sourceMappingURL=types.js.map

package/dist/entity/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/entity/types.ts"],"names":[],"mappings":"AAiCA,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAA;AACvF,CAAC"}

package/dist/entity/visibility.d.ts

@@ -0,0 +1,11 @@
+import type { EntityWorldView } from './types.js';
+/** Scopes replication and RPC visibility for an `@Entity` type. Default (undefined): visible to everyone. */
+export type VisibleTo = (viewerId: string, entity: object, world: EntityWorldView) => boolean;
+/**
+ * Whether `viewerId` can see `entity`: an owner always can; everyone else defers to `visibleTo`
+ * (no hook means visible to everyone). Shared by replication (who gets `enter`/`update`) and by
+ * `@Server` RPC authorisation (`EntityWorld.invoke`), so a caller can never act on an entity the
+ * server would not otherwise show them.
+ */
+export declare function isEntityVisible(isOwner: boolean, viewerId: string, entity: object, visibleTo: VisibleTo | undefined, world: EntityWorldView): boolean;
+//# sourceMappingURL=visibility.d.ts.map

package/dist/entity/visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility.d.ts","sourceRoot":"","sources":["../../src/entity/visibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,6GAA6G;AAC7G,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAA;AAE7F;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,KAAK,EAAE,eAAe,GACrB,OAAO,CAET"}

package/dist/entity/visibility.js

@@ -0,0 +1,10 @@
+/**
+ * Whether `viewerId` can see `entity`: an owner always can; everyone else defers to `visibleTo`
+ * (no hook means visible to everyone). Shared by replication (who gets `enter`/`update`) and by
+ * `@Server` RPC authorisation (`EntityWorld.invoke`), so a caller can never act on an entity the
+ * server would not otherwise show them.
+ */
+export function isEntityVisible(isOwner, viewerId, entity, visibleTo, world) {
+    return isOwner || !visibleTo || visibleTo(viewerId, entity, world);
+}
+//# sourceMappingURL=visibility.js.map

package/dist/entity/visibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility.js","sourceRoot":"","sources":["../../src/entity/visibility.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgB,EAChB,QAAgB,EAChB,MAAc,EACd,SAAgC,EAChC,KAAsB;IAEtB,OAAO,OAAO,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,CAAA;AACpE,CAAC"}

package/dist/entity/world.d.ts

@@ -0,0 +1,67 @@
+import type { EntityConstructor, EntityId, EntitySync, EntityWorldView } from './types.js';
+/** How the world reaches connected clients. Injected so the world stays testable without sockets. */
+export interface EntityTransport {
+    /** Push one entity-scoped `@Client` / `@Multicast` call to a client. */
+    sendRpc(playerId: string, id: EntityId, method: string, args: unknown[]): void;
+    /** Push one client their `{ enter, update, leave }` delta. */
+    sendSync(playerId: string, sync: EntitySync): void;
+    /** The currently connected players. */
+    players(): string[];
+}
+export interface EntityWorldOptions {
+    /** Entity classes registered up front (also auto-registered lazily on first spawn). */
+    types?: EntityConstructor<object>[];
+    transport?: EntityTransport;
+}
+/**
+ * Server-side entity registry: spawns entities, runs their `@ServerTick`, authorises their
+ * `@Server` calls, and flushes each client's interest-scoped delta.
+ */
+export declare class EntityWorld implements EntityWorldView {
+    private entities;
+    private infoByCtor;
+    private replicator;
+    private transport;
+    private nextId;
+    constructor(options?: EntityWorldOptions);
+    private register;
+    private infoOf;
+    /** Registers an entity, assigns its id and owner, and wires its server → client dispatch. */
+    spawn<T extends object>(entity: T, options?: {
+        ownerId?: string | null;
+    }): T;
+    despawn(id: EntityId): void;
+    get(id: EntityId): object | undefined;
+    byType<T extends object>(Type: EntityConstructor<T>): T[];
+    all(): object[];
+    /** Forget a disconnected client's view so they re-enter from scratch on reconnect. */
+    dropViewer(playerId: string): void;
+    /** Runs every entity's `@ServerTick` methods. Called by the server's fixed-step scheduler. */
+    tick(dt: number): void;
+    /** Computes and sends every connected client's delta. Called at the replication rate. */
+    flush(): void;
+    private replicationEntries;
+    /**
+     * Runs a client-initiated `@Server` call on one entity after checking the caller is allowed.
+     * Rejects on an unknown entity, a method that is not `@Server` on that type, an entity the caller
+     * cannot see, or a failed `canCall` — `canCall` alone would otherwise let a `canCall: 'anyone'`
+     * entity be driven by a client the `visibleTo` hook was written to hide it from entirely.
+     */
+    invoke(callerId: string, id: EntityId, method: string, args: unknown[]): Promise<unknown>;
+    private canCall;
+    /**
+     * Replaces `@Client` / `@Multicast` methods on this instance with sends, so the server stays
+     * independent of the Vite transform (plain tsx/node works) and tick code can call them directly.
+     *
+     * Both recompute visibility live against `this.transport.players()` rather than asking the
+     * replicator who was already sent an `enter` for this id, because `flush()` runs on its own timer:
+     * an entity spawned and called on within the same tick would otherwise have no recorded viewers yet
+     * and the rpc would reach nobody. That alone isn't sufficient though — a recipient who is newly
+     * visible but has not yet had a flush also has no client-side mirror to run the rpc against, so
+     * `sendToRecipient` first catches that one recipient up with a synthetic `enter` (recorded into the
+     * replicator so the next real flush sends a diff, not a duplicate enter) before sending the rpc, to
+     * guarantee enter-before-rpc per `(player, entity)`.
+     */
+    private bindClientDispatch;
+}
+//# sourceMappingURL=world.d.ts.map

package/dist/entity/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/entity/world.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE1F,qGAAqG;AACrG,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9E,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;IAClD,uCAAuC;IACvC,OAAO,IAAI,MAAM,EAAE,CAAA;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,KAAK,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAA;IACnC,SAAS,CAAC,EAAE,eAAe,CAAA;CAC5B;AAeD;;;GAGG;AACH,qBAAa,WAAY,YAAW,eAAe;IACjD,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,MAAM,CAAI;gBAEN,OAAO,GAAE,kBAAuB;IAK5C,OAAO,CAAC,QAAQ;IAuBhB,OAAO,CAAC,MAAM;IAId,6FAA6F;IAC7F,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAO,GAAG,CAAC;IAahF,OAAO,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI;IAI3B,GAAG,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS;IAIrC,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE;IAQzD,GAAG,IAAI,MAAM,EAAE;IAIf,sFAAsF;IACtF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIlC,8FAA8F;IAC9F,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQtB,yFAAyF;IACzF,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,kBAAkB;IAS1B;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAmB/F,OAAO,CAAC,OAAO;IAOf;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,kBAAkB;CA2B3B"}

package/dist/entity/world.js

@@ -0,0 +1,183 @@
+import { getMethodRoles } from '../decorators/metadata.js';
+import { getEntityHooks, getEntityName, getEntityOptions, isEntityClass } from '../decorators/entity.js';
+import { fieldPlanOf, ownerIdField, snapshotFields } from './fields.js';
+import { EntityReplicator } from './replicator.js';
+import { isEntityVisible } from './visibility.js';
+import { isEmptySync } from './types.js';
+const noopTransport = {
+    sendRpc() { }, sendSync() { }, players: () => [],
+};
+/**
+ * Server-side entity registry: spawns entities, runs their `@ServerTick`, authorises their
+ * `@Server` calls, and flushes each client's interest-scoped delta.
+ */
+export class EntityWorld {
+    entities = new Map();
+    infoByCtor = new Map();
+    replicator = new EntityReplicator();
+    transport;
+    nextId = 1;
+    constructor(options = {}) {
+        this.transport = options.transport ?? noopTransport;
+        for (const Type of options.types ?? [])
+            this.register(Type);
+    }
+    register(Type) {
+        const existing = this.infoByCtor.get(Type);
+        if (existing)
+            return existing;
+        if (!isEntityClass(Type)) {
+            throw new Error(`${Type.name || 'class'} is not decorated with @Entity`);
+        }
+        const proto = Type.prototype;
+        const hooks = getEntityHooks(proto);
+        const roles = getMethodRoles(proto);
+        const info = {
+            name: getEntityName(Type),
+            plan: fieldPlanOf(Type),
+            options: getEntityOptions(Type) ?? {},
+            serverTicks: Object.keys(hooks).filter(m => hooks[m] === 'serverTick'),
+            clientMethods: Object.fromEntries(Object.entries(roles).filter(([, r]) => r === 'client' || r === 'multicast')),
+            serverMethods: new Set(Object.keys(roles).filter(m => roles[m] === 'server')),
+        };
+        this.infoByCtor.set(Type, info);
+        return info;
+    }
+    infoOf(entity) {
+        return this.register(Object.getPrototypeOf(entity).constructor);
+    }
+    /** Registers an entity, assigns its id and owner, and wires its server → client dispatch. */
+    spawn(entity, options = {}) {
+        const info = this.infoOf(entity);
+        const id = this.nextId++;
+        const target = entity;
+        target['id'] = id;
+        target['ownerId'] = options.ownerId ?? null;
+        target['isServer'] = true;
+        target['hasAuthority'] = true;
+        this.entities.set(id, entity);
+        this.bindClientDispatch(entity, id, info);
+        return entity;
+    }
+    despawn(id) {
+        this.entities.delete(id);
+    }
+    get(id) {
+        return this.entities.get(id);
+    }
+    byType(Type) {
+        const out = [];
+        for (const entity of this.entities.values()) {
+            if (entity instanceof Type)
+                out.push(entity);
+        }
+        return out;
+    }
+    all() {
+        return [...this.entities.values()];
+    }
+    /** Forget a disconnected client's view so they re-enter from scratch on reconnect. */
+    dropViewer(playerId) {
+        this.replicator.dropViewer(playerId);
+    }
+    /** Runs every entity's `@ServerTick` methods. Called by the server's fixed-step scheduler. */
+    tick(dt) {
+        for (const entity of [...this.entities.values()]) {
+            for (const method of this.infoOf(entity).serverTicks) {
+                entity[method].call(entity, dt);
+            }
+        }
+    }
+    /** Computes and sends every connected client's delta. Called at the replication rate. */
+    flush() {
+        const entries = this.replicationEntries();
+        for (const playerId of this.transport.players()) {
+            const sync = this.replicator.computeSync(playerId, entries, this);
+            if (!isEmptySync(sync))
+                this.transport.sendSync(playerId, sync);
+        }
+    }
+    replicationEntries() {
+        const entries = [];
+        for (const [id, entity] of this.entities) {
+            const info = this.infoOf(entity);
+            entries.push({ id, entity, type: info.name, plan: info.plan, visibleTo: info.options.visibleTo });
+        }
+        return entries;
+    }
+    /**
+     * Runs a client-initiated `@Server` call on one entity after checking the caller is allowed.
+     * Rejects on an unknown entity, a method that is not `@Server` on that type, an entity the caller
+     * cannot see, or a failed `canCall` — `canCall` alone would otherwise let a `canCall: 'anyone'`
+     * entity be driven by a client the `visibleTo` hook was written to hide it from entirely.
+     */
+    async invoke(callerId, id, method, args) {
+        const entity = this.entities.get(id);
+        if (!entity)
+            throw new Error(`Unknown entity ${id}`);
+        const info = this.infoOf(entity);
+        const [typeName, methodName] = method.split('.');
+        if (typeName !== info.name || !methodName || !info.serverMethods.has(methodName)) {
+            throw new Error(`Unknown entity method: ${method}`);
+        }
+        const isOwner = entity[ownerIdField] === callerId;
+        if (!isEntityVisible(isOwner, callerId, entity, info.options.visibleTo, this)) {
+            // Same message as a missing id: a caller with no visibility shouldn't learn the entity exists.
+            throw new Error(`Unknown entity ${id}`);
+        }
+        if (!this.canCall(callerId, entity, info)) {
+            throw new Error(`Not allowed: ${method}`);
+        }
+        return entity[methodName].apply(entity, args);
+    }
+    canCall(callerId, entity, info) {
+        const rule = info.options.canCall ?? 'owner';
+        if (rule === 'anyone')
+            return true;
+        if (rule === 'owner')
+            return entity['ownerId'] === callerId;
+        return rule(callerId, entity, this);
+    }
+    /**
+     * Replaces `@Client` / `@Multicast` methods on this instance with sends, so the server stays
+     * independent of the Vite transform (plain tsx/node works) and tick code can call them directly.
+     *
+     * Both recompute visibility live against `this.transport.players()` rather than asking the
+     * replicator who was already sent an `enter` for this id, because `flush()` runs on its own timer:
+     * an entity spawned and called on within the same tick would otherwise have no recorded viewers yet
+     * and the rpc would reach nobody. That alone isn't sufficient though — a recipient who is newly
+     * visible but has not yet had a flush also has no client-side mirror to run the rpc against, so
+     * `sendToRecipient` first catches that one recipient up with a synthetic `enter` (recorded into the
+     * replicator so the next real flush sends a diff, not a duplicate enter) before sending the rpc, to
+     * guarantee enter-before-rpc per `(player, entity)`.
+     */
+    bindClientDispatch(entity, id, info) {
+        const sendToRecipient = (playerId, isOwner, key, args) => {
+            if (!this.replicator.hasInView(playerId, id)) {
+                const fields = snapshotFields(entity, info.plan, isOwner);
+                this.replicator.recordEnter(playerId, id, fields);
+                this.transport.sendSync(playerId, { enter: [{ type: info.name, id, fields }], update: [], leave: [] });
+            }
+            this.transport.sendRpc(playerId, id, key, args);
+        };
+        for (const [methodName, role] of Object.entries(info.clientMethods)) {
+            const key = `${info.name}.${methodName}`;
+            const send = role === 'client'
+                ? (...args) => {
+                    const ownerId = entity['ownerId'];
+                    if (typeof ownerId === 'string')
+                        sendToRecipient(ownerId, true, key, args);
+                }
+                : (...args) => {
+                    for (const playerId of this.transport.players()) {
+                        const isOwner = entity[ownerIdField] === playerId;
+                        if (isEntityVisible(isOwner, playerId, entity, info.options.visibleTo, this)) {
+                            sendToRecipient(playerId, isOwner, key, args);
+                        }
+                    }
+                };
+            Object.defineProperty(entity, methodName, { value: send, configurable: true, writable: true });
+        }
+    }
+}
+//# sourceMappingURL=world.js.map

package/dist/entity/world.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.js","sourceRoot":"","sources":["../../src/entity/world.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,13 +2,27 @@ export { GlobalStore, OwnerStore, Global, OwnerOnly, ServerOnly } from './decora
 export { System, Server, Client, Multicast } from './decorators/system.js';
 export { getStoreType, getPropertyRoles, getMethodRoles, setPropertyRole, setMethodRole } from './decorators/metadata.js';
 export type { StoreType, PropertyRole, MethodRole } from './decorators/metadata.js';
+export { Entity, Replicated, OwnerReplicated, Quantized, ServerTick, ClientSpawn, ClientDespawn, isEntityClass, getEntityName, getEntityOptions, getEntityHooks, getQuantizedFields, } from './decorators/entity.js';
+export type { EntityOptions, EntityHook, CanCall } from './decorators/entity.js';
+export { BaseEntity } from './entity/base-entity.js';
+export { EntityWorld } from './entity/world.js';
+export type { EntityTransport, EntityWorldOptions } from './entity/world.js';
+export { ClientEntityRegistry } from './entity/registry.js';
+export type { EntityCaller, ClientEntityRegistryOptions } from './entity/registry.js';
+export { EntityReplicator } from './entity/replicator.js';
+export type { ReplicationEntry } from './entity/replicator.js';
+export { fieldPlanOf, snapshotFields, diffFields, quantize } from './entity/fields.js';
+export type { FieldPlan } from './entity/fields.js';
+export { isEntityVisible } from './entity/visibility.js';
+export type { VisibleTo } from './entity/visibility.js';
+export type { EntityId, EntityConstructor, EntityWorldView, EntitySync, EntityEnter, EntityUpdate, } from './entity/types.js';
 export { BaseStore } from './store/base-store.js';
 export type { ReplicationBatch } from './store/base-store.js';
 export type { ConnectRequest, ConnectPayload, ServerContext } from './lifecycle/types.js';
 export { BaseServerLifecycle } from './lifecycle/base-server.js';
 export { BaseClientLifecycle } from './lifecycle/base-client.js';
 export { createRPCServer } from './transport/server.js';
-export type { RpcServer, TickOptions } from './transport/server.js';
+export type { RpcServer, TickOptions, ReplicationOptions } from './transport/server.js';
 export { ConnectionLostError, AuthRejectedError, RpcError, TimeoutError } from './transport/protocol.js';
 export { WsClient } from './transport/client.js';
 export type { ConnectionStatus, ConnectionQuality, WsClientOptions, LatencyThresholds } from './transport/client.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAC9F,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACzH,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAGnF,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAGzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAGhE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACxG,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAChD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACpH,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,YAAY,EAAE,GAAG,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAC9F,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACzH,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAGnF,OAAO,EACL,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EACtF,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,kBAAkB,GACnF,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAGhF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3D,YAAY,EAAE,YAAY,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AACtF,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AACvD,YAAY,EACV,QAAQ,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,GACpF,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAGzF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAGhE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AACvF,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACxG,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAChD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACpH,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,YAAY,EAAE,GAAG,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -2,6 +2,15 @@
 export { GlobalStore, OwnerStore, Global, OwnerOnly, ServerOnly } from './decorators/store.js';
 export { System, Server, Client, Multicast } from './decorators/system.js';
 export { getStoreType, getPropertyRoles, getMethodRoles, setPropertyRole, setMethodRole } from './decorators/metadata.js';
+// Entity decorators
+export { Entity, Replicated, OwnerReplicated, Quantized, ServerTick, ClientSpawn, ClientDespawn, isEntityClass, getEntityName, getEntityOptions, getEntityHooks, getQuantizedFields, } from './decorators/entity.js';
+// Entities
+export { BaseEntity } from './entity/base-entity.js';
+export { EntityWorld } from './entity/world.js';
+export { ClientEntityRegistry } from './entity/registry.js';
+export { EntityReplicator } from './entity/replicator.js';
+export { fieldPlanOf, snapshotFields, diffFields, quantize } from './entity/fields.js';
+export { isEntityVisible } from './entity/visibility.js';
 // Store
 export { BaseStore } from './store/base-store.js';
 // Lifecycle base classes

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAC9F,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAGzH,QAAQ;AACR,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAMjD,yBAAyB;AACzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAEhE,wCAAwC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACxG,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAC9F,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAC1E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAGzH,oBAAoB;AACpB,OAAO,EACL,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EACtF,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,kBAAkB,GACnF,MAAM,wBAAwB,CAAA;AAG/B,WAAW;AACX,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAE3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEzD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAEtF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAMxD,QAAQ;AACR,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAMjD,yBAAyB;AACzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAEhE,wCAAwC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACxG,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/store/base-store.d.ts

@@ -11,7 +11,6 @@ export declare class BaseStore {
     private _ownerData;
     private _dirtyGlobal;
     private _dirtyOwner;
-    private _flushScheduled;
     private _globalSeq;
     private _ownerSeqs;
     private _listeners;
@@ -31,10 +30,16 @@ export declare class BaseStore {
     /** True if anything is listening (legacy slot or subscribers). */
     get _hasListeners(): boolean;
     set(partial: Record<string, unknown>): void;
-    setOwner(key: string, playerId: string, value: unknown): void;
+    setOwner(key: string, playerId: string, rawValue: unknown): void;
     getOwner<T>(key: string, playerId: string): T;
     getSnapshot(playerId?: string): Record<string, unknown>;
-    private _scheduleFlush;
-    private _flush;
+    /**
+     * Drains accumulated dirty state (from `set()`/`setOwner()`) into one replication batch and
+     * emits it to listeners. `set()`/`setOwner()` no longer self-schedule this — the server calls
+     * `flush()` once per replication tick for every registered store (see `createRPCServer`'s
+     * replication timer), so store updates share one cadence with entity replication instead of
+     * running on an independent `process.nextTick()` clock. Cheap to call when nothing is dirty.
+     */
+    flush(): void;
 }
 //# sourceMappingURL=base-store.d.ts.map

package/dist/store/base-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-store.d.ts","sourceRoot":"","sources":["../../src/store/base-store.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;CACvC;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,UAAU,CAA4B;IAE9C,OAAO,CAAC,UAAU,CAA+C;IAEjE;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAElD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKlE,kHAAkH;IAClH,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAK/C,kEAAkE;IAClE,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAqB3C,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAgB7D,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC;IAI7C,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAcvD,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,MAAM;CAuCf"}
+{"version":3,"file":"base-store.d.ts","sourceRoot":"","sources":["../../src/store/base-store.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;CACvC;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,UAAU,CAA4B;IAE9C,OAAO,CAAC,UAAU,CAA+C;IAEjE;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAElD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKlE,kHAAkH;IAClH,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAK/C,kEAAkE;IAClE,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAsB3C,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAiBhE,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC;IAI7C,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAcvD;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;CAyCd"}

package/dist/store/base-store.js

@@ -1,9 +1,10 @@
 import { getPropertyRoles, getStoreType } from '../decorators/metadata.js';
+import { getQuantizedFields } from '../decorators/entity.js';
+import { quantize } from '../entity/fields.js';
 export class BaseStore {
     _ownerData = new Map();
     _dirtyGlobal = new Set();
     _dirtyOwner = new Map();
-    _flushScheduled = false;
     _globalSeq = 0;
     _ownerSeqs = new Map(); // playerId → seq
     _listeners = new Set();
@@ -32,11 +33,13 @@ export class BaseStore {
         return this._onReplication !== undefined || this._listeners.size > 0;
     }
     set(partial) {
-        if (getStoreType(Object.getPrototypeOf(this).constructor) === 'owner') {
+        const proto = Object.getPrototypeOf(this);
+        if (getStoreType(proto.constructor) === 'owner') {
             throw new Error('@OwnerStore does not support set(). Use setOwner() for all properties.');
         }
-        const roles = getPropertyRoles(Object.getPrototypeOf(this));
-        for (const [key, value] of Object.entries(partial)) {
+        const roles = getPropertyRoles(proto);
+        const quantized = getQuantizedFields(proto);
+        for (const [key, rawValue] of Object.entries(partial)) {
             const role = roles[key];
             if (role === 'ownerOnly') {
                 throw new Error(`Use setOwner() for @OwnerOnly property "${key}"`);
@@ -45,15 +48,15 @@ export class BaseStore {
                 throw new Error(`Unknown property "${key}" — must be decorated with @Global, @ServerOnly, or @OwnerOnly`);
             }
             ;
-            this[key] = value;
+            this[key] = quantize(rawValue, quantized[key]);
             if (role === 'global') {
                 this._dirtyGlobal.add(key);
-                this._scheduleFlush();
             }
         }
     }
-    setOwner(key, playerId, value) {
-        const roles = getPropertyRoles(Object.getPrototypeOf(this));
+    setOwner(key, playerId, rawValue) {
+        const proto = Object.getPrototypeOf(this);
+        const roles = getPropertyRoles(proto);
         const role = roles[key];
         if (role === undefined) {
             throw new Error(`Unknown property "${key}" — must be decorated with @Global, @ServerOnly, or @OwnerOnly`);
@@ -61,13 +64,13 @@ export class BaseStore {
         if (role !== 'ownerOnly') {
             throw new Error(`Use set() for @${role === 'global' ? 'Global' : 'ServerOnly'} property "${key}"`);
         }
+        const value = quantize(rawValue, getQuantizedFields(proto)[key]);
         if (!this._ownerData.has(key))
             this._ownerData.set(key, new Map());
         this._ownerData.get(key).set(playerId, value);
         if (!this._dirtyOwner.has(key))
             this._dirtyOwner.set(key, new Set());
         this._dirtyOwner.get(key).add(playerId);
-        this._scheduleFlush();
     }
     getOwner(key, playerId) {
         return this._ownerData.get(key)?.get(playerId);
@@ -87,16 +90,16 @@ export class BaseStore {
         }
         return snapshot;
     }
-    _scheduleFlush() {
-        if (this._flushScheduled)
+    /**
+     * Drains accumulated dirty state (from `set()`/`setOwner()`) into one replication batch and
+     * emits it to listeners. `set()`/`setOwner()` no longer self-schedule this — the server calls
+     * `flush()` once per replication tick for every registered store (see `createRPCServer`'s
+     * replication timer), so store updates share one cadence with entity replication instead of
+     * running on an independent `process.nextTick()` clock. Cheap to call when nothing is dirty.
+     */
+    flush() {
+        if (this._dirtyGlobal.size === 0 && this._dirtyOwner.size === 0)
             return;
-        this._flushScheduled = true;
-        process.nextTick(() => {
-            this._flushScheduled = false;
-            this._flush();
-        });
-    }
-    _flush() {
         if (!this._hasListeners) {
             // Nobody listening yet — discard dirty state so it doesn't accumulate
             // and leak into the first incremental patch after _onReplication is set.