djyarus / three-landscape

React-three-fiber compatible abstractions that make it easier to render high quality landscapes scenes

Three landscape

A growing collection of React-three-fiber compatible abstractions for rendering high quality, large scale landscapes scenes. I've been researching how AAA games render terrain and am replicating any browser compatible techniques here.

Note: this package is not capable of procedurally generating terrain. Height maps and other textures must be authored offline in programs such as WorldCreator or generated at run time with custom logic. This is something I'm interested in for its potential to reduce bundle sizes but is out of scope for this module.

Demo:

https://three-landscape.vercel.app/

Source code for example is available in the /examples/highland@latest directory

Installation

npm install three-landscape

Documentation

SplatStandardMaterial

Custom material that extends the meshStandardMaterial with additional properties for splat mapping. Splat mapping makes it possible to render terrains with much higher texture detail while reducing memory usage and bundle size: http://wiki.polycount.com/wiki/Splat

Can be used in vanilla (non react) Three.js projects by importing from the /three directory import SplatStandardMaterial from three-lanscape/three

supports:

• all the props & behaviors of meshStandardMaterial
• seamless tile blending (aka texture bombing)
• terrain and detail normal maps
• texture saturation and brightness filters for additional creative control

new props:

• splats*: [Texture] (expects splat data in rgb and a channels)
• normalMaps: [Texture]
• normalWeights: [float]
• diffuseMaps*: [Texture]
• scale*: [float] (size of terrain tiles)
• saturation: [float]
• brightness: [float]
• noise*: Texture

* required prop

function MySuperCoolTerrain() {
  const [displacement, normal, noise, d1, n1, d2, n2, d3, n3, d4, splat1, splat2] = useTexture([
    '/hd/heightmap.png',
    '/hd/normalmap.png',
    '/simplex-noise.png',
    '/Assets/Cliffs_02/Rock_DarkCrackyCliffs_col.jpg',
    '/Assets/Cliffs_02/Rock_DarkCrackyCliffs_norm.jpg',
    '/Assets/Rock_04/Rock_sobermanRockWall_col.jpg',
    '/Assets/Rock_04/Rock_sobermanRockWall_norm.jpg',
    '/Assets/Mud_03/Ground_WetBumpyMud_col.jpg',
    '/Assets/Mud_03/Ground_WetBumpyMud_norm.jpg',
    '/Assets/Grass_020/ground_Grass1_col.jpg',
    '/hd/splatmap_00.png',
    '/hd/splatmap_01.png'
  ])

  const { width, height } = displacement.image

  return (
    <mesh position={[0, 0, 0]} rotation={[-Math.PI / 2, 0, 0]}>
      <planeBufferGeometry args={[100, 100, width, height]} />
      <SplatStandardMaterial
        splats={[splat1, splat2]}
        normalMap={normal}
        normalMaps={[n1, n2, n3]} // note there are less normals than diffuse maps - normals are not required for each tile type
        diffuseMaps={[d1, d2, d3, d4, d4, d3]}
        scale={[128 / 4, 128 / 2, 128, 128 * 2, 128, 128, 10]}
        noise={noise}
        displacementMap={displacement}
        displacementScale={10}
        displacementBias={-10}
      />
    </mesh>
  )
}

See example directory for advanced usage and example textures but

Note: The textures are not covered by the MIT license and should not be used with out first acquiring the rights to do so.

---

useProgressiveTexture

Similar to useTexture from drie but progressively loads higher quality textures over time.

function Terrain(){
    const [quality, textures] = useProgressiveTextures([
      ['/heightmap.png','/normalmap.png'],
      ['/hd/heightmap.png','/hd/normalmap.png']
    ])

    const [displacement, normal] = textures[quality]
    return(
      <mesh>
        <planeBufferGeometry/>
        <meshStandardMaterial color="green" normalMap={normal} displacementMap={displacement} />
      </mesH>
    )
}

It is a texture loader that accepts an array of url arrays and returns: Array of texture batches and an int holding the index of the highest quality texture batch that has been downloaded.

All textures in a batch (['/hd/heightmap.png','/hd/[email protected]']) are resolved before moving on to the next highest quality level To get performance benefits, resource batches should be of ordered by ascending quality.

Note: as long as you serve a /basis_transcoder.js and /basis_transcoder.wasm useProgressiveTexture can also auto resolve highly compressed basis textures. See the BasisTextureLoader and Basisu project for more details: https://github.com/BinomialLLC/basis_universal

Roadmap:

Thought it might be fun to let people vote on new feature ideas! If you're interested in a particular feature leave a thumbs up on the assosiated issue:

view issues sorted by most votes

Contributing

In lieu of a formal style guide, take care to maintain the existing coding style. Please Lint and test your code before submitting.

License

MIT License does not apply to any of the image files in the examples directory