Module math 

Vectors, angles and direction helpers made for audio games.

Coordinate system

The engine uses a right-handed system with z pointing up:

• +x is east (right on a map)
• +y is north (forward on a map)
• +z is up

Angles (“yaw” or “facing”) are compass degrees: 0 = north, 90 = east, 180 = south, 270 = west. A 2D side scroller simply uses x for left/right and z for up/down, a top down game uses x and y, and a full 3D game uses all three.

The angle up or down (“pitch”) is in degrees too: 0 = level with the horizon, 90 = straight up, -90 = straight down.

Positions: vec3(x, y, z)

A position is a Vec3 with three numbers in meters, written vec3(x, y, z):

• x: how far east (positive) or west (negative)
• y: how far north (positive) or south (negative)
• z: how far up (positive) or down (negative)

vec3(3.0, -2.0, 1.5) is 3 m east, 2 m south and 1.5 m up from the origin vec3(0.0, 0.0, 0.0) (also written Vec3::ZERO). The same type describes directions and velocities: vec3(0.0, 2.0, 0.0) as a velocity is 2 m/s north.

use audio_code::math::*;

let player = vec3(3.0, -2.0, 1.5);
let east = player.x;                              // 3.0
let above = player + vec3(0.0, 0.0, 2.0);         // 2 m higher
let ahead = player + forward(90.0) * 5.0;         // 5 m to the east
let distance = player.distance(above);            // 2.0
assert_eq!(east, 3.0);
assert!((distance - 2.0).abs() < 1e-5);
assert!((ahead.x - 8.0).abs() < 1e-5);

Modules

random

Random helpers so you do not need an extra crate for the basics.

Structs

Vec2

A 2-dimensional vector.

Vec3

A 3-dimensional vector.

Functions

angle_difference

Shortest signed difference to - from in degrees, in the range -180.0..=180.0. Positive means turning clockwise (to the right).

bearing

Compass bearing in degrees from from to to, ignoring height.

clock_position

Converts an angle relative to the player (0 = straight ahead) to a clock position, e.g. 90 degrees becomes 3 (o’clock). Returns 1..=12.

db_to_linear

Converts decibels to a linear volume factor (0 dB = 1.0, -6 dB ≈ 0.5).

describe_position

Describes where target is relative to someone at from facing yaw, ready to be spoken. The distance is the straight line in 3D. A height difference (z) of a meter or more is added:

direction_name

Converts a compass angle to a name such as “north east”. Uses 8 directions.

elevation

Angle in degrees from from up to to: 90 = straight above, 0 = same height, -90 = straight below.

forward

Unit vector pointing in the compass direction yaw on the ground plane.

forward_3d

Unit vector pointing in compass direction yaw, tilted up by pitch degrees (90 = straight up, -90 = straight down). With pitch 0 it equals forward.

lerp

Linear interpolation between a and b.

linear_to_db

Converts a linear volume factor to decibels.

look_at

Compass direction (yaw) and pitch in degrees that point from from to to, e.g. to aim at a target or to make a body look at it.

move_towards

Moves position by distance in compass direction yaw on the ground plane.

normalize_angle

Wraps an angle into the range 0.0..360.0.

right

Unit vector pointing to the right of the compass direction yaw.

up_3d

Unit vector pointing out of the top of the head of someone facing yaw and looking up by pitch degrees. With pitch 0 it is +z.

vec2

Creates a 2-dimensional vector.

vec3

Creates a 3-dimensional vector.