settings

Read and write configuration options for CraftOS and your programs.

When a computer starts, it reads the current value of settings from the /.settings file. These values then may be read or modified.

Usage

• Define an basic setting 123 and read its value.

  settings.define("my.setting", {
      description = "An example setting",
      default = 123,
      type = number,
  })
  print("my.setting = " .. settings.get("my.setting")) -- 123

  You can then use the set program to change its value (e.g. set my.setting 456), and then re-run the example program to check it has changed.

Changes

• New in version 1.78

define(name [, options])Source

Define a new setting, optional specifying various properties about it.

While settings do not have to be added before being used, doing so allows you to provide defaults and additional metadata.

Parameters

1. name string The name of this option
2. options? { description? = string, default? = any, type? = string }

   Options for this setting. This table accepts the following fields:

   • description: A description which may be printed when running the set program.
   • default: A default value, which is returned by settings.get if the setting has not been changed.
   • type: Require values to be of this type. Setting the value to another type will error.

Changes

• New in version 1.87.0

undefine(name)Source

Remove a definition of a setting.

If a setting has been changed, this does not remove its value. Use settings.unset for that.

Parameters

1. name string The name of this option

Changes

• New in version 1.87.0

set(name, value)Source

Set the value of a setting.

⚠ warning

Calling settings.set does not update the settings file by default. You must call settings.save to persist values.

Parameters

1. name string The name of the setting to set
2. value The setting's value. This cannot be nil, and must be serialisable by textutils.serialize.

Throws

• If this value cannot be serialised

See also

• settings.unset

get(name [, default])Source

Get the value of a setting.

Parameters

1. name string The name of the setting to get.
2. default? The value to use should there be pre-existing value for this setting. If not given, it will use the setting's default value if given, or nil otherwise.

Returns

1. The setting's, or the default if the setting has not been changed.

Changes

• Changed in version 1.87.0: Now respects default value if pre-defined and default is unset.

getDetails(name)Source

Get details about a specific setting.

Parameters

1. name string The name of the setting to get.

Returns

1. { description? = string, default? = any, type? = string, value? = any } Information about this setting. This includes all information from settings.define, as well as this setting's value.

Changes

• New in version 1.87.0

unset(name)Source

Remove the value of a setting, setting it to the default.

settings.get will return the default value until the setting's value is set, or the computer is rebooted.

Parameters

1. name string The name of the setting to unset.

See also

• settings.set
• settings.clear

clear()Source

Resets the value of all settings. Equivalent to calling settings.unset

• on every setting.

@see settings.unset

getNames()Source

Get the names of all currently defined settings.

Returns

1. { string } An alphabetically sorted list of all currently-defined settings.

load([sPath])Source

Load settings from the given file.

Existing settings will be merged with any pre-existing ones. Conflicting entries will be overwritten, but any others will be preserved.

Parameters

1. sPath? string The file to load from, defaulting to .settings.

Returns

1. boolean Whether settings were successfully read from this file. Reasons for failure may include the file not existing or being corrupted.

See also

• settings.save

Changes

• Changed in version 1.87.0: sPath is now optional.

save([sPath])Source

Save settings to the given file.

This will entirely overwrite the pre-existing file. Settings defined in the file, but not currently loaded will be removed.

Parameters

1. sPath? string The path to save settings to, defaulting to .settings.

Returns

1. boolean If the settings were successfully saved.

See also

• settings.load

Changes

• Changed in version 1.87.0: sPath is now optional.