Add a paramtype2 that applies a transformation matrix out of a predefined list

[sfan5]

Problem

Sometimes modders want to

• offset the rendered nodes
• or rotate them in ways that are not possible now
• or scale them without editing the boxes or source meshes

Solutions

Introduce the ability to specify arbitrary transformation matrices for nodes.
Allow specifying a list and have a paramtype2 that chooses between them.

This could look as follows:

-- these work on 4x4 matrics and are omitted for brevity
-- we should add proper matrix helpers when implementing this
function identity_matrix() end
function translation_matrix(x, y, z) end
function scale_matrix(x, y, z) end
function mat_mul(m1, m2) end

core.register_node("test:test", {
	paramtype2 = "transform",
	transformations = {
		identity_matrix(), -- 0
		translation_matrix(0, -0.5, 0), -- 1
		scale_matrix(0, 1.6, 0), -- 2
		mat_mul(scale_matrix(0, 1.6, 0), translation_matrix(0, -0.5, 0)), -- 3
	},
})

For people who want colors

We would add a paramtype2 = "colortransform", though how many bits to use is not clear.
Perhaps multiple variants:

paramtype2 = "color2transform" -- 0bTTTTTTCC
paramtype2 = "color4transform" -- 0bTTTTCCCC
paramtype2 = "color6transform" -- 0bTTCCCCCC

If this is considered too inflexible we would need to revive #11019 or wait for SSCSM to fix this (as always).

Implications on mesh building:

A simple and safe way that works for a start is to turn every node that uses this (particularly drawtype = "normal") into a "standalone" node (like allfaces).
We probably want to disallow it for (flowing)liquid.
Thinking further we could try to handle it more generally, so that mere 90° rotations do not cause duplicate faces.

Implications on culling and such:

Using this to make a node unreasonably larger or offset (e.g. move up by 32 nodes) should simply be declared unsupported.

Implications on raytracing:

Should work if you throw the math at it.
(however since we don't modify collision or selection boxes we won't need this?)

Implications on collision or selection boxes:

None.

Alternatives

this is literally the ideal api
(credit to @appgurueu for the original idea)

Additional context

this would obsolete/solve:

• Offset and/or rotation for instances of nodes with drawtype == "mesh" #15463
• Add scale paramtype2 for nodeboxes, meshes, and plantlike nodes equivalent to visual_scale #15497
• Add 'offsetfacedir' paramtype2 to allow more fine placement of “attached stuff” #12352
• Variable node visual scale with param2 #11469
• nodedef visual_scale (if we allow specifying a default transform)

In fact in the far future you could implement all of wallmounted, facedir, 4dir, degrotate using this and drop them.

[appgurueu]

we should add proper matrix helpers when implementing this

Agreed! Let's do that first and ideally separately. Should we:

1. Write a userdata wrapper around core::matrix4 (lets us reuse Irrlicht code (which sucks a bit) and be consistent with it) or
2. Implement 4x4 matrices in pure Lua (consistent with vector)

[sfan5]

I vote 2.
Doing that first is also a good idea because I don't want to be the one to implement this.

[kromka-chleba]

Implement 4x4 matrices in pure Lua (consistent with vector)

Cirno's perfect math library has 4x4 matrices but it is apparently unmaintained and you'd need to check if it works.
https://github.com/excessive/cpml

I also maintain a fork for my game which works in Luanti and has a converter for vec3 -> vector and vector -> vec3:
https://codeberg.org/perfect_city_game_studio/pcity_cpml

Though keep it mind it's a hack and I'm not really a math person so I can't really maintain this properly.

[appgurueu]

Cirno's perfect math library has 4x4 matrices but it is apparently unmaintained and you'd need to check if it works.

The code looks okay, though from a first glance I already see a couple issues:

• It, of course, lives in its own realm with its own conventions and vectors. Care needs to be taken especially with rotations.
• Some operations are poorly optimized: It unnecessarily multiplies with sparse matrices in a few places. ¹
• It implements a non-exact equals => equality isn't transitive, which is bad.

Footnotes

1. I would let it get away with this if things weren't (prematurely?) optimized (e.g. by manual unrolling of loops) throughout the rest of the file. ↩