[0.13-0.15] [Library]Factorio Standard Library Project 0.8.0

[Afforess]

Type: Library
Name: Factorio Standard Library
Description: The Factorio Standard Library is a project to bring Factorio modders high-quality, commonly-required utilities and tools
License: MIT License
Version: 0.8.0
Release: 2017-01-12
Tested-With-Factorio-Version: 0.13.11+, 0.14.X, 0.15.X
Category: Library
Github: https://github.com/Afforess/Factorio-Stdlib
Releases: https://github.com/Afforess/Factorio-Stdlib/releases
Wiki: https://github.com/Afforess/Factorio-Stdlib/wiki
Lua Docs: http://afforess.github.io/Factorio-Stdlib/

What is the Factorio Standard Library?

Description

The Factorio Standard Library is a project to bring Factorio modders high-quality, commonly-required utilities and tools that developers have been often copying around, remixing, and rewriting poor quality copies of. Basic tools like logging, math calculations, and position or area manipulation, which often involve repeated operations or are commonly reproduced in mods have a high-quality, documented version in the Factorio Standard Library.

Why the Factorio Standard Library?

Why

Because I get sick of copying and pasting code. Because Rseding91 said if the project was high enough quality, it might be included in the base game and be available for all modders. And, because I can.

How do I use the Factorio Standard Library?

Examples

• Logging Example
• Avoiding iteration, and general stdlib tools
• Entity Data

See all examples on the wiki.

Contributing to the Factorio Standard Library

Contributions

I'm currently looking for contributions that add classes to manipulate Factorio positions, areas, and other common factorio data-structures. Any code you regularly re-use is also a candidate for inclusion. Open up a Pull Request and we can discuss it!

Version history

Versions

• Version 0.8.0 (No Breaking Changes)
  • Fixed loading error when train module was loaded before the game object existed
  • Fixed Trains.on_train_id_changed event not firing correctly
  • Deprecated Area.adjust, due to misleading name. (use Area.normalize instead)
  • 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
  • Added Entity.set_industructible, 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
  • Note: Thanks to Andy Hunt, Alex Aulbach, and Nexela for their contributions to 0.8.0!
• Version 0.7.0 (No Breaking Changes)
  • Fixed documentation for Entity.to_collision_area
  • Fixed documentation for Area.to_table
  • Changed Game.print_all to print to offline players (fixes https://github.com/Afforess/Factorio-St ... ues/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)
  • 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")
  • Note: Thanks to Andy Hunt, Alex Aulbach, and credomane for their contributions to 0.7.0!
• Version 0.6.0 (No Breaking Changes)
  • Fixed documentation for the Time module
  • Fixed missing newline in the documentation for the Logger.new function
  • Changed table.each to abort iteration if the callback returns true. Iteration continues for false, nil, or missing return values.
  • 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.*'`
  • Note: Thanks to dkaisers, lossycrypt, Choumiko, and credomane for their contributions to 0.6.0!
• Version 0.5.1 (No Breaking Changes)
  • 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
  • Note: Thanks to mojo2012 for the bug report
• Version 0.5.0 (No Breaking Changes)
  • 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 contants, 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
  • Note: Thanks to mojo2012, Choumiko, and Supercheese for their contributions to 0.5.0
• Version 0.4.0 (No Breaking Changes)
  • 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 Event.remove, allows events to be de-registered
  • Bugfix: Fixed incorrect parameters in Surface.find_all_entities
  • Note: Thanks to Choumiko for their contributions to 0.4.0
• Version 0.3.0 (No Breaking Changes)
  • Add Area.iterate function, allows iteration of the positions inside an area
  • Add Entity.has function, can safely test if an entity has read access to a field
  • Add Surface.lookup function, capable of converting strings, tables, or arrays to LuaSurface factorio object
  • Add Surface.find_all_entities function, searches all loaded chunks on surface(s) for all entities that match criteria
  • Add 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
  • Note: Thanks to Choumiko and TheOneFreeMankini for their contributions to 0.3.0
• Version 0.2.1 (No Breaking Changes)
  • Add Area.expand function, expands an area by a given amount
  • Add Area.shrink function, shrinks an area by a given amount
  • Correct documentation for Area.offset
• Version 0.2.0 (No Breaking Changes)
  • Add Position.distance_squared for Euclidean distances between two points
  • Add Position.distance for Euclidean distances between two points
  • Add Position.manhattan_distance for calculating the manhattan distance between two points
  • Add Entity.to_selection_area, creates an area that surrounds an entity selection box
  • Add Entity.to_collision_area, creates an area that surrounds an entity collision box
  • Add Area.inside function, tests if a position is inside an area
  • Add Area.offset function, offsets an area by a position
  • Add Area.round_to_integer function, rounds are to integer
  • Add 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 (No Breaking Changes)
  • Code is tested on circleci automatically
  • Position, Game, and Inventory modules are 100% unit-tested
  • Added inventory module, with copy_inventory function
  • Added many new functions to Position module, thanks to Choumiko!
  • Fixed Game.print_force and Game.print_surface, previously would msg all players, even not on those surfaces/forces.
• Version 0.0.6
  • Initial public release

[seronis]

Outstanding. Thank you for your work

[Supercheese]

Another nice bit to have would be a function to copy the contents of one inventory into another (perhaps even with filters to only copy certain types of items?)

A simplistic example:

Code: Select all

function copyInventory(from, to)
	local inventory = from.get_inventory(defines.inventory.chest)
	local contents = inventory.get_contents()
	for n, c in pairs(contents) do
		to.insert({name=n, count=c})
	end
end

I'm not sure the above code will work in all cases, though -- like for blueprints, it might not copy over the set-up blueprint but just give a blank one instead. And it hardcodes the #define for chest, rather than allowing others like player inventory, etc.

[Afforess]

Another nice bit to have would be a function to copy the contents of one inventory into another (perhaps even with filters to only copy certain types of items?)

A simplistic example:

Code: Select all

function copyInventory(from, to)
	local inventory = from.get_inventory(defines.inventory.chest)
	local contents = inventory.get_contents()
	for n, c in pairs(contents) do
		to.insert({name=n, count=c})
	end
end

I'm not sure the above code will work in all cases, though -- like for blueprints, it might not copy over the set-up blueprint but just give a blank one instead. And it hardcodes the #define for chest, rather than allowing others like player inventory, etc.

Inventory.copy_inventory is now in release 0.1.0.

Also notable, all of the code except the logging is currently unit tested. This actually caught a bug in the codebase, and has already proven valuable.

[Afforess]

Version 0.2.0 released. More functions, more unit tests, and now, error messages for missing arguments when using stdlib apis. See the API docs or changelog for details.

[Afforess]

Version 0.2.1 is released. Two new Area functions, and improved the documentation for the Area functions.

[MrDoomah]

Hey, perhaps you can include my code for finding all entities (or filtered entities):

Code: Select all

function create_number_table(array)
	local new_array = {}
	for _,v in pairs(array) do
		table.insert(new_array,v)
	end
	return new_array
end

function find_entities(input)
	-- input = {name = string, type = string, force = string or force, surface = string or {table of surface(s)}
	local array = {}
	
	if type(input.surface) == "string" then input.surface = {game.surfaces[input.surface]} end
	local surfaces = input.surface or game.surfaces
	
	for _,surface in pairs(surfaces) do
		for chunk in surface.get_chunks() do
			local entities = surface.find_entities_filtered{
				area = {left_top = {chunk.x*32, chunk.y*32}, right_bottom = {(chunk.x+1)*32, (chunk.y+1)*32}}, 
				name = input.name, 
				type = input.type, 
				force = input.force}
			for _,entity in ipairs(entities) do
				array["x"..entity.position.x.."y"..entity.position.y] = entity
			end
		end
	end
	return create_number_table(array)
end

Input is a table containing:
name (string)
type (string)
force (string or force (eg game.player.force)
surface (string eg "nauvis" or table of surfaces eg {game.player.surface}, you can't input game.player.surface directly without brackets)
all optional.

The create_number_array() function is optional, it just make sure that your returned array is nicely ordered so you can do a #operator on it.

It could technically overwrite entities if they are on the same spot since I just their location as key for the array. (This is on purpose so that entities that are on chuck borders don't appear twice in the array, without the need to check the array whether or not that entity is already in it.)

[Afforess]

Factorio Stdlib 0.3.0 is released, with many new additions. See the changelog for full details.

Hey, perhaps you can include my code for finding all entities (or filtered entities)

Thanks for the suggestion. 0.3.0 includes Surface.find_all_entities, which closely matches what you suggested.

[Afforess]

Factorio Standard Library 0.4.0 is released! Many improvements to core classes, like table and string. Factorio Standard Library is entirely forward compatible, if you are on an old version, there is zero risk in upgrading.

[Afforess]

I've updated the wiki with two new examples on how to use the Factorio Standard Library:

The first new example is on avoiding iteration, and general stdlib tools: https://github.com/Afforess/Factorio-St ... dlib-tools

The second new example is on how to take advantage of entity data storage: https://github.com/Afforess/Factorio-St ... ntity-data

[kasandraen]

I know a few functions I'd like to have easier acces to. dysoch use them a lot in Dytech. If you check Dytech Core and the Ovvrire functions, the functions like change recipe, addtorecipe etc are really helpful to use

[Afforess]

I know a few functions I'd like to have easier acces to. dysoch use them a lot in Dytech. If you check Dytech Core and the Ovvrire functions, the functions like change recipe, addtorecipe etc are really helpful to use

Sounds like a good idea. I haven't written a utility for the data class yet, but it is high on my list of things to improve.

[orzelek]

I know a few functions I'd like to have easier acces to. dysoch use them a lot in Dytech. If you check Dytech Core and the Ovvrire functions, the functions like change recipe, addtorecipe etc are really helpful to use

Sounds like a good idea. I haven't written a utility for the data class yet, but it is high on my list of things to improve.

You should talk with bobbingabout - he wrote boblibrary and those kind of functions are there already.

[Afforess]

I know a few functions I'd like to have easier acces to. dysoch use them a lot in Dytech. If you check Dytech Core and the Ovvrire functions, the functions like change recipe, addtorecipe etc are really helpful to use

Sounds like a good idea. I haven't written a utility for the data class yet, but it is high on my list of things to improve.

You should talk with bobbingabout - he wrote boblibrary and those kind of functions are there already.

I've seen and used a few of those myself for Marathon, so I know exactly what you are referring to

[jorgenRe]

Like this !

[CorrettoSambuca]

Hi, just leaving a note to say thanks for your work

By the way, is there an easy way to trigger events on a clock? For example every sunset and so on...

[y.petremann]

Something that would be really great would be a gui library (like what I already do in diplomacy) that would permit :

• Creating template (with styles) that can later be used needing less repetition of code and a better understanding of the code.
• Anonymous gui elements (sometimes you don't need a name for a label you never touch again)
• Advanced element event callback :
  • All : custom function callback and arguments per elements (like I do to pass arguments in diplomacy)
  • Checkbox : Current state
  • Text Area : Text content
  {*]Widgets groups : They will act like a single wigdet and so modifying a property would modify the widget inside it :
  • An example would be a progressbar with label.
  • Simple question dialog.
    {*]Item cell.

[Afforess]

Hi, just leaving a note to say thanks for your work

By the way, is there an easy way to trigger events on a clock? For example every sunset and so on...

There isn't (you could do an event on tick, and check the time of day), but clock events are an interesting idea.

[Afforess]

Something that would be really great would be a gui library (like what I already do in diplomacy) that would permit :

• Creating template (with styles) that can later be used needing less repetition of code and a better understanding of the code.
• Anonymous gui elements (sometimes you don't need a name for a label you never touch again)
• Advanced element event callback :
  • All : custom function callback and arguments per elements (like I do to pass arguments in diplomacy)
  • Checkbox : Current state
  • Text Area : Text content
  {*]Widgets groups : They will act like a single wigdet and so modifying a property would modify the widget inside it :
  • An example would be a progressbar with label.
  • Simple question dialog.
    {*]Item cell.

Yea, I have some minor experience with the GUI library, and I will suffice to say it could be massively improved by a library like stdlib. I agree with custom callbacks (the one giant event the game currently offers leads to terrible code most of the time), and the idea of creating gui templates is intriguing. I think there is a lot of ideas that for this particular part of the API.

[Afforess]

The Factorio Standard Library 0.5.0 is released, with a number of improvements & a few bug fixes:

Version 0.5.0

• 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 contants, 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
• Note: Thanks to mojo2012, Choumiko, and Supercheese for their contributions to 0.5.0