mirror of
https://github.com/bevyengine/bevy
synced 2024-12-22 02:53:07 +00:00
f8f8bdd4aa
# Objective - We introduce a gizmo that displays coordinate axes relative to a Transform*, primarily for debugging purposes. - See #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: ````rust 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: ````rust 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: <img width="206" alt="Screenshot 2024-02-29 at 2 41 45 PM" src="https://github.com/bevyengine/bevy/assets/2975848/789d1703-29ae-4295-80ab-b87459cf8037"> Note that, if scaling was applied as part of the given transformation, it shows up in scaling on the axes as well: <img width="377" alt="Screenshot 2024-02-29 at 2 43 53 PM" src="https://github.com/bevyengine/bevy/assets/2975848/6dc1caf4-8b3e-47f7-a86a-8906d870fa72"> --- ## 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: ````rust 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. |
||
|---|---|---|
| .. | ||
| macros | ||
| src | ||
| Cargo.toml | ||