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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdindex 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.mdxindex 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`; wthe old one, so what was built on the old ground still stands on it. The engine's noise is `estella:noise`, version 1. A providerwith `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 collidesdiff --git a/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdx b/docs/astro/src/content/docs/zh-cn/graphics/terrain.mdxindex 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.jsonindex 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.tsindex 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.jsonindex 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.mdindex 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 | nullvisible: 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 | undefinedwidth: 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: numberrestitution: 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 | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 | nullvisible: 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 | undefinedwidth: 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: numberrestitution: 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 | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 | nullvisible: 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 | undefinedwidth: 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: numberrestitution: 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 @@ MeshRendererPluginNodePlatformAdapter```+## 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 | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 | nullvisible: 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 | undefinedwidth: 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: numberrestitution: 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 | undefineddiff --git a/sdk/etc/terrain.api.md b/sdk/etc/terrain.api.mdindex 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: numbersizeZ: 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): PageTablestatic 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.mdindex 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 | nullvisible: 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 | undefinedwidth: 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: numberrestitution: 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 | undefineddiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.mjsindex 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.mjsindex 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.mjsindex 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":