Factorio Standard Library 2.1 Continued

A community-maintained continuation of the Factorio Standard Library for Factorio 2.1.

The library provides reusable Lua utilities, data-stage helpers, runtime event handling, geometry tools, entity wrappers and common helper functions for other Factorio mods.

This package is primarily intended as a dependency for other mods. It normally does not add visible gameplay content by itself.

Important

This is not an official release from the original Standard Library maintainers.

The continuation exists to support mods that still depend on the library while updating its APIs and internal behaviour for Factorio 2.1.

If the original maintainers return and wish to continue the project, this continuation can be archived, redirected or transferred as appropriate.

Compatibility

Factorio 2.1
Base game required
Space Age compatible
Internal mod name: stdlib2-continued

Mods must use the new dependency and import paths.

Example dependency:

"stdlib2-continued >= 2.1.1"

Example runtime import:

local Event = require("__stdlib2-continued__/stdlib/event/event")

The original stdlib2 internal mod name and __stdlib2__/ import root are not provided by this continuation.

Purpose

Factorio mods frequently need the same types of utility code:

Event registration
Player and force lifecycle handling
Table and string helpers
Position and area calculations
Prototype manipulation
Entity and inventory wrappers
Configuration management
Logging and debugging
Migration helpers
Queue management

The Standard Library collects these features into one shared dependency so individual mods do not need to maintain separate copies.

Runtime event system

The event module provides a central interface for registering and managing Factorio runtime events.

Features include:

Registering one or more event IDs
Registering nth-tick handlers
Combining multiple handlers
Protected handler execution
Lifecycle hooks
Build and mining event groups
Player event registration
Force event registration
Surface event registration
Mod-version change handling
Remote interface integration

The protected-event mode can catch and report handler failures instead of immediately terminating the entire event chain.

Dependent mods should still validate queued entities, players and surfaces before using them because Factorio objects may become invalid between events.

Player helpers

The player module provides helpers for tracking player-specific data and reacting to player lifecycle events.

Supported use cases include:

Creating default player data
Initialising joining players
Handling removed players
Tracking player indexes
Responding to controller changes
Managing player-specific state
Accessing common player events through one registration interface

Force helpers

The force module provides similar lifecycle support for Factorio forces.

It can help dependent mods:

Initialise force-specific storage
Respond to force creation
Handle merged forces
Track force data
Register force event callbacks
Manage shared state across multiplayer forces

Surface helpers

Surface helpers provide tools for surface lifecycle handling and surface-related calculations.

The continuation updates surface and statistics behaviour for the Factorio 2.1 runtime APIs.

Diagnostic exports can write statistics separately for each surface and force.

Position, area and direction utilities

The library includes utility modules for working with Factorio coordinates and geometry.

Available helpers include:

Position comparison
Position copying
Position flooring
Position translation
Position distance
Position rotation
Position orientation
Bounding-box manipulation
Area expansion
Area offsetting
Area iteration
Chunk conversion
Tile conversion
Direction conversion
Orientation conversion

These helpers are commonly used for entity searches, blueprint processing, construction ranges and spatial calculations.

Data-stage prototype helpers

The data modules provide wrappers around Factorio prototype tables.

Supported prototype types include:

Items
Fluids
Recipes
Technologies
Entities
Resources
Categories
Inventory-related prototypes

Typical operations include:

Copying prototypes
Extending prototypes
Modifying ingredients
Modifying recipe results
Adding technology unlocks
Changing recipe categories
Working with prototype icons
Updating subgroup and ordering data
Validating prototype existence

Factorio 2.1 recipe categories are handled using the current categories array while preserving convenient library methods.

Recipe utilities

The recipe module provides higher-level helpers for recipe manipulation.

Examples include:

Adding ingredients
Removing ingredients
Replacing ingredients
Adding products
Removing products
Copying recipes
Enabling or disabling recipes
Adding recipe unlocks to technologies
Changing crafting categories
Working with normalised ingredient definitions

These helpers are especially useful for compatibility patches between content mods.

Entity and inventory helpers

The entity modules provide wrapper functions for common LuaEntity and LuaInventory operations.

Use cases include:

Entity validation
Entity copying
Inventory iteration
Item insertion and removal
Resource handling
Entity lookup
Position-based entity operations
Inventory content checks

Dependent mods should still account for Factorio 2.1 item quality when passing item stack definitions.

Utility modules

The continuation includes general-purpose modules for:

Tables
Strings
Mathematics
Colours
Linked lists
Unique arrays
Enumerable collections
Type checking
Logging
Configuration files
Queues
Migration utilities

These modules can be imported individually. Mods do not need to load the entire library when only one utility is required.

Example:

local Position = require("__stdlib2-continued__/stdlib/area/position")
local Table = require("__stdlib2-continued__/stdlib/utils/table")

Debug and export helpers

The library includes optional debugging and diagnostic export functions.

Factorio 2.1 continuation updates include:

helpers.write_file
helpers.remove_path
helpers.table_to_json
storage instead of the removed global table
Per-surface production statistics
Per-force diagnostic exports

Available exports may include:

Event data
Player data
Force data
Surface data
Mod storage
Item production statistics
Fluid production statistics
Pollution statistics
Kill counts
Entity build counts

These functions are primarily intended for mod developers and troubleshooting.

Factorio 2.1 continuation changes

The continuation contains a broad compatibility update for Factorio 2.1.

Notable changes include:

New internal mod name: stdlib2-continued
New import root: __stdlib2-continued__/
Updated Factorio 2.1 metadata
Updated LuaObject detection
Updated recipe category handling
Updated runtime helper APIs
Updated persistent storage handling
Updated per-surface statistics
Updated direction handling for the expanded direction enum
Updated test fixtures
Updated package generation
Updated automated releases

Testing

The continuation includes the restored historical test suite and additional Factorio 2.1 compatibility checks.

Automated checks include:

Metadata validation
Import-root validation
Lua 5.2 syntax validation
Factorio-compatible ZIP validation
More than 500 Busted unit tests
Package and checksum generation

Passing unit tests do not guarantee that every possible dependent mod is compatible. Mods using undocumented internal behaviour may still require changes.

For mod developers

Add the library as a dependency in info.json:

{
  "dependencies": [
    "base >= 2.1",
    "stdlib2-continued >= 2.1.1"
  ]
}

Import only the modules required by your mod:

local Event = require("__stdlib2-continued__/stdlib/event/event")
local Position = require("__stdlib2-continued__/stdlib/area/position")
local Recipe = require("__stdlib2-continued__/stdlib/data/recipe")

Do not use the original import path:

require("__stdlib2__/...")

Mods migrating from the older library should search their entire source tree for:

stdlib2
__stdlib2__/
Old Factorio runtime helper APIs
Direct uses of the removed global table
Pre-2.1 recipe category assumptions

Known scope

The continuation aims to preserve the existing Standard Library API where practical.

However, compatibility cannot be guaranteed for every historical mod because:

Some mods used undocumented internal functions
Some Factorio APIs were removed or redesigned
Item quality may require changes in dependent mods
Recipe and prototype schemas have changed
Runtime objects may behave differently in Factorio 2.1

Please report missing compatibility functions with an example of the dependent mod and the exact error.

Reporting problems

Please report reproducible library problems through the GitHub issue tracker:

https://github.com/goakiller900/stdlib2/issues

Include:

Factorio version
Standard Library version
The dependent mod name and version
The failing import or function
The complete error message
A minimal reproduction when possible
factorio-current.log when relevant

Source code

https://github.com/goakiller900/stdlib2

Credits

Original Factorio Standard Library by Afforess, Jackie P. Mueller and the historical project contributors.

Factorio 2.1 continuation maintained by Goakiller900.

Thanks to the original maintainers, contributors, test authors and dependent mod developers whose work made the library useful across many Factorio releases.