SANDBOX — this is a test environment. No servers are actually deployed and no real payments are charged.
Source-checkedLibraries & compatibility

Blueprint Manipulation Library

by The_LORD_thy_GOD · for Factorio

A utility library for other mods that need advanced manipulation of Factorio blueprints.

76KDownloads
3 mo agoLast updated
MITLicense
2.1Latest game version

About Blueprint Manipulation Library

From Factorio Mod Portal

A utility library for other mods that need advanced manipulation of Factorio blueprints.

bplib is a set of tools for use by other Factorio mods that need to manipulate blueprints.

Its primary purpose is to address the following pain points for developers working with custom entities that need advanced interaction with blueprints:

  • Abstracting over blueprints within or without books, in the library, in the inventory, etc. and treating them in a unified fashion.
  • Correctly identifying and updating pre-existing entities in the world when an overlapping blueprint is stamped down.
  • Correctly extracting blueprint tags from world entities into blueprints, including when blueprints are updated via "select new contents."
  • Doing all of the above while supporting absolute and relative snapping, offsets, books, libraries, the kitchen sink, etc.

Basic Usage

NOTE TO DEVELOPERS: As of Factorio 2.1, the previously-deprecated blueprint.lua API is removed altogether. You must port your mods to the new 2.0 API.

Extraction Events

bplib can raise an event whenever your custom entity is extracted into a user blueprint, giving you a writable blueprint object to which you can store custom tags. First register your entity for extraction events:

-- data.lua
-- Add one entry like this for every entity you want to track
data.raw["mod-data"]["bplib"].data.extract_entity_names["your-entity"] = true

Then bind-to and handle these events in control:

-- control.lua
script.on_event("bplib-extract", function(event)
  for blueprint_index, entity in pairs(event.entities)
    -- The event is raised for all mods, so you must filter for your mod's entities
    if entity.name == "your_entity" then
      event.blueprint.set_blueprint_entity_tags(blueprint_index, { your = "tags here" })
    end
  end
end)

The event object has the following type:

---@class bplib.ExtractEvent
---@field name "bplib-extract"
---@field tick MapTick
---@field player_index uint32 Player who is extracting entities into a blueprint.
---@field blueprint LuaItemStack|LuaRecord The blueprint that entities are being extracted into.
---@field entities {[uint32]: LuaEntity} Map from blueprint entity indices to world entities that were extracted into the blueprint.

Positions Events

bplib can raise an event whenever a player pre-builds a blueprint involving your custom entities. This event will tell you where in the world your custom entities will be built when the subsequent on_build events fire.

Register:

-- data.lua
-- Add one entry like this for every entity you want to track
data.raw["mod-data"]["bplib"].data.position_entity_names["your-entity"] = true

Handle:

-- control.lua
script.on_event("bplib-positions", function(event)
  for blueprint_index, pos in pairs(event.positions)
    -- The event is raised for all mods, so you must filter for your mod's entities
    if entity.name == "your_entity" then
      -- `pos` is where your entity will be built in the world.
    end
  end
end)

Event type:

---@class bplib.PositionsEvent
---@field name "bplib-positions"
---@field tick MapTick
---@field player_index uint32 Player who is applying a blueprint.
---@field blueprint LuaItemStack|LuaRecord The blueprint that is being applied.
---@field bbox BoundingBox The bounding box of the area where the blueprint is being applied.
---@field positions {[uint32]: MapPosition} Map from blueprint entity indices to world positions where those entities will be placed.
---@field orientation_info {position: MapPosition, direction: defines.direction, flip_horizontal?: boolean, flip_vertical?: boolean} Information about how the blueprint was oriented when placed
---@field surface_index The surface where the blueprint was placed.
---@field cause any The Factorio event that caused this bplib event.

Overlap Events

bplib can raise an event whenever a player pre-builds a blueprint where an entity in that blueprint would overlap with an entity with the same name (or ghost thereof) that already exists in the world. This can be used to correctly transfer custom entity settings onto the pre-existing entity.

Register:

-- data.lua
-- Add one entry like this for every entity you want to track
data.raw["mod-data"]["bplib"].data.overlap_entity_names["your-entity"] = true

Handle:

-- control.lua
script.on_event("bplib-overlaps", function(event)
  for blueprint_index, overlapped_entity in pairs(event.overlaps)
    -- The event is raised for all mods, so you must filter for your mod's entities
    if overlapped_entity.name == "your_entity" then
      local settings = event.blueprint.get_blueprint_entity_tags(blueprint_index)
      -- Apply your mod's logic here...
    end
  end
end)

Event type:

---@class bplib.OverlapsEvent
---@field name "bplib-overlaps"
---@field tick MapTick
---@field player_index uint32 Player who is applying a blueprint.
---@field blueprint LuaItemStack|LuaRecord The blueprint that is being applied.
---@field bbox BoundingBox The bounding box of the area where the blueprint is being applied.
---@field positions {[uint32]: MapPosition} Map from blueprint entity indices to world positions where those entities will be placed. This contains all positions that were calculated by bplib, regardless of overlap.
---@field overlaps {[uint32]: LuaEntity} Map from blueprint entity indices to world entities that overlap with those blueprint entities. This contains only overlaps.
---@field orientation_info {position: MapPosition, direction: defines.direction, flip_horizontal?: boolean, flip_vertical?: boolean} Information about how the blueprint was oriented when placed
---@field surface_index The surface where the blueprint was placed.
---@field cause any The Factorio event that caused this bplib event.

Dynamic Registration

Read the full description on Factorio Mod Portal →

Highlights

From source data

Game versions

Built for Factorio 2.1.

Footprint

Rated a light load on a server.

License

Published under MIT.

Blueprint Manipulation Library on Nxeon

From our catalogue
One-click install
Supported on Nxeon Factorio servers. We download it from Factorio Mod Portal, place it, and restart the server.
Server side
Required on the server
Server load
light
Smallest plan we suggest
Factorio — 2 GB (2 GB RAM). This follows our own load rating above, not a benchmark.
Latest build
2.1.4, released 2026-08-26

Run Blueprint Manipulation Library on a Factorio server

Pick a server or deploy a new one above; it is installed in one click.

What kind of mod it is

From the catalog
Listed on Factorio Mod Portal as “Mods”

Libraries & compatibility

Foundations and fixes other mods build on. Usually installed because something else needs it.

Runs on your server

From source side support

Factorio Mod Portal lists Blueprint Manipulation Library as required on the server. Check its Factorio Mod Portal page to see whether players need it too.

Compatibility

Game
Factorio
Runs on
Serverrequired on the server
Game versions
2.1

Verified at the source

  • ✓Factorio Mod PortalOfficial listing, checked 2026-10-08Open ↗
  • ✓AuthorThe_LORD_thy_GOD, as published on Factorio Mod Portal
  • ✓LicenseMITFree

Blueprint Manipulation Library, answered

Generated from the mod’s own source data.

Do my players need to install Blueprint Manipulation Library?

Factorio Mod Portal lists Blueprint Manipulation Library as required on the server. Check its Factorio Mod Portal page to see whether players need it too.

Is it free?

Yes. Blueprint Manipulation Library is free to download from Factorio Mod Portal. Its license is MIT.

How do I add it to my Nxeon server?

Use “Add to a server” on this page, or open NxLabs from your dashboard. We install it, restart your server and switch it on.

NxLabs

Run Blueprint Manipulation Library on a Factorio server.

Deploy in about a minute from $2.99 a month, then add Blueprint Manipulation Library in one click.