svelte-realtime 0.6.0-next.73 → 0.6.0-next.74

package/README.md

@@ -3644,11 +3644,14 @@ export const arena = live.smooth({
       { within: 400, rate: 1 },                // near: every tick
       { within: 800, rate: 3 },                // mid: every 3rd tick
       { within: 1200, rate: 8 }                // fringe: every 8th tick
-    ]
+    ],
+    budget: 64                                  // optional per-subscriber delivery ceiling (entities per tick)
   }
 });
 ```
 
+`budget` puts a hard per-subscriber ceiling on how many entities one tick delivers: past it the due set trims farthest-first (band, then distance - the fringe fades before the duel next to you), and a trimmed entity stays owed, delivering the moment the budget frees, so motion is throttled, never lost. The ceiling also tightens itself for a subscriber whose socket is backpressured - the server reads each connection's outbound queue as it culls, scaling the budget down smoothly (to a floor of one) as the queue approaches the transport's shedding limit - so a congested client sheds its fringe gracefully instead of having the transport drop arbitrary frames, and a lagging shooter's rewind reach widens automatically with its real delivery cadence. Always-visible entities ride above the ceiling. Per-client interest mode only (`cells` mode fans out per cell and has no per-subscriber walk to bound - combining them throws).
+
 The area-of-interest centre is the subscriber's own entity by default, so a player-centric game needs no extra wiring. A spectator or free-cam whose view is not its own entity calls `view.reportCenter(x, y)` to point culling at where the camera looks (and `view.clearCenter()` to revert); the report rides a volatile send, an unchanged centre is dropped, and it takes effect even on a still board, so panning across a paused scene reveals what is there.
 
 > **Authoritative games: gate the centre report.** By default reports are ungated (`centerPolicy: 'any'`) - deliberately, because on self-selecting surfaces (cursors, canvases, geo-dashboards) choosing your own view IS the feature. On a server-authoritative game topic, though, an ungated report is a radar cheat: a modified client recenters replication anywhere on the map. Set `interest: { centerPolicy: 'own-entity' }` to clamp every connection that owns a positioned entity to that entity (spectators - connections whose entity resolves no position - keep the free-cam), or pass a callback `(ctx, center, ownPos) => boolean | { x, y }` to decide per report (return a point to clamp instead of rejecting; a throw rejects). A rejected report behaves like no report, a previously-accepted override is dropped, and clearing is always allowed. It applies identically in cells mode, where the report drives the cell subscriptions themselves. `lod` bands let distant motion fade at a throttled, id-staggered cadence instead of consuming the same bandwidth as a nearby duel; a small hysteresis margin on the band edges stops an entity hovering on a ring from flickering, and an entity entering range (or crossing into a nearer band) is always delivered at once. Relevancy is a delivery preference, never authorization - the `guard` stays the separate auth layer - and the polarity is to over-deliver: a subscriber with no resolvable centre is delivered the whole board. The join snapshot is scoped the same way: a syncing subscriber receives the in-range roster plus the always-visible entities (and always its own entity, its reconciliation basis), not the whole board - entities it later moves toward are caught up on first sight. **Off by default**, gated end to end on `interest != null`, so a topic without it is byte-identical to the broadcast-all path (the gate overhead benchmarks within noise, well under 1%). Culling re-sends an entity only when it actually moved since a subscriber last saw it, which relies on `apply` returning a NEW state object on a change rather than mutating in place - the same contract the broadcast itself already depends on (an in-place mutation makes the authority think nothing changed). At arena scale the cull delivers roughly 90% less per client, and the saving grows with the population. It works single-instance and across the cluster: a topic's owner culls its own local subscribers against the full cluster-wide catalog, and every other instance runs the same cull on the receive side - it keeps a shadow catalog (seeded from the owner's cold-join snapshot so a stationary in-range entity is never missed, then updated from inbound relays) and delivers each of its local subscribers only the relayed updates inside its area of interest. So the last hop to a remote player is culled too, never over-delivered. The inter-instance relay itself still carries every update between instances (the owner cannot cull per remote subscriber, since it does not hold a remote subscriber's centre); trimming that bus traffic is a separate future optimization.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "svelte-realtime",
-	"version": "0.6.0-next.73",
+	"version": "0.6.0-next.74",
 	"publishConfig": {
 		"tag": "next"
 	},

package/src/server/interest.js

@@ -219,6 +219,25 @@ export function createInterestState(interest) {
 	const subSet = new Set();
 	/** @type {number[]} empty always-visible list for candidatesAt (ring-less entities are never hit candidates) */
 	const noAlwaysVisible = [];
+	// Per-subscriber budget scratch (pooled; touched only when a delivery budget
+	// is active for the subscriber, so the uncapped path allocates nothing). The
+	// due banded entries collect here so an over-budget tick can trim the
+	// farthest ones; parallel arrays keep the scan allocation-free.
+	/** @type {string[]} */
+	const dueKeys = [];
+	/** @type {number[]} */
+	const dueBand = [];
+	/** @type {number[]} */
+	const dueD2 = [];
+	/** @type {number[]} previous band per due entry (-1 = first sight) */
+	const duePrevBand = [];
+	/** @type {any[]} previous last-sent state per due entry */
+	const duePrevSent = [];
+	/** @type {number[]} sortable index scratch for the over-budget trim */
+	const dueOrder = [];
+	/** Nearest-first order for the trim: band, then distance, then key (deterministic). */
+	const dueCompare = (a, b) =>
+		dueBand[a] - dueBand[b] || dueD2[a] - dueD2[b] || (dueKeys[a] < dueKeys[b] ? -1 : 1);
 
 	/**
 	 * Record a subscriber's reported area-of-interest center (the optional
@@ -303,12 +322,30 @@ export function createInterestState(interest) {
 	 * a fringe entity's motion accumulated across throttled ticks is flushed on its
 	 * next due tick whether or not it happened to move on that exact tick.
 	 *
+	 * When a delivery budget is active for a subscriber (`budgetOf` returns a
+	 * finite count), at most that many BANDED entities are delivered to it this
+	 * tick: the due set is trimmed farthest-first (band, then distance - the
+	 * fringe demotes before the action around the player), and a trimmed entry's
+	 * LOD record is reverted to its pre-tick value, so the entity stays due and
+	 * delivers as soon as the budget frees - throttled, never lost. Always-visible
+	 * entities and whole-board (uncentered) subscribers bypass the budget: the
+	 * first are an explicit app statement, the second is the over-deliver safety
+	 * polarity, and neither has a distance to trim by. The candidate membership
+	 * (`getCandidates`) is untouched by a trim - an entity delivered earlier is
+	 * still on the shooter's screen and stays hittable; one never delivered never
+	 * entered the membership at all.
+	 *
 	 * @param {Array<{ key: string, state: any }>} catalog the authority catalog
 	 * @param {Iterable<string>} subscribers the local subscriber identities
 	 * @param {number} tick a monotonic integer tick counter (drives the LOD cadence)
+	 * @param {(identity: string) => number | undefined} [budgetOf] the effective
+	 *   per-subscriber delivery budget for this tick (already scaled by whatever
+	 *   pressure signal the caller reads); a non-finite / undefined return means
+	 *   uncapped. Kept as an injected read so this pass stays clock- and I/O-free.
 	 * @returns {Map<string, Set<string>>} identity -> entity keys to deliver this tick
 	 */
-	function compute(catalog, subscribers, tick) {
+	function compute(catalog, subscribers, tick, budgetOf) {
+		const budgeted = typeof budgetOf === 'function';
 		const n = catalog.length;
 
 		// 1. Resolve every entity's position once; collect the always-visible ones.
@@ -358,6 +395,14 @@ export function createInterestState(interest) {
 			if (lodForS === undefined) { lodForS = new Map(); lod.set(identity, lodForS); }
 			const relevant = new Set();
 			seen.clear();
+			// Resolve this subscriber's effective delivery budget once per tick.
+			let cap = Infinity;
+			if (budgeted) {
+				const b = budgetOf(identity);
+				if (typeof b === 'number' && Number.isFinite(b) && b >= 1) cap = Math.floor(b);
+			}
+			const capped = cap !== Infinity;
+			let dueCount = 0;
 
 			// 4. The candidate set is the in-radius cull when centered, or every entity
 			// when whole-board. Each candidate is delivered only when its state changed
@@ -398,9 +443,43 @@ export function createInterestState(interest) {
 				// so a stationary in-range entity is never re-sent.
 				const cadence = prevBand < 0 || band !== prevBand || rate <= 1 || tick % rate === hashes[idx] % rate;
 				const due = changed && cadence;
-				if (due) relevant.add(key);
+				if (due) {
+					relevant.add(key);
+					if (capped) {
+						// Record what the trim below needs: the sort keys (band, d2)
+						// and the pre-tick LOD record to revert a trimmed entry to.
+						dueKeys[dueCount] = key;
+						dueBand[dueCount] = band;
+						dueD2[dueCount] = d2;
+						duePrevBand[dueCount] = prevBand;
+						duePrevSent[dueCount] = prevSent;
+						dueCount++;
+					}
+				}
 				lodForS.set(key, { band, sent: due ? state : prevSent });
 			}
+			// Over budget: keep the `cap` nearest due entries (band, then distance,
+			// then key - fully deterministic) and revert the rest to their pre-tick
+			// LOD record, so a trimmed entity stays due and delivers when the budget
+			// frees. A reverted first-sight entry is REMOVED (it was never delivered,
+			// so it must not enter the candidate membership); a reverted known entry
+			// keeps its old band, so a dropped band-crossing re-detects and delivers
+			// promptly once there is room.
+			if (capped && dueCount > cap) {
+				dueOrder.length = dueCount;
+				for (let i = 0; i < dueCount; i++) dueOrder[i] = i;
+				dueOrder.sort(dueCompare);
+				for (let i = cap; i < dueCount; i++) {
+					const j = dueOrder[i];
+					const key = dueKeys[j];
+					relevant.delete(key);
+					if (duePrevBand[j] < 0) lodForS.delete(key);
+					else lodForS.set(key, { band: duePrevBand[j], sent: duePrevSent[j] });
+				}
+			}
+			// Release the pooled state references so a departed entity's last state
+			// is not retained by the scratch until the next capped tick.
+			for (let i = 0; i < dueCount; i++) duePrevSent[i] = undefined;
 			// Forget entities that left this subscriber's range, so a re-entry is a
 			// fresh first-sight (delivered at once) and the map stays bounded by the
 			// live in-range set rather than every entity ever seen.

package/src/server/smooth.js

@@ -277,6 +277,45 @@ const _SMOOTH_SNAPSHOT_MS = 1000;
  */
 const _SMOOTH_PENDING_GRACE_MS = 30000;
 
+/**
+ * The outbound-queue window that scales a subscriber's `interest.budget` down.
+ * Below LOW (the adapter pressure sampler's "notable queue" bar) the full budget
+ * applies; at HIGH (the uWS default `maxBackpressure`, where the adapter starts
+ * shedding frames outright) the budget floors at 1 - the innermost entity still
+ * flows, and a socket this wedged is about to be degraded by the transport
+ * anyway. Linear in between: congestion sheds the fringe first, smoothly,
+ * instead of letting the transport drop arbitrary frames at the cliff.
+ */
+const _SMOOTH_BUDGET_BUFFERED_LOW = 65536;
+const _SMOOTH_BUDGET_BUFFERED_HIGH = 1048576;
+
+/**
+ * Build the per-tick effective-budget reader for a topic with `interest.budget`
+ * set: the configured ceiling, scaled by the subscriber socket's CURRENT
+ * outbound queue depth. The read is per subscriber per tick (one native
+ * `getBufferedAmount` getter - the same accessor the adapter's pressure sampler
+ * walks); a platform whose sockets do not expose it (the deterministic sim, a
+ * bare test double) reads as unbuffered and keeps the full budget, so the pure
+ * relevancy pass stays deterministic wherever the transport is.
+ * @param {any} rec @param {number} budget
+ * @returns {(identity: string) => number | undefined}
+ */
+function _smoothBudgetOf(rec, budget) {
+	return (identity) => {
+		const ws = rec.registry.get(identity);
+		if (ws === undefined) return budget;
+		let buffered = 0;
+		if (typeof ws.getBufferedAmount === 'function') {
+			try { buffered = ws.getBufferedAmount(); } catch { buffered = 0; }
+		}
+		if (!(typeof buffered === 'number' && Number.isFinite(buffered)) || buffered <= _SMOOTH_BUDGET_BUFFERED_LOW) return budget;
+		if (buffered >= _SMOOTH_BUDGET_BUFFERED_HIGH) return 1;
+		const scale = 1 - (buffered - _SMOOTH_BUDGET_BUFFERED_LOW) / (_SMOOTH_BUDGET_BUFFERED_HIGH - _SMOOTH_BUDGET_BUFFERED_LOW);
+		const b = Math.floor(budget * scale);
+		return b >= 1 ? b : 1;
+	};
+}
+
 /**
  * One-shot dev guard. When live.smooth() runs on a platform that does not
  * implement the binary wire (`publishWire`/`sendWire`), the tick degrades to
@@ -458,6 +497,10 @@ export function _smoothRecord(name, cfg, platform, rt) {
 			// on - it closes over the record, so it cannot be built inside this
 			// literal. Null otherwise (the OFF-path shape is unchanged).
 			aoi: null,
+			// The per-subscriber effective-budget reader (interest.budget), assigned
+			// right below when the budget is set - same closes-over-the-record
+			// reason as aoi. Null otherwise (uncapped, byte-identical).
+			budgetOf: null,
 			// The server world view for the onTick hook (server game logic: forces,
 			// respawns, NPC drivers), assigned right below when onTick is configured.
 			// Null otherwise - the tick pays one null check. The warn latches keep a
@@ -494,6 +537,14 @@ export function _smoothRecord(name, cfg, platform, rt) {
 		// hitTest reads candidates / radius / interp-delay through one accessor so
 		// the shot handlers never branch on the interest mode (per-client vs cells).
 		if (cfg.hitTest) rec.aoi = _smoothAoi(rec);
+		// Per-subscriber delivery ceiling (interest.budget): the effective-budget
+		// reader the relevancy pass consults, scaled live by each subscriber
+		// socket's outbound queue. Null (the default) keeps the pass uncapped and
+		// byte-identical. Closes over the record (it reads the live registry), so
+		// it cannot be built inside the literal - the aoi precedent above.
+		if (rec.interest !== null && cfg.interest && cfg.interest.budget) {
+			rec.budgetOf = _smoothBudgetOf(rec, cfg.interest.budget);
+		}
 		if (cfg.onTick) {
 			// Version gate: the world view needs the authority's server-entity
 			// surface. Feature-detected (not version-compared) so a custom runtime
@@ -1066,7 +1117,7 @@ function _smoothCullTick(rec) {
 	const t = rec.lagComp !== null ? (_edgeOwnerNow(rec) ?? wallEpoch()) : 0;
 	const catalog = [];
 	for (const [key, state] of rec.shadow) catalog.push({ key, state });
-	const relevancy = rec.interest.compute(catalog, rec.registry.keys(), rec.interestTick++);
+	const relevancy = rec.interest.compute(catalog, rec.registry.keys(), rec.interestTick++, rec.budgetOf ?? undefined);
 	_smoothDeliverCulled(rec, relevancy, rec.shadow, rec.pendingRelay, t);
 	rec.pendingRelay.clear();
 	rec.shadowDirty = false;
@@ -1195,7 +1246,7 @@ function _smoothTick(rec) {
 	const wantInterest = rec.interest !== null && (wireUpdates.length > 0 || rec.interestDirty);
 	const catalog = (rec.lagComp !== null || wantInterest) ? rec.authority.catalog() : null;
 	const relevancy = wantInterest
-		? rec.interest.compute(catalog, rec.registry.keys(), rec.interestTick++)
+		? rec.interest.compute(catalog, rec.registry.keys(), rec.interestTick++, rec.budgetOf ?? undefined)
 		: null;
 	if (rec.lagComp !== null && catalog !== null) {
 		// Key the ring on the monotonic axis (immune to a wall backstep); `t` (wall)
@@ -1789,8 +1840,11 @@ function _validateWire(wire) {
  * relevancy pass consumes. `radius` and `position` are required when interest is
  * on (without a resolvable position there is nothing to cull on); `lod` bands,
  * when given, must be strictly ascending by `within` with an integer send-`rate`
- * of at least 1; `cell` tunes the spatial grid. `budget` is accepted but inert in
- * this version (a reserved per-client bandwidth ceiling).
+ * of at least 1; `cell` tunes the spatial grid. `budget` is the per-subscriber
+ * delivery ceiling (an integer of at least 1) the per-client cull enforces,
+ * scaled down further for a backpressured socket; it applies to the per-client
+ * interest mode only, so combining it with `cells` (which fans out per cell,
+ * with no per-subscriber walk to bound) is a config contradiction and throws.
  * @param {any} it
  */
 function _validateInterest(it) {
@@ -1809,6 +1863,14 @@ function _validateInterest(it) {
 	if (it.cells !== undefined && typeof it.cells !== 'boolean') {
 		throw new Error('[svelte-realtime] live.smooth() interest.cells must be a boolean');
 	}
+	if (it.budget !== undefined) {
+		if (!(typeof it.budget === 'number' && Number.isInteger(it.budget) && it.budget >= 1)) {
+			throw new Error('[svelte-realtime] live.smooth() interest.budget must be an integer of at least 1');
+		}
+		if (it.cells === true) {
+			throw new Error('[svelte-realtime] live.smooth() interest.budget applies to the per-client interest mode; cells mode fans out per cell and has no per-subscriber delivery walk to bound');
+		}
+	}
 	if (
 		it.centerPolicy !== undefined &&
 		it.centerPolicy !== 'any' &&
@@ -2561,7 +2623,13 @@ export async function _smoothResolveShot(rec, name, shooterKey, shooterEntity, c
  * `interest.lod` is an ascending list of `{ within, rate }` level-of-detail
  * bands (send every `rate` ticks within that distance; the outer band's edge is
  * the cull radius), `interest.cell` tunes the spatial grid, and
- * `interest.budget` is reserved (inert). `interest.cells` switches to
+ * `interest.budget` caps how many entities are delivered to one subscriber per
+ * tick: past the ceiling the due set trims farthest-first (fringe bands demote
+ * before the action around the player), a trimmed entity stays due and delivers
+ * as soon as the budget frees, and the ceiling scales down automatically for a
+ * subscriber whose socket is backpressured - congestion sheds the fringe
+ * smoothly instead of letting the transport drop arbitrary frames. Per-client
+ * interest mode only (with `cells` it throws). `interest.cells` switches to
  * population-scale cell-topic mode: area-of-interest becomes SUBSCRIPTION to
  * grid-cell topics (one encode per cell, native fan-out) instead of a
  * per-subscriber cull. `interest.centerPolicy` gates reported centers

package/src/server.d.ts

@@ -3239,7 +3239,19 @@ export interface SmoothInterestConfig {
 		| 'any'
 		| 'own-entity'
 		| ((ctx: LiveContext<any>, center: SmoothPoint, ownPos: SmoothPoint | null) => boolean | SmoothPoint);
-	/** Reserved per-client bandwidth ceiling - accepted but inert in this version. */
+	/**
+	 * Per-subscriber delivery ceiling (an integer of at least 1): at most this
+	 * many entities are delivered to one subscriber per tick. Past the ceiling
+	 * the due set trims farthest-first (band, then distance - the fringe demotes
+	 * before the action around the player); a trimmed entity stays due and
+	 * delivers as soon as the budget frees, so motion is throttled, never lost.
+	 * The ceiling scales down automatically for a subscriber whose socket is
+	 * backpressured (read from the connection's outbound queue each tick), so
+	 * congestion sheds the fringe smoothly instead of letting the transport
+	 * drop arbitrary frames at its limit. Always-visible entities (a null
+	 * `position`) bypass the ceiling. Per-client interest mode only - combining
+	 * it with `cells` throws at declaration. Off by default (uncapped).
+	 */
 	budget?: number;
 }