MineClone2/mods/MAPGEN/vl_terraforming/API.md

vl_terraforming -- Terraforming module

Terraforming module built with VoxeLibre and MineClonia in mind, but also useful for other games.

This module provides the following key functionalities:

• given a position, find the ground surface
• given a position and size, find a balanced height (trimmed median height)
• build a baseplate for a building
• clear the area above a building

All methods have a _vm version to work with Lua Voxel Manipulators

Rounded corners support

To get nicer looking baseplates, the code supports rounded corners.

These are obtained by intersecting the square with an ellipse. At zero rounding, we want the line go through the corner, at sx/2, sz/2.

For this, we need to make ellipse sized 2a=\sqrt{2} sx, 2b=\sqrt{2} sz, Which yields a = sx/\sqrt{2}, b=sz/\sqrt{2} and a^2=0.5 sx^2, b^2=0.5 sz^2 To get corners, we decrease a and b by the corners parameter each The ellipse condition dx^2/a^2+dz^2/b^2 \leq 1 then yields dx^2/(0.5 sx^2) + dz^2/(0.5 sz^2) \leq 1 We use wx2=2 sx^-2, wz2=2 sz^-2 and then dx^2 wx2 + dz^2 wz2 \leq 1.

vl_terraforming.find_ground(pos)

Find ground starting at the given position. When in a solid area, moves up; otherwise searches downwards.

This will ignore trees, mushrooms, and similar surface decorations.

vl_terraforming.find_under_air(pos)

Find ground or liquid surface, starting at the given position. When in a solid or liquid area, moves up; otherwise searches downwards.

This will ignore trees, mushrooms, and similar surface decorations.

vl_terraforming.find_liquid_surface(pos)

Find a liquid surface starting at the given position. When in a solid or liquid area, moves up; otherwise searches downwards.

This will ignore trees, mushrooms, and similar surface decorations.

vl_terraforming.find_under_water_surface(pos)

Find a solid surface covered by water starting at the given position. When in a solid area, moves up; otherwise searches downwards.

This will ignore trees, mushrooms, and similar surface decorations.

vl_terraforming.find_level(cpos, size, tolerance, surface, mode)

Find "level" (sufficiently even) ground for a structure, centered at the given position, and of the given size.

For this, five samples are taken: center, top left, top right, bottom left, and bottom right.

One of these values may be "extreme", and tolerance specifies the maximum height difference of the remaining four values.

The surface can be set to:

• "solid" (default, i.e., solid under air)
• "liquid" (liquid under air)
• "under_air" (both liquid and solid surfaces)
• "under_water" (solid under water)

The mode can be set to:

• "median" (default, use the median height, rounded)
• "min" (use the lowest support coordinate)
• "max" (use the highest support coordinate)

vl_terraforming.foundation(px, py, pz, sx, sy, sz, corners, surface_mat, platform_mat, stone_mat, dust_mat, pr)

The position (px, py, pz) and the size (sx, sy, sz) give the volume of the main base plate, where sy < 0, so that you can later place the structure at (px, py, pz).

The baseplate will be grown by 1 in the level below, to allow mobs to enter, then randomly fade away below. The negative depth sy can be used to control a minimum depth.

Corners specifies how much to cut the corners, use 0 for a square baseplate.

The materials specified (as lua nodes, to have param2 coloring support) are used a follows:

• surface_mat for surface nodes
• platform_mat below surface nodes
• stone_mat randomly used below platform_mat
• dust_mat on top of surface nodes (snow cover, optional)

pr is a PcgRandom random generator

vl_terraforming.clearance(px, py, pz, sx, sy, sz, corners, surface_mat, dust_mat, pr)

The position (px, py, pz) and the size (sx, sy, sz) give the volume overhead to clear.

The area will be grown by 1 above, to allow mobs to enter, then randomly fade away as height increases beyond sy.

corners specifies how much to cut the corners, use 0 for a square area.

surface_mat is the node used to turn nodes into surface nodes when widening the area. If set, the dust_mat will be sprinkled on top.

pr is a PcgRandom random generator

TODO

• make even more configurable
• add ceiling placement
• add an API that works on VM buffers
• benchmark when VM is faster than not using VM (5.9 has some optimizations not yet in VM)
• improve tree removal