npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

threejs-scatter

v0.1.0

Published

Streams instanced objects (trees, rocks, plants) over terrain in tiles: blue-noise placement, LODs and impostors

Readme

threejs-scatter

Streams instanced objects (trees, rocks, shrubs, anything) over terrain in camera-centred tiles, for three.js and react-three-fiber. Placement is seamless blue noise filtered by density, slope, height and clumping noise, so the world is a pure function of seed and position. Each layer and level of detail is one pooled instanced mesh (one per material group when material is an array, sharing the instance buffers), so draw calls don't grow with the number of tiles. Far away, octahedral impostors stand in for the meshes.

Part of threejs-worldgen. For generated trees, plants and rocks to scatter, see threejs-trees.

npm i threejs-scatter three
# for React:
npm i @react-three/fiber react

three.js

import * as THREE from 'three/webgpu'
import { materialColor } from 'three/tsl'
import { Scatter, bakeImpostor, scatterParamsNode } from 'threejs-scatter'

const renderer = new THREE.WebGPURenderer({ antialias: true })
await renderer.init()

const rockMaterial = new THREE.MeshStandardNodeMaterial({ color: '#777' })
rockMaterial.colorNode = materialColor.mul(scatterParamsNode().y) // colorVariation tint (1 off-scatter)
const rock = new THREE.Mesh(new THREE.DodecahedronGeometry(1), rockMaterial)
const impostor = await bakeImpostor(renderer, rock, { frames: 8, size: 512 })

const scatter = Scatter.create({
  camera, scene, terrain: (x, z) => myHeight(x, z), // or a terrain Mesh (baked into a heightfield once)
  seed: 7,
  layers: [{
    name: 'boulder',
    spacing: 12,                                  // Poisson-disk radius, metres
    density: (x, z) => myBiomes.rockiness(x, z),  // 0..1 keep probability (or a number)
    maxSlope: 1.5, align: 1, sink: 0.3, scale: [0.6, 2], tilt: 0.2, colorVariation: 0.15,
    cluster: { scale: 80, threshold: 0.5, strength: 0.8 }, // patches and clearings
    lods: [{ distance: 120, geometry: rock.geometry, material: rock.material }],
    impostor: { distance: 600, geometry: impostor.geometry, material: impostor.material, castShadow: false },
  }],
})
// With `scene` given it updates itself whenever the scene renders; otherwise call scatter.update() once per frame.

scatter.query(x, z, 5)        // instances near a point, deterministic, for gameplay / collision
scatter.set({ maxDistance: 400 }) // runtime changes; only what changed is rebuilt

React Three Fiber

import { Scatter } from 'threejs-scatter/react'

<mesh ref={ground} geometry={hills} />
<Scatter terrain={ground} seed={7} layers={[{ name: 'boulder', spacing: 12, lods: [{ distance: 150, geometry, material }] }]} />

Props are the options; the camera defaults to the R3F camera, terrain takes a mesh, a ref to one or a height function, and ref gives you the ScatterImpl instance (for query and stats).

Options

Scatter.create(options) / set(partial) / reset(full) / <Scatter {...props}>:

| Option | Default | | |---|---|---| | camera | — | Camera tiles stream around (R3F: the default camera). | | scene | — | If given, the scatter adds itself and updates on scene.onBeforeRender. | | terrain | flat | Mesh / group (baked to a heightfield) or (x, z) => y. | | seed | 1 | World seed. | | tileSize | 64 | Tile edge, metres. | | maxDistance | 600 | Nothing beyond this (each layer also stops at its last LOD distance). | | buildBudget | 4 | Milliseconds per frame for generating tiles, nearest first. | | lodHysteresis | 0.1 | Fractional band an instance must cross to switch level. | | refreshDistance | 1 | Camera movement (m) that re-sorts instances into levels. | | layers | [] | ScatterLayer[], below. |

Layer fields (all but name have defaults):

| Field | Default | | |---|---|---| | name | — | Also seeds the layer's clumping noise. | | group | name | Layers in one group share a point set and never overlap; each point goes to one layer by its density. | | spacing | 4 | Minimum distance between instances (group: the first layer's). | | density | 1 | 0..1 keep probability, or (x, z) => number (e.g. a biome weight). | | minSlope / maxSlope | 0 / Infinity | Terrain slope range (rise / run). | | minHeight / maxHeight | ±Infinity | Terrain height range. | | cluster | null | { scale, threshold, strength } noise that clumps instances into patches. | | scale | [1, 1] | Uniform scale range. | | align | 0 | 0 = upright, 1 = follow the terrain normal. | | randomYaw | true | Random turn about the up axis. | | tilt | 0 | Max random lean, radians. | | sink | 0 | Metres pushed into the ground. | | colorVariation | 0 | Per-instance brightness in scatterParams.y; multiply scatterParamsNode().y into your colorNode (before any weather, so snow stays white). | | lods | [] | { distance, geometry, material, castShadow? }[], nearest first; material may be an array for geometry groups. | | impostor | null | Far level drawn after the meshes (from bakeImpostor). | | castShadow / receiveShadow | true | |

Everything is plain JSON except terrain, camera, scene, a function density, and the LOD geometries and materials.

Exports

| Export | | |---|---| | Scatter | The streamer: create, set, reset, update(budgetMs?), query, setTerrain, regenerate, dispose, .object, .stats. | | bakeImpostor(renderer, object, { mode, frames, size, hemisphere, alphaTest }) | Renders object from frames × frames octahedral directions (or one side view, mode: 'billboard') into colour + normal atlases and returns { texture, normalTexture, material, geometry, bounds, dispose }. The material is lit, alpha-tested and picks the nearest view in TSL. | | scatterParamsNode() | TSL vec4 per instance: yaw, brightness tint, random 0..1. Every pooled mesh carries it, so materials can vary per instance. | | placeTile, poissonDisk, clusterFactor, groupSeed, INSTANCE_STRIDE | The pure placement functions (usable in a worker). | | selectLod, octEncode, octDecode, frameDirection, directionToFrame | Pure LOD and octahedral math. | | disposeLayers(layers) | Frees every geometry, material and texture of a set of layers. | | hash, hashString, mulberry32, valueNoise2, fbm2 | Deterministic random helpers. |

Pools start at 1100 instances and double as needed. That keeps three.js on its vertex-attribute instancing path (a smaller pool would put its matrices in a uniform buffer that is reallocated when the pool grows). Replaced pools are dropped (and garbage-collected) rather than dispose()d, because their geometry buffers are shared with the layer.

Multi-material levels are split into single-material meshes. In a shadow pass three.js draws every object with one override material and keys its render object by object, so the groups of a material-array mesh would share one render object and rebuild it (and its GPU binding buffers) for every group, every frame.

How placement stays seamless: one jittered candidate per global grid cell (spacing / 2) with a hashed priority; a few elimination rounds keep candidates that beat every live neighbour within spacing. A candidate's fate after k rounds depends only on candidates within (2k + 1) · spacing, so each tile evaluates that margin and keeps its own points: tiles match exactly whatever order they are built in.

Imports from three/webgpu (WebGPURenderer; falls back to WebGL2 by itself). Full API docs: https://askalice.github.io/threejs-worldgen/docs/.

License

Apache-2.0