os

The os API allows interacting with the current computer.

loadAPI(path)
pullEvent(filter)
pullEventRaw(filter)
version()
run(env, path, ...)
clock()Returns the number of seconds that the computer has been running.
cancelAlarm(token)Cancels an alarm previously started with setAlarm.
shutdown()Shuts down the computer immediately.
startTimer(timer)Starts a timer that will run for the specified number of seconds.
setAlarm(time)Sets an alarm that will fire at the specified world time.
date([formatA[, timeA]])Returns a date string (or table) using a specified format string and optional time to format.
cancelTimer(token)Cancels a timer previously started with startTimer.
time([locale])Returns the current time depending on the string passed in.
day([args])Returns the day depending on the locale specified.
setComputerLabel([label])Set the label of this computer.
getComputerLabel()Returns the label of the computer, or nil if none is set.
computerLabel()Returns the label of the computer, or nil if none is set.
getComputerID()Returns the ID of the computer.
computerID()Returns the ID of the computer.
queueEvent(name, ...)Adds an event to the event queue.
reboot()Reboots the computer immediately.
epoch([args])Returns the number of seconds since an epoch depending on the locale.
loadAPI(path)Source

Parameters

  1. path
pullEvent(filter)Source

Parameters

  1. filter
pullEventRaw(filter)Source

Parameters

  1. filter
version()Source
run(env, path, ...)Source

Parameters

  1. env
  2. path
  3. ...
clock()Source

Returns the number of seconds that the computer has been running.

Returns

  1. number The computer's uptime.
cancelAlarm(token)Source

Cancels an alarm previously started with setAlarm. This will stop the alarm from firing.

Parameters

  1. token number The ID of the alarm to cancel.

See also

shutdown()Source

Shuts down the computer immediately.

startTimer(timer)Source

Starts a timer that will run for the specified number of seconds. Once the timer fires, a timer event will be added to the queue with the ID returned from this function as the first parameter.

Parameters

  1. timer number The number of seconds until the timer fires.

Returns

  1. number The ID of the new timer.

Throws

  • If the time is below zero.

setAlarm(time)Source

Sets an alarm that will fire at the specified world time. When it fires, an alarm event will be added to the event queue.

Parameters

  1. time number The time at which to fire the alarm, in the range [0.0, 24.0).

Returns

  1. number The ID of the alarm that was set.

Throws

  • If the time is out of range.

date([formatA[, timeA]])Source

Returns a date string (or table) using a specified format string and optional time to format.

The format string takes the same formats as C's strftime function (http://www.cplusplus.com/reference/ctime/strftime/). In extension, it can be prefixed with an exclamation mark (!) to use UTC time instead of the server's local timezone.

If the format is exactly *t (optionally prefixed with !), a table will be returned instead. This table has fields for the year, month, day, hour, minute, second, day of the week, day of the year, and whether Daylight Savings Time is in effect. This table can be converted to a UNIX timestamp (days since 1 January 1970) with date.

Parameters

  1. formatA? string The format of the string to return. This defaults to %c, which expands to a string similar to "Sat Dec 24 16:58:00 2011".
  2. timeA? number The time to convert to a string. This defaults to the current time.

Returns

  1. any The resulting format string.

Throws

  • If an invalid format is passed.

cancelTimer(token)Source

Cancels a timer previously started with startTimer. This will stop the timer from firing.

Parameters

  1. token number The ID of the timer to cancel.

See also

time([locale])Source

Returns the current time depending on the string passed in. This will always be in the range [0.0, 24.0).

  • If called with ingame, the current world time will be returned. This is the default if nothing is passed.
  • If called with utc, returns the hour of the day in UTC time.
  • If called with local, returns the hour of the day in the timezone the server is located in.

This function can also be called with a table returned from date, which will convert the date fields into a UNIX timestamp (number of seconds since 1 January 1970).

Parameters

  1. locale? string | table The locale of the time, or a table filled by os.date("*t") to decode. Defaults to ingame locale if not specified.

Returns

  1. any The hour of the selected locale, or a UNIX timestamp from the table, depending on the argument passed in.

Throws

  • If an invalid locale is passed.

See also

  • date To get a date table that can be converted with this function.
day([args])Source

Returns the day depending on the locale specified.

  • If called with ingame, returns the number of days since the world was created. This is the default.
  • If called with utc, returns the number of days since 1 January 1970 in the UTC timezone.
  • If called with local, returns the number of days since 1 January 1970 in the server's local timezone.

Parameters

  1. args? string The locale to get the day for. Defaults to ingame if not set.

Returns

  1. number The day depending on the selected locale.

Throws

  • If an invalid locale is passed.

setComputerLabel([label])Source

Set the label of this computer.

Parameters

  1. label? string The new label. May be nil in order to clear it.
getComputerLabel()Source

Returns the label of the computer, or nil if none is set.

Returns

  1. string The label of the computer.
computerLabel()Source

Returns the label of the computer, or nil if none is set.

Returns

  1. string The label of the computer.
getComputerID()Source

Returns the ID of the computer.

Returns

  1. number The ID of the computer.
computerID()Source

Returns the ID of the computer.

Returns

  1. number The ID of the computer.
queueEvent(name, ...)Source

Adds an event to the event queue. This event can later be pulled with os.pullEvent.

Parameters

  1. name string The name of the event to queue.
  2. ... The parameters of the event.

See also

reboot()Source

Reboots the computer immediately.

epoch([args])Source

Returns the number of seconds since an epoch depending on the locale.

  • If called with ingame, returns the number of seconds since the world was created. This is the default.
  • If called with utc, returns the number of seconds since 1 January 1970 in the UTC timezone.
  • If called with local, returns the number of seconds since 1 January 1970 in the server's local timezone.

Parameters

  1. args? string The locale to get the seconds for. Defaults to ingame if not set.

Returns

  1. number The seconds since the epoch depending on the selected locale.

Throws

  • If an invalid locale is passed.