Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
{ wave, depth })` and `useWorld().waters` in `@runek/core`: the registry
of water a figure can get into. A water component of your own joins with
one `useWater` call.
- `Terrain` gains `shore`: the width, in units, of a beach around an
island (one with `falloff`). Past the land's edge the ground falls 2
units across it at one slope, from just above the world ground to
wading depth, before it drops to the deep, so an avatar can walk up
out of the sea: `shore: 6` slopes at about 18°, where the coast of a
small island without it runs past 60°. Land near the coast is lowered
to meet the beach. Worlds that don't set `shore` keep every height
they had. The workshop's "Island cove" template has one, and its dock
now starts on the beach.

### Changed

Expand Down
1 change: 1 addition & 0 deletions apps/docs/src/content/docs/components/terrain.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ Or as a node in a world file ([worlds as data](/docs/worlds-as-data)):
| `frequency` | `number` | `0.04` | Noise frequency. |
| `flatRadius` | `number` | `0` | Radius from center kept flat (for a build pad), in units. |
| `falloff` | `number` | `0` | Radial island falloff (0 = off). When set, the ground domes up toward the center and sinks below the world ground at its rim, so the mesh reads as a landmass surrounded by water. The value is the fraction of the half-extent that stays land before the coast (e.g. 0.8 = land out to 80% of the radius, then a shoreline into the sea). |
| `shore` | `number` | `0` | Width of a beach around an island, in units (0 = off; needs `falloff`). Past the land's edge the ground falls 2 units across this band at one slope, from 0.4 above the world ground to wading depth, then drops to the deep; land near the coast is lowered to meet it. So the beach is as gentle as it is wide: 6 slopes at about 18°, which an avatar walks up out of the sea, where a small island's bare coast is close to a cliff. It widens the island, so leave room for it inside `size`. |
| `collider` | `boolean` | `true` | Register a collider (default true). Set false for distant/backdrop terrain the player never walks, to skip a large trimesh collider. |
| `seed` | `number` | `1` | Seed for the deterministic variation: same seed, same result. |

Expand Down
1 change: 1 addition & 0 deletions apps/docs/src/workshop/schema/ranges.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ export const RANGES: Record<string, Record<string, [number, number, number]>> =
frequency: [0.005, 0.2, 0.005],
flatRadius: [0, 60, 0.5],
falloff: [0, 1, 0.01],
shore: [0, 20, 0.5],
},
Grass: { count: [0, 6000, 50], sway: [0, 3, 0.05] },
Person: {
Expand Down
5 changes: 3 additions & 2 deletions apps/docs/src/workshop/templates/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,7 @@ export const TEMPLATES: Template[] = [
size: [44, 44],
relief: 3,
falloff: 0.55,
shore: 6,
flatRadius: 7,
seed: 12,
color: '#d8c79a',
Expand All @@ -174,8 +175,8 @@ export const TEMPLATES: Template[] = [
})),
{ type: 'Campfire', anchor: 'ground', props: { position: [0, 0, 0], seed: 2 } },
{ type: 'Rocks', anchor: 'ground', props: { position: [-4, 0, 3], count: 5, seed: 7 } },
{ type: 'Dock', props: { position: [0, 0, 19], length: 9, seed: 3 } },
{ type: 'Sailboat', props: { position: [4, -0.2, 24], rotation: [0, 0.6, 0], seed: 5 } },
{ type: 'Dock', props: { position: [0, 0, 9.4], length: 9, seed: 3 } },
{ type: 'Sailboat', props: { position: [4, -0.2, 15.5], rotation: [0, 0.6, 0], seed: 5 } },
{
type: 'Person',
anchor: 'ground',
Expand Down
21 changes: 19 additions & 2 deletions packages/components/src/Terrain.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,13 @@ export interface TerrainProps {
* water. The value is the fraction of the half-extent that stays land before the coast
* (e.g. 0.8 = land out to 80% of the radius, then a shoreline into the sea). */
falloff?: number
/** Width of a beach around an island, in units (0 = off; needs `falloff`). Past the land's
* edge the ground falls 2 units across this band at one slope, from 0.4 above the world
* ground to wading depth, then drops to the deep; land near the coast is lowered to meet
* it. So the beach is as gentle as it is wide: 6 slopes at about 18°, which an avatar
* walks up out of the sea, where a small island's bare coast is close to a cliff. It
* widens the island, so leave room for it inside `size`. */
shore?: number
/** Register a collider (default true). Set false for distant/backdrop terrain the player
* never walks, to skip a large trimesh collider. */
collider?: boolean
Expand Down Expand Up @@ -60,6 +67,7 @@ export function Terrain({
frequency = TERRAIN_DEFAULTS.frequency,
flatRadius = TERRAIN_DEFAULTS.flatRadius,
falloff = TERRAIN_DEFAULTS.falloff,
shore = TERRAIN_DEFAULTS.shore,
collider = true,
seed = TERRAIN_DEFAULTS.seed,
}: TerrainProps) {
Expand All @@ -78,11 +86,20 @@ export function Terrain({
() =>
relief > 0
? terrainGeometry(
{ size: [sizeX, sizeZ], relief, resolution, frequency, flatRadius, falloff, seed },
{
size: [sizeX, sizeZ],
relief,
resolution,
frequency,
flatRadius,
falloff,
shore,
seed,
},
unit,
)
: null,
[sizeX, sizeZ, resolution, relief, frequency, flatRadius, falloff, seed, unit],
[sizeX, sizeZ, resolution, relief, frequency, flatRadius, falloff, shore, seed, unit],
)
useEffect(() => () => displaced?.dispose(), [displaced])

Expand Down
138 changes: 137 additions & 1 deletion packages/components/src/surfaces/terrain.test.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
import * as THREE from 'three'
import { describe, expect, it } from 'vitest'
import { terrainGeometry } from '../Terrain'
import { type TerrainShape, terrainSurface } from './terrain'
import { type TerrainShape, terrainHeight, terrainSurface } from './terrain'

// The workshop's "Island cove" terrain, before it had a shore.
const COVE: TerrainShape = { size: [44, 44], relief: 3, falloff: 0.55, flatRadius: 7, seed: 12 }

// Golden tests: the query must agree with the rendered mesh (and so the trimesh collider built
// from it), not with an idealized noise field. A downward ray against the real geometry is the
Expand All @@ -19,6 +22,12 @@ const SHAPES: Array<[string, TerrainShape, number]> = [
1,
],
['scaled unit', { size: [20, 20], relief: 5, resolution: 24, seed: 2 }, 2.5],
['island with a shore', { ...COVE, shore: 6 }, 1],
[
'scaled island with a shore',
{ size: [30, 30], relief: 3, falloff: 0.5, shore: 6, seed: 2 },
2.5,
],
]

function rayHeight(mesh: THREE.Mesh, x: number, z: number): number | null {
Expand Down Expand Up @@ -70,3 +79,130 @@ describe('terrainSurface', () => {
expect(field(6, 0)).toBeNull()
})
})

// `[x, z, height]` recorded before `shore` existed: a world that doesn't set it keeps every
// height to the bit.
const PINNED: Array<[string, TerrainShape, number, Array<[number, number, number]>]> = [
[
'rolling',
{ size: [40, 40], relief: 3, seed: 7 },
1,
[
[0, 0, -2.5691915560746565],
[3.5, -8.25, -2.422234472320204],
[-17, 12.5, -0.758471265605433],
[19.9, 19.9, 1.2120483001580982],
],
],
[
'island',
{ size: [44, 44], relief: 3, falloff: 0.55, seed: 12 },
1,
[
[0, 0, 1.574648448076914],
[5, -4, 1.3140135499601833],
[-6.5, 6.5, -0.05599064511028096],
[0, 10.25, -3.183853823247618],
[9, 7, -6.301590329062409],
[-15, 2, -7],
],
],
[
'island with a pad',
COVE,
1,
[
[2, 3, 0],
[7.5, 0, 0.010406006693069004],
[-6, 6, 0.11163907046015364],
[0, 9.5, -0.19430265029315943],
[8, -7.25, -2.259145591153959],
[0, 13, -5.90625],
[16, 16, -7],
],
],
[
'scaled island',
{ size: [30, 20], relief: 5, resolution: 24, falloff: 0.8, flatRadius: 2, seed: 2 },
2.5,
[
[4, -3, 0],
[-11, 9.5, 2.9324007804506964],
[0, 17.75, -6.056225105129616],
[20.5, 3, -19.847911112776647],
[30, -20, -22.5],
],
],
]

/** The steepest stretch, in degrees, of the band an avatar wades through: from 0.3 above the
* world ground to 1.5 below it, walked along radii of the collider's own triangles. */
function steepestShore(shape: TerrainShape, unit: number): number {
const field = terrainSurface.build(shape as Record<string, unknown>, { unit, ground: 0 })
const half = (Math.min(...(shape.size ?? [40, 40])) * unit) / 2
const step = 0.25 * unit
let steepest = 0
for (let a = 0; a < 360; a += 5) {
const dx = Math.cos((a * Math.PI) / 180)
const dz = Math.sin((a * Math.PI) / 180)
for (let r = 0; r + step < half; r += step) {
const near = field(dx * r, dz * r) as number
const far = field(dx * (r + step), dz * (r + step)) as number
if (Math.max(near, far) > 0.3 * unit || Math.min(near, far) < -1.5 * unit) continue
steepest = Math.max(steepest, Math.atan(Math.abs(far - near) / step))
}
}
return (steepest * 180) / Math.PI
}

describe('terrainHeight', () => {
for (const [name, shape, unit, points] of PINNED) {
it(`keeps its heights without a shore: ${name}`, () => {
const height = terrainHeight(shape, unit)
for (const [x, z, h] of points) expect(height(x, z)).toBe(h)
})
}

it('reads a shore only on an island', () => {
const rolling: TerrainShape = { size: [40, 40], relief: 3, seed: 7 }
const plain = terrainHeight(rolling, 1)
const shored = terrainHeight({ ...rolling, shore: 6 }, 1)
const cove = terrainHeight(COVE, 1)
const zeroed = terrainHeight({ ...COVE, shore: 0 }, 1)
for (const [x, z] of [
[0, 0],
[3.5, -8.25],
[0, 9.5],
[-12, 11],
]) {
expect(shored(x, z)).toBe(plain(x, z))
expect(zeroed(x, z)).toBe(cove(x, z))
}
})

describe('shore', () => {
it('turns a coast too steep to walk into a beach', () => {
expect(steepestShore(COVE, 1)).toBeGreaterThan(45)
expect(steepestShore({ ...COVE, shore: 6 }, 1)).toBeLessThan(25)
// No pad, more relief, a scaled unit: the land is cut down to meet the beach.
const hilly: TerrainShape = { size: [60, 60], relief: 6, falloff: 0.5, shore: 6, seed: 4 }
expect(steepestShore(hilly, 1)).toBeLessThan(25)
expect(steepestShore(hilly, 2.5)).toBeLessThan(25)
})

it('keeps the build pad flat and still sinks to the deep at the rim', () => {
const height = terrainHeight({ ...COVE, shore: 6 }, 1)
expect(height(0, 0)).toBe(0)
expect(height(-4, 5)).toBe(0)
expect(height(0, 21.9)).toBe(-7)
expect(height(-15.5, 15.5)).toBe(-7)
})

it('starts the beach at the edge of a pad wider than the land', () => {
const height = terrainHeight({ ...COVE, flatRadius: 12, shore: 6 }, 1)
expect(height(0, 11.9)).toBe(0)
expect(height(0, 15)).toBeCloseTo(0.4 - 1, 6)
expect(height(0, 18)).toBeCloseTo(-1.6, 6)
})
})
})
29 changes: 28 additions & 1 deletion packages/components/src/surfaces/terrain.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ export interface TerrainShape {
frequency?: number
flatRadius?: number
falloff?: number
shore?: number
seed?: number
}

Expand All @@ -19,9 +20,16 @@ export const TERRAIN_DEFAULTS = {
frequency: 0.04,
flatRadius: 0,
falloff: 0,
shore: 0,
seed: 1,
}

// Fraction of the half-extent an island's coast takes to fall from the land to the deep.
const COAST = 0.18
// A beach runs from this far above the world ground down to this far below it, in units.
const BEACH_TOP = 0.4
const BEACH_DEPTH = 1.6

function valueNoise(seed: number) {
const hash = (x: number, y: number) => {
let h = (seed ^ Math.imul(x, 374761393) ^ Math.imul(y, 668265263)) >>> 0
Expand Down Expand Up @@ -69,19 +77,38 @@ export function terrainHeight(shape: TerrainShape, unit: number): (x: number, z:
frequency = TERRAIN_DEFAULTS.frequency,
flatRadius = TERRAIN_DEFAULTS.flatRadius,
falloff = TERRAIN_DEFAULTS.falloff,
shore = TERRAIN_DEFAULTS.shore,
seed = TERRAIN_DEFAULTS.seed,
} = shape
const noise = valueNoise(seed)
const fr = flatRadius * unit
const half = (Math.min(size[0], size[1]) * unit) / 2
const sink = (relief + 4) * unit
if (falloff > 0 && shore > 0) {
// Island with a beach: past the land's edge the ground is a cone of one slope down to
// wading depth, then drops to the deep. The land may not rise above that cone, so nothing
// steeper stands behind the beach. The pad flattens the land alone (scaling the sea bed
// would steepen it), and a pad wider than the land pushes the beach out to its edge.
const top = BEACH_TOP * unit
const shelf = BEACH_DEPTH * unit
const width = shore * unit
const start = Math.max((falloff - COAST) * half, fr)
const end = start + width
return (x, z) => {
const r = Math.hypot(x, z)
let land = fbm(noise, x * frequency, z * frequency) * relief * unit
if (fr > 0) land *= smoothstep(r, fr, fr + 8 * unit)
const beach = Math.max(top - ((r - start) / width) * (top + shelf), -shelf)
return Math.min(land, beach) - (sink - shelf) * smoothstep(r, end, end + COAST * half)
}
}
return (x, z) => {
let h: number
if (falloff > 0) {
// Island mode: gentle land above the waterline, masked down to the deep at the rim.
const land = fbm(noise, x * frequency, z * frequency) * relief * unit
const rn = Math.hypot(x, z) / half
const mask = 1 - smoothstep(rn, falloff - 0.18, falloff)
const mask = 1 - smoothstep(rn, falloff - COAST, falloff)
h = land * mask - (1 - mask) * sink
} else {
h = (fbm(noise, x * frequency, z * frequency) - 0.5) * 2 * relief * unit
Expand Down
Loading
Loading