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.

docs(net): the provider, and which reader can be incremental

esengine541fa66e7873
diff --git a/docs/astro/src/content/docs/scripting/networking.mdx b/docs/astro/src/content/docs/scripting/networking.mdx
index e6207acd2..6e5a75a33 100644
--- a/docs/astro/src/content/docs/scripting/networking.mdx
+++ b/docs/astro/src/content/docs/scripting/networking.mdx
@@ -157,12 +157,45 @@ server.setInterestPolicy(({ connectionId, world, candidates }) => {
- **Owned entities are never culled** — a policy can't hide a client's own pawn.
- **Re-entering is seamless**: the respawn carries the entity's *current* state.
-- `radiusInterest` reads `Transform.position` by default (override with
- `{ position }`); placeless entities are always relevant, and it fails open
- while a connection owns no positioned entity yet.
+- `radiusInterest` reads the composed **world** position of `Transform` by
+ default (override with `{ position }`); placeless entities are always relevant,
+ and it fails open while a connection owns no positioned entity yet.
- Installing, replacing, or removing the policy mid-session is safe — the next
tick reconciles every connection's ghost set.
+#### Scaling it: `radiusInterestProvider`
+
+A policy is handed the population **per connection**, so whatever it reads it
+reads once per connection. A *provider* prepares one spatial index per sample and
+answers every connection from it:
+
+```typescript
+import { radiusInterestProvider } from 'esengine';
+
+server.setInterestProvider(radiusInterestProvider(800));
+```
+
+It answers exactly what the policy answers, and it has two modes — a difference
+in **capability**, not a fallback:
+
+| reader | what it does | why |
+|---|---|---|
+| the default `Transform` | keeps its index between samples and moves only the entities that actually moved | the engine reports which world transforms a composition changed |
+| a custom `position` | rebuilds the index every sample | nothing can know when an arbitrary function would answer differently |
+
+At 100,000 entities and 32 connections the kept index costs **18% of one core**
+against 195% for rebuilding it every sample, and reads 668 positions per sample
+instead of 100,000. With nothing moving it reads none.
+
+Two things follow from the kept index, and neither is a limitation you can work
+around by writing the reader differently:
+
+- If you supply `position`, you get the per-sample rebuild. That is the correct
+ answer for an arbitrary function, and it is still far cheaper than a policy.
+- Physics-driven and parent-driven movement both reach it, because both go
+ through the same composition. A game that writes `worldPosition` itself does
+ not — that field is the composition's output, not an input.
+
### Client prediction — zero-latency input
Without prediction, your own pawn only moves after a full server round trip.
diff --git a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx
index 726fc01c0..ca09a40aa 100644
--- a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx
+++ b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx
@@ -147,10 +147,38 @@ server.setInterestPolicy(({ connectionId, world, candidates }) => {
- **自有实体永不被剔除**——策略藏不掉客户端自己的 pawn。
- **重进无缝**:重新 spawn 携带实体的*当前*状态。
-- `radiusInterest` 默认读 `Transform.position`(可用 `{ position }` 覆盖);
- 无位置的实体恒相关;连接尚无带位置的自有实体时 fail-open(看到全部)。
+- `radiusInterest` 默认读 `Transform` 合成后的**世界**位置(可用 `{ position }`
+ 覆盖);无位置的实体恒相关;连接尚无带位置的自有实体时 fail-open(看到全部)。
- 会话中安装/替换/移除策略都是安全的——下一 tick 会调和每个连接的 ghost 集。
+#### 上规模:`radiusInterestProvider`
+
+策略是**按连接**拿到整个population的,所以它读什么就读几遍。而 *provider* 每次
+采样只准备一次空间索引,然后用它回答所有连接:
+
+```typescript
+import { radiusInterestProvider } from 'esengine';
+
+server.setInterestProvider(radiusInterestProvider(800));
+```
+
+它给出的答案与策略逐个实体一致,并且有两种模式——这是**能力**差别,不是降级:
+
+| 读取器 | 行为 | 原因 |
+|---|---|---|
+| 默认的 `Transform` | 索引跨采样保留,只移动真正动过的实体 | 引擎会报告一次合成改变了哪些世界变换 |
+| 自定义 `position` | 每次采样重建索引 | 没有人能知道一个任意函数何时会给出不同答案 |
+
+10 万实体、32 个连接时,保留索引占 **18% 单核**,而每采样重建是 195%;每采样读
+668 次位置而不是 10 万次。完全没有东西移动时读 0 次。
+
+保留索引带来两条结论,都不是换个写法就能绕开的:
+
+- 你传了 `position`,就走每采样重建。对任意函数来说这是正确答案,而且仍然远比
+ 策略便宜。
+- 物理驱动和父节点驱动的移动都会到达索引,因为两者都经过同一次合成。自己去写
+ `worldPosition` 的游戏则不会——那个字段是合成的输出,不是输入。
+
### 客户端预测——零延迟输入
不开预测时,你自己的 pawn 要等一整个来回才动。开启预测的方式是把**服务器玩法