voxelarea documentation problems

VoxelArea.adoc

VoxelArea

The VoxelArea metatable¹ provides an OOP-like² utility³ for dealing with LuaVoxelManip⁴ (specifically, for doing the index math⁵).

---

¹ Beginners are not likely to know what a metatable even is. The information is superfluous anyway.

² Beginners may not know what "OOP" means.

³ "Utility" is a bit technical, "helper" may be easier to understand.

⁴ "LuaVoxelManip" should probably be "the VoxelManip object" or similar.

⁵ "index math" is vague and unhelpful.

VoxelArea.new(self, o)¹

Sets self.__index to self and self as the metatable of o², which can have³ the following fields:

• MinEdge: Minimum position of the area, inclusive. Defaults to vector.new(1, 1, 1) if nil⁴.

• MaxEdge: Maximum position of the area, inclusive. Defaults to vector.new(0, 0, 0) if nil⁴.

Both positions should be vector`s of integer numbers; each component of `MinEdge should be smaller than the respective component of MaxEdge if the VoxelArea is to be non-empty. You can use minp, maxp = vector.sort(minp, maxp) to achieve this.

Calculates ystride and zstride⁵ and stores both in o%⁶.

Common usage:⁷

local voxelmanip = minetest.get_voxel_manip(pos_min, pos_max)
local emin, emax = voxelmanip:read_from_map(pos_min, pos_max)
local voxelarea = VoxelArea:new{ MinEdge = emin, MaxEdge = emax }

Warning

Always pass the actual emerged8 min9 &10 max9 positions. Do not pass the desired min &10 max positions11.

Warning

Never pass fractional values as min-12 or max edge.

Tip	You can use vector.floor, vector.round or vector.apply(vec, math.ceil) to guarantee integer values.

The following methods can both be called in an imperative manner¹³ (VoxelArea.<method>(self, …​)) or an OOP manner (recommended): self:<method>(…​). The below examples are documented using the latter style, where area is a valid table with VoxelArea as the metatable.¹⁴

---

¹ Documenting the internal representation of VoxelArea() is confusing and unnecesary, especially for beginners.

² We are documenting VoxelArea, not classes. It returns a new VoxelArea object, it’s as simple as that.

³ It will always have these fields.

⁴ Possibly superfluous.

⁵ What are ystride and zstride?

⁶ Again, referencing "o" is confusing and unnecessary.

⁷ Common syntax for those variables is usually vmanip and varea. Do we need to decide a policy on example variable naming? Also, literal-syntax should probably be avoided; It is only used because someone thought it was cute and no one bothered to change it.

⁸ Why would a beginner know what "emerged" means, especially without any context about VManip?

⁹ Use full "minimum" and "maximum".

¹⁰ Use "and".

¹¹ This is confusing.

¹² Inconsistent trailing dash.

¹³ Again, beginners may not know what imperative or OOP is. The only version we need to document is the supported syntax, which is OOP. Advanced users can extrapolate imperative usage if they wish.

¹⁴ If it’s recommended, just don’t bother with the imperative notes at all.

area:getExtent()

Returns the dimensions of area as integer vector¹.

---

¹ "Integer vector" is strange wording. Not sure how to improve. Also missing "an".

area:getVolume()

Returns the volume of area as integer¹.

---

¹ Missing "an".

area:index(x, y, z)

x, y, z are absolute coordinates of a node within the area. Returns an integer index to be used for data tables returned by VoxelManip objects.

Warning

This will silently floor the returned index instead of throwing an error. Make sure that the coordinates you pass are (1) not fractional and (2) within the area.

area:indexp(p)

Shorthand for area:index(p.x, p.y, p.z).

area:position(index)

Inverse to area:indexp. Returns the absolute node position corresponding to the index as a table with x, y and z fields.

Tip	The returned table is missing the vector metatable. If it is not performance-critical, use p = vector.new(area:position(index)) to create a copied vector with metatable.

area:contains(x, y, z)

Returns true if all x, y, z coordinates are between the respective MinEdge and MaxEdge coordinates, both inclusive.

area:containsp(p)

Shorthand for area:contains(p.x, p.y, p.z)

area:containsi(i)

Returns true if i is between 1 and the area volume, both inclusive.

Warning

area:containsi(area:indexp(p)) is not equivalent to area:containsp(p), as area:indexp will happily produce valid indices for some out-of-area positions.

area:iter(minx, miny, minz, maxx, maxy, maxz)

Returns an iterator (a function that returns the index of the current position and advances to the next one) that iterates in XYZ order (first incrementing X until the line has been finished, then Y until the plane has been finished, then Z until the cuboid has been finished).

area:iterp(minp, maxp)

Shorthand for area:iter(minp.x, minp.y, minp.z, maxp.x, maxp.y, maxp.z).

Example:¹

for index in area:iterp(pos_min, pos_max) do
	content_id_data[index] = ...
end

which is equivalent to (but shorter &² faster than):

for z = pos_min.z, pos_max.z do
	for y = pos_min.y, pos_max.y do
		for x = pos_min.x, pos_max.x do
			local index = area:index(x, y, z)
			content_id_data[index] = ...
		end
	end
end

---

¹ Do examples need to be runable? …​ is not likely valid out of context.

² Use "and".