BiomeGeneration

BiomeGeneration

Module for generating biomes in Minecraft worlds.

The typical workflow is:

1. Create a dimension object (e.g. Overworld, Nether, End) -> Dimension
2. Set the seed of the dimension -> setseed!
3. Get the biome at a specific coordinate -> getbiome

Or:

1. Create a world object -> WorldMap
2. Generate the biomes in the world -> genbiomes!

The biomes are stored in a WorldMap object, which is a 3D array of biomes. To get the coordinates of the biomes, use the coordinates function. It gives an iterator of CartesianIndex objects, a built-in Julia type. So any intuitive indexing should work out of the box.

Dimension{Version}

The parent type of every Minecraft dimension. There is generally three steps to use a dimension:

1. Create one dimension with a specific MCVersion and maybe some specific arguments.
2. Set the seed of the dimension with setseed!.
3. Do whatever you want with the dimension: get biomes, generate biomes, etc.

Examples

julia> overworld = Overworld(undef, mcv"1.18");

julia> setseed!(overworld, 42)

julia> getbiome(overworld, 0, 0, 63)
dark_forest::Biome = 0x1d

julia> setseed!(overworld, "I love cats")

julia> world = WorldMap(x=-100:100, z=-100:100, y=63);

julia> genbiomes!(overworld, world, scale=📏"1:4")

See also:

• Nether, Overworld, End
• setseed!, getbiome, genbiomes!
• WorldMap, Scale
• [MCVersion]
• threading

Extended help

End(::UndefInitializer, version::MCVersion)

The Minecraft End dimension.

Nether(::UndefInitializer, V::MCVersion)

The Nether dimension. See Dimension for general usage.

Minecraft version <1.16

Before version 1.16, the Nether is only composed of nether wastes. Nothing else.

Minecraft version >= 1.16 specificities

• If the 1:1 scale will never be used, adding sha=Val(false) to setseed! will save a very small amount of time (of the order of 100ns up to 1µs). The sha is a precomputed value only used for the 1:1 scale. But the default behavior is to compute the sha at each seed change for simplicity.

• In the biome generation functions, a last paramter confidence can be passed. It is a performance-related parameter between 0 and 1. A bit the same as the scale parameter, but it is a continuous value, and the scale is not modified.

Overworld(::UndefInitializer, ::mcvt">=1.18")

The Overworld dimension. See Dimension for general usage.

Minecraft version >= 1.18 specificities

• If the 1:1 scale will never be used, adding sha=Val(false) to setseed! will save a very small amount of time (of the order of 100ns up to 1µs). The sha is a precomputed value only used for the 1:1 scale. But the default behavior is to compute the sha at each seed change for simplicity.

• Two keyword arguments are added to the biome generation:

  • skip_depth=Val(false): if Val(true), the depth sampling is skipped. Time saved: 1/3 of the biome generation time.
  • skip_shift=Val(false): only for the 1:1 and 1:4 scales. If Val(true), the shift sampling is skipped. Time saved: 1/10 of the biome generation time.

Scale{N}
Scale(N::Integer)
📏"1:N"

The scale of a map. It represents the ratio between the size of the map an the real world. For example, a 1:4 scale map means that each block in the map represents a 4x4 area in the real world. So the coordinates (5, 5) are equal to the real world coordinates (20, 20).

N MUST ne to the form $4^n, n \geq 0$. So the more common scales are 1:1, 1:4, 1:16, 1:64, 1:256. The support for big scales is not guaranteed and depends on the function that uses it. Read the documentation of the function that uses it to know the supported values.

It is possible to use the alternative syntax 📏"1:N". The emoji name is :straight_ruler:.

Examples

julia> Scale(4)
Scale{4}()

julia> Scale(5)
ERROR: ArgumentError: The scale must be to the form 4^n. Got 1:5. The closest valid scales are 1:4 and 1:16.

julia> 📏"1:4" === Scale(4) === Scale{4}()
true

genbiomes!(dim::Dimension, world::WorldMap, scale=📏"1:1", threading=...; kwargs...) -> Nothing

Fill the world map with the biomes of the dimension dim. The args are specific to the dimension. See the documentation of the dimension for more information.

See also: WorldMap, Scale, Dimension, getbiome

getbiome(dim::Dimension, x::Real, z::Real, y::Real, scale=📏"1:1", args...; kwargs...) -> Biome
getbiome(dim::Dimension, coord, scale=📏"1:1", args...; kwargs...) -> Biome

Get the biome at the coordinates (x, z, y) in the dimension dim. The coordinates can be passed as numbers or as tuples or as CartesianIndex (the coords returned by coordinates).

The scale is defaulted to 1:1, i.e. the exact coordinates. The args are specific to the dimension. The y coord can be unnecessary sometimes, and so not passed. See the documentation of the dimension for more information.

See also: - Scale, genbiomes!, Dimension

setseed!(dim::Dimension, seed; kwargs...)

Set the seed of the dimension generator. It can be any valid seed you can pass like in Minecraft, but UInt64 is better if performance is a concern. To transform an UInt64 seed to a "normal" one, use signed(seed).

Other keyword arguments can be passed, specific to the dimension / minecraft version. They are often related to some micro-optimizations. See the documentation of the specific dimension for more information.

See also: Nether, Overworld, End

voronoi_access(sha::UInt64, coord::Union{CartesianIndex{3}, NTuple{3, T}}) where {T}
voronoi_access(sha::UInt64, x, z, y)

Compute the closest Voronoi cell based on the given coordinates (at 1:4 scale). Used by Minecraft to translate the 1:4 scale coordinates to the 1:1 scale.

For example we can find in some part of the biome generation source code:

julia> function getbiome(dimension, x, z, y, ::Scale{1})
           sx, sz, sy = voronoi_access(dimension, x, z, y)
           getbiome(dimension, sx, sz, sy, Scale(4))
       end

See also: voronoi_source

voronoi_source(ax::AbstractUnitRange)
voronoi_source(W::WorldMap{N}, dim::Val{D} = Val(N)) where {N, D}

Get the minimal map coordinates where we are sure to have all the Voronoi cells, i.e. we can find the source coordinates (can be computed with voronoi_access).

WorldMap{N} where N (N = 2, 3)
WorldMap(xrange::UnitRange, zrange::UnitRange, yrange::UnitRange)
WorldMap(xrange::UnitRange, zrange::UnitRange, y::Number)
WorldMap(xrange::UnitRange, zrange::UnitRange)
WorldMap(;x, z, y)

A 2D or 3D array of biomes. It is the main data structure used to store the biomes of a Minecraft world. It is a simple wrapper around AbstractArray{Biome, N}. So anything that works with arrays should work with WorldMap.

See also: view2d, coordinates

coordinates(M::WorldMap) -> CartesianIndices

Wrapper around CartesianIndices to get the coordinates of the biomes in the map. Useful to iterate over the coordinates of the map.

view2d(W::WorldMap{3}) -> WorldMap{2}

View a 3D world as a 2D world. Only works if the y size is 1. Otherwise, it throws an error. Useful for functions that only work with 2D worlds, even if the y size is 1, like 2d visualization.