openOMSI Development Tools

API reference

Generated from the API manifest, version 0.2.22.

Functions

after(seconds: number, fn: function) → integer id

Runs `fn` once, `seconds` of game time later.

audio.play(file: string, opts?: table) → integer id or nil, reason

Plays a WAV file of the plugin's folder. `opts`: `volume` (1), `pitch` (1), `loop`, `range` (metres heard at full volume, 5), and either `x, y, z` (a sound at a map point) or `on_bus = true` (it moves with the player's bus); none: heard alike everywhere. The game's volume setting applies. A plugin plays 32 at most.

permission: audio

audio.playing(id: integer) → boolean

Whether a sound of the plugin's still plays.

audio.set(id: integer, opts: table) → boolean

Changes a sound of the plugin's: `volume`, `pitch`, `range`, `x, y, z` / `on_bus`.

permission: audio

audio.stop(id: integer) → boolean

Stops a sound of the plugin's.

permission: audio

audio.stop_all() → nil

Stops every sound of the plugin's.

permission: audio

audio.volume() → number or nil

The game's volume setting, 0 to 1.

bus.acceleration() → across, along, up

Its acceleration in its own frame, m/s² without gravity: to the right, forwards, up.

bus.action(name: string, down?: bool) → boolean

A key action of the vehicles (`[vehicles]` of keyboard.cfg: `horn`, `parking_brake_toggle`, `kw_scheinwerfer_toggle`, `blinker_left_set`, `ticket_give`, ...): pressed and let go, or held (`down` true) and let go (`false`). `true` when the bus knows it.

permission: vehicle_write

bus.controls() → throttle, brake, clutch, steering

What the bus drives with now: the pedals (0 to 1) and the steering (-1 left to 1 right), from the keys, the mouse or a controller.

bus.damage() → table or nil

`{crashes, last_impact_kj, repair_minutes}`: the bus's crashes, the energy of the last one and how long a repair would take (`nil`: nothing to repair).

bus.destination() → name, index

The destination the bus shows and its index in `destinations` (nothing when none).

bus.destinations() → list of tables

The destinations of the bus's depot file: `{index, code, name, all_exit}` (`index` from 1, for `set_destination`).

bus.dirt() → number or nil

How dirty the bus is, 0 (clean) to 1.

bus.door(n: integer) → boolean or nil

Whether door leaf `n` (from 1) is open.

bus.door_count() → integer

The doorways the door keys work, front to back.

bus.doors() → list of numbers

Each door leaf's position, front to back: 0 shut, 1 open (the scripts' `door_0`, `door_1`, ...).

bus.doors_open() → boolean or nil

Whether any door is open (by the passengers' door flags where the bus has them).

bus.electrics() → boolean or nil

Whether the bus's electrics are on (the main switch).

bus.engine() → running, rpm, electrics

The engine: whether it runs, its rpm (where the bus shows one) and whether the electrics are on.

bus.engine_running() → boolean or nil

Whether the engine runs.

bus.file() → string or nil

The bus's `.bus` file, relative to the game folder.

bus.fuel() → number or nil

The fuel in the tank, litres (the scripts' `engine_tank_content`).

bus.gear() → integer or nil

The gear engaged (-1 reverse, 0 neutral), where the bus shows one.

bus.get_strings(names?: table) → table

The same for string variables.

bus.get_vars(names?: table) → table

Many script variables at once: a table name -> value of the names given, or of every variable of the bus without a list.

bus.handbrake() → boolean or nil

Whether the parking brake is on.

bus.headlights() → integer or nil

The headlights: 0 off, 1 side lights, 2 dipped, 3 high beam.

bus.horn() → boolean or nil

Whether the horn sounds.

bus.indicator() → string or nil

The indicators: `"off"`, `"left"`, `"right"` or `"hazard"`.

bus.interior_light() → number or nil

The passenger room's light, 0 (off) to 1.

bus.km_today() → number or nil

Kilometres driven this session (as the personnel file counts them).

bus.kneeling() → boolean or nil

Whether the bus kneels.

bus.mass() → number or nil

The bus's mass in kg.

bus.number() → string or nil

The bus's fleet number.

bus.odometer() → number or nil

The bus's odometer in km.

bus.orientation() → heading, pitch, bank

Heading (degrees clockwise from north), pitch (nose up positive) and bank (right side down positive).

bus.passengers() → total, seated, standing

The people aboard the bus: all, sitting, standing.

bus.play_sound(event: string) → boolean

Plays the bus's own sound of this event (a trigger name of its sound files, `ev_...`).

permission: vehicle_write

bus.retarder() → number or nil

The retarder's step, where the bus has one.

bus.rpm() → number or nil

The engine's revolutions per minute.

bus.sales() → tickets, money

Tickets sold this session and the money taken (the game knows no currency).

bus.set_destination(index: integer) → boolean

Shows destination `index` (from 1, as `destinations` lists them).

permission: vehicle_write

bus.set_indicator(state: string) → boolean

Sets the indicators: `"off"`, `"left"`, `"right"` or `"hazard"`.

permission: vehicle_write

bus.set_interior_light(on: bool) → boolean

Switches the passenger room's light on or off.

permission: vehicle_write

bus.set_line(line: string) → boolean

Types a line (route) into the bus's IBIS, as the player would.

permission: vehicle_write

bus.set_vars(values: table) → integer

Sets many script variables at once (a table name -> number); how many the bus has.

permission: vehicle_write

bus.shift(gear: integer) → boolean

Puts a manual gearbox's lever in a gear (-1 reverse, 0 neutral).

permission: vehicle_write

bus.sound_horn(down: bool) → boolean

Holds the horn (`true`) or lets it go.

permission: vehicle_write

bus.start_up() → string or nil

Starts the bus up the way Shift+U does (the battery, the electrics, the engine) - or shuts a running bus down; what the game says it does.

permission: vehicle_write

bus.state() → table or nil

Everything a dashboard shows, in one table: `speed` (km/h, signed), `gear`, `engine` (running), `rpm`, `electrics`, `doors_open`, `indicator`, `headlights`, `dirt`, `passengers`, `odometer`, `km_today`, `throttle`, `brake`, `clutch`, `steering`, `fuel`, `handbrake`, `horn`, `stop_request` (a key is `nil` where the bus does not have it).

bus.steering_angle() → angle, max

The front wheels' angle and the most they turn, degrees (right positive).

bus.stop_brake() → boolean or nil

Whether the stop brake (the door brake) holds the bus.

bus.stop_requested() → boolean or nil

Whether a passenger has asked to stop.

bus.ticket_request() → name, price

The ticket the passenger at the cash desk asks for (nothing when nobody asks).

bus.tickets() → list of tables

The tickets the map sells: `{name, price, day_ticket}`.

bus.toggle_door(n?: integer) → boolean

Presses the key of doorway `n` (from 1; 0 or none: all doors), as the player would.

permission: vehicle_write

bus.toggle_handbrake() → boolean

Puts the parking brake on or off, as its key does.

permission: vehicle_write

bus.trailers() → integer or nil

Parts coupled behind the bus (an articulated bus's rear counts).

bus.triggers() → list of strings

The names of the bus's script triggers (for `trigger`, `press`).

bus.velocity() → number or nil

The bus's speed in km/h, negative backwards.

bus.velocity_vector() → x, y, z

Its velocity in the world, m/s (x east, y north, z up).

bus.wheels() → list of tables

Each wheel: `{axle, side, rpm, radius, suspension, driven}` (`side` 0 left, 1 right; `suspension` the spring's travel).

camera.fov() → number or nil

Its vertical field of view, degrees.

camera.get() → table or nil

The camera: `{view, x, y, z, yaw, pitch, roll, fov, in_cab, zoom, look_yaw, look_pitch, width, height}` - map metres, degrees (yaw clockwise from north, pitch up positive), the vertical field of view, the picture's pixels.

camera.in_cab() → boolean

Whether the camera is in the player's own bus (driver or passenger view).

camera.look(yaw: number, pitch: number) → boolean

Turns the head (driver, passenger view) or swings the outside camera round the bus: degrees from straight ahead.

permission: camera

camera.orientation() → yaw, pitch, roll

Where it looks, degrees.

camera.position() → x, y, z

Where the camera is (map metres).

camera.project(x: number, y: number, z: number) → screen_x, screen_y

Where a map point is seen on the screen, in the panels' pixels (as `ui.screen` measures them); nothing when it is behind the camera. For labels over buses, stops, people.

camera.set_free(x: number, y: number, z: number, yaw?: number, pitch?: number) → boolean

Puts the free camera at a map point looking along `yaw` and `pitch` (degrees); the view becomes `"free"` (the player moves it on from there).

permission: camera

camera.set_view(view: string) → boolean

Switches the view: `"driver"`, `"pax"`, `"outside"`, `"map"` (the free camera above the bus), `"ego"` (walking), or a `view_*` action of keyboard.cfg.

permission: camera

camera.set_zoom(zoom: number) → boolean

The zoom of the view now (its field of view times this, 0.2 to 3).

permission: camera

camera.view() → string or nil

The view: `"driver"`, `"pax"`, `"outside"`, `"free"` or `"foot"`.

cancel(id: integer) → boolean

Stops a timer, a watch or a hotkey; `true` when there was one.

clock() → string

The game's time of day as `"HH:MM:SS"`.

command(name: string) → boolean

Does what a line of the game menu does: `refuel`, `wash`, `repair`, `shot`, `save`, `load`, `weather`, `later`, `earlier`, `info`, `timetable`, `reset`, `couple`, `uncouple`; `true` when the game knows it (it runs after the frame).

permission: world_write

debug(...?: any) → nil

A line of the log's debug level (shown with `RUST_LOG=debug`).

distance(x: number, y: number) → number or nil

Metres from the bus to a map point, or `nil` on foot.

duty.active() → boolean

Whether the player drives a duty (a line and tour of the timetable).

duty.at_stop() → boolean

Whether the bus stands at the next stop (within 25 m of it).

duty.delay() → number or nil

Seconds the bus is late (early negative), worked out between the stops as the game's timetable does.

duty.finish() → boolean

Gives the duty up (the bus drives on without a timetable); `true` when there was one.

permission: world_write

duty.get() → table or nil

The duty now: `line`, `tour`, `trip` (its number in the duty, from 1), `trips`, `trip_name`, `terminus`, `departure`, `arrival`, `stops`, `next_stop` and `previous_stop` (each a stop: `{number, name, id, arrival, departure, stops, x, y, z}`), `at_stop`, `trip_done`, `delay` (seconds, late positive).

duty.next_stop() → table or nil

The next stop of the trip (as `duty.stops` gives them).

duty.skip_stop() → string or nil

Skips the next stop (the duty goes on to the one after); the name of the stop skipped.

permission: world_write

duty.skip_to(stop: integer) → boolean

Makes stop `stop` (from 1) of the trip the next one, forwards or back.

permission: world_write

duty.start(line: string, tour: string, trip?: integer, stop?: integer) → true, or false and the reason

Takes a duty, as the game menu's "Line and tour" does: a line and tour of `timetable.lines`, its trip (from 1 in the order they leave; default the first) and the stop to start at (from 1 among those the trip calls at; default the first). The bus stays where it is.

permission: world_write

duty.stops() → list of tables

The stops of the trip now: `{number, name, id, arrival, departure, stops, passed, x, y, z}` (`stops` false: the bus passes it; `x, y, z` where the stop's place is known; `id` the map's object id).

duty.trip_stops(trip: integer) → list of tables or nil

The stops of a trip of the duty (from 1), as `duty.stops` gives them.

duty.trips() → list of tables

The trips of the duty: `{number, name, line, terminus, departure, arrival, stops}`.

emit(event: string, ...?: any) → nil

Sends an event to this plugin's own handlers at once (handy between the modules of a bigger plugin); an error of a handler is this call's.

error(...?: any) → nil

The same as an error line (the plugin goes on).

every(seconds: number, fn: function) → integer id

Runs `fn` every `seconds` of game time.

files.append(path: string, data: string) → true, or false and the reason

Adds to the end of a file of the data folder (a log, a CSV of trips).

permission: storage

files.delete(path: string) → boolean

Removes a file or an empty folder of the data folder.

permission: storage

files.dir() → string

Where the data folder is on this computer (to tell the player; the plugin reaches it with relative paths only).

permission: storage

files.exists(path: string) → boolean

Whether the data folder has this file or folder.

permission: storage

files.list(dir?: string) → list of tables, or nil and the reason

The entries of the data folder (or a folder in it): `{name, dir, size}`.

permission: storage

files.mkdir(path: string) → boolean

Makes a folder (and those above it) in the data folder.

permission: storage

files.read(path: string) → text, or nil and the reason

A file of the plugin's data folder (`path` relative to it; `..` and absolute paths are refused).

permission: storage

files.write(path: string, data: string) → true, or false and the reason

Writes a file of the data folder (its folders are made); at most 16 MB at once and 256 MB in all.

permission: storage

fmt.clock(seconds: number, with_seconds?: bool) → string

Seconds since midnight as `"HH:MM"` (`"HH:MM:SS"` with `true`); past midnight wraps.

fmt.delay(seconds: number) → string

A delay as a timetable display shows it: `"+2:30"` late, `"-0:45"` early, `"0:00"`.

fmt.distance(metres: number) → string

A distance as `"350 m"` or `"2.4 km"`.

fmt.duration(seconds: number) → string

A length of time as people read it: `"45 s"`, `"3 min 05 s"`, `"1 h 20 min"` (negative with a minus).

fmt.money(amount: number, symbol?: string) → string

An amount with two decimals and a currency symbol after it (`"12.50 €"`; the game knows no currency of its own).

fmt.number(x: number, decimals?: integer, separator?: string) → string

A number with `decimals` (0) and a thousands `separator` (`","`, `" "`; none by default).

fmt.pad(text: string, width: integer, right?: bool) → string

A text made `width` characters long with spaces (on the left with `right` = true, to line numbers up), or cut to it.

fmt.speed(kmh: number, unit?: string) → string

A speed as `"42 km/h"`, or in `"mph"` or `"m/s"`.

fmt.split(text: string, separator?: string) → list of strings

A text cut at every `separator` (`","` by default; plainly, no patterns).

fmt.trim(text: string) → string

A text without the spaces at its ends.

game.action(name: string) → boolean

A game action of keyboard.cfg's `[game]` (`sim_pause`, `view_set_map`, `view_toggle_informationdisplay`, `view_set_schedule`, ...), as its key does; `true` when the game knows it.

permission: world_write

game.api() → integer

The version of the plugin interface (`api_abi` of an `.oop`; raised only when something is taken away or changes).

game.fps() → number or nil

Frames a second now.

game.has(name: string) → boolean

Whether this game has an API function (`"weather.set"`): for a plugin that should also run in an older openOMSI.

game.menu_open() → boolean

Whether the game menu is open.

game.notify(text: string, kind?: string, seconds?: number) → boolean

A notification of the game's own (the cards the server's messages use): `kind` `"info"`, `"warning"` or `"alert"`.

permission: ui

game.platform() → string

The system the game runs on: `"windows"`, `"macos"`, `"linux"`, `"android"`.

game.screenshot() → string or nil

Takes a screenshot with the next frame, as the camera key does; the file it goes to (the `screenshot` event says when it is there).

permission: ui

game.settings() → table

The settings a plugin may read: `graphics` (`"vanilla"`, `"vanilla_plus"`, `"enhanced"`), `language` (the cockpit's, `"ENG"`), `ui_language`, `ui_scale`, `volume`, `fov`, `render_scale`, `max_fps`, `fullscreen`, `vsync`, `msaa`, `shadows`, `time_speed`, `units` (`"metric"`: speeds are km/h everywhere), ...

game.stats() → table

This session's counts, as the personnel file has them: `km`, `stops_served`, `stops_skipped`, `crashes`, `heavy_crashes`, `pedestrians`, `tickets`, `cash`, `passengers`, ...

game.version() → string

The game's version (`"0.2.22"`).

has_vehicle() → boolean

`true` while the player drives a vehicle.

info() → table

What the game is doing: `map`, `clock` (seconds since midnight), `day`, `year`, `view`, `paused`, `on_foot`, `multiplayer`, `traffic`, `speed`, `delay`, `map_path`, `version`; with a bus also `tile_x`, `tile_y`, `tile_pos_x`, `tile_pos_y`, `heading`, `vehicle_manufacturer`, `vehicle_model`, `destination`, `passengers`; `crashes`, `heavy_crashes`, `pedestrians_hit`; `situation`; on a duty also `line`, `tour`, `trip`, `trips`, `trip_name`, `terminus`, `stops`, `trip_done`, `next_stop`, `next_stop_number`, `next_stop_arrival`, `next_stop_departure`, `next_stop_id`, `at_stop`, `previous_stop`, `previous_stop_id`, `next_stop_distance`, `previous_stop_distance` (see the plugin docs for each).

info_value(key: string) → any

One value of `info()` without building the whole table: cheaper for a plugin that reads one or two every frame.

input.bindings(vehicles?: bool) → list of tables

The key bindings: `{action, key}` of the game's keys, or the vehicles' with `true` (`key` as the game writes it: `"Ctrl+D"`).

input.controllers() → list of tables

The steering wheels, pedals, joysticks and gamepads: `{name, gamepad, axes, buttons}` (`axes` each axis's value; `buttons` how many it has - the `controller_button` event tells presses).

input.hotkey(keys: string, fn: function) → integer id

Runs `fn(key)` when a key combination is pressed: `"F10"`, `"Ctrl+KeyH"`, `"Shift+Alt+Digit1"` (modifiers exact: `"KeyH"` is not `Ctrl+KeyH`). The keys still reach the bus. `cancel(id)` removes it.

input.key_down(key: string) → boolean

Whether a key is held now (winit's names, as the `key` event: `"KeyW"`, `"ShiftLeft"`, `"F5"`).

input.keys_down() → list of strings

Every key held now.

input.mouse() → x, y, left, right, middle

The mouse: where it is in the panels' pixels and its buttons held.

json.decode(text: string) → value, or nil and the reason

Reads JSON text: objects and arrays become tables, `null` nil.

json.encode(value: any, pretty?: bool) → string

A value as JSON text (a list as an array, a table with keys as an object; `pretty`: indented).

lan.active() → boolean

Whether this game is in a LAN session.

lan.chat(text: string) → true, or false and the reason

Says a line in the session's chat, as the player would (every player sees it; at most one a second).

permission: lan

lan.me() → id, name, host

This player in the session: its id (the host is 1), its name, whether it hosts.

lan.players() → list of tables

The other players of the session: `{id, name, host, bus, line, tour, x, y, z, heading, speed, on_foot, passengers}`.

lan.send(to: integer, text: string) → true, or false and the reason

Sends a short text (at most 120 characters, no `|`) to the same plugin on another player's game (`to` its id; 0: every other player); it hears `lan_message(from, text)`. A player sends at most about ten a second; a game without the plugin ignores them.

permission: lan

log(...?: any) → nil

A line in `game.log`, tagged `[lua <name>]` (`print` does the same).

map.entrypoints() → list of tables

The map's start points: `{index, name, x, y, z, heading}` (`index` from 1; the place where the game has read its tile).

map.ground(x: number, y: number) → number or nil

The height of the ground (the road where there is one, else the terrain) at a map point, where its tile is loaded.

map.info() → table or nil

`{name, friendly_name, path, left_hand_traffic, tile_size}`: the map's names, its global.cfg and the side it drives on.

map.lane(x: number, y: number) → table or nil

The traffic lane nearest to a map point: `{index, distance, speed_limit, name, traffic_light}`.

map.name() → string or nil

The map's name (its folder's).

map.object(id: integer) → x, y, z, heading

Where a map object is, by its id (a stop's id of the timetable, say); nothing when the game has not read its tile.

map.objects_near(x: number, y: number, radius?: number) → list of tables

The map objects within `radius` m (default 50, at most 2000 of them, nearest first): `{id, x, y, z, heading, distance}`.

map.place_on_road(x: number, y: number) → boolean

Puts the player's bus on the street nearest to a map point (within 300 m), along it.

permission: world_write

map.speed_limit() → number or nil

The speed limit (km/h) of the lane the player's bus drives on (`nil` off the lanes).

map.stops() → list of tables

The bus stops of the tiles loaded (around the camera): `{id, name, x, y, z, heading}`.

map.teleport(x: number, y: number, z?: number, heading?: number) → boolean

Moves the player's bus to a map point (z none: onto the highest ground there) facing `heading` (default north), as the game menu's move does; the `service` event says `teleport`.

permission: world_write

map.teleport_to(index: integer) → boolean

Moves the player's bus to start point `index` (from 1, as `map.entrypoints` lists them).

permission: world_write

map.terrain(x: number, y: number) → number or nil

The terrain's height alone at a map point.

map.tile() → tile_x, tile_y

The tile the player's bus is on (nothing on foot).

map.tile_at(x: number, y: number) → tile_x, tile_y, local_x, local_y

The tile of a map point and the metres in it (x east, y north).

map.tiles() → list of tables

The map's tiles: `{x, y, file, loaded}` (numbered as global.cfg's `[map]` list).

map.to_world(tile_x: integer, tile_y: integer, local_x: number, local_y: number) → x, y

A place given by its tile and the metres in it, in map coordinates.

message(text: string, seconds?: number) → nil

A line of text on the screen (5 seconds when not given).

permission: ui

off(event: string, fn: function) → nil

Removes a handler added with `on`.

on(event: string, fn: function) → the function

Adds a handler of an event (see the events); several may hear one event, in the order they were added.

other_var(id: integer, name: string) → number or nil

A script variable of one of `others`, or `nil`.

others(radius?: number) → list of tables

The other vehicles within `radius` m of the bus (default 300): each `{id, kind, name, x, y, z, heading}`, `kind` being `"ai"` (the traffic) or `"player"` (another player's bus in a LAN game); empty on foot.

people.counts() → walking, waiting, riding

The people of the map near the camera: walking, waiting at stops, riding a bus.

people.density() → number or nil

The people setting: 0 to 3, 1 the map's own amount.

people.list(radius?: number) → list of tables

The people (within `radius` m of the player's bus, when given): `{id, x, y, z, state, aboard, ai_bus, stop, destination, ticket, complaint}`. `state`: `"strolling"`, `"idle"`, `"standing"`, `"waiting"`, `"to_bus"`, `"boarding"`, `"riding"`, `"seated"`, `"leaving"`, `"to_stop"`; `aboard` in the player's bus; `complaint` 0 to 3 (3: they leave).

people.set_density(value: number) → boolean

Changes the people setting (0 to 3).

permission: traffic_write

people.stops() → list of tables

The stops near the camera where people wait: `{id, name, x, y, z, waiting}`.

people.waiting(stop: integer) → integer

How many people wait at a stop (its map object id).

plugin.broadcast(topic: string, data?: any) → nil

Sends a message to every other plugin loaded.

plugin.disable(reason?: string) → nil

Switches the plugin off until its file changes or the game starts again (its `stop` comes).

plugin.errors() → integer

How many errors the plugin had (at 10 it is switched off).

plugin.files(dir?: string) → list of tables

The files of the plugin's own folder (or a folder in it): `{name, dir, size}`.

plugin.list() → list of strings

The names of the plugins loaded, this one too.

plugin.name() → string

The plugin's name: its file's, or its folder's for a `main.lua`.

plugin.permissions() → list of strings

The permissions the plugin has (a plain `.lua` file has them all).

plugin.read(path: string) → text, or nil and the reason

A file of the plugin's own folder (a table of stops, a translation): read only, relative to the folder.

plugin.send(to: string, topic: string, data?: any) → nil

Sends a message to another plugin (by its name): it hears `message(from, topic, data)` in its next frame. The data is numbers, texts, booleans or tables of them.

plugin.set_setting(key: string, value: any) → boolean

Changes a setting (held to its range; saved); `true` when it took the value.

plugin.setting(key: string) → any

A setting's value (`nil`: no such setting).

plugin.settings(settings: table, title?: string) → table

Declares the plugin's settings: a list of `{key, type, label, default}` with `type` `"bool"`, `"number"` (`min`, `max`, `step`), `"text"` or `"choice"` (`choices`, a list of texts). The values the player chose before come back (as a table key -> value); the game makes a settings panel of them (`plugin.show_settings`), saves them in the data folder and sends `setting(key, value)` when one changes.

plugin.show_settings(on?: bool) → boolean

Shows the plugin's settings panel (or hides it with `false`); it can be dragged and closed while the panels have the mouse (`ui.focus`). `false` when the plugin declared no settings.

permission: ui

position() → x, y, z, heading

Where the bus is: map metres (x east, y north, z up) and its heading in degrees clockwise from north; nothing on foot.

press(name: string) → nil

Holds a key of the bus down: fires the trigger `name` (let it go with `release`).

permission: vehicle_write

release(name: string) → nil

Lets a key go: fires `<name>_off`.

permission: vehicle_write

send(port: integer, data: string) → true, or false and the reason

Sends `data` as one UDP datagram to `127.0.0.1:port`: to another program on this computer, never over the network. Not sent when the port is below 1024 or one of the game's multiplayer ports (27015-27024), the message is longer than 8 KB, or the plugin sent 100 in the last second.

permission: network_local

set_other_var(id: integer, name: string, value: number) → boolean

Sets a script variable of one of `others`; `true` when that vehicle has it. An AI vehicle keeps it until its scripts write it again; another player's bus takes its values from the network again.

permission: traffic_write

set_str(name: string, text: string) → boolean

Sets a string variable; `true` when the bus has it.

permission: vehicle_write

set_var(name: string, value: number) → boolean

Sets a script variable; `true` when the bus has that variable.

permission: vehicle_write

speed() → number

The bus's speed in km/h, forwards or backwards (0 on foot).

storage.all() → table

Everything stored, as one table.

permission: storage

storage.clear() → nil

Removes every key.

permission: storage

storage.delete(key: string) → boolean

Removes a key; `true` when it was there.

permission: storage

storage.get(key: string) → any

A value the plugin stored, or `nil`. The storage is the plugin's own and survives the session (kept as `storage.json` in its data folder).

permission: storage

storage.keys() → list of strings

The keys stored, in the order they were first set.

permission: storage

storage.save() → nil

Writes the storage now (it is written by itself when the game ends).

permission: storage

storage.set(key: string, value: any) → nil

Stores a value under a key: a number, text, boolean or a table of them (`nil` removes it). It is written when the game ends, the plugin is loaded again, or `storage.save()` is called.

permission: storage

str(name: string) → string or nil

A string variable of the bus's scripts (`IBIS_terminus_name`).

sys(name: string) → number or nil

A system variable of the scripts: `Time`, `Day`, `Weather_Temperature`, `SunAlt`, ... (read only).

time() → number

Seconds of game time since the plugin started (stands still while paused).

timetable.buses() → list of tables

The timetable buses of the AI on the road: `{id, line, tour, trip, terminus, departure, next_stop_id, at_stop, trip_done, delay, x, y, number}`.

timetable.lines() → list of tables

The map's lines: `{name, user_allowed, tours}`, each tour `{number, today, trips}` (`today`: it runs on the game's date).

timetable.stop_names() → list of tables

The stops the timetable knows: `{id, name}` (`id` the map's object id).

timetable.stops(line: string, tour: string, trip?: integer) → list of tables

The stops of a tour's trips (or of its trip `trip`, from 1 in the order they leave) that the bus calls at: `{trip, station, name, departure}`.

traffic.ahead(reach?: number) → table or nil

The AI vehicle ahead of the player's bus within `reach` m (default 100) and 20° of its heading, with its `distance`: for a distance warning or a cruise control.

traffic.clear() → integer or nil

Takes every car not running to a timetable off the road; how many went.

permission: traffic_write

traffic.counts() → driving, buses, asleep, parked

The AI vehicles: driving, timetable buses among them, asleep out of range, parked.

traffic.density() → cars, share

How many cars the traffic keeps around the camera, and the share of them that do not run to a timetable (0 to 1).

traffic.get(id: integer) → table or nil

One AI vehicle by its id, as `traffic.list` gives them.

traffic.light_ahead(reach?: number) → table or nil

The traffic light the player's bus comes to within `reach` m (default 80): `{aspect, change_in, distance}` - `aspect` `"red"`, `"red_yellow"`, `"green"`, `"green_yellow"`, `"yellow"` or `"dark"`, `change_in` the seconds to its next change.

traffic.list(radius?: number) → list of tables

The AI vehicles (within `radius` m of the player's bus, when given): `{id, kind, name, x, y, z, heading, speed, max_speed, waiting_for, standing, braking, blinker, line, distance}`. `kind`: `"car"`, `"taxi"`, `"bus"`, `"truck"`, `"timetable_bus"`, `"tram"`, `"bicycle"`; `waiting_for` why it waits or slows (`"lead"`, `"light"`, `"yield"`, `"people"`, ...); `standing` the seconds it has stood.

traffic.nearest(kind?: string) → table or nil

The AI vehicle nearest to the player's bus (of that `kind`, when given), with its `distance`.

traffic.remove(id: integer) → boolean

Takes an AI vehicle off the road (a timetable bus too: its timetable forgets it); its passengers get out.

permission: traffic_write

traffic.set_density(cars: integer, share?: number) → boolean

Changes the traffic's amount (as the game menu's slider: 0 to 500 cars) and, when given, the share not running to a timetable; it fills up or thins out over the next seconds.

permission: traffic_write

trigger(name: string) → nil

A key press of the bus: fires the trigger, then `<name>_off`.

permission: vehicle_write

ui.clear() → nil

Removes every panel of the plugin.

permission: ui

ui.focus(on: bool) → boolean

`true`: the panels get the mouse (the cursor shows, a click goes to the panel under it and none to the bus); `false`, Esc or a menu of the game gives it back. Returns the new state.

permission: ui

ui.focused() → boolean

Whether the panels have the mouse.

ui.moved(panel: string) → dx, dy

How far the player dragged a panel from where its table puts it (pixels).

ui.panels() → list of strings

The ids of the plugin's panels.

ui.remove(id: string) → boolean

Removes a panel; `true` when there was one.

permission: ui

ui.screen() → width, height, scale

The screen in the panels' pixels, and how many of the screen's own pixels one of them is.

ui.set(id: string, panel: table) → true, or false and the reason

Creates the panel `id` or replaces it; a table that is not right gives `false` and where (`"children[2].size: a number is expected"`). The same table again changes nothing.

permission: ui

ui.show(panel: string, on?: bool) → boolean

Shows a panel (or hides it with `false`; it is kept); `false` when there is none.

permission: ui

ui.toast(text: string, opts?: table) → true, or false and the reason

A notification card at the top right, newest at the top; it goes after `opts.seconds` (1 to 60, default 5). `opts`: `title`, `icon`, `color`. A plugin shows 8 at most: a ninth makes its oldest go.

permission: ui

ui.toggle(panel: string) → boolean

Shows a hidden panel or hides a shown one; whether it shows now.

permission: ui

ui.typing() → boolean

Whether the player types into a text field of a plugin now (the keys then go to the field, not to the bus).

ui.update(panel: string, element: string, values: table) → true, or false and the reason

Changes one element of a panel in place, by its id: `text`, `color`, `value` (a bar, a slider), `checked`, `selected`, `name` (an icon), `values` (a chart), `rows` (a table), `src` (an image) - cheaper than setting the whole panel again.

permission: ui

ui.value(panel: string, element: string) → any

The value of a checkbox, slider, text field or tabs element now (as `ui_change` gives it).

permission: ui

util.date(seconds?: number) → table

A real time (`util.now()` by default) as `{year, month, day, hour, minute, second, weekday}` in UTC (`weekday` 1 Monday).

util.ms() → number

Milliseconds of real time since the game started: for timing a plugin's own work.

util.now() → number

The real time: seconds since 1970 (UTC), with fractions.

util.random(min?: number, max?: number) → number

A random number: 0 to 1 without arguments, else a whole number from `min` to `max` (as `math.random`, but not repeating the same row in every plugin).

var(name: string) → number or nil

A script variable of the bus (`Velocity`, `elec_busbar_main`, the names the `.osc` files and `.opl` lists use); `nil` without a bus or for a name it does not have.

vars(kind?: string) → list of strings

The names of every variable of the bus's scripts, or of every string variable with `"str"`.

vec.angle_diff(a: number, b: number) → number

The turn from heading `a` to heading `b`, -180 to 180 degrees (right positive).

vec.bearing(x1: number, y1: number, x2: number, y2: number) → number

The heading from one map point to another.

vec.clamp(x: number, min: number, max: number) → number

`x` held between `min` and `max`.

vec.distance(x1: number, y1: number, x2: number, y2: number) → number

Metres between two map points (on the ground: x and y).

vec.distance3(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number) → number

Metres between two points in space.

vec.dot(x1: number, y1: number, x2: number, y2: number) → number

The dot product of two 2D vectors.

vec.heading(dx: number, dy: number) → number

The heading of a direction on the map, degrees clockwise from north (0 to 360), as the game's headings.

vec.length(x: number, y: number, z?: number) → number

The length of a vector (2D, or 3D with `z`).

vec.lerp(a: number, b: number, t: number) → number

From `a` to `b` by `t` (0 to 1, not held to it).

vec.normalize(x: number, y: number, z?: number) → x, y, z

The vector made 1 long (0 stays 0).

vec.rotate(x: number, y: number, degrees: number) → x, y

A vector turned clockwise by `degrees` (as headings turn).

vec.to_local(x: number, y: number, ox: number, oy: number, heading: number) → right, ahead

A map point seen from a place facing `heading`: metres to the right and ahead of it.

vehicle() → string or nil

The vehicle's name (manufacturer and type), or `nil` on foot.

vehicle_manufacturer() → string or nil

The manufacturer part of the vehicle's name, as its `[friendlyname]` has it (`"Solaris III Gen"`).

vehicle_model() → string or nil

The model part of the vehicle's name (`"Urbino 10 / 2D"`).

warn(...?: any) → nil

The same as a warning.

watch(kind: string, name: string, fn?: function) → integer id

Runs `fn(new, old)` whenever a value changes: `watch(name, fn)` a variable of the bus, `watch(kind, name, fn)` of kind `"var"`, `"str"`, `"sys"` or `"info"` (a key of `info()`).

weather.get() → table or nil

The weather now: `{name, visibility (m), wind_direction (°), wind_speed (m/s), temperature (°C), humidity (%), absolute_humidity (g/m³), pressure (hPa), clouds, cloud_base (m), precipitation ("none", "rain", "snow"), precipitation_rate (0..1), snow_cover, snow_on_road, wetness (the roads, 0..1), changing, locked}` (`locked`: it follows a real weather station and cannot be set).

weather.precipitation() → kind, rate

`"none"`, `"rain"` or `"snow"`, and how hard (0 to 1).

weather.preset(file: string, seconds?: number) → true, or false and the reason

Changes to a weather file (as `weather.presets` names it; `""`: the map's own, changing with the day) over `seconds` (default 1).

permission: world_write

weather.presets() → list of tables

The weather files installed: `{file, name}`.

weather.set(values: table) → true, or false and the reason

Changes the weather as the game menu's sliders do; any of `visibility`, `wind_direction`, `wind_speed`, `temperature`, `pressure`, `clouds` (`"-1"` none, `"Cumulus 1"`..`"3"`, `"Overcast 1"`), `cloud_base`, `precipitation` (`"none"`, `"rain"`, `"snow"`), `precipitation_rate` (0..1), `snow_cover`, `snow_on_road`, `wetness`; the rest stays. Held to the game's ranges; refused in a LAN game as a client or while the weather follows a station.

permission: world_write

weather.temperature() → number or nil

The air temperature, °C.

weather.visibility() → number or nil

How far one sees, metres.

weather.wetness() → number or nil

How wet the roads are, 0 (dry) to 1.

weather.wind() → direction, speed

The wind: where it comes from (degrees) and its speed (m/s).

world.date() → table or nil

The game's date: `{year, month, day, weekday, day_of_year}` (`weekday` 1 Monday to 7 Sunday).

world.pause() → boolean

Pauses the game, as P does (not in a LAN game). The plugins stand still with it: the player resumes it.

permission: world_write

world.paused() → boolean

Whether the game stands still (a plugin hears `pause` and runs no more until `resume`).

world.play_time() → number or nil

Seconds played this session (game time, never wraps).

world.season() → folder, snow

The season's texture folder (`nil`: the base textures) and whether snow lies.

world.set_date(year: integer, month: integer, day: integer) → boolean

Sets the game's date (the season's textures follow).

permission: world_write

world.set_time(time: any) → boolean

Sets the time of day: seconds since midnight or `"HH:MM"` / `"HH:MM:SS"`, as the game menu's clock does (the timetable starts again after a jump of minutes). Not in a LAN game as a client, nor while the clock follows the computer's.

permission: world_write

world.set_time_speed(factor: number) → boolean

Sets how much faster the clock runs (1 to 30; not in a LAN game).

permission: world_write

world.sun_altitude() → number or nil

The sun's height over the horizon, degrees.

world.time() → number or nil

The game's time of day, seconds since midnight.

world.time_speed() → number or nil

How much faster than real time the game's clock runs (1 to 30).

Events

start()

Right after the plugin was loaded (also after a reload).

vehicle(name)

The player got into a vehicle, changed it, or left it (`nil`).

frame(dt)

Every frame of the game, after the bus's own scripts; not while paused. `dt` is the frame's seconds of game time.

stop()

The game ends, or the plugin is about to be loaded again.

key(key, down)

A key went down (`true`) or came up: winit's name of it (`"KeyH"`, `"F5"`, `"Numpad8"`).

next_stop(new, old)

The duty's next stop changed, also to one of the same name (`omsi.info().next_stop_number` tells them apart).

view(new, old)

The view changed (`"driver"`, `"pax"`, `"outside"`, `"free"`, `"foot"`).

duty(line, tour)

A line and tour were taken (or given up: `nil`).

crash(energy_kj, speed_kmh)

The player's bus crashed: every crash, also one the same as the last (the screen's "Crash: 136 kJ"); above 50 kJ it is a heavy one.

pedestrian(count)

The bus knocked people down.

stops_skipped(count, due_at, now_at)

The duty jumped ahead: the bus passed stops of its trip without stopping (or was moved) and is now at a later one; the stops are numbered in the trip from 1.

service(kind, by, amount)

The player's bus was serviced or moved. `kind`: `"refuel"` (amount: litres put in), `"wash"` (amount: the dirt left), `"repair"` (amount: the game minutes it took), `"reset"` or `"teleport"`; `by`: `"player"`, `"plugin"`, `"host"` or `"game"`.

trip_done(trip, how, driving, comfort, tickets)

A trip of the duty ended, once: its number in the duty, `"arrived"`, `"skipped"` or `"given_up"`, then its ratings in per cent (driving, comfort, ticket selling).

jolt(along, across, speed_kmh, passengers)

The bus braked, sped up or cornered hard enough to cost driving rating (m/s², signed); at most one a second.

ticket_sold(name, price)

A ticket was sold at the cash desk: its name and price as the bus's ticket list has them.

ui_click(panel, element)

A button (or another clickable part) of one of the plugin's panels was clicked; `element` is `nil` for the panel itself. Enter in a text field is a click on it.

ui_focus(focused)

The panels got the mouse or gave it back (also by Esc, or a menu of the game opening).

ui_change(panel, element, value)

A checkbox (`true`/`false`), slider (its number), text field (its text, at every key) or tabs element (the tab's number from 1) of the plugin's panels was changed by the player.

message(from, topic, data)

Another plugin sent this one a message (`plugin.send`, `plugin.broadcast`): its name, the topic and the data (numbers, texts, tables).

setting(key, value)

The player changed one of the plugin's settings in its settings panel (`plugin.settings`).

door(door, open)

A door leaf of the player's bus opened (`true`) or closed: its number from 1, front to back.

doors(open)

The bus's doors opened (`true`: one or more open) or were all closed.

engine_start()

The player's bus's engine started running.

engine_stop()

Its engine stopped.

gear(new, old)

The gear engaged changed (-1 reverse, 0 neutral), where the bus has a gearbox it shows.

indicator(new, old)

The indicators changed: `"off"`, `"left"`, `"right"` or `"hazard"`.

headlights(new, old)

The headlights changed: 0 off, 1 side lights, 2 dipped, 3 high beam.

horn(down)

The horn started (`true`) or stopped.

handbrake(on)

The parking brake was put on (`true`) or released.

stop_request(on)

A passenger asked to stop (`true`), or the request went out.

passengers(count, old)

The number of passengers aboard the player's bus changed.

passenger_board(count, stop_id)

People got into the player's bus: how many, and the stop they waited at (its map object id, `nil` when none).

passenger_alight(count)

People got out of the player's bus.

stop_arrive(name, id, number, delay)

The bus came to the duty's next stop (within 25 m of it): its name, map object id, number in the trip (from 1) and the delay in seconds (late positive).

stop_depart(name, id, number, delay)

The bus left the stop it stood at (more than 35 m from it, or the duty moved on): the same values, the delay as it left.

trip_start(trip, name, terminus)

The duty moved on to another trip: its number in the duty (from 1), the timetable's name of the trip and its terminus.

duty_start(line, tour)

A duty was taken.

duty_end(line, tour)

The duty was given up (or another taken: `duty_end` of the old one comes first).

destination(new, old)

The destination the bus shows changed.

coupled(parts, old)

Something was coupled to or uncoupled from the bus: the parts behind it now.

minute(hour, minute)

The game's clock reached a new minute (also when it was set).

hour(hour)

The game's clock reached a new hour.

day(year, month, day)

The game's date changed.

tile(x, y, old_x, old_y)

The player's bus drove onto another tile of the map (numbered as global.cfg's `[map]` list).

weather(name)

The weather changed: another weather file, rain or snow beginning or ending, the snow cover, the clouds.

light_ahead(aspect, distance)

The traffic light ahead of the bus (within 80 m) changed or a new one came: its aspect (`"red"`, `"red_yellow"`, `"green"`, `"green_yellow"`, `"yellow"`, `"dark"`, `nil` when none is ahead any more) and its distance in metres.

red_light(speed_kmh)

The bus drove past a traffic light showing red (or red and yellow) at more than 5 km/h.

speed_limit(kmh, old)

The speed limit of the lane the bus drives on changed.

ai_collision(id, energy_kj)

The player's bus hit an AI vehicle (its id, as `traffic.list` gives it) with this energy.

pause()

The game was paused (the plugins stand still until `resume`; nothing else comes in between).

resume()

The game goes on after a pause.

menu_open()

The game menu opened.

menu_close()

The game menu closed.

screenshot(file)

A screenshot was taken: its file.

controller_button(device, button, down)

A button of a steering wheel, joystick or gamepad went down (`true`) or up: the device's name and the button's number.

lan_join(id, name)

A player joined the LAN session (or came back).

lan_leave(id, name)

A player left the LAN session.

lan_message(from, data)

The same plugin on another player's game sent this one a message (`lan.send`): the player's id and the text.

lan_chat(name, text)

A line was said in the LAN session's chat (by another player or this one).