LuaHelpers

Provides various helper and utility functions. It is accessible through the global object named helpers in all stages (settings, prototype and runtime).

Attributes

object_name

• Read: string
• Write: unknown
• Optional: false

The class name of this object. Available even when valid is false. For LuaStruct objects it may also be suffixed with a dotted path to a member of the struct.

game_version

• Read: string
• Write: unknown
• Optional: false

Current version of game

Methods

table_to_json

LuaHelpers.table_to_json(data: table) -> string

Call As

helpers.table_to_json(data)

Call Convention

• takes_table: false
• table_optional: false

Convert a table to a JSON string

Parameters

• data: table

Returns

• string

json_to_table

LuaHelpers.json_to_table(json: string) -> AnyBasic?

Call As

helpers.json_to_table(json)

Call Convention

• takes_table: false
• table_optional: false

Convert a JSON string to a table.

Parameters

• json: string — The string to convert.

Returns

• AnyBasic? — The returned object, or nil if the JSON string was invalid.

write_file

LuaHelpers.write_file(filename: string, data: LocalisedString, append?: boolean, for_player?: uint32)

Call As

helpers.write_file(filename, data, true)

Call Convention

• takes_table: false
• table_optional: false

Write a file to the script-output folder, located in the game's user data directory. The name and file extension of the file can be specified via the filename parameter.

Parameters

• filename: string — The name of the file. Providing a directory path (ex. "save/here/example.txt") will create the necessary folder structure in script-output.
• data: LocalisedString — The content to write to the file.
• append?: boolean — If true, data will be appended to the end of the file. Defaults to false, which will overwrite any pre-existing file with the new data.
• for_player?: uint32 — If given, the file will only be written for this player_index. Providing 0 will only write to the server's output if present. for_player cannot be used in settings and prototype stages.

send_udp

LuaHelpers.send_udp(port: uint16, data: LocalisedString, for_player?: uint32)

Call As

helpers.send_udp(port, data, for_player)

Call Convention

• takes_table: false
• table_optional: false

Send data to a UDP port on localhost for a specified player, if enabled.

This must be enabled per-instance with --enable-lua-udp.

Parameters

• port: uint16 — Destination port number (localhost only)
• data: LocalisedString — The content to send.
• for_player?: uint32 — If given, the packet will only be sent from this player_index. Providing 0 will only send from the server if present. for_player cannot be used in settings and prototype stages.

recv_udp

LuaHelpers.recv_udp(for_player?: uint32)

Call As

helpers.recv_udp()

Call Convention

• takes_table: false
• table_optional: false

Dispatch defines.events.on_udp_packet_received events for any new packets received by the specified player or the server.

This must be enabled per-instance with --enable-lua-udp.

UDP socket when enabled requests 256KB of receive buffer from the operating system. If there is more data than this between two subsequent calls of this method, data will be lost. That also applies to periods when the game is paused or is being saved as in those case the game update is not happening.

Note: lua event is not raised immediately as the UDP packet needs to be introduced into game state by means of input actions. Please keep incoming traffic as small as possible as in case of multiplayer game with many players, all this data will have to go through the multiplayer server and be distributed to all clients.

Not available in settings and prototype stages.

Parameters

• for_player?: uint32 — If given, packets will only be read from this player_index. Providing 0 will only read from the server if present.

remove_path

LuaHelpers.remove_path(path: string)

Call As

helpers.remove_path(path)

Call Convention

• takes_table: false
• table_optional: false

Remove a file or directory in the script-output folder, located in the game's user data directory. Can be used to remove files created by LuaHelpers::write_file.

Parameters

• path: string — The path to the file or directory to remove, relative to script-output.

direction_to_string

LuaHelpers.direction_to_string(direction: defines.direction) -> string

Call As

helpers.direction_to_string(direction)

Call Convention

• takes_table: false
• table_optional: false

Converts the given direction into the string version of the direction.

Parameters

• direction: defines.direction

Returns

• string

evaluate_expression

LuaHelpers.evaluate_expression(expression: MathExpression, variables?: Dict<string, double>) -> double

Call As

helpers.evaluate_expression(expression, variables)

Call Convention

• takes_table: false
• table_optional: false

Evaluate an expression, substituting variables as provided.

Parameters

• expression: MathExpression — The expression to evaluate.
• variables?: Dict<string, double> — Variables to be substituted.

Returns

• double

encode_string

LuaHelpers.encode_string(string: string) -> string?

Call As

helpers.encode_string(string)

Call Convention

• takes_table: false
• table_optional: false

Deflates and base64 encodes the given string.

Parameters

• string: string — The string to encode.

Returns

• string? — The encoded string or nil if the encode failed.

decode_string

LuaHelpers.decode_string(string: string) -> string?

Call As

helpers.decode_string(string)

Call Convention

• takes_table: false
• table_optional: false

Base64 decodes and inflates the given string.

Parameters

• string: string — The string to decode.

Returns

• string? — The decoded string or nil if the decode failed.

parse_map_exchange_string

LuaHelpers.parse_map_exchange_string(map_exchange_string: string) -> MapExchangeStringData

Call As

helpers.parse_map_exchange_string(map_exchange_string)

Call Convention

• takes_table: false
• table_optional: false

Convert a map exchange string to map gen settings and map settings.

Not available in settings and prototype stages.

Parameters

• map_exchange_string: string

Returns

• MapExchangeStringData

check_prototype_translations

LuaHelpers.check_prototype_translations()

Call As

helpers.check_prototype_translations()

Call Convention

• takes_table: false
• table_optional: false

Goes over all items, entities, tiles, recipes, technologies among other things and logs if the locale is incorrect.

Also prints true/false if called from the console.

Not available in settings and prototype stages.

is_valid_sound_path

LuaHelpers.is_valid_sound_path(sound_path: SoundPath) -> boolean

Call As

helpers.is_valid_sound_path(sound_path)

Call Convention

• takes_table: false
• table_optional: false

Checks if the given SoundPath is valid.

Not available in settings and prototype stages.

Parameters

• sound_path: SoundPath — Path to the sound.

Returns

• boolean

is_valid_sprite_path

LuaHelpers.is_valid_sprite_path(sprite_path: SpritePath) -> boolean

Call As

helpers.is_valid_sprite_path(sprite_path)

Call Convention

• takes_table: false
• table_optional: false

Checks if the given SpritePath is valid and contains a loaded sprite. The existence of the image is not checked for paths of type file.

Not available in settings and prototype stages.

Parameters

• sprite_path: SpritePath — Path to the image.

Returns

• boolean

create_profiler

LuaHelpers.create_profiler(stopped?: boolean) -> LuaProfiler

Call As

helpers.create_profiler()

Call Convention

• takes_table: false
• table_optional: false

Creates a LuaProfiler, which is used for measuring script performance.

LuaProfiler cannot be serialized.

Not available in settings and prototype stages.

Parameters

• stopped?: boolean — Create the timer stopped

Returns

• LuaProfiler

compare_versions

LuaHelpers.compare_versions(first: string, second: string) -> int32

Call As

helpers.compare_versions(first, second)

Call Convention

• takes_table: false
• table_optional: false

Compares 2 version strings.

Parameters

• first: string — First version string to compare.
• second: string — Second version string to compare.

Returns

• int32 — -1 if first is smaller than second, 0 if first equal second, 1 if first is greater than second.

multilingual_to_lower

LuaHelpers.multilingual_to_lower(input: string) -> string

Call As

helpers.multilingual_to_lower(input)

Call Convention

• takes_table: false
• table_optional: false

Converts the given string to lowercase and returns it. Unlike string.lower(), this function supports non-Latin characters.

Parameters

• input: string

Returns

• string — The input string converted to lowercase.