69 releases (40 breaking)
new 0.46.0 | Mar 27, 2023 |
---|---|
0.44.0 | Mar 13, 2023 |
0.29.0 | Dec 17, 2022 |
0.27.0 | Nov 29, 2022 |
#27 in Games
215 downloads per month
39KB
776 lines
This is the API reference for Oort. For more general information see the wiki.
Starter Code
Oort expects your code to have a Ship
type with a tick
method. Each
tutorial provides some starter code which includes this:
use oort_api::prelude::*;
pub struct Ship {}
impl Ship {
pub fn new() -> Ship {
Ship {}
}
pub fn tick(&mut self) {
}
}
The game will call your new
function when a ship is created and then call
tick
60 times per second during the simulation.
struct Ship
is useful for storing any state that needs to persist between
ticks. enum Ship
works too and can be helpful when this state differs between
ship classes.
The statement use oort_api::prelude::*
imports all the APIs so that you can use
them simply as e.g. position()
. See the [prelude] module documentation for
the details on everything this imports. The important APIs are covered below.
Subsystems
All actions performed by a ship (such as firing weapons or scanning the radar) occur between ticks. In particular, setting the radar heading or the radio channel will affect the scan results or messages received on the next tick.
Ship Status and Control
Basic status:
class() → Class
: Get the ship class (Fighter, Cruiser, etc).position() → Vec2
: Get the current position in meters.velocity() → Vec2
: Get the current velocity in m/s.heading() → f64
: Get the current heading in radians.angular_velocity() → f64
: Get the current angular velocity in radians/s.
Engine control:
accelerate(acceleration: Vec2)
: Linear acceleration. X axis is forward/back, Y axis is left/right. Units are m/s².turn(speed: f64)
: Rotate the ship. Unit is radians/s.torque(acceleration: f64)
: Angular acceleration. Unit is radians/s².
Engine limits:
max_forward_acceleration() -> f64
: Maximum forward acceleration.max_backward_acceleration() -> f64
: Maximum backward acceleration.max_lateral_acceleration() -> f64
: Maximum lateral acceleration.max_angular_acceleration() -> f64
: Maximum angular acceleration.
Weapons
Guns:
fire(index: usize)
: Fire a weapon (gun or missile).aim(index: usize, angle: f64)
: Aim a weapon (for weapons on a turret).explode()
: Self-destruct.
Radar
Radar in Oort is modeled as a beam that can be pointed in any direction and which has a width between 1/360 of a circle to a full circle. Enemy ships illuminated by this beam reflect an amount of energy proportional to their radar cross section (larger for larger ships). The radar can return one contact per tick. Any changes to heading/width/filtering take effect on the next tick.
The position and velocity returned for a contact will have error inversely related to the signal strength.
Basic operation:
set_radar_heading(angle: f64)
: Point the radar at the given heading, relative to the ship heading.set_radar_width(width: f64)
: Adjust the beam width (in radians).scan() → Option<ScanResult>
: Get the radar contact with the highest signal strength.struct ScanResult { position: Vec2, velocity: Vec2, class: Class }
: Structure returned byscan
.
Advanced filtering:
set_radar_min_distance(dist: f64)
: Set the minimum distance filter.set_radar_max_distance(dist: f64)
: Set the maximum distance filter.
Retrieving current state:
radar_heading() -> f64
: Get current radar heading.radar_width() -> f64
: Get current radar width.radar_min_distance() -> f64
: Get current minimum distance filter.radar_max_distance() -> f64
: Get current maximum distance filter.
Radio
The radio can be used to send or receive a single value per tick. There are 10 channels available (0 to 9), shared between all teams.
set_radio_channel(channel: usize)
: Change the radio channel. Takes effect next tick.get_radio_channel() -> usize
: Get the radio channel.send(data: f64)
: Send a message on a channel.receive() -> f64
: Receive a message from the channel. The message with the strongest signal is returned.select_radio(index: usize)
: Select the radio to control with subsequent API calls. Frigates have 4 radios and cruisers have 8.
Special Abilities
Some ship classes have a unique special ability. These abilities are activated for a certain time and then need to reload.
activate_ability(ability: Ability)
: Activates a special ability.- Available abilities:
Ability::Boost
: Fighter and missile only. Applies a 100 m/s² forward acceleration for 2s. Reloads in 10s.Ability::ShapedCharge
: Missile only. [explode()
][prelude::explode] will create a jet of shrapnel instead of a circle.Ability::Decoy
: Torpedo only. Mimics the radar signature of a Cruiser for 0.5s. Reloads in 10s.Ability::Shield
: Cruiser only. Deflects damage for 1s. Reloads in 5s.
Scalar Math
PI
,TAU
: Constants.x.abs()
: Absolute value.x.sqrt()
: Square root.x.sin()
,x.cos()
,x.tan()
: Trigonometry.
See the Rust documentation for the full list of f64 methods.
Vector Math
Two-dimensional floating point vectors (Vec2) are ubiquitous in Oort and are used to represent positions, velocities, accelerations, etc.
vec2(x: f64, y: f64) → Vec2
: Create a vector.v.x, v.y → f64
: Get a component of a vector.v1 +- v2 → Vec2
: Basic arithmetic between vectors.v */ f64 → Vec2
: Basic arithmetic between vectors and scalars.-v → Vec2
: Negate a vector.v.length() → f64
: Length.v.normalize() → Vec2
: Normalize to a unit vector.v.rotate(angle: f64) → Vec2
: Rotate counter-clockwise.v.angle() → f64
: Angle of a vector.v1.dot(v2: Vec2) → f64
: Dot product.v1.cross(v2: Vec2) → f64
: Cross product.v1.distance(v2: Vec2) → f64
: Distance between two points.
Debugging
Clicking on a ship in the UI displays status information and graphics indicating its acceleration, radar cone, etc. You can add to this with the functions below.
debug!(...)
: Add status text.draw_line(v0: Vec2, v1: Vec2, color: u32)
: Draw a line.draw_triangle(center: Vec2, radius: f64, color: u32)
: Draw a triangle.draw_square(center: Vec2, radius: f64, color: u32)
: Draw a square.draw_diamond(center: Vec2, radius: f64, color: u32)
: Draw a diamond.draw_polygon(center: Vec2, radius: f64, sides: i32, angle: f64, color: u32)
: Draw a regular polygon.draw_text!(topleft: Vec2, color: u32, ...)
: Draw text.
Entering debug mode by pressing the 'g' key also displays debug graphics from all ships.
Miscellaneous
current_tick() → f64
: Returns the number of ticks elapsed since the simulation started.current_time() → f64
: Returns the number of seconds elapsed since the simulation started.angle_diff(a: f64, b: f64) → f64
: Returns the shortest (possibly negative) distance between two angles.rand(low: f64, high: f64) → f64
: Get a random number.seed() → u128
: Returns a seed useful for initializing a random number generator.
Ship Classes
Fighter
: Small, fast, and lightly armored.- Health: 100
- Acceleration: Forward/Reverse: 60 m/s², Lateral: 30 m/s², Angular: 2π rad/s²
- Weapon 0: Gun, Damage: 7, Speed: 1000 m/s, Reload: 66ms
- Weapon 1: Torpedo, Reload: 5s
Frigate
: Medium size with heavy armor and an extremely powerful main gun.- Health: 10000
- Acceleration: Forward/Reverse: 10 m/s², Lateral: 5 m/s², Angular: π/4 rad/s²
- Weapon 0: Gun, Damage: 1000, Speed: 4000 m/s, Reload: 1 second
- Weapon 1: Gun, Damage: 7, Speed: 1000 m/s, Reload: 66ms, Turreted
- Weapon 2: Gun, Damage: 7, Speed: 1000 m/s, Reload: 66ms, Turreted
- Weapon 3: Missile, Reload: 2s
Cruiser
: Large, slow, and heavily armored. Rapid fire missile launchers and devastating torpedos.- Health: 20000
- Acceleration: Forward/Reverse: 5 m/s², Lateral: 2.5 m/s², Angular: π/8 rad/s²
- Weapon 0: Gun, Damage: 6×7, Speed: 1000 m/s, Reload: 0.4s, Turreted
- Weapon 1: Missile, Reload: 1.2s
- Weapon 2: Missile, Reload: 1.2s
- Weapon 3: Torpedo, Reload: 3s
Missile
: Highly maneuverable but unarmored. Explodes on contact or after anexplode
call.- Health: 20
- Acceleration: Forward/Reverse: 200 m/s², Lateral: 50 m/s², Angular: 4π rad/s²
- Warhead: 20×15
Torpedo
: Better armor, larger warhead, but less maneuverable than a missile. Explodes on contact or after anexplode
call.- Health: 100
- Acceleration: Forward/Reverse: 70 m/s², Lateral: 20 m/s², Angular: 4π rad/s²
- Warhead: 100×50
Dependencies
~94KB