bevyengine / bevyengine/bevy

2d rotations are cumbersome

Open
#14,525 7 comments 4 reactions 0 assignees View on GitHub
A-Math C-Docs C-Usability D-Straightforward
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 16h
Merged PRs (30d)
171

Description

## How can Bevy's documentation be improved?

The docs for `Vec2`, `Dir2`, `Rot2`, and `Quat` are poorly cross-linked/associated. This means it is quite a headache for new users of these APIs to figure out how to do conversions, and some of the conversions seem needlessly convoluted.

Here is the incantation to get `Quat` from `Dir2` in 2d space:
```rust
let rotation = Quat::from_rotation_z(direction.rotation_from_x().as_radians());
```

Here is some code to place an entity at a random radial position around another entity:
```rust
let direction = rng.gen_range((0.)..TAU);
let mut point_transform = Transform::from_translation(Vec3::default().with_x(spawn_radius));
point_transform.translate_around(Vec3::default(), Quat::from_rotation_z(direction));
```

Here I'm getting the `Aabb` zone for doing 2d projectile intersection tests. Yes, `Aabb2d` panics randomly if you don't correct by `PI - rotation`...
```rust
let mut rotation = Quat::default().angle_between(zone_transform.rotation.normalize());
if rotation > PI / 2. {
rotation = PI - rotation;
}
rotation = rotation.clamp(0., PI / 2.);
let entity_aabb = zone_aabb
.get_2d_from_vec(Vec2::default())
.transformed_by(zone_transform.translation.truncate(), rotation);
let entity_aabb = AabbCast2d::new(
entity_aabb,
Vec2::default(),
Dir2::new(last_pos - zone_transform.translation.truncate())
.unwrap_or(Dir2::new_unchecked(Vec2::default().with_x(1.))),
(zone_transform.translation.truncate() - last_pos).length(),
);
```

Contributor guide

Open the contributing guide

Research direction

Start by reading the documentation for Vec2, Dir2, Rot2, and Quat, using the reported conversion and rotation examples as the current user experience. Map where these APIs and Aabb2d are documented, then define completion as clearer cross-links and less convoluted guidance for 2D rotation conversions.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, game-dev
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.