Add matrix & rotation Lua APIs (2nd try) by appgurueu · Pull Request #16870 · luanti-org/luanti

appgurueu · 2026-01-21T22:18:52Z

This PR exposes userdata wrappers around Irrlicht 4x4 matrices and rotation quaternions. This is already useful as-is; I expect it to be even more useful once we eventually give proper control over client rendering to modders via SSCSM.

Closes #7478, closes #15985.

How to test

Unit tests are included; the bindings should work as expected. Testing more error cases (e.g. wrong types) could be considered.

Follow up

After this is merged, functions that take rotations (e.g. bone overrides, entity rotations) should be updated to accept Rotation objects. There should perhaps be new getters that produce Rotation objects.

To discuss

This PR is Ready for Review.

I am grateful for @grorp's and everyone else's comments on the last PR. I think I have dealt with everything decently here.

Supersedes #16212. (I wanted to reopen that PR, but it turns out funny things happen once you rebase and force push.)

Full disclosure: I did experiment with GitHub copilot in the making of this PR since it is quite a chore-y job of writing bindings. It was quite underwhelming though, so I ended up writing most of it by hand still.

doc/lua_api.md

src/script/lua_api/l_matrix4.cpp

src/script/lua_api/l_rotation.cpp

appgurueu · 2026-02-02T23:40:28Z

Thanks for the review! I'll address it soon.

Another thing that came to my mind, I'll want a rotation constructor similar to vector.dir_to_rotation(direction[, up]), aka "look at".

Currently considering a Rotation.mapsto(dir_in, dir_out) that would give you a rotation that maps dir_in to dir_out, rotating only vectors in the plane spanned by the two directions.

I should probably also add some devtest test entities that make use of these APIs to prove visually that everything works out in the end.

- Rename "all" to "full" - Move reflection constructor implementation to matrix4.h - Fix up and reword docs a bit

appgurueu · 2026-02-05T11:20:00Z

I've now addressed the review, so now I'm waiting on further replies / comments, and maybe will implement the additional Rotation.mapsto and visual devtest tests in the meantime (though they are not strictly necessary for this PR).

src/script/common/helper.cpp

appgurueu · 2026-02-07T14:43:47Z

Okay, about non-finite floats:

For rotations, it's clear that we don't want them. We effectively have as invariant that we want a normalized quaternion (a well-defined rotation), and that only works with finite floats. So I don't permit them there.

For matrices, we can allow them, and most operations (e.g. applying matrices to vectors, matrix multiplication, etc.) are still well-defined. In fact it is possible to get matrices with infinities through matrix multiplication if things go out of range. It's also possible to put in large doubles which get cast to inf floats.
So I would prefer not to outright ban them.

Thoughts? Scream if you think this is a problem.

appgurueu · 2026-02-07T14:45:51Z

Two meta-thoughts:

Do we mark this experimental?
Do we put it on the 5.17 milestone?

Desour

Sorry, idk why I haven't left any comments on this yet, for 8? months. Must have forgotten.

Only some inputs on doc for now (hopefully not too annoying).

Desour · 2026-02-07T20:09:54Z

doc/lua_api.md

 * `vector.cross(v1, v2)`:
-    * Returns the cross product of `v1` and `v2`.
+    * Returns the *right-handed* cross product of `v1` and `v2`.
+    * To get the left-handed cross product
+      (e.g. for use with rotations), swap `v1` and `v2`.


cross((1,0,0), (0,1,0)) is (0,0,1).
In a right-handed coord system this is right-handed.
But luanti worlds use a left-handed coord system, so it's left-handed.

Doc needs to be clear. Just saying "right-handed" is ambiguous.

Desour · 2026-02-07T20:12:23Z

doc/lua_api.md

+The precision of the implementation may change (improve) in the future.
+Rotations currently use 32-bit floats (*less* precision than the Lua number type).
+
+Rotations use **left-handed** conventions.


Desour · 2026-02-07T20:16:30Z

doc/lua_api.md

+Rotations currently use 32-bit floats (*less* precision than the Lua number type).
+
+Rotations use **left-handed** conventions.
+


Suggested change

In the current implementation, Rotations are just an abstraction over quaternions.

Would be helpful info (and grep endpoint) imo for users who want to use quaternions.

Desour · 2026-02-07T20:18:41Z

doc/lua_api.md

+  * This is consistent with the Euler angles that can be used for entities.
+    You can do `Rotation.euler_zxy((-rotation):unpack())`
+    to convert an entity rotation vector (note the handedness conversion).
+* `Rotation.mapsto(dir_from, dir_to)`:


Sound like a function that returns a bool.
Would prefer mappingto or similar.

Also, why no snake case? maps_to

Desour · 2026-02-07T20:23:58Z

doc/lua_api.md

+* `Rotation.identity()`: Constructs a no-op rotation.
+* `Rotation.quaternion(x, y, z, w)`:
+  Constructs a rotation from a quaternion (which need not be normalized).
+* `Rotation.axis_angle(axis, angle)`:


(

Also here, sounds like it's measuring the axis of an angle (yes this makes no sense, but that's how I read x), the thinking comes afterwards).
from_axis_angle would be more clear.

Similar for other ctors.

Well, I guess one can get accustomed to this kind of naming.

)

Desour · 2026-02-07T20:54:47Z

doc/lua_api.md

+========
+
+Luanti uses 4x4 matrices to represent linear transformations of 3D vectors.
+For this, 3D vectors are embedded into 4D space.


into 3D projective space using homogeneous coordinates.

Desour · 2026-02-07T21:07:50Z

doc/lua_api.md

+* `mat:compose(...)`: Shorthand for `Matrix4.compose(mat, ...)`.
+* `mat:determinant()`: Returns the determinant.
+* `mat:invert()`: Returns a newly created inverse, or `nil` if the matrix is (close to being) singular.
+* `mat:transpose()`: Returns a transposed copy of the matrix.


(

Would like to also have the adjucate (adj) (essentially a cheaper but scaled inverse). (And combination of adj and transposed.)
(Probably will only get relevant once we have 4d vectors though.)
(Could also have even more ctors then, i.e. for projection matrices.)

)

Desour · 2026-02-07T21:14:34Z

doc/lua_api.md

+* `mat:is_affine_transform([tolerance = 0])`:
+  Whether the matrix is an affine transformation in 3d space,
+  meaning it is a 3d linear transformation plus a translation.
+  (This is the case if the last column is approximately 0, 0, 0, 1.)


Suggested change

(This is the case if the last column is approximately 0, 0, 0, 1.)

(This is the case if the last row is approximately 0, 0, 0, 1.)

(Also, technically you can also have affine transformations with other last rows (0,0,0,a), but you have to divide by the w component (by a) when dehomogenizing (equivalent: divide the whole matrix by a). But idk if doc formulation could include this easily, or should.)

Desour · 2026-02-07T21:18:10Z

doc/lua_api.md

+let `mat = Matrix4.compose(Matrix4.translation(t), Matrix4.rotation(r), Matrix4.scale(s))`.
+Then we can decompose `mat` further. Note that `mat` must not shear or reflect.
+
+* `rotation, scale = mat:get_rs()`:


When reading mat:get_rs() somewhere, I wouldn't know what it means. Is it that common that it needs such a short name?
get_rot_scale?

TRS is a common thing, but I'm not sure if RS is clear to people

I will give this a longer name.

Desour · 2026-02-07T21:21:04Z

doc/lua_api.md

+  meaning it is a 3d linear transformation plus a translation.
+  (This is the case if the last column is approximately 0, 0, 0, 1.)
+
+For working with affine transforms, the following methods are available:


What if not, methods will still exist, right? UB? Or unspecified result? (I.e. may it crash?)

appgurueu · 2026-02-07T23:38:39Z

Sorry, idk why I haven't left any comments on this yet, for 8? months. Must have forgotten.
Only some inputs on doc for now (hopefully not too annoying).

No worries, I appreciate the review; there's no rush. I'll address it in a bit.

SmallJoker · 2026-02-15T18:15:12Z

doc/lua_api.md

+  * `mat:transform_pos(pos)`:
+    * Apply the matrix to a vector representing a position.
+    * Applies the transformation as if w = 1 and discards the resulting w component.


So ... does this effectively do M * T(v.append(1)) where T means transposing?

If you take v.append(1) to be the row vector (x, y, z, 1), and then discard the w component: Yes.

appgurueu added @ Script API Feature ✨ PRs that add or enhance a feature labels Jan 21, 2026

appgurueu mentioned this pull request Jan 21, 2026

Add matrix & rotation Lua APIs #16212

Closed

sfan5 reviewed Jan 27, 2026

View reviewed changes

appgurueu added the Action / change needed Code still needs changes (PR) / more information requested (Issues) label Feb 2, 2026

appgurueu added 24 commits February 4, 2026 15:57

matrix4.h: Extract & expose determinant

4511658

WIP matrix & rotation lua APIs

1bbf0a9

Polish

5cd05c5

improve some things

f5f5e0b

fix & bustitute

520562e

more stuff

2b53ad8

update .luacheckrc

7008ad7

.

9f3a7d2

or not

1cee968

envs

a91aab0

Document that matrix composition is RTL

c1f81f4

Improve :compose documentation

fc78638

Improve docs

a80ffcb

Rename rotation euler angle functions to euler_xyz

7aff109

- Use typical conventions (column vectors)

6f10600

- Rename "all" to "full" - Move reflection constructor implementation to matrix4.h - Fix up and reword docs a bit

Add Matrix4.trs

dde62da

Discourage use of vector rotation methods

ed83284

Abbreviations

b40dd9e

Add vector.unpack

69ea311

Add Rotation.euler_zxy_rh constructor

4f74d23

fixup abbr

fffe3b3

test and fix

305d6fa

Add euler_zxy conversions

6ede96a

remove redundant-ish test

b36db6f

appgurueu added 4 commits February 4, 2026 15:57

.luacheckrc

545bfd2

Update docs

3db0766

Euler

8110803

...

f42c657

appgurueu force-pushed the feat/matrix4 branch from 000ddbd to 215d4e8 Compare February 4, 2026 14:58

minor stuff

caba0fa

appgurueu force-pushed the feat/matrix4 branch from 215d4e8 to caba0fa Compare February 4, 2026 22:58

appgurueu added 3 commits February 5, 2026 00:07

scope luacheck global decls to unittests

63af28a

.

2fad015

.

808793e

appgurueu removed the Action / change needed Code still needs changes (PR) / more information requested (Issues) label Feb 4, 2026

sfan5 reviewed Feb 5, 2026

View reviewed changes

src/script/common/helper.cpp Outdated Show resolved Hide resolved

sfan5 reviewed Feb 5, 2026

View reviewed changes

src/script/common/helper.cpp Outdated Show resolved Hide resolved

appgurueu added 3 commits February 5, 2026 20:35

move matrix & quaternion operator << to irrlicht_changes/printing.h

4828bd5

precision

e2378fb

details

6cc50b2

rawr

bbc1da8

Add Rotation.mapsto

2db2bc4

Desour reviewed Feb 7, 2026

View reviewed changes

ryvnf mentioned this pull request Feb 13, 2026

Add vector2 lua API for 2D vectors #16929

Open

4 tasks

SmallJoker reviewed Feb 15, 2026

View reviewed changes

		Rotations currently use 32-bit floats (less precision than the Lua number type).

		Rotations use left-handed conventions.



	In the current implementation, Rotations are just an abstraction over quaternions.

	(This is the case if the last column is approximately 0, 0, 0, 1.)
	(This is the case if the last row is approximately 0, 0, 0, 1.)

Conversation

appgurueu commented Jan 21, 2026

How to test

Follow up

To discuss

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

appgurueu commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

appgurueu commented Feb 5, 2026

Uh oh!

Uh oh!

Uh oh!

appgurueu commented Feb 7, 2026

Uh oh!

appgurueu commented Feb 7, 2026

Uh oh!

Desour left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

appgurueu commented Feb 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

appgurueu Feb 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

appgurueu commented Feb 2, 2026 •

edited

Loading

appgurueu Feb 15, 2026 •

edited

Loading