Factorio.com|Forums|Wiki|Mod Portal|API Docs

# Factorio Runtime Docs Version 2.0.77

# LuaHelpers - Runtime Docs

## Class LuaHelpers

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

## Members

table_to_json(data) | → string | Convert a table to a JSON string
Convert a table to a JSON string
json_to_table(json) | → AnyBasic? | Convert a JSON string to a table.
Convert a JSON string to a table.
write_file(filename, data, append?, for_player?) |  | Write a file to the `script-output` folder, located in the game's user data directory. [...]
Write a file to the `script-output` folder, located in the game's user data directory. [...]
send_udp(port, data, for_player?) |  | Send data to a UDP port on localhost for a specified player, if enabled. [...]
Send data to a UDP port on localhost for a specified player, if enabled. [...]
recv_udp(for_player?) |  | Dispatch defines.events.on_udp_packet_received events for any new packets received by the specified player or the server. [...]
Dispatch defines.events.on_udp_packet_received events for any new packets received by the specified player or the server. [...]
remove_path(path) |  | Remove a file or directory in the `script-output` folder, located in the game's user data directory. [...]
Remove a file or directory in the `script-output` folder, located in the game's user data directory. [...]
direction_to_string(direction) | → string | Converts the given direction into the string version of the direction.
Converts the given direction into the string version of the direction.
evaluate_expression(expression, variables?) | → double | Evaluate an expression, substituting variables as provided.
Evaluate an expression, substituting variables as provided.
encode_string(string) | → string? | Deflates and base64 encodes the given string.
Deflates and base64 encodes the given string.
decode_string(string) | → string? | Base64 decodes and inflates the given string.
Base64 decodes and inflates the given string.
parse_map_exchange_string(map_exchange_string) | → MapExchangeStringData | Convert a map exchange string to map gen settings and map settings. [...]
Convert a map exchange string to map gen settings and map settings. [...]
check_prototype_translations() |  | Goes over all items, entities, tiles, recipes, technologies among other things and logs if the locale is incorrect. [...]
Goes over all items, entities, tiles, recipes, technologies among other things and logs if the locale is incorrect. [...]
is_valid_sound_path(sound_path) | → boolean | Checks if the given SoundPath is valid. [...]
Checks if the given SoundPath is valid. [...]
is_valid_sprite_path(sprite_path) | → boolean | Checks if the given SpritePath is valid and contains a loaded sprite. [...]
Checks if the given SpritePath is valid and contains a loaded sprite. [...]
create_profiler(stopped?) | → LuaProfiler | Creates a LuaProfiler, which is used for measuring script performance. [...]
Creates a LuaProfiler, which is used for measuring script performance. [...]
compare_versions(first, second) | → int32 | Compares 2 version strings.
Compares 2 version strings.
multilingual_to_lower(input) | → string | Converts the given string to lowercase and returns it. [...]
Converts the given string to lowercase and returns it. [...]
object_name | :: R string | The class name of this object. [...]
The class name of this object. [...]
game_version | :: R string | Current version of game
Current version of game

## Methods

### table_to_json(data) → string

Convert a table to a JSON string

#### Parameters

data | :: table |

### json_to_table(json) → AnyBasic?

Convert a JSON string to a table.

#### Parameters

json | :: string | The string to convert.
The string to convert.

#### Return values

→ AnyBasic? | The returned object, or `nil` if the JSON string was invalid.

### write_file(filename, data, append?, for_player?)

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`.
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.
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`.
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.
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(port, data, for_player?)

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)
Destination port number (localhost only)
data | :: LocalisedString | The content to send.
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.
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(for_player?)

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.
If given, packets will only be read from this `player_index`. Providing `0` will only read from the server if present.

### remove_path(path)

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`.
The path to the file or directory to remove, relative to `script-output`.

### direction_to_string(direction) → string

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

#### Parameters

direction | :: defines.direction |

### evaluate_expression(expression, variables?) → double

Evaluate an expression, substituting variables as provided.

#### Parameters

expression | :: MathExpression | The expression to evaluate.
The expression to evaluate.
variables | :: dictionary[string → double]? | Variables to be substituted.
Variables to be substituted.

#### Example

    -- Calculate the number of research units required to unlock mining productivity level 10
    local formula = game.forces["player"].technologies["mining-productivity-4"].research_unit_count_formula
    local units = helpers.evaluate_expression(formula, { L = 10, l = 10 })

### encode_string(string) → string?

Deflates and base64 encodes the given string.

#### Parameters

string | :: string | The string to encode.
The string to encode.

#### Return values

→ string? | The encoded string or `nil` if the encode failed.

### decode_string(string) → string?

Base64 decodes and inflates the given string.

#### Parameters

string | :: string | The string to decode.
The string to decode.

#### Return values

→ string? | The decoded string or `nil` if the decode failed.

### parse_map_exchange_string(map_exchange_string) → MapExchangeStringData

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

Not available in settings and prototype stages.

#### Parameters

map_exchange_string | :: string |

### check_prototype_translations()

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(sound_path) → boolean

Checks if the given SoundPath is valid.

Not available in settings and prototype stages.

#### Parameters

sound_path | :: SoundPath | Path to the sound.
Path to the sound.

### is_valid_sprite_path(sprite_path) → boolean

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.
Path to the image.

### create_profiler(stopped?) → LuaProfiler

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
Create the timer stopped

### compare_versions(first, second) → int32

Compares 2 version strings.

#### Parameters

first | :: string | First version string to compare.
First version string to compare.
second | :: string | Second version string to compare.
Second version string to compare.

#### Return values

→ int32 | -1 if first is smaller than second, 0 if first equal second, 1 if first is greater than second.

### multilingual_to_lower(input) → string

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

#### Parameters

input | :: string |

#### Return values

→ string | The input string converted to lowercase.

## Attributes

### object_name :: Read string

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

Current version of game