script_module - Outerra/anteworld GitHub Wiki
bool preload_object(const coid::token& model_url) |
||
| Parameter Description | Returns | Description |
|---|---|---|
| model_url: URL of the object model to preload | return: true if preloading succeeded | Preload object |
coid::token get_module_dir() const |
||
| Parameter Description | Returns | Description |
| return: module directory | Get module directory | |
void set_time(int dyear, double tday, bool utc, float flowmul = 1) |
||
| Parameter Description | Returns | Description |
|
dyear: day of the year tday: time of day in seconds utc: true for UTC, false for solar time flowmul: time flow multiplier (default: 1) |
Set time, either solar or UTC | |
bool load_location(const coid::token& name, bool use_datetime) |
||
| Parameter Description | Returns | Description |
|
name: save name use_datetime: if date/time is contained in the location file, apply it |
return: true if the location was found | Jump to a location that was saved in game campos |
bool set_location(double lon, double lat, float height) |
||
| Parameter Description | Returns | Description |
|
lon: longitude lat: latitude height: height above terrain |
return: true if the location is valid | Jump to a location given lat/lon and height above terrain |
bool is_location_ready() const |
||
| Parameter Description | Returns | Description |
| return: true if last loaded location is ready | Check if the last loaded location is ready | |
bool open_window(const coid::token& url) |
||
| Parameter Description | Returns | Description |
|
url: relative path, with optional query part (e.g. url?param1¶m2 ...) recognized tokens: name - window name width - initial window width height - initial window height x - initial window x position y - initial window y position transparent - true or 1 if the window should support transparency |
return: true if the window was successfully opened | Open a browser window, loading specified html |
int set_value_str(int param_a, int param_b, const coid::token& value) |
||
| Parameter Description | Returns | Description |
|
param_a: first parameter param_b: second parameter value: string value to set |
return: | Function for communicating between html windows and script, sets string value for the specified parameters |
int get_value_str(int param_a, int param_b, ifc_out coid::charstr& value) |
||
| Parameter Description | Returns | Description |
|
param_a: first parameter param_b: second parameter value: string value retrieved |
return: | Function for communicating between html windows and script, gets string value for the specified parameters |
int set_value_num(int param_a, int param_b, double value) |
||
| Parameter Description | Returns | Description |
|
param_a: first parameter param_b: second parameter value: numeric value to set |
return: | Function for communicating between html windows and script, sets numeric value for the specified parameters |
int get_value_num(int param_a, int param_b, ifc_out double& value) |
||
| Parameter Description | Returns | Description |
|
param_a: first parameter param_b: second parameter value: numeric value retrieved |
return: | Function for communicating between html windows and script, gets numeric value for the specified parameters |
int register_event_ext(const coid::token& name, bool release_event, uint group = 0) |
||
| Parameter Description | Returns | Description |
|
name: hierarchic action name, file/group/action release_event: true if handler should also receive release events (if bound to key) group: activation group where the action is assigned (can be enabled/disabled together) (default: 0) |
return: slot ID or -1 on fail | Register event action handler |
int register_axis_ext(const coid::token& name, const ot::ramp_params& ramp, uint group = 0) |
||
| Parameter Description | Returns | Description |
|
name: hierarchic action name, file/group/action ramp: value limiter parameters (ignored for buttons) group: activation group where the action is assigned (can be enabled/disabled together) (default: 0) |
return: slot ID or -1 on fail | Register axis action handler |
int register_axis_handler(const coid::token& name, ot::fn_axis_action&& handler, const ot::ramp_params& ramp, int handler_id = 0, const float* def_val = nullptr, uint group = 0) |
||
| Parameter Description | Returns | Description |
|
name: hierarchic action name, file/group/action handler: optional handler for changed value, void fn(float val, uint code, uint channel, int handler_id) ramp: value limiter parameters handler_id: extra data for the handler (default is 0) def_val: optional default action value group: activation group where the action is assigned (can be enabled/disabled together) (default: 0) |
return: slot ID or -1 on fail | Register input action sending events on value change (full state button and axis) |
int register_event_handler(const coid::token& name, ot::fn_event_action&& handler, int handler_id = 0, uint group = 0, uint extra_channels = 0) |
||
| Parameter Description | Returns | Description |
|
name: hierarchic action name, file/group/action handler: optional handler for changed value, void fn(int flags, uint code, uint channel, int handler_id) handler_id: optional extra data for the handler (default: 0) group: activation group where the action is assigned (can be enabled/disabled together) (default: 0) extra_channels: number of extra channels that are handled (multiple engines etc) |
return: slot ID or -1 on fail | Register input action sending events on button press (value > 0) |
void action_group(uint group, bool activate); |
||
| Parameter Description | Returns | Description |
|
group: group ID activate: activate/deactivate the group |
Activate or deactivate given action group | |
void set_center_value(int action, float center); |
||
| Parameter Description | Returns | Description |
|
action: action ID center: center value, will be clamped to minval..maxval range |
Set the value to center to, default 0 | |
void set_action_value(int action, float value, bool hold); |
||
| Parameter Description | Returns | Description |
|
action: action ID value: instant action value, will be clamped to minval..maxval range hold: true if the value should be held (disabled centering) |
Set instant action value | |
void set_instant_action_value(int action, float value, bool notify); |
||
| Parameter Description | Returns | Description |
|
action: action ID value: instant action value, will be clamped to minval..maxval range notify: invoke/don't invoke the handler |
Set instant action value | |
iref<ot::object> create_instance(const coid::token& model, const double3& pos, const glm::quat& rot, ot::object_create_flags flags) |
||
| Parameter Description | Returns | Description |
|
model: full model path under packages dir pos: world position of the pivot point rot: orientation of the model flags: persistent, colliding, kinematic create flags |
return: reference to the created object instance | Create object instance |
iref<ot::object> create_static_instance(const coid::token& model, const double3& pos, const glm::quat& rot, ot::object_create_flags flags) |
||
| Parameter Description | Returns | Description |
|
model: full model path under packages dir pos: world position of the pivot point rot: orientation of the model flags: persistent, colliding, kinematic create flags |
return: reference to the created object instance | Create object instance as a static object |
entity_handle create_sensor(const double3& pos, const quat& rot, float radius) |
||
| Parameter Description | Returns | Description |
|
pos: position of the sensor rot: rotation of the sensor radius: radius of the sphere-shaped sensor |
return:entity_handle of the sensor | Create sensor of sphere shape |
const coid::dynarray32<ot::triggered_sensor_info>& get_tiggered_sensors() const |
||
| Parameter Description | Returns | Description |
| return: array of sensors triggered in the current frame | Get sensors triggered in current frame | |
const coid::dynarray<ot::impact_info>& get_landed_projectiles() const |
||
| Parameter Description | Returns | Description |
| return: array of landed projectiles (tracers) | Get array of landed projectiles (tracers) | |
int2 screen_size() const |
||
| Parameter Description | Returns | Description |
| return: screen size in pixels | Retrieve the screen size in pixels. | |
float meter_size(float dist) const |
||
| Parameter Description | Returns | Description |
| dist: distance | return: screen size (in pixels) of one meter large object at given distance from camera | Calculate the screen size in pixels of a 1-meter object at a given distance. |
float pixel_size(const double3& pos, float pixels = 1.0f) const |
||
| Parameter Description | Returns | Description |
|
pos: ECEF position pixels: width/height in pixels (defauls: 1.0) |
return: object size (in meters) of object at given pos that occupies given width of pixels | Calculate the object size in meters for a given pixel width or height. |
const double3& get_camera_pos() const |
||
| Parameter Description | Returns | Description |
| return: current camera world position | Retrieve the current camera world position | |
float3 get_camera_dir() const |
||
| Parameter Description | Returns | Description |
| return: current camera direction | Retrieve the current camera direction. | |
const quat& get_camera_rot(bool base = true) const |
||
| Parameter Description | Returns | Description |
| base: if true, returns final camera rotation (with trackers rotation applied), otherwise returns the base rotation | return: current camera rotation from default ECEF frame | Retrieve the current camera rotation |
float3 get_camera_hpr() const |
||
| Parameter Description | Returns | Description |
| return: current camera heading pitch roll angles [rad] | Retrieve the current camera orientation as heading, pitch, and roll angles. | |
void set_camera_pos(const double3& pos) |
||
| Parameter Description | Returns | Description |
| pos: world position | Set camera position in the world | |
void set_camera_dir(const float3& dir, bool align_horizon) |
||
| Parameter Description | Returns | Description |
|
dir: direction vector in ECEF align_horizon: if true, align camera to be horizontal |
Set camera direction, aligned with the tangent plane | |
void set_camera_rot(const quat& rot, bool camspace = true) |
||
| Parameter Description | Returns | Description |
|
rot: rotation from default ECEF frame camspace: true for camera space (-z forward), false for model space (+y forward) |
Set camera rotation | |
void set_camera_fov(float hfov, float vfov = 0) |
||
| Parameter Description | Returns | Description |
|
hfov: horizontal fov in degrees vfov: optional vertical fov in degrees, otherwise computed from aspect ratio |
Set camera field of view (FOV) | |
float2 get_camera_fov() const |
||
| Parameter Description | Returns | Description |
| return: current camera horizontal and vertical fov in degrees | Retrieve camera field of view | |
float3 get_screen_pos(const double3& pos) const |
||
| Parameter Description | Returns | Description |
| pos: world position | return: position xy in normalized -1..1 range and depth from the camera | Get normalized screen position where a point in the world would be projected |
float3 get_screen_pix(const double3& pos, bool ydown = true) const |
||
| Parameter Description | Returns | Description |
|
pos: world position ydown: screen position with y+ axis going down |
return: position xy in pixels (left-top origin) and depth from the camera | Get screen position where a point in the world would be projected |
double3 get_world_pos_from_screen_pos(const float2& screenpos, float distance) const |
||
| Parameter Description | Returns | Description |
|
screenpos: screen position xy in normalized -1..1 range distance: distance from camera in meters |
return: ECEF position | Get world position distance away from given direction |
double3 get_world_pos_from_screen_pix(const float2& screenpix, float distance) const |
||
| Parameter Description | Returns | Description |
|
screenpix: pixel position on the screen (top-left origin) distance: distance from camera in meters |
return: ECEF position | Get world position distance away from given direction |
float3 ray_from_screen_pix(const float2& screenpix, bool pnorm = true) const |
||
| Parameter Description | Returns | Description |
|
screenpix: pixel position on the screen, left-bottom origin pnorm: normalize the output vector; if false, vector points to the projection plane |
return: ray in world space | View ray in world space for given pixel coordinates |
float3 ray_from_screen_pos(const float2& screenpos, bool pnorm = true) const |
||
| Parameter Description | Returns | Description |
|
screenpos: screen position xy in normalized -1..1 range pnorm: normalize output vector; if false the vector goes onto the projection plane (can be multiplied with scene depth instead of ray depth) |
return: ray in world space | View ray in world space for given pixel coordinates |
iref<ot::object> find_object(const double3& from, const float3& ray, float maxlen, ifc_out double3* hitpoint = 0, ifc_out float3* normal = 0, entity_handle exclude_obj = entity_handle()) const |
||
| Parameter Description | Returns | Description |
|
from: world position of the start point ray: normalized ray direction maxlen: maximum distance to check hitpoint: optional, world space coordinates of hit point normal: optional, surface normal at hit point exclude_obj: optional, object to exclude from intersection |
return: iref to the object, if any | Find an object intersected by the ray Note: keep the ray as short as possible |
iref<ot::object> find_object_mesh(const double3& from, const float3& ray, float maxlen, ifc_out int& mesh_id, ifc_out double3* hitpoint = 0, ifc_out float3* normal = 0, entity_handle exclude_obj = entity_handle()) const; |
||
| Parameter Description | Returns | Description |
|
mesh_id: [out] collision mesh (shape) id hitpoint: [out] world space coordinates of point hit normal: maximum distance to check hitpoint: optional, world space coordinates of hit point normal: [out] world space surface normal |
return: iref to the mesh, if any | Find object and its collision mesh hit by the ray Note: keep the ray as short as possible |
float ray_intersect(const double3& from, const float3& dir, float maxdist, float negdist = -FLT_MIN, ifc_out float* waterdist = 0, ifc_out ot::hitpoint* hp = 0, ot::hit_flags hpflags = {.hit = true, .normal = true}) const; |
||
| Parameter Description | Returns | Description |
|
from: world position of the start point dir: ray direction (normalized) maxdist: max distance to check negdist: negative distance to check in case the 'from' point is under terrain, must be <0 hp: hitpoint, normal and material info. Contains also meshid and objid if hp->fobjects param is true |
return: distance to intersection, >= maxdist if none, <= negdist if missing terrain data or too far below terrain | Find intersection with terrain |
bool is_valid_object(entity_handle eid) const |
||
| Parameter Description | Returns | Description |
| eid: entity ID | return: true if given entity is a valid object | Checks whether entity is valid object |
iref<ot::object> get_object(entity_handle eid) const; |
||
| Parameter Description | Returns | Description |
| eid: entity ID | return: object reference | Get object |
bool remove_object(entity_handle eid); |
||
| Parameter Description | Returns | Description |
| eid: entity ID | return: true if object was successfully removed | Remove object |
void pause(bool value) |
||
| Parameter Description | Returns | Description |
| value: true -> pause, false->unpause | Pause the engine | |
virtual void before_simulation_step(int dtns, uint64 ns_sim) { } |
||
| Parameter Description | Returns | Description |
|---|---|---|
|
dtns: time delta [ns] since simulation step ns_sim: absolute simulation time [ns] |
Event before simulation step | |
virtual void visual_update(float dtrender, float dtsim, float dtinterpolate) { } |
||
| Parameter Description | Returns | Description |
|
dtrender: time delta [s] since the last frame dtsim: simulation time delta [s] since the last frame dtinterpolate: delta time from last simulation step to predicted frame time |
Game visual update (simulation step) event | |
virtual bool on_initialize() { throw coid::exception(HANDLER_NOT_IMPLEMENTED_MESSAGE); } |
||
| Parameter Description | Returns | Description |
| return: true if initialization was successful | Initialize script module | |
virtual bool on_initialize_script() { return true; } |
||
| Parameter Description | Returns | Description |
| return: true if initialization was successful | Initialize script module | |
virtual void update_actions_script(float dt, const coid::range<int32>& actbuf) { } |
||
| Parameter Description | Returns | Description |
|
dt: delta time since the last frame actbuf: |
Invoke script-side registered actions | |
virtual int on_set_value_str(int param_a, int param_b, const coid::token& value) { throw coid::exception(HANDLER_NOT_IMPLEMENTED_MESSAGE); } |
||
| Parameter Description | Returns | Description |
|
param_a: first parameter param_b: second parameter value: string value to set |
return: int result of the operation | Event for communicating between html windows and script, sets string value from script |
virtual int on_get_value_str(int param_a, int param_b, coid::charstr& value) { throw coid::exception(HANDLER_NOT_IMPLEMENTED_MESSAGE); } |
||
| Parameter Description | Returns | Description |
|
param_a: first parameter param_b: second parameter value: string value to retrieve |
return: int result of the operation | Event for communicating between html windows and script, gets string value from html window |
virtual int on_set_value_num(int param_a, int param_b, double value) { throw coid::exception(HANDLER_NOT_IMPLEMENTED_MESSAGE); } |
||
| Parameter Description | Returns | Description |
|
param_a: first parameter param_b: second parameter value: numeric value to set |
return: int result of the operation | Event for communicating between html windows and script, sets numeric value from script |
virtual int on_get_value_num(int param_a, int param_b, double& value) { throw coid::exception(HANDLER_NOT_IMPLEMENTED_MESSAGE); } |
||
| Parameter Description | Returns | Description |
|
param_a: first parameter param_b: second parameter value: numeric value to retrieve |
return: int result of the operation | Event for communicating between html windows and script, gets numeric value from html window |
virtual void on_destroy() { } |
||
| Parameter Description | Returns | Description |
| Event triggered when the object is destroyed | ||
virtual bool on_reload() { return false; } |
||
| Parameter Description | Returns | Description |
| return: false if reload fails, true if reload is successful | Event triggered when the object is reloaded | |
virtual void on_final_camera(const double3& pos, const quat& rot) { } |
||
| Parameter Description | Returns | Description |
|
pos: camera position in world space rot: camera rotation as a quaternion |
Invoked after the final camera position in the frame is known | |
virtual void on_before_reload(coid::dynarray<uint8>& user_data) { } |
||
| Parameter Description | Returns | Description |
| user_data: user data | Called before script module is reloaded | |
virtual void on_after_reload(const coid::dynarray<uint8>& user_data) { } |
||
| Parameter Description | Returns | Description |
| user_data: value filled in on_before_reload | Event triggered after the script module is reloaded | |
virtual bool on_mouse_button(int button, bool state, ot::kbd_modifier modifiers) { return false; } |
||
| Parameter Description | Returns | Description |
|
button: mouse button (0 = left, 1 = right, 2 = middle) state: true for pressed, false for released modifiers: keyboard modifier bit flags, from LSB: LSHIFT, RSHIFT, LCTRL, RCTRL, LALT, RALT |
return: | Mouse button press/release event |
virtual bool on_mouse_wheel(int dy, ot::kbd_modifier modifiers) { return false; } |
||
| Parameter Description | Returns | Description |
|
dy: roll amount modifiers: keyboard modifier bit flags |
return: | Mouse wheel event |
virtual void on_main_menu(bool value) { } |
||
| Parameter Description | Returns | Description |
| value: true if menu opened, false if menu closed | Event fired on the main menu open/close | |
virtual void on_preload_object_done(coid::token model_url) { } |
||
| Parameter Description | Returns | Description |
| model_url: url of preloaded objdef | Event called when preloading of object is done | |
virtual void force_bind_script_events() { } |
||
| Parameter Description | Returns | Description |