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(terrain): a Planet component draws ground on a sphere from a provider that answers by direction

yhh996c91df0eb2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 69bf88a4e..557b80c68 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@ published separately; it ships inside the editor.
### Added
+- **A `Planet`: ground on a sphere.** A `Planet` component draws ground on a round world: a cube whose six faces are each a quadtree, every point pushed out to the radius, the finest cells under the eye and a handful of coarse nodes from space, so one ground is drawn from the surface and from orbit. It reads a generator the game registers with `registerPlanetProvider`, which answers for directions from the centre (a sphere has no x and z) with heights and layer weights. It is the first slice of round worlds: the ground is drawn; collision, the layers' textures, the sea, a round sky and gravity toward the centre are not in it yet.
- **A far world is planned sparsely, and a failed asset load is tried again.** A layer's `farSpacing` plans the far versions of its plants that much further apart, so ground cover that keeps a quarter of its plants far off no longer plans all of them first, and the far plants of a planet settle in a quarter of the time. A world whose recipes' assets fail to load while the project is still opening tries again, a few times and a little later each time, instead of staying empty.
- **A quality level sets how far plants keep their detail.** A level's profile takes a `detailScale` (0.25 to 1; Low 0.5, Medium 0.8, High 1): a placed plant changes to its cheaper mesh, stops being drawn and stops casting a shadow at that share of its distances, so the same world draws a fraction of the triangles on a phone. It is a row in Project Settings → Rendering → Quality Levels.
- **Placed plants cast shadows only as far as twice their detailed distance.** `MeshInstances` takes a `shadowDistance` (metres from the eye past which an instance casts no shadow); a plant kind with a cheaper mesh sets it to twice that mesh's distance, so a tree far off is drawn into the shadow maps no more than its shadow is worth.
diff --git a/docs/astro/src/content/docs/graphics/terrain.mdx b/docs/astro/src/content/docs/graphics/terrain.mdx
index f2d64ec35..02b7a7921 100644
--- a/docs/astro/src/content/docs/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/graphics/terrain.mdx
@@ -253,6 +253,37 @@ A version names an algorithm for good. A saved world keeps `generatorVersion`; w
the old one, so what was built on the old ground still stands on it. The engine's noise is `estella:noise`, version 1. A provider
with `heightAt` answers a point at once; without it a point is answered from small sampled tiles at the finest cell size.
+## A planet
+
+A **`Planet`** is ground on a sphere. It is the same machinery as the ground above with a round world under it: a cube whose six faces are each a quadtree, every point pushed out to
+the radius, so the finest cells are under the eye and a planet seen from far off is a handful of coarse nodes. The same ground is drawn from the surface and from space, with nothing
+to switch between.
+
+| Field | What it does |
+|---|---|
+| `radius` | The planet's radius in metres. The planet stands at its entity, unrotated and unscaled. |
+| `provider`, `world`, `generatorVersion`, `seed` | The generator the ground is made by (`registerPlanetProvider`), the world it belongs to as the game names it, its version and its seed. The same four are the same ground everywhere. |
+| `cellSize`, `detail` | The finest cell of the ground's mesh in metres, and how far out the finest cells reach (above 1 is further). |
+| `layerColor0`–`3`, `macroScale`, `macroVariation` | The four layers' colours (grass, dirt, snow, rock), and the wander in brightness laid over them. |
+
+A planet's provider answers for **directions**, not positions: it is handed unit directions from the planet's centre and the radius they are on, and gives back each one's height above the radius
+and, if it paints, four layer weights. A sphere has no x and z, so a generator reads three-dimensional noise at the point's place, which has no seam and no pole.
+
+```typescript
+registerPlanetProvider({
+ id: 'my-game:planet',
+ versions: [1],
+ range: () => [-40, 200],
+ sample({ seed, radius, directions, count }) {
+ const heights = new Float32Array(count);
+ for (let i = 0; i < count; i++) heights[i] = myHeight(seed, radius, directions[i * 3]!, directions[i * 3 + 1]!, directions[i * 3 + 2]!);
+ return { heights };
+ },
+});
+```
+
+This is the first slice of round worlds: it draws the ground. Collision, the layers' textures, the sea, a sky that follows the horizon round and gravity toward the centre are not in it yet.
+
## Limits
- **Collision is the finest level.** Far off the ground is drawn coarser than it collides, which is unseen from where anything collides
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
index 561c94727..a2b9a31e0 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx
@@ -180,6 +180,21 @@ registerTerrainProvider(planet);
一个版本永久对应一种算法。存档的世界保留 `generatorVersion`;算法改变时新增一个版本并保留旧版本,这样建在旧地面上的东西仍立在原处。引擎的噪声是 `estella:noise` 版本 1。带 `heightAt` 的生成器能立刻回答单点;没有它时,单点从按最细格子采样的小块里回答。
+## 星球
+
+**`Planet`** 是球面上的地面。机制和上面的地面一样,只是下面是一个圆的世界:一个立方体,六个面各是一棵四叉树,每个点都被推到半径上,所以最细的格子在眼睛下面,从远处看星球只是几个粗节点。从地面看和从太空看是同一份地面,中间没有什么要切换。
+
+| 字段 | 作用 |
+|---|---|
+| `radius` | 星球半径,单位米。星球立在它的实体处,不旋转、不缩放。 |
+| `provider`、`world`、`generatorVersion`、`seed` | 生成地面的生成器(`registerPlanetProvider`)、游戏给它起的世界名、版本和种子。这四个相同,各处的地面就相同。 |
+| `cellSize`、`detail` | 地面网格最细的格子,单位米;以及最细的格子往外延伸多远(大于 1 更远)。 |
+| `layerColor0`–`3`、`macroScale`、`macroVariation` | 四个图层的颜色(草、土、雪、岩),以及盖在上面的亮度起伏。 |
+
+星球的提供器回答的是**方向**,不是位置:它拿到从星球中心出发的单位方向和它们所在的半径,给出每个方向上高出半径的高度,如果上色,再给出四个图层权重。球面没有 x 和 z,所以生成器读三维噪声,没有接缝也没有极点。
+
+这是圆形世界的第一片:它画出地面。碰撞、图层贴图、海、跟着地平线转的天空和指向球心的重力还没有。
+
## 限制
- **碰撞按最细一级。** 远处的地面画得比碰撞粗,但碰撞发生的地方看不出来;只有运动的物体在 `collisionDistance` 内才有可碰的地面。
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index b814eab17..956e2693f 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 115,
"beta": 171,
- "experimental": 2517,
+ "experimental": 2545,
"deprecated": 3
},
- "total": 2803,
+ "total": 2831,
"subsystems": [
{
"id": "mobile-controls",
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index 5ffbc1057..9ac38ba72 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -91,6 +91,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
SortingGroup: { category: 'graphics', summary: 'Makes an entity and its whole subtree sort as one unit — the group states the layer and order, members state their place inside it.', doc: 'graphics/sprites', anchor: 'sorting-groups', anchorZh: '排序组' },
StaticBatch: { category: 'graphics', summary: 'Marks a mesh that will not move, so the meshes sharing its material are merged into one draw while the game runs; it also records what became of this one.', doc: 'performance/static-batching', anchor: 'what-happens', anchorZh: '会发生什么' },
Terrain: { category: 'graphics', summary: 'Ground made from a heightmap or noise, painted by height and slope, and drawn in chunks that coarsen with distance.', doc: 'graphics/terrain', anchor: 'the-component', anchorZh: '组件' },
+ Planet: { category: 'graphics', summary: 'Ground on a sphere, drawn as six quadtrees round the eye from a generator the game registers, finest underfoot and a handful of coarse nodes from space.', doc: 'graphics/terrain', anchor: 'a-planet', anchorZh: '星球' },
Foliage: { category: 'graphics', summary: 'Scatters grass or a mesh across an area and over a terrain, drawn a cell at a time, swaying in the wind and thinning out with distance.', doc: 'graphics/foliage', anchor: 'the-component', anchorZh: '组件' },
PlacedFoliage: { category: 'graphics', summary: 'Keeps every plant an artist placed by hand as data in one entity, grown a cell at a time as instances of the plants\' own meshes.', doc: 'graphics/foliage', anchor: 'placed-plants', anchorZh: '手摆植物' },
MeshInstances: { category: 'graphics', summary: 'Draws the mesh of a MeshRenderer at many places as one renderable, culling each place and choosing its mesh by distance.', doc: 'graphics/foliage', anchor: 'placed-plants', anchorZh: '手摆植物' },
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 1cb4c349e..4882949da 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -3807,6 +3807,118 @@
}
]
},
+ {
+ "name": "Planet",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "radius",
+ "type": "number",
+ "default": "4000",
+ "doc": "The planet's radius in metres. The planet stands at its entity, unrotated and unscaled.",
+ "range": "≥ 1"
+ },
+ {
+ "key": "provider",
+ "type": "string",
+ "default": "empty",
+ "doc": "The generator the ground is made by, registered with registerPlanetProvider. The same provider, world, seed and version are the same ground everywhere."
+ },
+ {
+ "key": "world",
+ "type": "string",
+ "default": "empty",
+ "doc": "The world (a planet) the ground belongs to, as the game names it; handed to the provider."
+ },
+ {
+ "key": "generatorVersion",
+ "type": "number",
+ "default": "1",
+ "doc": "The generator version the planet was made with. A version the provider no longer has fails the planet rather than growing other ground under what was built on it.",
+ "range": "≥ 1, step 1"
+ },
+ {
+ "key": "seed",
+ "type": "number",
+ "default": "1",
+ "doc": "Another seed is another planet.",
+ "range": "step 1"
+ },
+ {
+ "key": "cellSize",
+ "type": "number",
+ "default": "1.5",
+ "doc": "The finest cell of the ground's mesh, in metres: what it is drawn at near the eye. Further off the cells double, level by level.",
+ "range": "≥ 0.01"
+ },
+ {
+ "key": "detail",
+ "type": "number",
+ "default": "1.5",
+ "doc": "Above 1 the finest cells reach further out before the ground coarsens.",
+ "range": "0.25–8, step 0.05"
+ },
+ {
+ "key": "layerColor0",
+ "type": "Color",
+ "default": "#477533"
+ },
+ {
+ "key": "layerColor1",
+ "type": "Color",
+ "default": "#735c3d"
+ },
+ {
+ "key": "layerColor2",
+ "type": "Color",
+ "default": "#edf2fa"
+ },
+ {
+ "key": "layerColor3",
+ "type": "Color",
+ "default": "#66615c"
+ },
+ {
+ "key": "macroScale",
+ "type": "number",
+ "default": "90",
+ "doc": "The size, in metres, of the ground's own wander in brightness.",
+ "range": "≥ 1"
+ },
+ {
+ "key": "macroVariation",
+ "type": "number",
+ "default": "0.35",
+ "doc": "How strongly the ground's brightness wanders.",
+ "range": "0–1, step 0.01"
+ }
+ ],
+ "animatable": [
+ "radius",
+ "generatorVersion",
+ "seed",
+ "cellSize",
+ "detail",
+ "layerColor0.r",
+ "layerColor0.g",
+ "layerColor0.b",
+ "layerColor0.a",
+ "layerColor1.r",
+ "layerColor1.g",
+ "layerColor1.b",
+ "layerColor1.a",
+ "layerColor2.r",
+ "layerColor2.g",
+ "layerColor2.b",
+ "layerColor2.a",
+ "layerColor3.r",
+ "layerColor3.g",
+ "layerColor3.b",
+ "layerColor3.a",
+ "macroScale",
+ "macroVariation"
+ ]
+ },
{
"name": "PointJoint3D",
"source": "ts",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 98bc164bf..20c08feef 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 159 beta · 1843 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1864 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4012,6 +4012,11 @@ parent: number | null
visible: boolean | undefined
```
+## FACES — const @experimental
+```
+readonly { normal: readonly [number, number, number]; a: readonly [number, number, number]; b: readonly [number, number, number]; }[]
+```
+
## FILL_AXIS — const @experimental
```
Record<LinearFillDirection, readonly [FillMethod, FillOrigin]>
@@ -6728,6 +6733,69 @@ updated: boolean | undefined
width: number | undefined
```
+## Planet — const @experimental
+```
+ComponentDef<PlanetData>
+```
+
+## PlanetData — interface @experimental
+```
+cellSize: number
+detail: number
+generatorVersion: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+macroScale: number
+macroVariation: number
+provider: string
+radius: number
+seed: number
+world: string
+```
+
+## PlanetPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): PlanetPlugin
+static prototype: PlanetPlugin
+```
+
+## PlanetProvider — interface @experimental
+```
+id: string
+range: (seed: number, version: number, radius: number) => [number, number]
+sample: (region: PlanetRegion) => TerrainSamples | Promise<TerrainSamples>
+versions: readonly number[]
+```
+
+## PlanetRegion — interface @experimental
+```
+count: number
+directions: Float32Array<ArrayBufferLike>
+radius: number
+seed: number
+version: number
+world: string
+```
+
+## PlanetStatus — interface @experimental
+```
+reason: string | undefined
+state: "failed" | "ready" | "loading"
+```
+
+## Planets — class @experimental
+```
+built_: Map<number, Built>
+status: (entity: Entity) => PlanetStatus | null
+static new (): Planets
+static prototype: Planets
+```
+
## Plant — interface @experimental
```
phase: number
@@ -9223,6 +9291,23 @@ radius: number
restitution: number
```
+## SphereNode — interface @experimental
+```
+face: number
+ix: number
+iz: number
+level: number
+```
+
+## SphereTreeParams — interface @experimental
+```
+leafSize: number
+maxHeight: number
+minHeight: number
+radius: number
+range0: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -12877,7 +12962,7 @@ MotionDriver<AnimatorBlend2DMotion>
## buildPatchMesh — function @experimental
```
-(cells: number): MeshData
+(cells: number, flipped?: boolean): MeshData
```
## buildText — function @experimental
@@ -13475,6 +13560,11 @@ DiagnosticsPlugin
(before: Census, after: Census): CensusDelta[]
```
+## direction — function @experimental
+```
+(face: number, u: number, v: number, out?: [number, number, number]): [number, number, number]
+```
+
## disconnect — function @beta
```
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
@@ -13750,6 +13840,11 @@ EventBindingPlugin
(g: MaterialGraph, ids: readonly string[], ref: string, name?: string): ExtractedSubgraph
```
+## faceOf — function @experimental
+```
+(dx: number, dy: number, dz: number): { face: number; u: number; v: number; }
+```
+
## fetchDecodePixels — function @experimental
```
(url: string, maxEdge?: number): Promise<DecodedPixels>
@@ -14310,6 +14405,11 @@ InputRouter
(p: Pick<QuadtreeParams, "range0">, level: number): number
```
+## levelsFor — function @experimental
+```
+(radius: number, leafSize: number): number
+```
+
## lifecyclePlugin — const @experimental
```
LifecyclePlugin
@@ -14500,11 +14600,26 @@ MeshRendererPlugin
() => InputState
```
+## nodeAt — function @experimental
+```
+(levels: number, face: number, level: number, u: number, v: number): SphereNode
+```
+
## nodeKey — function @experimental
```
(level: number, ix: number, iz: number): string
```
+## nodePoint — function @experimental
+```
+(p: SphereTreeParams, levels: number, node: SphereNode, s: number, t: number, height: number, out?: [number, number, number]): [number, number, number]
+```
+
+## nodeRect — function @experimental
+```
+(levels: number, node: SphereNode): { u0: number; v0: number; span: number; }
+```
+
## noiseProvider — function @experimental
```
(params: (seed: number) => NoiseParams): TerrainProvider
@@ -14720,6 +14835,16 @@ ParticlePlugin
(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
```
+## planetPlugin — const @experimental
+```
+PlanetPlugin
+```
+
+## planetProvider — function @experimental
+```
+(id: string): PlanetProvider | undefined
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -15030,6 +15155,11 @@ PrefabsPlugin
(config: Pick<PackagedGameConfig, "sideModules">): void
```
+## registerPlanetProvider — function @experimental
+```
+(provider: PlanetProvider): void
+```
+
## registerPreSceneDrawCallback — function @experimental
```
(id: string, fn: PreSceneDrawCallback): void
@@ -15365,6 +15495,11 @@ Plugin
(forms: PluralForms, count: number, selector: PluralSelector): string
```
+## selectSphereNodes — function @experimental
+```
+(p: SphereTreeParams, ex: number, ey: number, ez: number, levels?: number): SphereNode[]
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -15645,6 +15780,11 @@ ServicesPlugin
(init: UIEntityInit): Entity
```
+## sphereNodeKey — const @experimental
+```
+(n: SphereNode) => string
+```
+
## spineCullingContractFrom — function @experimental
```
(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index fad381430..61f621329 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 1862 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 1883 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4020,6 +4020,11 @@ parent: number | null
visible: boolean | undefined
```
+## FACES — const @experimental
+```
+readonly { normal: readonly [number, number, number]; a: readonly [number, number, number]; b: readonly [number, number, number]; }[]
+```
+
## FILL_AXIS — const @experimental
```
Record<LinearFillDirection, readonly [FillMethod, FillOrigin]>
@@ -6931,6 +6936,69 @@ updated: boolean | undefined
width: number | undefined
```
+## Planet — const @experimental
+```
+ComponentDef<PlanetData>
+```
+
+## PlanetData — interface @experimental
+```
+cellSize: number
+detail: number
+generatorVersion: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+macroScale: number
+macroVariation: number
+provider: string
+radius: number
+seed: number
+world: string
+```
+
+## PlanetPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): PlanetPlugin
+static prototype: PlanetPlugin
+```
+
+## PlanetProvider — interface @experimental
+```
+id: string
+range: (seed: number, version: number, radius: number) => [number, number]
+sample: (region: PlanetRegion) => TerrainSamples | Promise<TerrainSamples>
+versions: readonly number[]
+```
+
+## PlanetRegion — interface @experimental
+```
+count: number
+directions: Float32Array<ArrayBufferLike>
+radius: number
+seed: number
+version: number
+world: string
+```
+
+## PlanetStatus — interface @experimental
+```
+reason: string | undefined
+state: "failed" | "ready" | "loading"
+```
+
+## Planets — class @experimental
+```
+built_: Map<number, Built>
+status: (entity: Entity) => PlanetStatus | null
+static new (): Planets
+static prototype: Planets
+```
+
## Plant — interface @experimental
```
phase: number
@@ -9436,6 +9504,23 @@ radius: number
restitution: number
```
+## SphereNode — interface @experimental
+```
+face: number
+ix: number
+iz: number
+level: number
+```
+
+## SphereTreeParams — interface @experimental
+```
+leafSize: number
+maxHeight: number
+minHeight: number
+radius: number
+range0: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -13105,7 +13190,7 @@ MotionDriver<AnimatorBlend2DMotion>
## buildPatchMesh — function @experimental
```
-(cells: number): MeshData
+(cells: number, flipped?: boolean): MeshData
```
## buildText — function @experimental
@@ -13728,6 +13813,11 @@ DiagnosticsPlugin
(before: Census, after: Census): CensusDelta[]
```
+## direction — function @experimental
+```
+(face: number, u: number, v: number, out?: [number, number, number]): [number, number, number]
+```
+
## disconnect — function @beta
```
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
@@ -14003,6 +14093,11 @@ EventBindingPlugin
(g: MaterialGraph, ids: readonly string[], ref: string, name?: string): ExtractedSubgraph
```
+## faceOf — function @experimental
+```
+(dx: number, dy: number, dz: number): { face: number; u: number; v: number; }
+```
+
## fetchDecodePixels — function @experimental
```
(url: string, maxEdge?: number): Promise<DecodedPixels>
@@ -14573,6 +14668,11 @@ InputRouter
(p: Pick<QuadtreeParams, "range0">, level: number): number
```
+## levelsFor — function @experimental
+```
+(radius: number, leafSize: number): number
+```
+
## lifecyclePlugin — const @experimental
```
LifecyclePlugin
@@ -14763,11 +14863,26 @@ MeshRendererPlugin
() => InputState
```
+## nodeAt — function @experimental
+```
+(levels: number, face: number, level: number, u: number, v: number): SphereNode
+```
+
## nodeKey — function @experimental
```
(level: number, ix: number, iz: number): string
```
+## nodePoint — function @experimental
+```
+(p: SphereTreeParams, levels: number, node: SphereNode, s: number, t: number, height: number, out?: [number, number, number]): [number, number, number]
+```
+
+## nodeRect — function @experimental
+```
+(levels: number, node: SphereNode): { u0: number; v0: number; span: number; }
+```
+
## noiseProvider — function @experimental
```
(params: (seed: number) => NoiseParams): TerrainProvider
@@ -14983,6 +15098,16 @@ ParticlePlugin
(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
```
+## planetPlugin — const @experimental
+```
+PlanetPlugin
+```
+
+## planetProvider — function @experimental
+```
+(id: string): PlanetProvider | undefined
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -15293,6 +15418,11 @@ PrefabsPlugin
(config: Pick<PackagedGameConfig, "sideModules">): void
```
+## registerPlanetProvider — function @experimental
+```
+(provider: PlanetProvider): void
+```
+
## registerPreSceneDrawCallback — function @experimental
```
(id: string, fn: PreSceneDrawCallback): void
@@ -15628,6 +15758,11 @@ Plugin
(forms: PluralForms, count: number, selector: PluralSelector): string
```
+## selectSphereNodes — function @experimental
+```
+(p: SphereTreeParams, ex: number, ey: number, ez: number, levels?: number): SphereNode[]
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -15908,6 +16043,11 @@ ServicesPlugin
(init: UIEntityInit): Entity
```
+## sphereNodeKey — const @experimental
+```
+(n: SphereNode) => string
+```
+
## spineCullingContractFrom — function @experimental
```
(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 8e4d95ebe..79084028c 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 161 beta · 1842 experimental · 3 deprecated
+Symbols: 115 public · 161 beta · 1863 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4007,6 +4007,11 @@ parent: number | null
visible: boolean | undefined
```
+## FACES — const @experimental
+```
+readonly { normal: readonly [number, number, number]; a: readonly [number, number, number]; b: readonly [number, number, number]; }[]
+```
+
## FILL_AXIS — const @experimental
```
Record<LinearFillDirection, readonly [FillMethod, FillOrigin]>
@@ -6723,6 +6728,69 @@ updated: boolean | undefined
width: number | undefined
```
+## Planet — const @experimental
+```
+ComponentDef<PlanetData>
+```
+
+## PlanetData — interface @experimental
+```
+cellSize: number
+detail: number
+generatorVersion: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+macroScale: number
+macroVariation: number
+provider: string
+radius: number
+seed: number
+world: string
+```
+
+## PlanetPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): PlanetPlugin
+static prototype: PlanetPlugin
+```
+
+## PlanetProvider — interface @experimental
+```
+id: string
+range: (seed: number, version: number, radius: number) => [number, number]
+sample: (region: PlanetRegion) => TerrainSamples | Promise<TerrainSamples>
+versions: readonly number[]
+```
+
+## PlanetRegion — interface @experimental
+```
+count: number
+directions: Float32Array<ArrayBufferLike>
+radius: number
+seed: number
+version: number
+world: string
+```
+
+## PlanetStatus — interface @experimental
+```
+reason: string | undefined
+state: "failed" | "ready" | "loading"
+```
+
+## Planets — class @experimental
+```
+built_: Map<number, Built>
+status: (entity: Entity) => PlanetStatus | null
+static new (): Planets
+static prototype: Planets
+```
+
## Plant — interface @experimental
```
phase: number
@@ -9218,6 +9286,23 @@ radius: number
restitution: number
```
+## SphereNode — interface @experimental
+```
+face: number
+ix: number
+iz: number
+level: number
+```
+
+## SphereTreeParams — interface @experimental
+```
+leafSize: number
+maxHeight: number
+minHeight: number
+radius: number
+range0: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -12872,7 +12957,7 @@ MotionDriver<AnimatorBlend2DMotion>
## buildPatchMesh — function @experimental
```
-(cells: number): MeshData
+(cells: number, flipped?: boolean): MeshData
```
## buildText — function @experimental
@@ -13470,6 +13555,11 @@ DiagnosticsPlugin
(before: Census, after: Census): CensusDelta[]
```
+## direction — function @experimental
+```
+(face: number, u: number, v: number, out?: [number, number, number]): [number, number, number]
+```
+
## disconnect — function @beta
```
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
@@ -13745,6 +13835,11 @@ EventBindingPlugin
(g: MaterialGraph, ids: readonly string[], ref: string, name?: string): ExtractedSubgraph
```
+## faceOf — function @experimental
+```
+(dx: number, dy: number, dz: number): { face: number; u: number; v: number; }
+```
+
## fetchDecodePixels — function @experimental
```
(url: string, maxEdge?: number): Promise<DecodedPixels>
@@ -14305,6 +14400,11 @@ InputRouter
(p: Pick<QuadtreeParams, "range0">, level: number): number
```
+## levelsFor — function @experimental
+```
+(radius: number, leafSize: number): number
+```
+
## lifecyclePlugin — const @experimental
```
LifecyclePlugin
@@ -14505,11 +14605,26 @@ MeshRendererPlugin
NodePlatformAdapter
```
+## nodeAt — function @experimental
+```
+(levels: number, face: number, level: number, u: number, v: number): SphereNode
+```
+
## nodeKey — function @experimental
```
(level: number, ix: number, iz: number): string
```
+## nodePoint — function @experimental
+```
+(p: SphereTreeParams, levels: number, node: SphereNode, s: number, t: number, height: number, out?: [number, number, number]): [number, number, number]
+```
+
+## nodeRect — function @experimental
+```
+(levels: number, node: SphereNode): { u0: number; v0: number; span: number; }
+```
+
## noiseProvider — function @experimental
```
(params: (seed: number) => NoiseParams): TerrainProvider
@@ -14725,6 +14840,16 @@ ParticlePlugin
(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
```
+## planetPlugin — const @experimental
+```
+PlanetPlugin
+```
+
+## planetProvider — function @experimental
+```
+(id: string): PlanetProvider | undefined
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -15035,6 +15160,11 @@ PrefabsPlugin
(config: Pick<PackagedGameConfig, "sideModules">): void
```
+## registerPlanetProvider — function @experimental
+```
+(provider: PlanetProvider): void
+```
+
## registerPreSceneDrawCallback — function @experimental
```
(id: string, fn: PreSceneDrawCallback): void
@@ -15370,6 +15500,11 @@ Plugin
(forms: PluralForms, count: number, selector: PluralSelector): string
```
+## selectSphereNodes — function @experimental
+```
+(p: SphereTreeParams, ex: number, ey: number, ez: number, levels?: number): SphereNode[]
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -15650,6 +15785,11 @@ ServicesPlugin
(init: UIEntityInit): Entity
```
+## sphereNodeKey — const @experimental
+```
+(n: SphereNode) => string
+```
+
## spineCullingContractFrom — function @experimental
```
(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index f1c493d55..d24018f70 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 159 beta · 1864 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1885 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4007,6 +4007,11 @@ parent: number | null
visible: boolean | undefined
```
+## FACES — const @experimental
+```
+readonly { normal: readonly [number, number, number]; a: readonly [number, number, number]; b: readonly [number, number, number]; }[]
+```
+
## FILL_AXIS — const @experimental
```
Record<LinearFillDirection, readonly [FillMethod, FillOrigin]>
@@ -7016,6 +7021,69 @@ updated: boolean | undefined
width: number | undefined
```
+## Planet — const @experimental
+```
+ComponentDef<PlanetData>
+```
+
+## PlanetData — interface @experimental
+```
+cellSize: number
+detail: number
+generatorVersion: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+macroScale: number
+macroVariation: number
+provider: string
+radius: number
+seed: number
+world: string
+```
+
+## PlanetPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): PlanetPlugin
+static prototype: PlanetPlugin
+```
+
+## PlanetProvider — interface @experimental
+```
+id: string
+range: (seed: number, version: number, radius: number) => [number, number]
+sample: (region: PlanetRegion) => TerrainSamples | Promise<TerrainSamples>
+versions: readonly number[]
+```
+
+## PlanetRegion — interface @experimental
+```
+count: number
+directions: Float32Array<ArrayBufferLike>
+radius: number
+seed: number
+version: number
+world: string
+```
+
+## PlanetStatus — interface @experimental
+```
+reason: string | undefined
+state: "failed" | "ready" | "loading"
+```
+
+## Planets — class @experimental
+```
+built_: Map<number, Built>
+status: (entity: Entity) => PlanetStatus | null
+static new (): Planets
+static prototype: Planets
+```
+
## Plant — interface @experimental
```
phase: number
@@ -9511,6 +9579,23 @@ radius: number
restitution: number
```
+## SphereNode — interface @experimental
+```
+face: number
+ix: number
+iz: number
+level: number
+```
+
+## SphereTreeParams — interface @experimental
+```
+leafSize: number
+maxHeight: number
+minHeight: number
+radius: number
+range0: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -13171,7 +13256,7 @@ MotionDriver<AnimatorBlend2DMotion>
## buildPatchMesh — function @experimental
```
-(cells: number): MeshData
+(cells: number, flipped?: boolean): MeshData
```
## buildText — function @experimental
@@ -13774,6 +13859,11 @@ DiagnosticsPlugin
(before: Census, after: Census): CensusDelta[]
```
+## direction — function @experimental
+```
+(face: number, u: number, v: number, out?: [number, number, number]): [number, number, number]
+```
+
## disconnect — function @beta
```
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
@@ -14049,6 +14139,11 @@ EventBindingPlugin
(g: MaterialGraph, ids: readonly string[], ref: string, name?: string): ExtractedSubgraph
```
+## faceOf — function @experimental
+```
+(dx: number, dy: number, dz: number): { face: number; u: number; v: number; }
+```
+
## fetchDecodePixels — function @experimental
```
(url: string, maxEdge?: number): Promise<DecodedPixels>
@@ -14619,6 +14714,11 @@ InputRouter
(p: Pick<QuadtreeParams, "range0">, level: number): number
```
+## levelsFor — function @experimental
+```
+(radius: number, leafSize: number): number
+```
+
## lifecyclePlugin — const @experimental
```
LifecyclePlugin
@@ -14809,11 +14909,26 @@ MeshRendererPlugin
() => InputState
```
+## nodeAt — function @experimental
+```
+(levels: number, face: number, level: number, u: number, v: number): SphereNode
+```
+
## nodeKey — function @experimental
```
(level: number, ix: number, iz: number): string
```
+## nodePoint — function @experimental
+```
+(p: SphereTreeParams, levels: number, node: SphereNode, s: number, t: number, height: number, out?: [number, number, number]): [number, number, number]
+```
+
+## nodeRect — function @experimental
+```
+(levels: number, node: SphereNode): { u0: number; v0: number; span: number; }
+```
+
## noiseProvider — function @experimental
```
(params: (seed: number) => NoiseParams): TerrainProvider
@@ -15029,6 +15144,16 @@ ParticlePlugin
(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
```
+## planetPlugin — const @experimental
+```
+PlanetPlugin
+```
+
+## planetProvider — function @experimental
+```
+(id: string): PlanetProvider | undefined
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -15339,6 +15464,11 @@ PrefabsPlugin
(config: Pick<PackagedGameConfig, "sideModules">): void
```
+## registerPlanetProvider — function @experimental
+```
+(provider: PlanetProvider): void
+```
+
## registerPreSceneDrawCallback — function @experimental
```
(id: string, fn: PreSceneDrawCallback): void
@@ -15674,6 +15804,11 @@ Plugin
(forms: PluralForms, count: number, selector: PluralSelector): string
```
+## selectSphereNodes — function @experimental
+```
+(p: SphereTreeParams, ex: number, ey: number, ez: number, levels?: number): SphereNode[]
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -15954,6 +16089,11 @@ ServicesPlugin
(init: UIEntityInit): Entity
```
+## sphereNodeKey — const @experimental
+```
+(n: SphereNode) => string
+```
+
## spineCullingContractFrom — function @experimental
```
(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined
diff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.md
index b7b7cea04..13e0c8a1a 100644
--- a/sdk/etc/terrain.api.md
+++ b/sdk/etc/terrain.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/terrain
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 0 public · 0 beta · 66 experimental · 0 deprecated
+Symbols: 0 public · 0 beta · 94 experimental · 0 deprecated
## Eroded — interface @experimental
```
@@ -18,6 +18,11 @@ sizeX: number
sizeZ: number
```
+## FACES — const @experimental
+```
+readonly { normal: readonly [number, number, number]; a: readonly [number, number, number]; b: readonly [number, number, number]; }[]
+```
+
## FieldSource — class @experimental
```
bounds: readonly [number, number, number, number]
@@ -165,6 +170,81 @@ static new (atlasSize: number): PageTable
static prototype: PageTable
```
+## Planet — const @experimental
+```
+ComponentDef<PlanetData>
+```
+
+## PlanetData — interface @experimental
+```
+cellSize: number
+detail: number
+generatorVersion: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+macroScale: number
+macroVariation: number
+provider: string
+radius: number
+seed: number
+world: string
+```
+
+## PlanetPageSource — interface @experimental
+```
+levels: number
+maxHeight: number
+minHeight: number
+provider: PlanetProvider
+radius: number
+seed: number
+version: number
+world: string
+```
+
+## PlanetPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): PlanetPlugin
+static prototype: PlanetPlugin
+```
+
+## PlanetProvider — interface @experimental
+```
+id: string
+range: (seed: number, version: number, radius: number) => [number, number]
+sample: (region: PlanetRegion) => TerrainSamples | Promise<TerrainSamples>
+versions: readonly number[]
+```
+
+## PlanetRegion — interface @experimental
+```
+count: number
+directions: Float32Array<ArrayBufferLike>
+radius: number
+seed: number
+version: number
+world: string
+```
+
+## PlanetStatus — interface @experimental
+```
+reason: string | undefined
+state: "failed" | "ready" | "loading"
+```
+
+## Planets — class @experimental
+```
+built_: Map<number, Built>
+status: (entity: Entity) => PlanetStatus | null
+static new (): Planets
+static prototype: Planets
+```
+
## ProceduralParams — interface @experimental
```
frequency: number
@@ -226,6 +306,23 @@ path: { x: number; y: number; z: number; }[]
state: "noGround" | "reached" | "unreachable" | "exhausted"
```
+## SphereNode — interface @experimental
+```
+face: number
+ix: number
+iz: number
+level: number
+```
+
+## SphereTreeParams — interface @experimental
+```
+leafSize: number
+maxHeight: number
+minHeight: number
+radius: number
+range0: number
+```
+
## Splat — interface @experimental
```
height: number
@@ -428,7 +525,12 @@ ResourceDef<Terrains>
## buildPatchMesh — function @experimental
```
-(cells: number): MeshData
+(cells: number, flipped?: boolean): MeshData
+```
+
+## direction — function @experimental
+```
+(face: number, u: number, v: number, out?: [number, number, number]): [number, number, number]
```
## erodeHeightfield — function @experimental
@@ -441,6 +543,11 @@ ResourceDef<Terrains>
(field: Heightfield, p: ErosionParams): Generator<number, Eroded, void>
```
+## faceOf — function @experimental
+```
+(dx: number, dy: number, dz: number): { face: number; u: number; v: number; }
+```
+
## findGroundPath — function @experimental
```
(ground: ReachGround, fromX: number, fromZ: number, toX: number, toZ: number, options?: ReachOptions): ReachResult
@@ -461,16 +568,56 @@ ResourceDef<Terrains>
(p: Pick<QuadtreeParams, "range0">, level: number): number
```
+## levelsFor — function @experimental
+```
+(radius: number, leafSize: number): number
+```
+
## makePage — function @experimental
```
(source: TerrainSource, x0: number, z0: number, size: number, repaint?: Repaint): PageImage | Promise<PageImage>
```
+## makePlanetPage — function @experimental
+```
+(src: PlanetPageSource, node: SphereNode): PageImage | Promise<PageImage>
+```
+
+## nodeAt — function @experimental
+```
+(levels: number, face: number, level: number, u: number, v: number): SphereNode
+```
+
+## nodeBound — function @experimental
+```
+(p: SphereTreeParams, levels: number, node: SphereNode): { x: number; y: number; z: number; r: number; }
+```
+
+## nodeDistance — function @experimental
+```
+(p: SphereTreeParams, levels: number, node: SphereNode, ex: number, ey: number, ez: number): number
+```
+
## nodeKey — function @experimental
```
(level: number, ix: number, iz: number): string
```
+## nodePoint — function @experimental
+```
+(p: SphereTreeParams, levels: number, node: SphereNode, s: number, t: number, height: number, out?: [number, number, number]): [number, number, number]
+```
+
+## nodeRect — function @experimental
+```
+(levels: number, node: SphereNode): { u0: number; v0: number; span: number; }
+```
+
+## nodeSpan — const @experimental
+```
+(levels: number, level: number) => number
+```
+
## noiseProvider — function @experimental
```
(params: (seed: number) => NoiseParams): TerrainProvider
@@ -501,11 +648,26 @@ ResourceDef<Terrains>
(json: unknown, file?: string): TerrainLayerDef
```
+## planetPlugin — const @experimental
+```
+PlanetPlugin
+```
+
+## planetProvider — function @experimental
+```
+(id: string): PlanetProvider | undefined
+```
+
## proceduralHeightfield — function @experimental
```
(p: ProceduralParams): Heightfield
```
+## registerPlanetProvider — function @experimental
+```
+(provider: PlanetProvider): void
+```
+
## registerTerrainProvider — function @experimental
```
(provider: TerrainProvider): void
@@ -521,6 +683,26 @@ ResourceDef<Terrains>
(p: QuadtreeParams, ex: number, ey: number, ez: number): TerrainNode[]
```
+## selectSphereNodes — function @experimental
+```
+(p: SphereTreeParams, ex: number, ey: number, ez: number, levels?: number): SphereNode[]
+```
+
+## sphereNodeKey — const @experimental
+```
+(n: SphereNode) => string
+```
+
+## sphereRange — const @experimental
+```
+(p: Pick<SphereTreeParams, "range0">, level: number) => number
+```
+
+## tangentFrame — function @experimental
+```
+(face: number, d: readonly [number, number, number], eu: [number, number, number], ev: [number, number, number]): void
+```
+
## terrainNormal — function @experimental
```
(field: Heightfield, u: number, v: number, sizeX: number, sizeZ: number, heightScale: number): [number, number, number]
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 353a4de21..25caa13fe 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 159 beta · 1855 experimental · 3 deprecated
+Symbols: 115 public · 159 beta · 1876 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4007,6 +4007,11 @@ parent: number | null
visible: boolean | undefined
```
+## FACES — const @experimental
+```
+readonly { normal: readonly [number, number, number]; a: readonly [number, number, number]; b: readonly [number, number, number]; }[]
+```
+
## FILL_AXIS — const @experimental
```
Record<LinearFillDirection, readonly [FillMethod, FillOrigin]>
@@ -6730,6 +6735,69 @@ updated: boolean | undefined
width: number | undefined
```
+## Planet — const @experimental
+```
+ComponentDef<PlanetData>
+```
+
+## PlanetData — interface @experimental
+```
+cellSize: number
+detail: number
+generatorVersion: number
+layerColor0: Color
+layerColor1: Color
+layerColor2: Color
+layerColor3: Color
+macroScale: number
+macroVariation: number
+provider: string
+radius: number
+seed: number
+world: string
+```
+
+## PlanetPlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: (app?: App) => void
+name: string
+static new (): PlanetPlugin
+static prototype: PlanetPlugin
+```
+
+## PlanetProvider — interface @experimental
+```
+id: string
+range: (seed: number, version: number, radius: number) => [number, number]
+sample: (region: PlanetRegion) => TerrainSamples | Promise<TerrainSamples>
+versions: readonly number[]
+```
+
+## PlanetRegion — interface @experimental
+```
+count: number
+directions: Float32Array<ArrayBufferLike>
+radius: number
+seed: number
+version: number
+world: string
+```
+
+## PlanetStatus — interface @experimental
+```
+reason: string | undefined
+state: "failed" | "ready" | "loading"
+```
+
+## Planets — class @experimental
+```
+built_: Map<number, Built>
+status: (entity: Entity) => PlanetStatus | null
+static new (): Planets
+static prototype: Planets
+```
+
## Plant — interface @experimental
```
phase: number
@@ -9225,6 +9293,23 @@ radius: number
restitution: number
```
+## SphereNode — interface @experimental
+```
+face: number
+ix: number
+iz: number
+level: number
+```
+
+## SphereTreeParams — interface @experimental
+```
+leafSize: number
+maxHeight: number
+minHeight: number
+radius: number
+range0: number
+```
+
## Spine — const @beta
```
ResourceDef<SpineManager>
@@ -12903,7 +12988,7 @@ MotionDriver<AnimatorBlend2DMotion>
## buildPatchMesh — function @experimental
```
-(cells: number): MeshData
+(cells: number, flipped?: boolean): MeshData
```
## buildText — function @experimental
@@ -13501,6 +13586,11 @@ DiagnosticsPlugin
(before: Census, after: Census): CensusDelta[]
```
+## direction — function @experimental
+```
+(face: number, u: number, v: number, out?: [number, number, number]): [number, number, number]
+```
+
## disconnect — function @beta
```
(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph
@@ -13776,6 +13866,11 @@ EventBindingPlugin
(g: MaterialGraph, ids: readonly string[], ref: string, name?: string): ExtractedSubgraph
```
+## faceOf — function @experimental
+```
+(dx: number, dy: number, dz: number): { face: number; u: number; v: number; }
+```
+
## fetchDecodePixels — function @experimental
```
(url: string, maxEdge?: number): Promise<DecodedPixels>
@@ -14346,6 +14441,11 @@ InputRouter
(p: Pick<QuadtreeParams, "range0">, level: number): number
```
+## levelsFor — function @experimental
+```
+(radius: number, leafSize: number): number
+```
+
## lifecyclePlugin — const @experimental
```
LifecyclePlugin
@@ -14536,11 +14636,26 @@ MeshRendererPlugin
() => InputState
```
+## nodeAt — function @experimental
+```
+(levels: number, face: number, level: number, u: number, v: number): SphereNode
+```
+
## nodeKey — function @experimental
```
(level: number, ix: number, iz: number): string
```
+## nodePoint — function @experimental
+```
+(p: SphereTreeParams, levels: number, node: SphereNode, s: number, t: number, height: number, out?: [number, number, number]): [number, number, number]
+```
+
+## nodeRect — function @experimental
+```
+(levels: number, node: SphereNode): { u0: number; v0: number; span: number; }
+```
+
## noiseProvider — function @experimental
```
(params: (seed: number) => NoiseParams): TerrainProvider
@@ -14756,6 +14871,16 @@ ParticlePlugin
(app: App, entity: Entity, view?: Entity): PlanarReflectionStatus
```
+## planetPlugin — const @experimental
+```
+PlanetPlugin
+```
+
+## planetProvider — function @experimental
+```
+(id: string): PlanetProvider | undefined
+```
+
## platformCanOpenData — function @experimental
```
(): boolean
@@ -15066,6 +15191,11 @@ PrefabsPlugin
(config: Pick<PackagedGameConfig, "sideModules">): void
```
+## registerPlanetProvider — function @experimental
+```
+(provider: PlanetProvider): void
+```
+
## registerPreSceneDrawCallback — function @experimental
```
(id: string, fn: PreSceneDrawCallback): void
@@ -15401,6 +15531,11 @@ Plugin
(forms: PluralForms, count: number, selector: PluralSelector): string
```
+## selectSphereNodes — function @experimental
+```
+(p: SphereTreeParams, ex: number, ey: number, ez: number, levels?: number): SphereNode[]
+```
+
## serializeAnimClip — function @experimental
```
(asset: AnimClipAssetData): Record<string, unknown>
@@ -15681,6 +15816,11 @@ ServicesPlugin
(init: UIEntityInit): Entity
```
+## sphereNodeKey — const @experimental
+```
+(n: SphereNode) => string
+```
+
## spineCullingContractFrom — function @experimental
```
(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 001f5cce8..9b4294188 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -799,6 +799,11 @@ export {
Terrain, TerrainExtent, Terrains, TerrainsRes, TerrainPlugin, terrainPlugin, NOISE_PROVIDER, type TerrainData, type TerrainStatus,
} from './terrain/terrainPlugin';
export { paintWeights } from './terrain/paint';
+export { Planet, Planets, PlanetPlugin, planetPlugin, type PlanetData, type PlanetStatus } from './terrain/planetPlugin';
+export { registerPlanetProvider, planetProvider, type PlanetProvider, type PlanetRegion } from './terrain/planetProvider';
+export {
+ FACES, direction, faceOf, levelsFor, nodeAt, nodePoint, nodeRect, selectSphereNodes, sphereNodeKey, type SphereNode, type SphereTreeParams,
+} from './terrain/sphere';
export {
Foliage, FoliageField, FoliageRes, FoliagePlugin, foliagePlugin, type FoliageData,
} from './foliage/foliagePlugin';
diff --git a/sdk/src/terrain/index.ts b/sdk/src/terrain/index.ts
index 41fa696b2..5db782810 100644
--- a/sdk/src/terrain/index.ts
+++ b/sdk/src/terrain/index.ts
@@ -23,3 +23,10 @@ import { registerTerrainSupport } from './terrainSupport';
registerTerrainSupport();
export { paintWeights } from './paint';
+export { Planet, Planets, PlanetPlugin, planetPlugin, type PlanetData, type PlanetStatus } from './planetPlugin';
+export { registerPlanetProvider, planetProvider, type PlanetProvider, type PlanetRegion } from './planetProvider';
+export { makePlanetPage, tangentFrame, type PlanetPageSource } from './planetPages';
+export {
+ FACES, direction, faceOf, levelsFor, nodeAt, nodeBound, nodeDistance, nodePoint, nodeRect, nodeSpan, selectSphereNodes, sphereNodeKey, sphereRange,
+ type SphereNode, type SphereTreeParams,
+} from './sphere';
diff --git a/sdk/src/terrain/patch.ts b/sdk/src/terrain/patch.ts
index c88bf552d..3fba43734 100644
--- a/sdk/src/terrain/patch.ts
+++ b/sdk/src/terrain/patch.ts
@@ -9,7 +9,7 @@
*/
import { MeshChannel, MeshChannelType, packChannels, type MeshData } from '../asset/meshFormat';
-export function buildPatchMesh(cells: number): MeshData {
+export function buildPatchMesh(cells: number, flipped = false): MeshData {
const n = Math.max(1, Math.floor(cells));
const { channels, vertexStride } = packChannels([
{ semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32 },
@@ -36,7 +36,8 @@ export function buildPatchMesh(cells: number): MeshData {
for (let j = 0; j < n; j++) for (let i = 0; i < n; i++) {
const a = j * (n + 1) + i, b = a + 1, c = a + n + 1, d = c + 1;
// Facing up: a, then the next row, then the next column, runs counter-clockwise from above.
- indices.set([a, c, b, b, c, d], at);
+ // `flipped` is the same grid wound the other way round: a cube face's (u, v, out) is a right-handed frame, where flat ground's (x, z, up) is not.
+ indices.set(flipped ? [a, b, c, b, d, c] : [a, c, b, b, c, d], at);
at += 6;
}
return { channels, vertexStride, vertexCount: count, vertices, indices, aabbMin: [0, 0, 0], aabbMax: [1, 1, 1] };
diff --git a/sdk/src/terrain/planetPages.ts b/sdk/src/terrain/planetPages.ts
new file mode 100644
index 000000000..ce55a0b3d
--- /dev/null
+++ b/sdk/src/terrain/planetPages.ts
@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file planetPages.ts
+ * @brief A planet node's page: its heights, normals and paint, sampled from a provider by direction.
+ *
+ * @details The same three images a flat node's page holds (pages.ts), laid out the same way so the one atlas and the one page table serve both: a
+ * node's square of its face sampled `PAGE_TEXELS` times along each side with one more sample past each edge. What differs is the normal. Flat
+ * ground has one up for every sample; here up is the direction from the planet's centre, so the normal is stored in the frame at its own
+ * sample, x along the face's u direction made perpendicular to up, z along its v direction, y up; the shader builds the same frame from the
+ * direction and the face and turns it back.
+ */
+import { PAGE_SIDE, PAGE_TEXELS, type PageImage } from './pages';
+import { FACES, direction, nodeRect, type SphereNode } from './sphere';
+import type { PlanetProvider } from './planetProvider';
+
+/** What a planet page is made against. */
+export interface PlanetPageSource {
+ provider: PlanetProvider;
+ world: string;
+ seed: number;
+ version: number;
+ radius: number;
+ /** The levels of the planet's tree (see sphere.ts). */
+ levels: number;
+ minHeight: number;
+ maxHeight: number;
+}
+
+/** The frame at a unit direction on a face: the face's u and v directions made perpendicular to it. */
+export function tangentFrame(face: number, d: readonly [number, number, number], eu: [number, number, number], ev: [number, number, number]): void {
+ const f = FACES[face]!;
+ for (const [axis, out] of [[f.a, eu], [f.b, ev]] as const) {
+ const k = axis[0] * d[0] + axis[1] * d[1] + axis[2] * d[2];
+ const x = axis[0] - d[0] * k, y = axis[1] - d[1] * k, z = axis[2] - d[2] * k;
+ const len = Math.hypot(x, y, z) || 1;
+ out[0] = x / len; out[1] = y / len; out[2] = z / len;
+ }
+}
+
+/** Samples a node's page: the grid's directions go to the provider, and what comes back is encoded. May answer later, as the provider may. */
+export function makePlanetPage(src: PlanetPageSource, node: SphereNode): PageImage | Promise<PageImage> {
+ const n = PAGE_SIDE;
+ const { u0, v0, span } = nodeRect(src.levels, node);
+ const step = span / PAGE_TEXELS;
+ const dirs = new Float32Array(n * n * 3);
+ const d: [number, number, number] = [0, 0, 0];
+ for (let j = 0; j < n; j++) for (let i = 0; i < n; i++) {
+ direction(node.face, u0 + (i - 1) * step, v0 + (j - 1) * step, d);
+ const k = (j * n + i) * 3;
+ dirs[k] = d[0]; dirs[k + 1] = d[1]; dirs[k + 2] = d[2];
+ }
+ const got = src.provider.sample({ world: src.world, seed: src.seed, version: src.version, radius: src.radius, directions: dirs, count: n * n });
+ return got instanceof Promise ? got.then((r) => encodePlanetPage(src, node, dirs, r.heights, r.paint)) : encodePlanetPage(src, node, dirs, got.heights, got.paint);
+}
+
+function encodePlanetPage(src: PlanetPageSource, node: SphereNode, dirs: Float32Array, h: Float32Array, given?: Float32Array): PageImage {
+ const n = PAGE_SIDE;
+ let min = Infinity, max = -Infinity;
+ for (let j = 1; j <= n - 2; j++) for (let i = 1; i <= n - 2; i++) { const v = h[j * n + i]!; min = Math.min(min, v); max = Math.max(max, v); }
+ const span = Math.max(src.maxHeight - src.minHeight, 1e-6);
+ const heights = new Uint8Array(n * n * 4), paint = new Uint8Array(n * n * 4), paint2 = new Uint8Array(n * n * 4);
+ // The position of a sample, in metres from the planet's centre.
+ const at = (i: number, j: number, out: [number, number, number]): void => {
+ const ci = Math.min(Math.max(i, 0), n - 1), cj = Math.min(Math.max(j, 0), n - 1), k = cj * n + ci, r = src.radius + h[k]!;
+ out[0] = dirs[k * 3]! * r; out[1] = dirs[k * 3 + 1]! * r; out[2] = dirs[k * 3 + 2]! * r;
+ };
+ const a: [number, number, number] = [0, 0, 0], b: [number, number, number] = [0, 0, 0], c: [number, number, number] = [0, 0, 0], e: [number, number, number] = [0, 0, 0];
+ const eu: [number, number, number] = [0, 0, 0], ev: [number, number, number] = [0, 0, 0];
+ for (let j = 0; j < n; j++) for (let i = 0; i < n; i++) {
+ const k = j * n + i;
+ const enc = Math.round(Math.min(Math.max((h[k]! - src.minHeight) / span, 0), 1) * 65535);
+ // The surface's tangents toward +u and +v from the samples either side, and the normal they make, outward.
+ at(i - 1, j, a); at(i + 1, j, b); at(i, j - 1, c); at(i, j + 1, e);
+ const tu = [b[0] - a[0], b[1] - a[1], b[2] - a[2]], tv = [e[0] - c[0], e[1] - c[1], e[2] - c[2]];
+ let nx = tu[1]! * tv[2]! - tu[2]! * tv[1]!, ny = tu[2]! * tv[0]! - tu[0]! * tv[2]!, nz = tu[0]! * tv[1]! - tu[1]! * tv[0]!;
+ const dir: [number, number, number] = [dirs[k * 3]!, dirs[k * 3 + 1]!, dirs[k * 3 + 2]!];
+ let len = Math.hypot(nx, ny, nz) || 1;
+ nx /= len; ny /= len; nz /= len;
+ if (nx * dir[0] + ny * dir[1] + nz * dir[2] < 0) { nx = -nx; ny = -ny; nz = -nz; }
+ tangentFrame(node.face, dir, eu, ev);
+ const lx = nx * eu[0] + ny * eu[1] + nz * eu[2], lz = nx * ev[0] + ny * ev[1] + nz * ev[2];
+ const up = nx * dir[0] + ny * dir[1] + nz * dir[2];
+ len = Math.hypot(lx, up, lz) || 1;
+ heights[k * 4] = enc >> 8;
+ heights[k * 4 + 1] = enc & 255;
+ heights[k * 4 + 2] = Math.round((lx / len * 0.5 + 0.5) * 255);
+ heights[k * 4 + 3] = Math.round((lz / len * 0.5 + 0.5) * 255);
+ // The paint the provider gave; without it, rock where it is steep and grass elsewhere, so a planet with no paint is still readable.
+ let w0 = 0, w1 = 0, w2 = 0, w3 = 0;
+ if (given) { w0 = given[k * 4]!; w1 = given[k * 4 + 1]!; w2 = given[k * 4 + 2]!; w3 = given[k * 4 + 3]!; }
+ else { const steep = Math.min(Math.max((0.9 - up / len) * 6, 0), 1); w0 = 1 - steep; w3 = steep; }
+ paint[k * 4] = Math.round(Math.min(Math.max(w0, 0), 1) * 255);
+ paint[k * 4 + 1] = Math.round(Math.min(Math.max(w1, 0), 1) * 255);
+ paint[k * 4 + 2] = Math.round(Math.min(Math.max(w2, 0), 1) * 255);
+ paint[k * 4 + 3] = Math.round(Math.min(Math.max(w3, 0), 1) * 255);
+ }
+ return { heights, paint, paint2, min: Number.isFinite(min) ? min : src.minHeight, max: Number.isFinite(max) ? max : src.maxHeight };
+}
diff --git a/sdk/src/terrain/planetPlugin.ts b/sdk/src/terrain/planetPlugin.ts
new file mode 100644
index 000000000..9977f1be0
--- /dev/null
+++ b/sdk/src/terrain/planetPlugin.ts
@@ -0,0 +1,443 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file planetPlugin.ts
+ * @brief The `Planet` component: ground on a sphere, drawn as six quadtrees round the eye, from a provider a game names.
+ *
+ * @details The same machinery as flat ground (terrainPlugin.ts) with a sphere under it: the tree is cut by the eye's distance to each node (sphere.ts), a
+ * node is the one shared patch drawn as an instance, its page (heights, normals, paint) is made from the provider by direction (planetPages.ts) into
+ * the one atlas, and the Planet shader (planetShader.ts) puts every vertex of the patch on the sphere. From the ground the finest nodes are under the
+ * eye; from space the whole planet is a handful of coarse ones, so a planet seen from far off and from underfoot is one thing.
+ *
+ * The planet entity is its centre and stands unrotated and unscaled: its children are the nodes, placed in its space. The first slice draws the ground;
+ * collision, the layers' textures, the sea and the sky of a round world are the next ones.
+ */
+import type { App, Plugin } from '../app/app';
+import { defineSystem, Schedule } from '../ecs/system';
+import {
+ defineComponent, Camera, MeshRenderer, Transform,
+ type ComponentDef, type CameraData, type MeshRendererData, type TransformData,
+} from '../ecs/component';
+import { Assets } from '../asset/AssetPlugin';
+import type { MaterialShaderSource } from '../asset/loaders/MaterialShaderAssetLoader';
+import { Material, MATERIAL_FORMAT_VERSION } from '../render/material';
+import { BlendMode } from '../render/blend';
+import { createTextureFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';
+import { getResourceManager, provideTextureContent, withdrawTextureContent } from '../wasm/resourceManager';
+import { TextureContent } from '../wasm';
+import { EditorView, editorViewEye } from '../camera/EditorView';
+import { log } from '../util/logger';
+import { bakesOf } from '../runtime/bakes';
+import type { Color, Entity } from '../types';
+import { PageTable, PAGE_SIDE, PAGE_TEXELS, PATCH_CELLS, type PageImage } from './pages';
+import { buildPatchMesh } from './patch';
+import { planetProvider, planetProvidersRevision, type PlanetProvider } from './planetProvider';
+import { makePlanetPage, type PlanetPageSource } from './planetPages';
+import { levelsFor, nodePoint, selectSphereNodes, sphereNodeKey, type SphereNode, type SphereTreeParams } from './sphere';
+
+/** The fields of the `Planet` component. @experimental */
+export interface PlanetData {
+ /** The planet's radius in metres. */
+ radius: number;
+ /** The generator the ground is made by (registerPlanetProvider), the world it belongs to as the game names it, its version and its seed. */
+ provider: string;
+ world: string;
+ generatorVersion: number;
+ seed: number;
+ /** The finest cell of the ground's mesh, in metres, and how far out the finest cells reach before the ground coarsens (above 1 is further). */
+ cellSize: number;
+ detail: number;
+ /** The four layers' colours: grass, dirt, snow, rock. */
+ layerColor0: Color;
+ layerColor1: Color;
+ layerColor2: Color;
+ layerColor3: Color;
+ /** The size, in metres, of the ground's own wander in brightness, and how strong it is (0 to 1). */
+ macroScale: number;
+ macroVariation: number;
+}
+
+const rgb = (r: number, g: number, b: number): Color => ({ r, g, b, a: 1 });
+
+/**
+ * Ground on a sphere. Presence is the opt-in; its children are the quadtree's nodes.
+ *
+ * @experimental
+ */
+export const Planet: ComponentDef<PlanetData> = defineComponent<PlanetData>('Planet', {
+ radius: 4000, provider: '', world: '', generatorVersion: 1, seed: 1, cellSize: 1.5, detail: 1.5,
+ layerColor0: rgb(0.28, 0.46, 0.2), layerColor1: rgb(0.45, 0.36, 0.24), layerColor2: rgb(0.93, 0.95, 0.98), layerColor3: rgb(0.4, 0.38, 0.36),
+ macroScale: 90, macroVariation: 0.35,
+}, {
+ fields: {
+ radius: { min: 1, category: 'Shape', tooltip: 'The planet\'s radius in metres. The planet stands at its entity, unrotated and unscaled.' },
+ provider: { category: 'Shape', tooltip: 'The generator the ground is made by, registered with registerPlanetProvider. The same provider, world, seed and version are the same ground everywhere.' },
+ world: { category: 'Shape', tooltip: 'The world (a planet) the ground belongs to, as the game names it; handed to the provider.' },
+ generatorVersion: { min: 1, step: 1, category: 'Shape', tooltip: 'The generator version the planet was made with. A version the provider no longer has fails the planet rather than growing other ground under what was built on it.' },
+ seed: { step: 1, category: 'Shape', tooltip: 'Another seed is another planet.' },
+ cellSize: { min: 0.01, category: 'Detail', tooltip: 'The finest cell of the ground\'s mesh, in metres: what it is drawn at near the eye. Further off the cells double, level by level.' },
+ detail: { min: 0.25, max: 8, step: 0.05, category: 'Detail', tooltip: 'Above 1 the finest cells reach further out before the ground coarsens.' },
+ layerColor0: { label: 'Grass', category: 'Layers' },
+ layerColor1: { label: 'Dirt', category: 'Layers' },
+ layerColor2: { label: 'Snow', category: 'Layers' },
+ layerColor3: { label: 'Rock', category: 'Layers' },
+ macroScale: { min: 1, category: 'Layers', tooltip: 'The size, in metres, of the ground\'s own wander in brightness.' },
+ macroVariation: { min: 0, max: 1, step: 0.01, category: 'Layers', tooltip: 'How strongly the ground\'s brightness wanders.' },
+ },
+});
+
+/** The side of the atlases the pages are kept in, in texels. */
+const ATLAS_SIZE = 2048;
+/** Most levels a planet's tree may have: a node's place on its face is packed in a float, ix * 2048 + iz, which holds eleven levels' worth. */
+const MAX_LEVELS = 12;
+/** Pages asked at once of a provider that answers later. */
+const PAGES_IN_FLIGHT = 16;
+
+interface Built {
+ signature: string;
+ data: PlanetData;
+ provider: PlanetProvider | null;
+ /** What the planet is made against, and how its tree is cut. */
+ source: PlanetPageSource | null;
+ tree: SphereTreeParams | null;
+ epoch: number;
+ table: PageTable;
+ heights: number;
+ paint: number;
+ mesh: number;
+ instance: number;
+ nodes: Map<string, Entity>;
+ spare: Entity[];
+ wanted: Map<string, SphereNode>;
+ asked: Set<string>;
+ pending: boolean;
+ failure: string | null;
+ /** The registry's revision when the provider was last looked for, so a late registration is noticed. */
+ providers: number;
+}
+
+/** Where a planet stands: still being made, ready, or failed (with why). */
+export interface PlanetStatus { state: 'loading' | 'ready' | 'failed'; reason?: string }
+
+/** The planets of an app, for what asks about them. @experimental */
+export class Planets {
+ readonly built_ = new Map<Entity, Built>();
+
+ /** How a planet stands, or null for an entity that is not one. */
+ status(entity: Entity): PlanetStatus | null {
+ const b = this.built_.get(entity);
+ if (!b) return null;
+ return b.failure ? { state: 'failed', reason: b.failure } : { state: b.instance && b.source ? 'ready' : 'loading' };
+ }
+}
+
+export class PlanetPlugin implements Plugin {
+ name = 'planet';
+
+ private stock_ = 0;
+ private planets_: Planets | null = null;
+
+ build(app: App): void {
+ const planets = new Planets();
+ this.planets_ = planets;
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
+ if (!app.hasResource(Assets)) return;
+ // A planet whose entity has gone is let go.
+ for (const [entity, built] of planets.built_) {
+ if (app.world.valid(entity) && app.world.has(entity, Planet)) continue;
+ this.destroy(app, built);
+ planets.built_.delete(entity);
+ }
+ for (const entity of app.world.getEntitiesWithComponents([Planet, Transform])) {
+ const data = app.world.get(entity, Planet) as PlanetData;
+ const signature = signatureOf(data);
+ let built = planets.built_.get(entity);
+ if (!built || built.signature !== signature || (built.failure && built.providers !== planetProvidersRevision())) {
+ if (built) this.destroy(app, built);
+ built = this.make(signature, data, (built?.epoch ?? 0) + 1);
+ planets.built_.set(entity, built);
+ }
+ built.data = { ...data };
+ if (built.failure || !built.source || !built.tree) continue;
+ if (!built.instance) {
+ if (!built.pending) void this.prepare(app, built);
+ continue;
+ }
+ this.draw(app, entity, built);
+ }
+ }, { name: 'PlanetSystem' }));
+ }
+
+ cleanup(app?: App): void {
+ const planets = this.planets_;
+ if (app && planets) for (const built of planets.built_.values()) this.destroy(app, built);
+ planets?.built_.clear();
+ if (this.stock_) Material.release(this.stock_);
+ this.stock_ = 0;
+ }
+
+ /** What a planet is made against, from its fields: its provider, and the cut its tree is made with. */
+ private make(signature: string, data: PlanetData, epoch: number): Built {
+ const built: Built = {
+ signature, data: { ...data }, provider: null, source: null, tree: null, epoch, table: new PageTable(ATLAS_SIZE),
+ heights: 0, paint: 0, mesh: 0, instance: 0, nodes: new Map(), spare: [], wanted: new Map(), asked: new Set(), pending: false, failure: null,
+ providers: planetProvidersRevision(),
+ };
+ const provider = planetProvider(data.provider);
+ if (!provider) {
+ built.failure = data.provider ? `the planet provider "${data.provider}" is not registered` : 'the planet names no provider';
+ return built;
+ }
+ if (!provider.versions.includes(data.generatorVersion)) {
+ built.failure = `the planet provider ${provider.id} has no version ${data.generatorVersion} (it has ${provider.versions.join(', ') || 'none'})`;
+ return built;
+ }
+ const [minHeight, maxHeight] = provider.range(data.seed, data.generatorVersion, data.radius);
+ const leafSize = PATCH_CELLS * Math.max(data.cellSize, 1e-3);
+ const levels = levelsFor(data.radius, leafSize);
+ if (levels > MAX_LEVELS) {
+ built.failure = `a planet of radius ${data.radius} m with ${data.cellSize} m cells needs ${levels} levels of tree; ${MAX_LEVELS} is the most (raise cellSize)`;
+ return built;
+ }
+ built.provider = provider;
+ built.tree = { radius: data.radius, minHeight, maxHeight, leafSize, range0: leafSize * 2.5 * Math.max(data.detail, 0.25) };
+ built.source = { provider, world: data.world, seed: data.seed, version: data.generatorVersion, radius: data.radius, levels, minHeight, maxHeight };
+ return built;
+ }
+
+ /** The stock material: the Planet shader, compiled once. */
+ private async stock(app: App): Promise<number> {
+ if (this.stock_) return this.stock_;
+ const source = await app.getResource(Assets).load<MaterialShaderSource>('material-shader', 'builtin:planet');
+ const shader = source.compile([]);
+ if (this.stock_) return this.stock_;
+ this.stock_ = Material.createFromAsset({
+ version: MATERIAL_FORMAT_VERSION, type: 'material', shader: 'builtin:planet', blendMode: BlendMode.None,
+ depthTest: true, depthWrite: true, cull: 0, properties: {},
+ }, shader);
+ return this.stock_;
+ }
+
+ private async prepare(app: App, built: Built): Promise<void> {
+ built.pending = true;
+ const epoch = built.epoch;
+ try {
+ const material = await this.stock(app);
+ if (built.epoch !== epoch) return;
+ const assets = app.getResource(Assets);
+ built.mesh = assets.createMesh(buildPatchMesh(PATCH_CELLS, true));
+ const blank = new Uint8Array(ATLAS_SIZE * ATLAS_SIZE * 4);
+ const params = { filterMode: 'linear', wrapMode: 'clamp', srgb: false } as const;
+ built.heights = createTextureFromPixels(app.wasmModule, { width: ATLAS_SIZE, height: ATLAS_SIZE, pixels: blank }, TextureContent.Transient, false, params);
+ built.paint = createTextureFromPixels(app.wasmModule, { width: ATLAS_SIZE, height: ATLAS_SIZE, pixels: blank }, TextureContent.Transient, false, params);
+ // A device that lost the atlases has lost every page in them: they are made again as they are wanted.
+ for (const handle of [built.heights, built.paint]) provideTextureContent(handle, () => { built.table.clear(); return true; });
+ built.instance = Material.createInstance(material);
+ if (!built.mesh || !built.heights || !built.paint || !built.instance) {
+ built.failure = 'the engine refused the planet\'s mesh, atlases or material';
+ log.warn('planet', built.failure);
+ return;
+ }
+ const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(built.instance, name, value); };
+ set('u_heightPages', Material.tex(built.heights));
+ set('u_paintPages', Material.tex(built.paint));
+ set('u_planetPages', 1);
+ set('u_atlasTexels', ATLAS_SIZE);
+ set('u_pageTexels', PAGE_TEXELS);
+ set('u_patchCells', PATCH_CELLS);
+ set('u_planetRadius', built.data.radius);
+ set('u_planetLevels', built.source!.levels);
+ set('u_heightRange', { x: built.tree!.minHeight, y: Math.max(built.tree!.maxHeight - built.tree!.minHeight, 1e-6) });
+ set('u_lodRange0', built.tree!.range0);
+ } catch (e) {
+ built.failure = e instanceof Error ? e.message : String(e);
+ log.error('planet', 'preparing the planet failed', e);
+ } finally {
+ built.pending = false;
+ }
+ }
+
+ /** Where the eye is, in the planet's space: the editor's, while it looks at the scene in 3D, else the active camera's. */
+ private eye(app: App, t: TransformData): [number, number, number] | null {
+ if (app.hasResource(EditorView)) {
+ const view = app.getResource(EditorView);
+ if (view.active && view.perspective) {
+ const e = editorViewEye(view);
+ return [e.x - t.worldPosition.x, e.y - t.worldPosition.y, e.z - t.worldPosition.z];
+ }
+ }
+ for (const entity of app.world.getEntitiesWithComponents([Camera, Transform])) {
+ if (!(app.world.get(entity, Camera) as CameraData).isActive) continue;
+ const c = app.world.get(entity, Transform) as TransformData;
+ return [c.worldPosition.x - t.worldPosition.x, c.worldPosition.y - t.worldPosition.y, c.worldPosition.z - t.worldPosition.z];
+ }
+ return null;
+ }
+
+ /** Chooses the nodes for the eye, makes the pages they want within the budget, and places the nodes. */
+ private draw(app: App, entity: Entity, built: Built): void {
+ const tree = built.tree!, src = built.source!;
+ const t = app.world.get(entity, Transform) as TransformData;
+ const eye = this.eye(app, t) ?? [0, tree.radius + tree.maxHeight * 2, 0];
+ const chosen = selectSphereNodes(tree, eye[0], eye[1], eye[2], src.levels);
+ const table = built.table;
+ table.tick();
+
+ // Each node is drawn by its own page, or by its nearest ancestor that has one; a node under an ancestor drawn instead is not.
+ built.wanted.clear();
+ const drawn = new Map<string, SphereNode>();
+ const covered = new Set<string>();
+ const parent = (n: SphereNode): SphereNode => ({ face: n.face, level: n.level + 1, ix: n.ix >> 1, iz: n.iz >> 1 });
+ for (const node of chosen) {
+ let n: SphereNode | null = node;
+ const own = sphereNodeKey(node);
+ if (!table.get(own)) built.wanted.set(own, node);
+ while (n && !table.get(sphereNodeKey(n))) {
+ n = n.level + 1 < src.levels ? parent(n) : null;
+ if (n && !table.get(sphereNodeKey(n))) built.wanted.set(sphereNodeKey(n), n);
+ }
+ if (!n) continue;
+ const key = sphereNodeKey(n);
+ if (n !== node) covered.add(key);
+ drawn.set(key, n);
+ }
+ for (const [key, n] of drawn) {
+ for (let up = n; up.level + 1 < src.levels;) {
+ up = parent(up);
+ if (covered.has(sphereNodeKey(up))) { drawn.delete(key); break; }
+ }
+ }
+ this.makePages(app, built, eye);
+
+ const set = (name: string, value: Parameters<typeof Material.setUniform>[2]): void => { Material.setUniform(built.instance, name, value); };
+ set('u_planetCenter', { x: t.worldPosition.x, y: t.worldPosition.y, z: t.worldPosition.z, w: 0 });
+ // Not the pass's camera: a shadow is drawn from the light, and its ground must be the one the eye sees.
+ set('u_terrainEye', { x: eye[0], y: eye[1], z: eye[2], w: 1 });
+ const d = built.data;
+ for (const [i, c] of [d.layerColor0, d.layerColor1, d.layerColor2, d.layerColor3].entries()) set(`u_tint${i}`, { x: c.r, y: c.g, z: c.b, w: c.a });
+ set('u_macroScale', d.macroScale);
+ set('u_macroVariation', d.macroVariation);
+ this.place(app, entity, built, drawn);
+ }
+
+ /** Makes the wanted pages, coarse and near first, for as long as the frame can spare. */
+ private makePages(app: App, built: Built, eye: [number, number, number]): void {
+ const bakes = bakesOf(app);
+ if (built.wanted.size === 0) { bakes.mark(built, 'Building the planet', 1); return; }
+ const src = built.source!;
+ const centre = (n: SphereNode): number => {
+ const p = nodePoint(built.tree!, src.levels, n, 0.5, 0.5, 0);
+ return Math.hypot(p[0] - eye[0], p[1] - eye[1], p[2] - eye[2]);
+ };
+ const order = [...built.wanted.values()].sort((a, b) => b.level - a.level || centre(a) - centre(b));
+ let made = 0;
+ const store = (key: string, image: PageImage): boolean => {
+ const page = built.table.claim(key, image.min, image.max);
+ if (!page) return false;
+ const [ox, oy] = built.table.origin(page.slot);
+ updateTextureSubregion(app.wasmModule, built.heights, ox, oy, PAGE_SIDE, PAGE_SIDE, image.heights);
+ updateTextureSubregion(app.wasmModule, built.paint, ox, oy, PAGE_SIDE, PAGE_SIDE, image.paint);
+ return true;
+ };
+ const epoch = built.epoch;
+ for (const node of order) {
+ const key = sphereNodeKey(node);
+ if (built.asked.has(key)) continue;
+ const image = makePlanetPage(src, node);
+ if (image instanceof Promise) {
+ if (built.asked.size >= PAGES_IN_FLIGHT) break;
+ built.asked.add(key);
+ void image.then((img) => {
+ built.asked.delete(key);
+ if (built.epoch === epoch && built.heights) store(key, img);
+ }, (e) => {
+ built.asked.delete(key);
+ log.warn('planet', `the provider failed a page (${key})`, e);
+ });
+ continue;
+ }
+ if (!store(key, image)) break;
+ built.wanted.delete(key);
+ made++;
+ // The frame's one budget, shared with the bakes and the chunks of the world; at least one page a frame.
+ if (!bakes.hasTime()) break;
+ }
+ bakes.mark(built, 'Building the planet', made === 0 ? 0 : 1 - built.wanted.size / (built.wanted.size + made));
+ }
+
+ /** Puts a node entity on each node drawn (reusing the ones it had), and takes the rest away. */
+ private place(app: App, entity: Entity, built: Built, drawn: Map<string, SphereNode>): void {
+ const world = app.world, tree = built.tree!, levels = built.source!.levels;
+ for (const [key, e] of built.nodes) {
+ if (drawn.has(key)) continue;
+ built.nodes.delete(key);
+ if (!world.valid(e)) continue;
+ const mr = world.get(e, MeshRenderer) as MeshRendererData;
+ if (mr.enabled) world.insert(e, MeshRenderer, { ...mr, enabled: false });
+ built.spare.push(e);
+ }
+ const p: [number, number, number] = [0, 0, 0];
+ for (const [key, n] of drawn) {
+ const page = built.table.get(key)!;
+ built.table.touch(key);
+ let e = built.nodes.get(key);
+ if (e === undefined || !world.valid(e)) {
+ e = built.spare.pop();
+ if (e === undefined || !world.valid(e)) {
+ e = world.spawn('PlanetNode');
+ world.insert(e, Transform, {});
+ world.setParent(e, entity);
+ }
+ built.nodes.set(key, e);
+ }
+ const [ox, oy] = built.table.origin(page.slot);
+ // The tint names the page, the level and the face, and the node's place on its face (see the Planet shader's hook).
+ const color = { r: (ox + 0.5) / ATLAS_SIZE, g: (oy + 0.5) / ATLAS_SIZE, b: n.level + 1 + 16 * n.face, a: n.ix * 2048 + n.iz + 1 };
+ // The node's box in the planet's space, which is all culling reads: the corners, the edges' middles and the middle, at its least and most height.
+ const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+ for (let j = 0; j <= 4; j++) for (let i = 0; i <= 4; i++) for (const h of [page.min, page.max]) {
+ nodePoint(tree, levels, n, i / 4, j / 4, h, p);
+ for (let k = 0; k < 3; k++) { lo[k] = Math.min(lo[k]!, p[k]!); hi[k] = Math.max(hi[k]!, p[k]!); }
+ }
+ const position = { x: lo[0]!, y: lo[1]!, z: lo[2]! };
+ const scale = { x: Math.max(hi[0]! - lo[0]!, 1e-3), y: Math.max(hi[1]! - lo[1]!, 1e-3), z: Math.max(hi[2]! - lo[2]!, 1e-3) };
+ const t = world.get(e, Transform) as TransformData;
+ if (t.position.x !== position.x || t.position.y !== position.y || t.position.z !== position.z || t.scale.x !== scale.x || t.scale.y !== scale.y || t.scale.z !== scale.z) {
+ world.insert(e, Transform, { ...t, position, scale });
+ }
+ const mr = world.tryGet(e, MeshRenderer) as MeshRendererData | null;
+ if (!mr || !mr.enabled || mr.color.r !== color.r || mr.color.g !== color.g || mr.color.b !== color.b || mr.color.a !== color.a || mr.material !== built.instance) {
+ world.insert(e, MeshRenderer, {
+ ...(mr ?? {}), mesh: built.mesh, material: built.instance, lit: true, opaque: true, cullBackfaces: true, color, enabled: true,
+ } as Partial<MeshRendererData>);
+ }
+ }
+ }
+
+ private destroy(app: App, built: Built): void {
+ built.epoch++;
+ bakesOf(app).clear(built);
+ const world = app.world;
+ for (const e of [...built.nodes.values(), ...built.spare]) if (world.valid(e)) world.despawn(e);
+ built.nodes.clear();
+ built.spare.length = 0;
+ built.wanted.clear();
+ const rm = getResourceManager();
+ for (const handle of [built.heights, built.paint]) {
+ if (!handle) continue;
+ withdrawTextureContent(handle);
+ rm?.releaseTexture(handle);
+ }
+ if (built.instance) Material.release(built.instance);
+ if (built.mesh && app.hasResource(Assets)) app.getResource(Assets).releaseBuiltMesh(built.mesh);
+ built.instance = built.mesh = built.heights = built.paint = 0;
+ built.table.clear();
+ }
+}
+
+/** What, changed, makes the planet again: everything but the colours and the wander, which are read each frame. */
+function signatureOf(d: PlanetData): string {
+ return JSON.stringify([d.radius, d.provider, d.world, d.generatorVersion, d.seed, d.cellSize, d.detail]);
+}
+
+export const planetPlugin = new PlanetPlugin();
diff --git a/sdk/src/terrain/planetProvider.ts b/sdk/src/terrain/planetProvider.ts
new file mode 100644
index 000000000..4803fbb37
--- /dev/null
+++ b/sdk/src/terrain/planetProvider.ts
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file planetProvider.ts
+ * @brief Ground on a sphere made by a generator a game names: one function of a direction, versioned, the same on every machine.
+ *
+ * @details The provider of flat ground (provider.ts) answers for a square of world positions; this one answers for directions from a planet's
+ * centre, because a sphere has no x and z. It is handed the unit directions to sample and the radius they are on, and gives back the height
+ * above that radius at each and, if it paints the ground, four layer weights. The same rules hold: every sample is the same function read
+ * at another direction, so two pages that share an edge share its samples; a version names an algorithm for good.
+ */
+import type { TerrainSamples } from './provider';
+
+/** What a provider is asked to sample: a list of unit directions from the planet's centre. */
+export interface PlanetRegion {
+ /** The world (a planet) the ground belongs to, as the game names it. */
+ world: string;
+ seed: number;
+ /** The generator version the planet was made with. */
+ version: number;
+ /** The planet's radius in metres: a provider reasons in metres, a direction is only where. */
+ radius: number;
+ /** `count` unit directions, x, y, z one after the other. */
+ directions: Float32Array;
+ count: number;
+}
+
+/** A generator of ground on a sphere. */
+export interface PlanetProvider {
+ /** The name a Planet asks for it by. */
+ readonly id: string;
+ /** The generator versions it can still make. */
+ readonly versions: readonly number[];
+ /** The least and most height above the radius its ground can have for this seed, version and radius: what the GPU encodes heights over. */
+ range(seed: number, version: number, radius: number): [number, number];
+ /** The ground in the directions asked: heights in metres above the radius, and the layer weights if it paints. May answer later. */
+ sample(region: PlanetRegion): TerrainSamples | Promise<TerrainSamples>;
+}
+
+const providers_ = new Map<string, PlanetProvider>();
+let revision_ = 0;
+
+/**
+ * Makes `provider` available to every Planet that names it. A second provider under the same id replaces the first. A planet that named one not yet
+ * registered (a script registers it after the scene loaded) is made once it is.
+ * @experimental
+ */
+export function registerPlanetProvider(provider: PlanetProvider): void {
+ providers_.set(provider.id, provider);
+ revision_++;
+}
+
+/** The provider registered under `id`, if any. */
+export function planetProvider(id: string): PlanetProvider | undefined {
+ return providers_.get(id);
+}
+
+/** @internal Bumped on every registration, so a planet whose provider was missing asks again. */
+export function planetProvidersRevision(): number {
+ return revision_;
+}
diff --git a/sdk/src/terrain/planetShader.ts b/sdk/src/terrain/planetShader.ts
new file mode 100644
index 000000000..546ef8e78
--- /dev/null
+++ b/sdk/src/terrain/planetShader.ts
@@ -0,0 +1,367 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file planetShader.ts
+ * @brief The Planet built-in shader: ground on a sphere, from the pages of its quadtree nodes, painted by four layer colours.
+ *
+ * Every node is the one shared patch (terrain/patch.ts) as flat ground is, and its instance says which node it is: the tint holds the page's corner in the
+ * atlas (x and y), the level and the face (z: level + 1 + 16 * face), and the node's place on its face (w: ix * 2048 + iz + 1, exact in a float for up to eleven levels
+ * a side). The model is the node's box in the planet's space, which is only what culling reads. The vertex stage works the point out from that: the direction
+ * on the cube face, pushed out to the radius plus the page's height; it hands the fragment stage the page and the face to find its normal and paint by.
+ */
+import { makeBuiltinShaderTemplate } from '../render/builtinShaders';
+
+const PLANET = `#pragma shader "Planet"
+#pragma version 300 es
+#pragma domain Lit
+// The four layers' colours: grass, dirt, snow, rock.
+#pragma param u_tint0 color default(0.28,0.46,0.2,1)
+#pragma param u_tint1 color default(0.45,0.36,0.24,1)
+#pragma param u_tint2 color default(0.93,0.95,0.98,1)
+#pragma param u_tint3 color default(0.4,0.38,0.36,1)
+// The ground's own wander in brightness, in metres a feature, and how strong it is.
+#pragma param u_macroScale float default(90) range(1,100000) ui(slider)
+#pragma param u_macroVariation float default(0.35) range(0,1) ui(slider)
+#pragma param u_sharpness float default(1.6) range(1,8) ui(slider)
+#pragma param u_roughness float default(0.92) range(0,1) ui(slider)
+// The ground in pages (pages.ts; the Planet component writes these): heights and normals, and the paint, in two atlases; the planet's radius, its centre
+// in the world, how many levels its tree has; level 0 drawn out to u_lodRange0, each level twice as far; u_terrainEye is the eye the nodes were chosen for,
+// in the planet's space, so every pass (a shadow's too) slides the vertices by it and all draw one ground.
+#pragma param u_planetPages float default(0) range(0,1) ui(slider)
+#pragma param u_heightPages texture default(white) texel(data)
+#pragma param u_paintPages texture default(white) texel(data)
+#pragma param u_atlasTexels float default(2048) range(1,16384) ui(slider)
+#pragma param u_pageTexels float default(64) range(1,1024) ui(slider)
+#pragma param u_patchCells float default(32) range(1,512) ui(slider)
+#pragma param u_planetRadius float default(4000) range(1,100000000) ui(slider)
+#pragma param u_planetLevels float default(8) range(1,16) ui(slider)
+#pragma param u_heightRange vec2 default(0,1)
+#pragma param u_lodRange0 float default(100) range(0,1000000) ui(slider)
+#pragma param u_planetCenter vec4 default(0,0,0,0)
+#pragma param u_terrainEye vec4 default(0,0,0,0)
+
+#pragma vertexoffset
+// The three directions that make a cube face's frame: its normal, and where u and v grow (terrain/sphere.ts, FACES).
+vec3 pnN(int f) {
+ if (f == 0) return vec3(1.0, 0.0, 0.0);
+ if (f == 1) return vec3(-1.0, 0.0, 0.0);
+ if (f == 2) return vec3(0.0, 1.0, 0.0);
+ if (f == 3) return vec3(0.0, -1.0, 0.0);
+ if (f == 4) return vec3(0.0, 0.0, 1.0);
+ return vec3(0.0, 0.0, -1.0);
+}
+vec3 pnA(int f) {
+ if (f == 0) return vec3(0.0, 0.0, -1.0);
+ if (f == 1) return vec3(0.0, 0.0, 1.0);
+ if (f == 2 || f == 3 || f == 4) return vec3(1.0, 0.0, 0.0);
+ return vec3(-1.0, 0.0, 0.0);
+}
+vec3 pnB(int f) {
+ if (f == 2) return vec3(0.0, 0.0, -1.0);
+ if (f == 3) return vec3(0.0, 0.0, 1.0);
+ return vec3(0.0, 1.0, 0.0);
+}
+// The direction from the planet's centre to the point (u, v) of a face: the cube point, its coordinates spread by tangent, normalised.
+vec3 pnDirection(int f, float u, float v) {
+ return normalize(pnN(f) + tan(u * 0.78539816) * pnA(f) + tan(v * 0.78539816) * pnB(f));
+}
+// The face's u and v directions made perpendicular to up: the frame a page's normal is stored in.
+vec3 pnEu(int f, vec3 up) { vec3 a = pnA(f); return normalize(a - up * dot(a, up)); }
+vec3 pnEv(int f, vec3 up) { vec3 b = pnB(f); return normalize(b - up * dot(b, up)); }
+// The node's page: its height decoded texel by texel and blended (a filtered pair of bytes is no number).
+float pnPageHeight(vec2 texel) {
+ vec2 f = texel - 0.5;
+ ivec2 i = ivec2(floor(f));
+ vec2 t = f - vec2(i);
+ vec4 a = texelFetch(u_heightPages, i, 0), b = texelFetch(u_heightPages, i + ivec2(1, 0), 0);
+ vec4 c = texelFetch(u_heightPages, i + ivec2(0, 1), 0), d = texelFetch(u_heightPages, i + ivec2(1, 1), 0);
+ vec4 hs = vec4(a.r * 65280.0 + a.g * 255.0, b.r * 65280.0 + b.g * 255.0, c.r * 65280.0 + c.g * 255.0, d.r * 65280.0 + d.g * 255.0) / 65535.0;
+ return u_heightRange.x + mix(mix(hs.x, hs.y, t.x), mix(hs.z, hs.w, t.x), t.y) * u_heightRange.y;
+}
+void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {
+ if (u_planetPages < 0.5) return;
+ vec4 tint = esInstanceTint();
+ mat4 model = esInstanceModel();
+ vec3 boxMin = model[3].xyz;
+ vec3 boxSize = vec3(max(model[0][0], 1e-6), max(model[1][1], 1e-6), max(model[2][2], 1e-6));
+ float face = floor((tint.z - 1.0) / 16.0);
+ float level = tint.z - 1.0 - face * 16.0;
+ float at = tint.w - 1.0;
+ float ix = floor(at / 2048.0);
+ float iz = at - ix * 2048.0;
+ float span = 2.0 / exp2(u_planetLevels - 1.0 - level);
+ float u0 = -1.0 + ix * span, v0 = -1.0 + iz * span;
+ int f = int(face + 0.5);
+ // The tint holds the page's corner plus half a texel (so it is never zero); its first sample is one texel in, past the border.
+ vec2 page = tint.xy * u_atlasTexels + 0.5;
+ vec2 g = uv * u_patchCells;
+ // Toward the end of its level's range a vertex slides onto the grid of the level above, so where two levels meet they share an edge.
+ float h0 = pnPageHeight(page + uv * u_pageTexels + 0.5);
+ vec3 p0 = pnDirection(f, u0 + uv.x * span, v0 + uv.y * span) * (u_planetRadius + h0);
+ float range = u_lodRange0 * exp2(level);
+ float k = clamp((distance(u_terrainEye.xyz, p0) - range * 0.7) / (range * 0.3), 0.0, 1.0);
+ g -= fract(g * 0.5) * 2.0 * k;
+ vec2 q = g / u_patchCells;
+ vec2 texel = page + q * u_pageTexels + 0.5;
+ float h = pnPageHeight(texel);
+ vec3 dir = pnDirection(f, u0 + q.x * span, v0 + q.y * span);
+ vec3 P = dir * (u_planetRadius + h);
+ local = (P - boxMin) / boxSize;
+ vec2 nxz = textureLod(u_heightPages, texel / u_atlasTexels, 0.0).ba * 2.0 - 1.0;
+ vec3 nl = vec3(nxz.x, sqrt(max(1.0 - dot(nxz, nxz), 0.0)), nxz.y);
+ vec3 n = nl.x * pnEu(f, dir) + nl.y * dir + nl.z * pnEv(f, dir);
+ // The normal goes through the inverse transpose of the node's scale: put in what comes out as n.
+ localNormal = n * boxSize;
+ // The fragment reads the page where the vertex is, and the face: the colour carries them, divided by the tint it is multiplied by on the way.
+ es_vertexColor = vec4(texel / u_atlasTexels, face, 1.0) / tint;
+}
+#pragma end
+
+#pragma vertexoffset wgsl
+fn pnN(f : i32) -> vec3f {
+ if (f == 0) { return vec3f(1.0, 0.0, 0.0); }
+ if (f == 1) { return vec3f(-1.0, 0.0, 0.0); }
+ if (f == 2) { return vec3f(0.0, 1.0, 0.0); }
+ if (f == 3) { return vec3f(0.0, -1.0, 0.0); }
+ if (f == 4) { return vec3f(0.0, 0.0, 1.0); }
+ return vec3f(0.0, 0.0, -1.0);
+}
+fn pnA(f : i32) -> vec3f {
+ if (f == 0) { return vec3f(0.0, 0.0, -1.0); }
+ if (f == 1) { return vec3f(0.0, 0.0, 1.0); }
+ if (f == 2 || f == 3 || f == 4) { return vec3f(1.0, 0.0, 0.0); }
+ return vec3f(-1.0, 0.0, 0.0);
+}
+fn pnB(f : i32) -> vec3f {
+ if (f == 2) { return vec3f(0.0, 0.0, -1.0); }
+ if (f == 3) { return vec3f(0.0, 0.0, 1.0); }
+ return vec3f(0.0, 1.0, 0.0);
+}
+fn pnDirection(f : i32, u : f32, v : f32) -> vec3f {
+ return normalize(pnN(f) + tan(u * 0.78539816) * pnA(f) + tan(v * 0.78539816) * pnB(f));
+}
+fn pnEu(f : i32, up : vec3f) -> vec3f { let a = pnA(f); return normalize(a - up * dot(a, up)); }
+fn pnEv(f : i32, up : vec3f) -> vec3f { let b = pnB(f); return normalize(b - up * dot(b, up)); }
+fn pnPageHeight(texel : vec2f) -> f32 {
+ let f = texel - vec2f(0.5);
+ let i = vec2i(floor(f));
+ let t = f - vec2f(i);
+ let a = textureLoad(u_heightPages, i, 0);
+ let b = textureLoad(u_heightPages, i + vec2i(1, 0), 0);
+ let c = textureLoad(u_heightPages, i + vec2i(0, 1), 0);
+ let d = textureLoad(u_heightPages, i + vec2i(1, 1), 0);
+ let hs = vec4f(a.r * 65280.0 + a.g * 255.0, b.r * 65280.0 + b.g * 255.0, c.r * 65280.0 + c.g * 255.0, d.r * 65280.0 + d.g * 255.0) / 65535.0;
+ return mc.u_heightRange.x + mix(mix(hs.x, hs.y, t.x), mix(hs.z, hs.w, t.x), t.y) * mc.u_heightRange.y;
+}
+fn esMaterialVertex(local : ptr<function, vec3f>, localNormal : ptr<function, vec3f>, uv : vec2f) {
+ if (mc.u_planetPages < 0.5) { return; }
+ let tint = esInstanceTint();
+ let model = esInstanceModel();
+ let boxMin = model[3].xyz;
+ let boxSize = vec3f(max(model[0][0], 1e-6), max(model[1][1], 1e-6), max(model[2][2], 1e-6));
+ let face = floor((tint.z - 1.0) / 16.0);
+ let level = tint.z - 1.0 - face * 16.0;
+ let at = tint.w - 1.0;
+ let ix = floor(at / 2048.0);
+ let iz = at - ix * 2048.0;
+ let span = 2.0 / exp2(mc.u_planetLevels - 1.0 - level);
+ let u0 = -1.0 + ix * span;
+ let v0 = -1.0 + iz * span;
+ let f = i32(face + 0.5);
+ let page = tint.xy * mc.u_atlasTexels + vec2f(0.5);
+ var g = uv * mc.u_patchCells;
+ let h0 = pnPageHeight(page + uv * mc.u_pageTexels + vec2f(0.5));
+ let p0 = pnDirection(f, u0 + uv.x * span, v0 + uv.y * span) * (mc.u_planetRadius + h0);
+ let range = mc.u_lodRange0 * exp2(level);
+ let k = clamp((distance(mc.u_terrainEye.xyz, p0) - range * 0.7) / (range * 0.3), 0.0, 1.0);
+ g = g - fract(g * 0.5) * 2.0 * k;
+ let q = g / mc.u_patchCells;
+ let texel = page + q * mc.u_pageTexels + vec2f(0.5);
+ let h = pnPageHeight(texel);
+ let dir = pnDirection(f, u0 + q.x * span, v0 + q.y * span);
+ let P = dir * (mc.u_planetRadius + h);
+ *local = (P - boxMin) / boxSize;
+ let nxz = textureSampleLevel(u_heightPages, u_heightPages_s, texel / mc.u_atlasTexels, 0.0).ba * 2.0 - vec2f(1.0);
+ let nl = vec3f(nxz.x, sqrt(max(1.0 - dot(nxz, nxz), 0.0)), nxz.y);
+ let n = nl.x * pnEu(f, dir) + nl.y * dir + nl.z * pnEv(f, dir);
+ *localNormal = n * boxSize;
+ es_vertexColor = vec4f(texel / mc.u_atlasTexels, face, 1.0) / tint;
+}
+#pragma end
+
+#pragma fragment
+precision highp float;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+in highp vec2 v_worldPos;
+#ifdef MESH_NORMALS
+in highp vec3 v_worldNormal;
+in highp vec3 v_worldXYZ;
+#endif
+
+#ifdef ES_GBUFFER
+layout(location = 0) out vec4 fragColor;
+layout(location = 1) out vec4 fragSurface;
+
+vec2 packNormal(vec3 n) {
+ n /= (abs(n.x) + abs(n.y) + abs(n.z));
+ vec2 sgn = vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);
+ vec2 e = n.z >= 0.0 ? n.xy : (1.0 - abs(n.yx)) * sgn;
+ return e * 0.5 + 0.5;
+}
+#else
+out vec4 fragColor;
+#endif
+
+vec3 pnA(int f) {
+ if (f == 0) return vec3(0.0, 0.0, -1.0);
+ if (f == 1) return vec3(0.0, 0.0, 1.0);
+ if (f == 2 || f == 3 || f == 4) return vec3(1.0, 0.0, 0.0);
+ return vec3(-1.0, 0.0, 0.0);
+}
+vec3 pnB(int f) {
+ if (f == 2) return vec3(0.0, 0.0, -1.0);
+ if (f == 3) return vec3(0.0, 0.0, 1.0);
+ return vec3(0.0, 1.0, 0.0);
+}
+// Value noise in three dimensions: a planet has no plane to lay a flat noise on.
+float pnHash(vec3 p) {
+ p = fract(p * vec3(0.1031, 0.1030, 0.0973));
+ p += dot(p, p.yzx + 33.33);
+ return fract((p.x + p.y) * p.z);
+}
+float pnNoise(vec3 p) {
+ vec3 i = floor(p), f = fract(p);
+ f = f * f * (3.0 - 2.0 * f);
+ float a = mix(mix(pnHash(i), pnHash(i + vec3(1, 0, 0)), f.x), mix(pnHash(i + vec3(0, 1, 0)), pnHash(i + vec3(1, 1, 0)), f.x), f.y);
+ float b = mix(mix(pnHash(i + vec3(0, 0, 1)), pnHash(i + vec3(1, 0, 1)), f.x), mix(pnHash(i + vec3(0, 1, 1)), pnHash(i + vec3(1, 1, 1)), f.x), f.y);
+ return mix(a, b, f.z);
+}
+
+void main() {
+#ifdef MESH_NORMALS
+ highp vec3 P = v_worldXYZ;
+#else
+ highp vec3 P = vec3(v_worldPos.x, 0.0, v_worldPos.y);
+#endif
+ vec3 up = normalize(P - u_planetCenter.xyz);
+ int f = int(v_color.z + 0.5);
+ vec4 paint = texture(u_paintPages, v_color.xy);
+ vec2 nxz = texture(u_heightPages, v_color.xy).ba * 2.0 - 1.0;
+ vec3 nl = vec3(nxz.x, sqrt(max(1.0 - dot(nxz, nxz), 0.0)), nxz.y);
+ vec3 a = pnA(f), b = pnB(f);
+ vec3 eu = normalize(a - up * dot(a, up)), ev = normalize(b - up * dot(b, up));
+ vec3 N = normalize(nl.x * eu + nl.y * up + nl.z * ev);
+
+ vec4 w = max(paint, vec4(0.0));
+ w /= max(dot(w, vec4(1.0)), 1e-4);
+ w = pow(w, vec4(u_sharpness));
+ w /= max(dot(w, vec4(1.0)), 1e-4);
+ vec3 albedo = u_tint0.rgb * w.x + u_tint1.rgb * w.y + u_tint2.rgb * w.z + u_tint3.rgb * w.w;
+ vec3 q = (P - u_planetCenter.xyz) / u_macroScale;
+ float broad = pnNoise(q) * 0.6 + pnNoise(q * 4.1 + 7.0) * 0.4;
+ albedo *= mix(1.0, 0.7 + 0.6 * broad, u_macroVariation);
+
+ float roughness = u_roughness;
+ SurfaceExt ext = surfaceExtNone(N);
+ vec3 viewDir = viewDirection(P);
+ vec3 lit = applyLightingSurface(albedo, N, P, viewDir, 0.0, roughness, 0.5, 1.0, ext);
+ fragColor = vec4(lit, 1.0);
+#ifdef ES_GBUFFER
+ fragSurface = vec4(packNormal(N), roughness, 0.75);
+#endif
+}
+#pragma end
+
+#pragma fragment wgsl
+fn pnA(f : i32) -> vec3f {
+ if (f == 0) { return vec3f(0.0, 0.0, -1.0); }
+ if (f == 1) { return vec3f(0.0, 0.0, 1.0); }
+ if (f == 2 || f == 3 || f == 4) { return vec3f(1.0, 0.0, 0.0); }
+ return vec3f(-1.0, 0.0, 0.0);
+}
+fn pnB(f : i32) -> vec3f {
+ if (f == 2) { return vec3f(0.0, 0.0, -1.0); }
+ if (f == 3) { return vec3f(0.0, 0.0, 1.0); }
+ return vec3f(0.0, 1.0, 0.0);
+}
+fn pnHash(p0 : vec3f) -> f32 {
+ var p = fract(p0 * vec3f(0.1031, 0.1030, 0.0973));
+ p = p + dot(p, p.yzx + 33.33);
+ return fract((p.x + p.y) * p.z);
+}
+fn pnNoise(p : vec3f) -> f32 {
+ let i = floor(p);
+ var f = fract(p);
+ f = f * f * (3.0 - 2.0 * f);
+ let a = mix(mix(pnHash(i), pnHash(i + vec3f(1.0, 0.0, 0.0)), f.x), mix(pnHash(i + vec3f(0.0, 1.0, 0.0)), pnHash(i + vec3f(1.0, 1.0, 0.0)), f.x), f.y);
+ let b = mix(mix(pnHash(i + vec3f(0.0, 0.0, 1.0)), pnHash(i + vec3f(1.0, 0.0, 1.0)), f.x), mix(pnHash(i + vec3f(0.0, 1.0, 1.0)), pnHash(i + vec3f(1.0, 1.0, 1.0)), f.x), f.y);
+ return mix(a, b, f.z);
+}
+
+#ifdef ES_GBUFFER
+struct FragOut {
+ @location(0) color : vec4f,
+ @location(1) surface : vec4f,
+};
+
+fn packNormal(n : vec3f) -> vec2f {
+ let a = n / (abs(n.x) + abs(n.y) + abs(n.z));
+ let sgn = vec2f(select(-1.0, 1.0, a.x >= 0.0), select(-1.0, 1.0, a.y >= 0.0));
+ var e = a.xy;
+ if (a.z < 0.0) { e = (vec2f(1.0) - abs(a.yx)) * sgn; }
+ return e * 0.5 + 0.5;
+}
+
+@fragment fn fs_main(v : VSOut) -> FragOut {
+#else
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+#endif
+ g_probeSlot = v.v_probeSlot;
+#ifdef MESH_LIGHTMAP
+ g_lightmap = v.v_lightmap;
+#endif
+#ifdef MESH_NORMALS
+ let P = v.v_worldXYZ;
+#else
+ let P = vec3f(v.v_worldPos.x, 0.0, v.v_worldPos.y);
+#endif
+ let up = normalize(P - mc.u_planetCenter.xyz);
+ let f = i32(v.v_color.z + 0.5);
+ let paint = textureSample(u_paintPages, u_paintPages_s, v.v_color.xy);
+ let nxz = textureSample(u_heightPages, u_heightPages_s, v.v_color.xy).ba * 2.0 - vec2f(1.0);
+ let nl = vec3f(nxz.x, sqrt(max(1.0 - dot(nxz, nxz), 0.0)), nxz.y);
+ let a = pnA(f);
+ let b = pnB(f);
+ let eu = normalize(a - up * dot(a, up));
+ let ev = normalize(b - up * dot(b, up));
+ let N = normalize(nl.x * eu + nl.y * up + nl.z * ev);
+
+ var w = max(paint, vec4f(0.0));
+ w = w / max(dot(w, vec4f(1.0)), 1e-4);
+ w = pow(w, vec4f(mc.u_sharpness));
+ w = w / max(dot(w, vec4f(1.0)), 1e-4);
+ var albedo = mc.u_tint0.rgb * w.x + mc.u_tint1.rgb * w.y + mc.u_tint2.rgb * w.z + mc.u_tint3.rgb * w.w;
+ let q = (P - mc.u_planetCenter.xyz) / mc.u_macroScale;
+ let broad = pnNoise(q) * 0.6 + pnNoise(q * 4.1 + vec3f(7.0)) * 0.4;
+ albedo = albedo * mix(1.0, 0.7 + 0.6 * broad, mc.u_macroVariation);
+
+ let roughness = mc.u_roughness;
+ let ext = surfaceExtNone(N);
+ let viewDir = viewDirection(P);
+ let lit = applyLightingSurface(albedo, N, P, viewDir, 0.0, roughness, 0.5, 1.0, ext);
+#ifdef ES_GBUFFER
+ var frag : FragOut;
+ frag.color = vec4f(lit, 1.0);
+ frag.surface = vec4f(packNormal(N), roughness, 0.75);
+ return frag;
+#else
+ return vec4f(lit, 1.0);
+#endif
+}
+#pragma end
+`;
+
+export const PLANET_SHADER_TEMPLATE = makeBuiltinShaderTemplate('planet', 'Planet',
+ 'Ground on a sphere, from the pages of a Planet component\'s quadtree nodes, painted by four layer colours.', PLANET);
diff --git a/sdk/src/terrain/terrainSupport.ts b/sdk/src/terrain/terrainSupport.ts
index 8a19109dd..3ebc16e17 100644
--- a/sdk/src/terrain/terrainSupport.ts
+++ b/sdk/src/terrain/terrainSupport.ts
@@ -10,11 +10,15 @@ import { addAssetLoader } from '../asset/optionalLoaders';
import { registerBuiltinShaderTemplate } from '../render/builtinShaders';
import { TERRAIN_LAYERS_SHADER_TEMPLATE, TERRAIN_SHADER_TEMPLATE } from './terrainShader';
import { TerrainPlugin } from './terrainPlugin';
+import { PLANET_SHADER_TEMPLATE } from './planetShader';
+import { PlanetPlugin } from './planetPlugin';
import { TerrainLayerAssetLoader } from './layers';
export function registerTerrainSupport(): void {
registerBuiltinShaderTemplate(TERRAIN_SHADER_TEMPLATE);
registerBuiltinShaderTemplate(TERRAIN_LAYERS_SHADER_TEMPLATE);
+ registerBuiltinShaderTemplate(PLANET_SHADER_TEMPLATE);
addEntryPlugin('terrain', () => new TerrainPlugin());
+ addEntryPlugin('planet', () => new PlanetPlugin());
addAssetLoader('terrain', () => new TerrainLayerAssetLoader());
}
diff --git a/sdk/tests/terrain-sphere.test.ts b/sdk/tests/terrain-sphere.test.ts
index 21786b51c..1ac2309d9 100644
--- a/sdk/tests/terrain-sphere.test.ts
+++ b/sdk/tests/terrain-sphere.test.ts
@@ -115,3 +115,43 @@ describe('the nodes drawn round an eye', () => {
expect(sphereNodeKey(nd)).toBe(`${face}:2:${nd.ix}:${nd.iz}`);
});
});
+
+describe('a planet node\'s page', () => {
+ const src = (height: (d: [number, number, number]) => number) => ({
+ provider: {
+ id: 't', versions: [1], range: () => [-50, 250] as [number, number],
+ sample: ({ directions, count }: { directions: Float32Array; count: number }) => {
+ const heights = new Float32Array(count);
+ for (let i = 0; i < count; i++) heights[i] = height([directions[i * 3]!, directions[i * 3 + 1]!, directions[i * 3 + 2]!]);
+ return { heights };
+ },
+ },
+ world: 'w', seed: 1, version: 1, radius: planet.radius, levels, minHeight: -50, maxHeight: 250,
+ });
+ const decode = (page: { heights: Uint8Array }, k: number) => (page.heights[k * 4]! * 256 + page.heights[k * 4 + 1]!) / 65535 * 300 - 50;
+
+ it('holds the height the provider gave, over the range, and says up is up on level ground', async () => {
+ const { makePlanetPage } = await import('../src/terrain/planetPages');
+ const { PAGE_SIDE } = await import('../src/terrain/pages');
+ const page = await makePlanetPage(src(() => 40), { face: 2, level: 3, ix: 5, iz: 9 });
+ const k = Math.floor(PAGE_SIDE / 2) * PAGE_SIDE + Math.floor(PAGE_SIDE / 2);
+ expect(decode(page, k)).toBeCloseTo(40, 2);
+ expect(page.min).toBeCloseTo(40, 3);
+ expect(page.max).toBeCloseTo(40, 3);
+ // The normal is stored in the frame at the sample: x and z are the tangents, so level ground leans neither way (128 of 255).
+ expect(Math.abs(page.heights[k * 4 + 2]! - 128)).toBeLessThanOrEqual(1);
+ expect(Math.abs(page.heights[k * 4 + 3]! - 128)).toBeLessThanOrEqual(1);
+ });
+
+ it('leans the normal away from a rising slope, whichever face the node is on', async () => {
+ const { makePlanetPage } = await import('../src/terrain/planetPages');
+ const { PAGE_SIDE } = await import('../src/terrain/pages');
+ for (const face of [2, 4, 5]) {
+ // Ground that rises with the direction's x, steeply: on these faces x runs along u, so the normal leans in the frame's x.
+ const page = await makePlanetPage(src((d) => 2000 * d[0]), { face, level: 4, ix: 3, iz: 4 });
+ const k = Math.floor(PAGE_SIDE / 2) * PAGE_SIDE + Math.floor(PAGE_SIDE / 2);
+ const leanX = page.heights[k * 4 + 2]! - 128, leanZ = page.heights[k * 4 + 3]! - 128;
+ expect(Math.hypot(leanX, leanZ)).toBeGreaterThan(2);
+ }
+ });
+});
diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjs
index 23b73b79d..4f4f21fdc 100644
--- a/tools/check-corpus-authoring.mjs
+++ b/tools/check-corpus-authoring.mjs
@@ -122,6 +122,7 @@ const DISPOSITION = {
// — derived: a system writes them; authored, they would be a bug —
RuntimeOnly: ['derived', 'tags a world-only entity a system re-derives; scene serialization skips tagged entities, so authoring one would delete it on save'],
NetGhost: ['derived', 'replication tags a remote proxy with it; the authority writes it, never the scene'],
+ Planet: ['owed', 'authored by a game today (star-neighbors, a round planet from its own generator); an example that registers a planet provider is owed'],
MeshInstances: ['derived', 'the foliage and world generation systems write it, one entity a kind and part of a cell; its places are data a system computes, not something a scene authors'],
PlacedFoliage: ['derived', 'a generated world grows its plants through the same machinery without the component, and a project that places plants by hand writes the kinds and records with a script from its own rules; the lists are generated data, not something a scene is authored by hand with'],
PlacedObject: ['derived', 'a generated world writes it on what it places for the game to interact with; authored, it would name a placement no rule made'],
diff --git a/tools/check-gizmo-coverage.mjs b/tools/check-gizmo-coverage.mjs
index c6a279ccc..09790f967 100644
--- a/tools/check-gizmo-coverage.mjs
+++ b/tools/check-gizmo-coverage.mjs
@@ -114,6 +114,8 @@ const DISPOSITION = {
'MeshInstances.minDistance': ['no-place', 'a distance from the eye, not a region of the entity'],
'MeshInstances.drawDistance': ['no-place', 'a distance from the eye, not a region of the entity'],
'MeshInstances.shadowDistance': ['no-place', 'a distance from the eye, not a region of the entity'],
+ 'Planet.radius': ['renders', 'the sphere drawn at the entity is the outline'],
+ 'Planet.cellSize': ['no-place', 'the finest cell of the ground\'s mesh near the eye, not a region of the entity'],
'PlacedFoliage.sizeX': ['renders', 'the area the plants are placed over is the outline'],
'PlacedFoliage.sizeZ': ['renders', 'the area the plants are placed over is the outline'],
'PlacedFoliage.cellSize': ['no-place', 'the side of the cells the area is cut into, not a region of the entity'],
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 2430b0e3d..0608ac15f 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2916,6 +2916,8 @@ export const NOTED = {
{"note":"The editor's own eye shows the scene's post-processing."},
"feat(terrain): the maths of ground on a cube sphere and the nodes drawn round an eye":
{"internal":"The first layer of spherical terrain: pure maths and node selection, not yet drawn."},
+ "feat(terrain): a Planet component draws ground on a sphere from a provider that answers by direction":
+ {"note":"A `Planet`: ground on a sphere."},
"feat(assets): a project names folders its asset database leaves alone":
{"note":"A project can keep folders out of its asset database."},
"feat(worldgen): a plant part may cast no shadow, and far cells are capped at two cells wide":