scatter3dplugin

Trees, grass and boulders, where each stands a pure function of its cell.

#Putting it in a scene

List it after terrain3d, whose ground it stands on, and before render3d. scatter3d has no row: where every instance stands is worked out from its cell, the same on the server and every seat, and a child scene inherits world.scatter3d from the manager scene. Until the land has loaded nothing is drawn.

"plugins": ["loader", "scenemanager", "player", "terrain3d", "scatter3d", "render3d"],
"world": {
  "loader": { "assets": { "firs": { "type": "model", "url": "/games/mygame/assets/firs.glb", "preload": true } } },
  "scatter3d": {
    "mods": { "ground": "terrain3d", "land": "terrain3d" },
    "cutout": 0.5,
    "coverage": 0.3,
    "budget": 3,
    "remember": 50000,
    "packs": {
      "firs": {
        "asset": "firs",
        "rows": { "tall": { "weight": 3, "solid": 0.4, "tall": 14 }, "short": { "weight": 1, "solid": 0.3, "tall": 8 } },
        "cell": 10, "reach": 400, "seed": 11, "lods": [60, 160], "shadow": 120, "leaf": 0.6,
        "density": 0.4,
        "rules": [{ "q": "height", "lo": 105, "hi": 28 }, { "q": "slope", "lo": 0.5, "hi": 0.3 }],
        "clearing": 30, "size": [0.8, 0.5], "vary": 0.15
      },
      "rocks": {
        "shape": { "detail": 2, "lumpy": [0.8, 0.4], "squash": 0.6 },
        "colour": "#7d7a72",
        "rows": { "a": { "weight": 1, "solid": 0.9, "tall": 0.6 }, "b": { "weight": 1, "solid": 0.9, "tall": 0.6 } },
        "cell": 14, "reach": 300, "seed": 4, "lods": [120], "shadow": 80, "leaf": 0,
        "density": 0.15, "rules": [{ "q": "slope", "lo": 0.1, "hi": 0.3 }], "biomes": { "tundra": 1, "forest": 0.4 },
        "clearing": 20, "size": [0.6, 1.4], "vary": 0.1
      }
    }
  },
  "terrain3d": { "mods": { "ready": ["scatter3d"] } }
}

#Properties

Read from world.scatter3d. A change to any number rebuilds the field.

.mods : { ground, land, hollows? }

The plugins whose ground the server and the page place on, and the plugins whose boxes clear instances (see Mods).

.cutout : number

The alpha at which a model's blended materials are cut, 0 to 1. Every blended material becomes an alpha-tested card, written to depth. A masked material keeps its own cutoff.

.coverage : number

How much a card's alpha gains per mip level its texture is read at, so far leaves do not thin to sticks as the texture shrinks: alpha × (1 + level × coverage).

.budget : number

Milliseconds a frame the page may spend placing cells newly in reach, at least one cell a frame. Cells nearest the camera go first. Where terrain3d lends its workers, cells are placed there and the budget bounds nothing.

.remember : number

How many cells the server keeps per scene for solids, a whole number above 0. Past it, the one placed longest ago is dropped and placed again, the same, when asked for.

.hollows : number

With a hollows mod, the most boxes cleared at once, the ones nearest the camera. A whole number above 0.

.packs : { [name]: pack }

Each pack is a grid of square cells, at most one instance a cell, drawn round the camera out to its reach.

#Packs

What is drawn

A model pack's meshes are named <row>-<lod>, or <row>-<lod>-<part> for a LOD in several parts, such as tall-0 and tall-1-leaves. A row that is drawn needs a mesh for every LOD. Every LOD of a row is moved so LOD 0's lowest point is on the ground and its middle on the instance's point.

Where it grows

Cell (i, j) covers [i·cell, (i + 1)·cell) across x and z. The instance's point is jittered over the whole cell. It is kept when a random value for the cell falls under the keep: density × the painted surface's cover × every rule's ramp × the biomes' weight.

Each instance

Each instance is turned to a random yaw, tilted toward the ground's slope and sunk until it touches. How far it leans is its foot's width over its height, at most 1: a tussock lies along the slope and a fir stands up straight.

How it is drawn

Boulders

shape: { detail, lumpy: [base, range], squash }. Each row is a variant: a sphere of radius 1 subdivided detail times, each vertex pushed out to between base and base + range of itself, then its height multiplied by squash, shaded face by face. Its middle is at the ground, so half of it is buried.

Without a surface, it is drawn in colour. A surface mixes two noises, n = a × noise at broad + b × noise at fine, with mix [a, b] and the frequencies in cycles a metre:

#Methods

Rules

From #plugins/scatter3d/scatter3d.sim.ts.

solids( w, x, z, r, ground ) : { x, z, radius, tall? }[]

Every kept instance of a row with solid whose circle reaches within r metres of (x, z). tall is given when the row gives one. A stroke on the ground drops the cells it reaches, so they are placed again on the new ground.

placed( w ) : ground

The ground mods.ground names, to hand to solids or place. Throws when the scene names none.

place( pack, i, j, ground ) : { i, j, x, z, row, size, yaw, tint } | undefined

Cell (i, j)'s instance, its point in metres and its yaw in radians, or undefined when the cell is refused.

On the page

Through plugins.scatter3d.

solids( x, z, r ) : { x, z, radius, tall? }[]

The same as the rule's, over this page's land.

ready( ) : boolean

Whether every cell in reach of terrain3d's prepared place is placed. True with no place in hand.

packs( ) : { [name]: object }

Each built pack: at, the camera's cell; held, its cells; pending, the cells waiting to be placed; looks, its instanced meshes by "<row> <shell>"; models, each drawn row's LODs with its foot, edge, rise and lean; and ahead, the prepared place's cells.

cellKey( i, j ) : number

The key a cell is held under in held.

#Mods

Name them in world.scatter3d.mods.

• terrain3d
  ground on the server and land on the page: the height, the painted cover, the record ramps and what has changed. List terrain3d before scatter3d.
• box3dvehicle
  hollows: a car's body and wheels, so grass it stands in is not drawn through it.

#Used by

• terrain3d
  Waits for scatter3d's ready before a prepared place is done.
• cover3d
  Finds cover behind its solid instances.
• walker
  Walks bodies round its solid instances.
• hitscan3d
  Stops shots at its solid instances, up to their tall.

#In the guide