Copy constants from C++ to Typescript definition file (openrct2.d.ts)

[pfroud]

I noticed the typescript definition file sometimes says to to look at the C++ source. Should I copy constants from C++ into the .d.ts file?

For example:

interface StaffHireArgs extends GameActionArgs {
    // ...
    staffOrders: number; // bit mask. See STAFF_ORDERS in openrct2/entity/Staff.h
}

The definition in Staff.h is:

enum STAFF_ORDERS
{
    STAFF_ORDERS_SWEEPING = (1 << 0),
    STAFF_ORDERS_WATER_FLOWERS = (1 << 1),
    STAFF_ORDERS_EMPTY_BINS = (1 << 2),
    STAFF_ORDERS_MOWING = (1 << 3),
    STAFF_ORDERS_INSPECT_RIDES = (1 << 0),
    STAFF_ORDERS_FIX_RIDES = (1 << 1)
};

I think these numbers will never change, so they could easily be add to the .d.ts file.

Simple way:

const STAFF_ORDERS_SWEEPING = (1 << 0);
const STAFF_ORDERS_WATER_FLOWERS = (1 << 1);
const STAFF_ORDERS_EMPTY_BINS = (1 << 2);
const STAFF_ORDERS_MOWING = (1 << 3);
const STAFF_ORDERS_INSPECT_RIDES = (1 << 0);
const STAFF_ORDERS_FIX_RIDES = (1 << 1)

To use the simple way:

staffOrders = STAFF_ORDERS_SWEEPING | STAFF_ORDERS_EMPTY_BINS;

Slightly fancier way:

const STAFF_ORDERS = {
    SWEEPING: (1 << 0),
    WATER_FLOWERS: (1 << 1),
    EMPTY_BINS: (1 << 2),
    MOWING: (1 << 3),
    INSPECT_RIDES: (1 << 0),
    FIX_RIDES: (1 << 1)
} as const;

(The as const thing prevents the properties inside the object from being changed.)

To use the fancier way:

staffOrders = STAFF_ORDERS.SWEEPING | STAFF_ORDERS.EMPTY_BINS;

This could NOT change the plugin API version, it's fully backwards compatible. In this example the staffType property would still be a number.

[ZehMatt]

Why not use enums? https://www.typescriptlang.org/docs/handbook/enums.html

[Basssiiie]

I think it's a good idea, but I think it needs some thought into how we can prevent the enums from desyncing, because now they will need to be updated in two different spots if changes are needed.

Or should we just make enum-string maps for all of them and deprecate the integer fields?

Side note: whatever the solution though, the enums should conform to the code style already present openrct2.d.ts.

[ZehMatt]

I generally hate the idea of manually updating the reference to be honest, it would have been best to document the entire API reference directly in the code and have libclang or some other parser get all the things and automatically generate it.

[Basssiiie]

Yeah that'd be great. I suspect it's not gonna be easy to generate one that matches the current d.ts file though with things like inheritance and the various variations of flags/enums implementations.