Factorio Standard Library

by Nexela

The Factorio Standard Library is a project to bring Factorio modders high-quality, commonly-required utilities and tools.

1 year, 7 months ago
0.17 - 1.1


Version: 1.4.8
Date: 2022-11-27
    - Fix a crash in Event.get_event_handler(event_id) (#159)
Version: 1.4.7
Date: 2022-06-04
    - Dispatched events with a nil filter function will return the pattern as the second argument. #157
    - Remove __DebugAdapter mutates.
Version: 1.4.6
Date: 2020-11-25
    - Added Entity:count_circuit_connections.
    - Added Event:on_init_if, Event:on_load_if, Event.on_event_if.
    - Added Data:Util:extend_style_by_name.
    - Added Entity:find_resources.
    - Inventory:transfer_inventory returns a dictionary of filters if dest can't hold them.
    - Removed Entity:destroy_entity, Entity:create_entity, Entity:revive_entity.
Version: 1.4.5
Date: 2020-09-22
    - Added Position:flip.
    - Added Position:swapped and Position:flipped mutates.
    - Added Area:min, Area:max, Area:width, Area:height, Area:rectangle.
    - Potential optimization with Queue.
Version: 1.4.4
Date: 2020-08-23
    - Fix error with Inventory:get_blueprint on empty blueprint books.
Version: 1.4.3
Date: 2020-05-24
    - Add Orientation module.
    - Add Direction module.
    - Added mod name to some log events.
    - Use raise_built instead of manual events.
Version: 1.4.2
Date: 2020-03-19
    - Added Item:add_to_labs.
    - Added Item:remove_from_labs.
    - Added Entity:change_lab_inputs.
    - Added Inventory.swap_inventory.
    - Added Inventory.transfer_inventory.
    - Replace Color with Color2 see Docs.
    - Added Table.all
Version: 1.4.1
Date: 31.1.2020

    - Fix changelog formatting and errors.

    - Added Interface.get_global and Interface.get_globals.

    - String_Array changed to a function return.
    - Removed Core __index to itself.
    - Standardized __index requires.
    - Remove data.lua file as it is no longer needed.
Version: 1.4.0
Date: 26.1.2020

    - Update to Factorio 0.18
Version: 1.3.0
Date: 21.7.2019

    - Added Position:random.
    - Added Position:update.
    - Added Position:to_string_xy.
    - Added Position:normalized, ceiled, floored, rounded for modifying the position in place.
    - Added Position:is_Position, is_simple_position, is_complex_position.
    - Added Area:update.
    - Added Area:to_string_xy.
    - Added Area:is_normalized.
    - Added Area:dimensions.
    - Added Area:rectangle.
    - Added Area:is_Area, is_simple_area, is_complex_area.
    - Added new Color module (color2).

    - Position:center correctly looks inwards when on a boundry.
    - Area:center_points correctly looks inwards when on a boundry.
    - Technology:add_pack type check fix.

    - Area:iterate, spiral_iterate can return a position object.
    - Removed safetostring.
    - Area/Position:set is now Area/Position:load.
    - Area:normalized now normalizes the area in place.
Version: 1.2.2
Date: 21.7.2019

    - Added Gui.on_confirmed.
Version: 1.2.1
Date: 13.7.2019

    - Added Event.core_events.init_and_load.
    - Added Direction.to_vector.

    - Factorio doesn't allow requiring in functions no moar.
Version: 1.2.0
Date: 22.6.2019

    - Added Position:flip_x, Position:flip_y
    - Added Queue:peek_at, push_at, pop_at, next, rnext.
    - Added Queue[i] support for pushing or overwriting items in the queue.
    - Added STDLIB global variable containing factorio-stdlib specific scripts.
    - Added globals concat, safetostring.

    - Everything is unified under __class
Version: 1.1.1
Date: 14.6.2019

    - Made Event.dispatch more effecient.

    - Event.dispatch does not pcall on Core Events if protected mode is set.

    - Events can now be registered with a table of options to overide the default set options.
Version: 1.1.0
Date: 4.6.2019

    - Event shortcuts have proper return.

    - Added Event.on_event.
    - Added Table.unique_values.
    - Added Game. write_mods()/write_statistics()/write_surfaces().

    - Updated the readme and wiki.
    - Removed mod_name requirement from Logger. Any mods using this module may need to remove the mod_name paramater when creating a new logger.
Version: 1.0.7
Date: 4.6.2019

    - Fix Changes logic for real this time.
Version: 1.0.6
Date: 4.6.2019

    - Fix Changes logic.
Version: 1.0.5
Date: 4.6.2019

    - Added Event.set_protected_mode().
    - Added Player.pdata().
    - Added Quickstart chart_size_multiplier config.
    - Added vendor script version (simple semvar).
    - Added vendor script pulsar (A* pathfinding).

    - Changes module no longer uses pcall. Changes files will need to be registered.

  Minor Features:
    - Added thumbnail.
    - Added settings namespace to the test data loader.
    - Add settings namespace to the test data loader
Version: 1.0.4
Date: 4.6.2019

    - Fix quickstart script deleting the character.

  Minor Features:
    - Added magic deploy script.
Version: 1.0.3
Date: 4.6.2019

    - Fix player->character renames for .17.35
Version: 1.0.2
Date: 4.6.2019

    - Actually include the data.lua file in the release.
Version: 1.0.1
Date: 4.6.2019

    - Add data.lua file to trick Factorio into thinking this mod changes the game.
Version: 1.0.0
Date: 4.6.2019

  Major Features:
    - Initial Release as a library mod.
    - Initial Release of the Data library

    - Added inspect available as a global function a prettier table printer.
    - Added vendor scripts; beholder, bump, cron, enumerable, inspect, md5, memoize, middleclass, mm, semver, serpent, stateful

    - All modules and classes are local by default.
    - All global variables have been eliminated.
    - Any module that registers events must have their register_events() function called.
    - Module locations have been moved around to have a more consistent structure. Check out the API docs.
    - Area/Position are now returned as objects.
    - Remove marker debug entities in favor of built in rendering.
Version: 0.8.0
Date: 1.27.2017

    - Added Entity.set_indestructible, toggles an entity so that it can not be damaged or mined by either the player or other forces
    - Added Entity.set_frozen, toggles an entity as inactive, making it inoperable and non-rotatable
    - Added Surface.get_surface_bounds, creates an area that represents the generated boundaries of a surface

    - Changed Surface.find_all_entities to support area search criteria
    - Changed Inventory.copy_inventory to support itemstacks with durability, health or ammo
    - Changed Trains.find_filtered to support the entity type in the search criteria. Defaults to 'locomotive'
    - Changed Entity.set_data/Entity.get_data to use a unit's unit_number as a key for data, enhancing performance for entities who have unit_numbers
    - Deprecated Area.adjust, due to misleading name. (use Area.normalize instead)

    - Fixed loading error when train module was loaded before the game object existed
    - Fixed Trains.on_train_id_changed event not firing correctly
Version: 0.7.0
Date: 30.9.2016

    - Added Area.adjust, modifies area to ensure x,y coordinate values are normalized
    - Added Area.construct, creates an area from two pairs of x,y coordinates
    - Added Area.size, replaces the deprecated function, Area.area.
    - Added Position.copy, creates a copy of a position
    - Added Position.construct, creates a position from an x,y pair
    - Added table.find, searches a table for the first element that matches the function
    - Added table.any, searches a table and returns true if any elements matches the function
    - Added Trains module, providing train utility methods and events:
    - Added Trains.set_data, sets persistent mod data on a train
    - Added Trains.get_data, gets mod data on a train
    - Added Trains.on_train_id_changed event, contains the old and new id of the train, and fires when a train id changes (e.g. locomotives are added to an existing train)
    - Added Trains.find_filtered, searches and returns a table of trains on surface(s) for trains that match the area, name, or state criteria
    - Added Trains.get_train_id, returns the train id of a train
    - Added Trains.get_main_locomotive, finds and returns the main locomotive entity of any train
    - Added Time-based events, require 'stdlib/event/time' to enable them, then register the events to script them.
    - Event.Time.sunset, fires an event when sunset occurs for a surface
    - Event.Time.sunrise, fires an event when sunrise occurs for a surface
    - Event.Time.midday, fires an event noon occurs for a surface
    - Event.Time.midnight, fires an event when midnight occurs for a surface
    - Event.Time.minutely, fires an event when an in-game minute passes
    - Event.Time.hourly, fires an event when an in-game hour passes
    - Event.Time.daily, fires an event when an in-game day passes
    - Added Config system, for easier management of persistent mod configuration
    - Added Config.new, ex: Config.new(global.config) creates a new configuration, stored at global.config
    - Added config.set, allows setting a value at nested paths, ex: (Config.new(global.config).set("your.path.here", foo)
    - Added config.get, allows getting nested values, ex: (Config.new(global.config).get("your.path.here")
    - Added config.delete, deletes a value at a config path, ex: (Config.new(global.config).delete("your.path.here")
    - Added config.is_set, tests whether a config value is set or not, ex: (Config.new(global.config).is_set("your.path.here")

    - Changed Game.print_all to print to offline players (fixes <https://github.com/Afforess/Factorio-Stdlib/issues/49>)
    - Deprecated Game.print_force (use force.print instead)
    - Deprecated Game.print_surface (use surface.print instead)
    - Deprecated Area.area, due to misleading name. (use Area.size instead)

    - Fixed documentation for the Entity.to_collision_area
    - Fixed documentation for the Area.to_table
Version: 0.6.0
Date: 30.7.2016

    - Added table.keys, when passed a table, returns a copy of all the keys in the table
    - Added table.values, when passed a table, returns a copy of all of the values in the table
    - Added table.flatten, when passed a table, creates a copy of the table where inner nested tables were flattened into the outer table
    - Added table.min, when passed an array, returns the minimum value
    - Added table.max, when passed an array, returns the maximum value
    - Added table.sum, when passed an array, adds up all the values and returns the sum
    - Added table.avg, when passed an array, calculates the average value
    - Added Area.area, calculates the size an area occupies
    - Added Tile.adjacent, given a tile, returns a list of adjacent tile positions  (N, E, S, W) or (N, NE, E, SE, S, SW, W, NW), depending if diagonal tiles are specified.
    - Added Position.equals method, to test whether two positions are at the same x,y coordinate positions
    - Added string.split, which when given a separator, will split a string apart on the separator, returning a list of substrings
    - Added string.is_empty, to test if a string is nil or the empty string
    - Added a GUI event handler system. Multiple handlers for each event can be registered, using regex patterns to match element names.
    - Gui.on_click(pattern, callback) fires a click event to the callback for any gui element whose name that matches the pattern
    - Gui.on_checked_state_changed(pattern, callback) fires a on_checked_state_change event to the callback for any gui element whose name that matches the pattern
    - Gui.on_text_changed(pattern, callback) fires a on_text_changed event to the callback for any gui element whose name that matches the pattern
    - Added a Data module, which allows for easier search and manipulation of data structures
    - Data.select, when given a selection string, returns a list of all data.raw elements that matched the selection. The returned list is backed by the real data.raw and changes to it are reflected in the data.raw and therefore the game.
    - `Data.select('recipe') -- returns a table with all recipes`
    - `Data.select('recipe:steel.*') -- returns a table with all recipes whose name matches 'steel.*'``
    - `Data.select('recipe:steel.*').energy_required = 1 -- sets all recipes whose name matches 'steel.*' to require 1 energy to produce`
    - `Data.select('recipe:steel.*').apply('energy_required', 1) = 1 -- sets all recipes whose name matches 'steel.*' to require 1 energy to produce. Apply returns itself, so apply function calls can be chained.`
    - Recipe.select, when given a selection string, returns a list of all recipe elements in data.raw that matched the selection. The returned list is backed by the real data.raw and changes to it are reflected in the data.raw and therefore the game.
    - `Recipe.select('steel.*:ingredients') -- returns a table with all ingredients from all recipes whose name matches 'steel.*'`
    - `Recipe.select('steel.*:ingredients:iron-plate') -- returns a table with all iron-plate ingredient objects, from all recipes whose name matches 'steel.*'`

    - Changed table.each to abort iteration if the callback returns true. Iteration continues for false, nil, or missing return values.

    - Fixed documentation for the Time module
    - Fixed missing newline in the documentation for the Logger.new function
Version: 0.5.1
Date: 4.7.2016

    - Fixed Event registry not notifying of an error in an event handler when the game was loaded, but no players were connected to the game
Version: 0.5.0
Date: 12.6.2016

    - Improved table.map, filter, and each to also include additional arguments and index.
    - Added Event.core_events, allows registering Events for on_init, on_load, and on_configuration_changed
    - Added options to Logger.new, adds option to modify the file extension and alter the timestamp format
    - Added Chunk.get to calculate the chunk coordinates for a given tile position
    - Added Chunk.get_data, retrieves mod data stored on a chunk position
    - Added Chunk.set_data sets mod data on a chunk position
    - Added Tile.from_position, calculates tile coordinates from a position
    - Added Tile.to_area, returns the area that a single tile occupies
    - Added Tile.get_data, retrieves mod data stored on a tile position
    - Added Tile.set_data, sets mod data on a tile position
    - Added Area.spiral_iterate, is an alternate iterator (compared to Area.iterate) that iterates the Area in an inside-out spiral fashion
    - Added Area.center, returns the center position of an Area
    - Added string.contains, tests if a string contains a substring
    - Added Time constants, provides easy reference for Time.SECOND, Time.MINUTE, Time.HOUR, Time.DAY, and Time.WEEK in factorio tick time
    - Improved the lua docs, so they share the same look and feel as the factorio lua docs

    - Fixed Logger writing after one hour instead of one minute
    - Fixed Event registry with Event.core_events.init not raising errors correctly
Version: 0.4.0
Date: 9.5.2016

    - Added string.trim(), which can remove leading and trailing whitespace from a string
    - Added string.starts_with(...), tests if a string starts with a given substring
    - Added string.ends_with(...), tests if a string ends with a given substring
    - Added Entity.get_data, retrieves persistent mod-data associated with an entity
    - Added Entity.set_data, sets or removes persistent mod-data associated with an entity
    - Added table.each, iterates a table and applies a function to each value in the table
    - Added table.filter, iterates a table and returns a copy that contains all the elements that passed the filter
    - Added table.first, returns the first item in the array
    - Added table.last, returns the last item in the array
    - Added table.map, returns a copy of the table transformed by the function
    - Added table.merge, merges table b into table a, overwriting any duplicate entries in table a with values in table b
    - Improved Event Registry
    - Added access to the event handler reference (the function handling the event) in event._handler
    - Added Event.remove, allows events to be de-registered

    - Fixed incorrect parameters in Surface.find_all_entities
Version: 0.3.0
Date: 24.4.2016

    - Added Area.iterate function, allows iteration of the positions inside an area
    - Added Entity.has function, can safely test if an entity has read access to a field
    - Added Surface.lookup function, capable of converting strings, tables, or arrays to LuaSurface factorio object
    - Added Surface.find_all_entities function, searches all loaded chunks on surface(s) for all entities that match criteria
    - Added Event Registry, provides alternate Event registration from script.on_event.
    - Event.register allows multiple event handlers to be registered for the same event
    - Events that cause an error will not abort the game but print a warning to all players
    - Events handlers cascade and can be aborted. Returning true in an event handler prevents any later handlers from being executed.

    - Clarified documentation for Logger.log
Version: 0.2.1
Date: 12.4.2016

    - Added Area.expand function, expands an area by a given amount
    - Added Area.shrink function, shrinks an area by a given amount

    - Correct documentation for Area.offset
Version: 0.2.0
Date: 6.4.2016

    - Added Position.distance_squared for Euclidean distances between two points
    - Added Position.distance for Euclidean distances between two points
    - Added Position.manhattan_distance for calculating the manhattan distance between two points
    - Added Entity.to_selection_area, creates an area that surrounds an entity selection box
    - Added Entity.to_collision_area, creates an area that surrounds an entity collision box
    - Added Area.inside function, tests if a position is inside an area
    - Added Area.offset function, offsets an area by a position
    - Added Area.round_to_integer function, rounds are to integer
    - Added Area.to_table function, converts area to x/y, left_top/right_bottom format
    - Majority of functions now give error messages for missing arguments
Version: 0.1.0
Date: 6.6.2016

    - Added Inventory.copy_inventory function
    - Added Position.add function
    - Added Position.subtract function
    - Added Position.translate function
    - Added Position.tostring function
    - Unit testing with [busted lua library](http://olivinelabs.com/busted)
Version: 0.0.6
Date: 6.6.2016

    - Initial release