131 releases (73 breaking)

0.79.3 Apr 19, 2024
0.79.1 Dec 28, 2023
0.78.2 Nov 22, 2023
0.54.1 Jul 21, 2023
0.27.0 Nov 29, 2022

#9 in Games

GPL-3.0-or-later

54KB
1K SLoC

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:

Engine control:

Engine limits:

Weapons

Radar

Radar in Oort is modeled as a beam that can be pointed in any direction and which has a beam width between 1/720 to 1/4 of a circle (min 1/3600 for frigates and cruisers). 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 radar 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:

Advanced filtering:

Electronic Counter Measures (ECM):

The goal of ECM is to make enemy radar less effective. For ECM to work, the enemy radar must be pointed towards your ship, and your ship's radar must be pointed at the enemy. Your radar will not return contacts while ECM is enabled.

Retrieving current state:

Radio

The radio can be used to send or receive a [f64; 4] message per tick. There are 10 channels available (0 to 9), shared between all teams.

Special Abilities

Some ship classes have a unique special ability. These abilities need to be activated, after which they will function for a short time before needing to reload. An ability can be deactivated early via the API. If an ability is activated and never deactivated, then it will automatically start back up again after its reload time passes.

Scalar Math

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.

The entire maths_rs crate is also available.

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.

Entering debug mode by pressing the 'g' key also displays debug graphics from all ships.

Miscellaneous

Extra Crates

The following crates are available for use in your code:

  • byteorder: Utilities to read and write binary data, useful for radio.
  • maths_rs: A linear algebra library.
  • oorandom: A random number generation library.

Ship Classes

  • Fighter: Small, fast, and lightly armored.
    • Health: 100
    • Acceleration: Forward: 60 m/s², Lateral: 30 m/s², Reverse: 30 m/s², Angular: 2π rad/s²
    • Weapon 0: Gun, Speed: 1000 m/s, Reload: 66ms
    • Weapon 1: Missile, Reload: 5s
  • Frigate: Medium size with heavy armor and an extremely powerful main gun.
    • Health: 10000
    • Acceleration: Forward: 10 m/s², Lateral: 5 m/s², Reverse: 5 m/s², Angular: π/4 rad/s²
    • Weapon 0: Gun, Speed: 4000 m/s, Reload: 2 seconds
    • Weapon 1: Gun, Speed: 1000 m/s, Reload: 66ms, Turreted
    • Weapon 2: Gun, 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: 5 m/s², Lateral: 2.5 m/s², Reverse: 2.5 m/s², Angular: π/8 rad/s²
    • Weapon 0: Gun, Speed: 2000 m/s, Burst size: 6, Reload: 5s, 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 an explode call.
    • Health: 20
    • Fuel: 2000 m/s
    • Acceleration: Forward: 300 m/s², Reverse: 0 m/s², Lateral: 100 m/s², Angular: 4π rad/s²
  • Torpedo: Better armor, larger warhead, but less maneuverable than a missile. Explodes on contact or after an explode call.
    • Health: 100
    • Fuel: 3000 m/s
    • Acceleration: Forward: 70 m/s², Reverse: 0 m/s², Lateral: 20 m/s², Angular: 2π rad/s²

Dependencies

~440–650KB
~15K SLoC