Procedural
Deterministic noise, chunk streaming and terrain generation helpers for procedural worlds.
Namespace: caffeine.procedural
hash#
Lua: caffeine.procedural.hash
hash(x, z, seed, salt) -> number
Deterministic hash of a cell, seed and salt.
| Parameters | Type | Description |
|---|---|---|
x | number | Integer X. |
z | number | Integer Z. |
seed | number | Seed. |
salt | number | Extra salt. |
Returns: number. Hash value (named hash01 in the engine).
Example
local r = caffeine.procedural.hash(3, 4, 42, 0)
noise2d#
Lua: caffeine.procedural.noise2d
noise2d(x, z, seed) -> number
2D value noise.
| Parameters | Type | Description |
|---|---|---|
x | number | X coordinate. |
z | number | Z coordinate. |
seed | number | Seed. |
Returns: number. Noise value.
Example
local n = caffeine.procedural.noise2d(1.5, 2.5, 42)
fbm2d#
Lua: caffeine.procedural.fbm2d
fbm2d(x, z, seed, octaves, lacunarity, persistence) -> number
2D fractal Brownian motion noise.
| Parameters | Type | Description |
|---|---|---|
x | number | X coordinate. |
z | number | Z coordinate. |
seed | number | Seed. |
octaves | number | Octave count. |
lacunarity | number | Frequency multiplier per octave. |
persistence | number | Amplitude multiplier per octave. |
Returns: number. Noise value.
Example
local h = caffeine.procedural.fbm2d(x * 0.02, z * 0.02, 42, 5, 2.0, 0.5)
worldToChunk#
Lua: caffeine.procedural.worldToChunk
worldToChunk(worldCoord, chunkSize) -> number
Converts a world coordinate to a chunk index.
| Parameters | Type | Description |
|---|---|---|
worldCoord | number | World coordinate. |
chunkSize | number | Chunk size in world units. |
Returns: number. Chunk index.
Example
local cx = caffeine.procedural.worldToChunk(pos.x, 64)
findTerrain#
Lua: caffeine.procedural.findTerrain
findTerrain() -> number
Finds the terrain entity.
Returns: number. Terrain entity id, or 0 if none.
Example
local t = caffeine.procedural.findTerrain()
getFocusChunk#
Lua: caffeine.procedural.getFocusChunk
getFocusChunk(directorId, chunkSize, focusId) -> table
Returns the chunk the focus entity is in.
| Parameters | Type | Description |
|---|---|---|
directorId | number | Entity id of the procedural world director. |
chunkSize | number | Chunk size, used if the director has no procedural settings. |
focusId | number | Focus entity id. Optional. |
Returns: table. Table with cx and cz (0, 0 if unavailable).
Example
local c = caffeine.procedural.getFocusChunk(dir, 64, player)
print(c.cx, c.cz)
isChunkLoaded#
Lua: caffeine.procedural.isChunkLoaded
isChunkLoaded(directorId, cx, cz) -> boolean
Checks whether a chunk is loaded for the director.
| Parameters | Type | Description |
|---|---|---|
directorId | number | Entity id of the procedural world director. |
cx | number | Chunk X index. |
cz | number | Chunk Z index. |
Returns: boolean. true if the chunk is loaded.
Example
print(caffeine.procedural.isChunkLoaded(dir, 0, 0))
unloadChunk#
Lua: caffeine.procedural.unloadChunk
unloadChunk(directorId, cx, cz)
Unloads a chunk of the director.
| Parameters | Type | Description |
|---|---|---|
directorId | number | Entity id of the procedural world director. |
cx | number | Chunk X index. |
cz | number | Chunk Z index. |
Returns: none
Example
caffeine.procedural.unloadChunk(dir, 0, 0)
stream#
Lua: caffeine.procedural.stream
stream(directorId, terrainId, cx, cz, preset)
Streams chunks around the given chunk, adding procedural settings to the director if needed.
| Parameters | Type | Description |
|---|---|---|
directorId | number | Entity id of the procedural world director. |
terrainId | number | Terrain entity id. Optional. |
cx | number | Chunk X index. |
cz | number | Chunk Z index. |
preset | string | Preset name. Optional. |
Returns: none
Example
caffeine.procedural.stream(dir, caffeine.procedural.findTerrain(), 0, 0)
generateTerrainChunk#
Lua: caffeine.procedural.generateTerrainChunk
generateTerrainChunk(terrainId, cx, cz, seed, preset)
Generates one terrain chunk.
| Parameters | Type | Description |
|---|---|---|
terrainId | number | Terrain entity id. |
cx | number | Chunk X index. |
cz | number | Chunk Z index. |
seed | number | Seed. |
preset | string | Preset name. Optional. |
Returns: none
Example
caffeine.procedural.generateTerrainChunk(terrain, 0, 0, 42)
spawnCube#
Lua: caffeine.procedural.spawnCube
spawnCube(directorId, cx, cz, x, y, z, sx, sy, sz) -> number
Spawns a cube entity tagged with the director and chunk.
| Parameters | Type | Description |
|---|---|---|
directorId | number | Entity id of the procedural world director. |
cx | number | Chunk X index. |
cz | number | Chunk Z index. |
x | number | World X. |
y | number | World Y. |
z | number | World Z. |
sx | number | Scale X. |
sy | number | Scale Y. |
sz | number | Scale Z. |
Returns: number. Id of the new entity, or 0 if no world.
Example
local c = caffeine.procedural.spawnCube(dir, 0, 0, 1, 0.5, 1, 1, 1, 1)
fillTerrainNoise#
Lua: caffeine.procedural.fillTerrainNoise
fillTerrainNoise(terrainId, seed, amplitude)
Fills the terrain heightmap with fractal noise.
| Parameters | Type | Description |
|---|---|---|
terrainId | number | Terrain entity id. |
seed | number | Seed. |
amplitude | number | Height multiplier; results are clamped to 0..1. |
Returns: none
Example
caffeine.procedural.fillTerrainNoise(terrain, 42, 1.0)