Add coordinate axes gizmo

[mweatherley]

Objective

• We introduce a gizmo that displays coordinate axes relative to a Transform*, primarily for debugging purposes.
• See Tracking issue: Amazing Gizmos #9400

Solution

A new method, Gizmos::axes, takes a Transform* as input and displays the standard coordinate axes, transformed according to it; its signature looks like this:

pub fn axes(&mut self, transform: into TransformPoint, base_length: f32) { //... }

If my carefully placed asterisks hadn't already tipped you off, the argument here is not actually a Transform but instead anything which implements TransformPoint, which allows it to work also with GlobalTransform (and also Mat4 and Affine3A, if the user happens to be hand-rolling transformations in some way).

The base_length parameter is a scaling factor applied to the coordinate vectors before the transformation takes place; in other words, the caller can use this to help size the coordinate axes appropriately for the entity that they are attached to.

An example invocation of this method looks something like this:

fn draw_axes_system(
    mut gizmos: Gizmos,
    query: Query<&Transform, With<MyMarkerComponent>>,
) {
    for &transform in &query {
        gizmos.axes(transform, 2.);
    }
}

The result is the three coordinate axes, X, Y, Z (colored red, green, and blue, respectively), drawn onto the entity:

Note that, if scaling was applied as part of the given transformation, it shows up in scaling on the axes as well:

---

Changelog

• Added Gizmos::axes in bevy_gizmos/src/arrows.rs
• Fixed a minor issue with ArrowBuilder::with_tip_length not correctly implementing builder style (no external impact)

---

Discussion

Design considerations

I feel pretty strongly that having no default length scale is for the best, at least for the time being, since it's very easy for the length scale to be too small, leading to the axes being hidden inside the body of the object they are associated with. That is, if the API instead looked like this:

gizmos.axes(transform); // or
gizmos.axes(transform).with_length_scale(3.0);

then I think it's a reasonable expectation that the first thing would "just work" for most applications, and it wouldn't, which would be kind of a footgun.

Future steps

There are a few directions that this might expand in the future:

1. Introduce additional options via the standard builder pattern; i.e. introducing AxesBuilder<T: TransformPoint> so that people can configure the axis colors, normalize all axes to a fixed length independent of scale deformations, etc.

2. Fold this functionality into a plugin (like AabbGizmoPlugin) so that the functionality becomes more-or-less automatic based on certain fixed marker components. This wouldn't be very hard to implement, and it has the benefit of making the axes more frictionless to use. Furthermore, if we coupled this to the AABB functionality we already have, we could also ensure that the plugin automatically sizes the axes (by coupling their size to the dimensions of the AABB, for example).

3. Implement something similar for 2d. Honestly, I have no idea if this is desired/useful, but I could probably just implement it in this PR if that's the case.

[alice-i-cecile]

I'd prefer to have an example for this, but I'm fine to punt that to follow-up :) At some point higher-level gizmos may make more sense in bevy_dev_tools, but this is a good addition.

I really like your argument for forcing users to supply base_length, and suggestion to integrate with AABBs later.

[mweatherley]

I'd prefer to have an example for this, but I'm fine to punt that to follow-up :)

Cool! I wasn't sure if this merited an example, but I'd be happy to produce one in a follow-up.

At some point higher-level gizmos may make more sense in bevy_dev_tools, but this is a good addition.

I was wondering about this, but I'm pretty out of the loop with the whole bevy_dev_tools discussion, so I'm glad you brought it up!

[pablo-lua]

Good changes. I think maybe we can do some kind of builder with this on the future (probably when we move this to bevy_dev_tools)

[pablo-lua]

this is better for builders! Good to have this change.