Add clarity for query.bone_orientation_matrix and TRS

[johnb003]

Describe the missing content

• (MOST IMPORTANT) We cannot use the bone_orientation_matrix because there's no documentation about returning a matrix type from Molang. Can you somehow get vector types and do Matrix x Vector operations? Can a Matrix x Struct that looks like a vector work? If the result is still a native Vector type from that I can't see how to access it as a struct? Or can the matrix components be accessed directly? Are there struct names to get each component of the matrix?
• When querying a bone from a hierarchy it's important to know if it's local (relative to the parent), relative to the entity / character frame, or relative to the world. I have discovered experimentally it's relative to the entity (TRS)
• Can we inverse the TRS or Matrix types?
• Is X flipped in entities? It appears to be in blockbench.

Vanilla usage example I'm surprised the bone_orientation_matrix went from experimental to public, as I can't find any example of anyone successfully using it.

By the way the matrix form would be WAY easier to use, because you could transform a point by a few dot products rather than having to compute sin/cos trig on 3 different axes hopefully applying them in the right order to apply the TRS.

Additional context It'd be great if people could learn about the transform stack here: bone_anim.position bone_geo.pivot bone_anim.rotation bone_geo.rotation bone_geo.pivot_inverse * bone_anim.scale

where each rotation is a concatenation of 3 Euler rotations in the order rotateX, rotateY, rotateZ (as the order a vector would be transformed), but alas, you might want to clarify how transforms written in column major order are like: Z Y X * v.

Caveat that in my example with the pivots, I think bone_anim.rotation and bone_geo.rotation are additive. As such they're more like: a.rotate.z b.rotate.z a.rotate.y b.rotate.y a.rotate.x * b.rotate.x

Also, the "this" argument in the case of the rotation would actually represent BOTH the geo rotation and the bone rotation.

To simply transform a point (from a bone space) by a TRS to the ent space, one would have to do:

// T Rz Ry Rx S * v // v transforms through this transform stack right to left: // I wrote this math thinking it was right-handed, and I've flipped all the angles to make it left handed. (Because I noticed it's left handed in blockbench).

// The following code has only been tested in the block bench "list variables you want to preview" as a fake pre_animation. There are limitations in blockbench that do no properly handle the syntax so it was really picky and I couldn't reuse variables.

t.point.x = -20; t.point.y = 1; t.point.z = 20;

t.translatex = slider('translate x') t.translatey = slider('translate y') t.translatez = slider('translate z') t.rotx = slider('rot x angle') t.roty = slider('rot y angle') t.rotz = slider('rot z angle') t.scalex = slider('scale x', 0.01) t.scaley = slider('scale y', 0.01) t.scalez = slider('scale z', 0.01)

t.point2.x = t.point.x t.scalex t.point2.y = t.point.y t.scaley t.point2.z = t.point.z * t.scalez

t.cosanglex=math.cos(-t.rotx); t.sinanglex=math.sin(-t.rotx); t.point3.x = t.point2.x; t.point3.y = t.cosanglex t.point2.y - t.sinanglex t.point2.z; t.point3.z = t.sinanglex t.point2.y + t.cosanglex t.point2.z;

t.cosangley=math.cos(-t.roty); t.sinangley=math.sin(-t.roty); t.point4.x = t.cosangley t.point3.x - t.sinangley t.point3.z; t.point4.y = t.point3.y; t.point4.z = t.sinangley t.point3.x + t.cosangley t.point3.z;

t.cosanglez=math.cos(-t.rotz); t.sinanglez=math.sin(-t.rotz); t.point5.x = t.cosanglez t.point4.x - t.sinanglez t.point4.y; t.point5.y = t.sinanglez t.point4.x + t.cosanglez t.point4.y; t.point5.z = t.point4.z;

t.point6.x = t.point5.x + t.translatex t.point6.y = t.point5.y + t.translatey t.point6.z = t.point5.z + t.translatez

If matrices with operators worked, here's how it would look

t.in_point.x = -20; t.in_point.y = 1; t.in_point.z = 20;

// with ideal structure promotion to vectors, and the ability to invoke Matrix Vector multiply, it'd be: t.parent_mat = q.bone_orientation_matrix('parent') t.out_point = v.parent_mat t.in_point

// then you would need to be able to promote the vector to structure access: t.out_point.x t.out_point.y t.out_point.z

If matrices without operators, it's still way better

t.in_point.x = -20; t.in_point.y = 1; t.in_point.z = 20;

t.parent_mat = q.bone_orientation_matrix('parent')

// w/ math.dot and access to vectors: t.out_point.x = math.dot(t.parent_mat.x_axis, t.in_point) t.out_point.y = math.dot(t.parent_mat.y_axis, t.in_point) t.out_point.z = math.dot(t.parent_mat.z_axis, t.in_point)

• Finally, even if we had nothing new but at least a way to access the matrices m[0..15], it's still be cleaner than the first option, but I'll leave that as a final exercise to you.
• After having said all of that, recall there's a lot of info that could be provided from this, but the most important is how to even access the matrix from the existing API call.

Thank you!

[AragornDaoZhen]

Thank you so much for sharing. I'm also trying to use this molang, but I don't know how to use it, and I get an error.

If I want to use rightItem bone, I should write bone_orientation_matrix(rightItem)? or bone_orientation_matrix(...rightArm/rightItem)?

[tryashtar]

We also need documentation about what "queryable geometry" is