BlizzLib Documentation

Introduction

BlizzLib is a lightweight Factorio modding library designed to remove tedious parts of Factorio prototype creation and shorten commonly used syntax.

BlizzLib is designed to kill boilerplates.

BlizzLib was originally created as a personal tool but is available publicly for anyone who wants to use it.

If you find issues or have feature suggestions, feel free to report them. Suggestions are welcome and will be reviewed.

Setting Up BlizzLib

Adding BlizzLib as a Dependency

Add BlizzLib to your info.json:

{
    "dependencies": ["base","blizzlib"]
}

Loading BlizzLib

In your mod's data.lua, put these lines at the top:

mod_name = "your_mod_name"

local Blizz = require("__blizzlib__/lib-funcs")

Replace your_mod_name with your actual mod name.

mod_name is required for BlizzLib's custom icon system.

Using Multiple Prototype Files

You can write your entire mod inside data.lua, or split your prototypes into multiple files.

If using multiple files, they must be placed inside a folder named prototypes Example:

your-mod/
│
├── data.lua
│
└── prototypes/
    ├── items.lua
    ├── recipes.lua
    └── technologies.lua

Every prototype file must start with:

local Blizz = require("__blizzlib__/lib-funcs")

Then load them from data.lua:

require("prototypes.items")
require("prototypes.recipes")
require("prototypes.technologies")

Example:

require("prototypes.items")

loads:

prototypes/items.lua

Icon System

BlizzLib has a simplified icon system supporting both vanilla Factorio icons and custom mod icons.

Vanilla Icons

Use the BASE shortcut.

BlizzLib automatically converts underscores into hyphens.

Example:

BASE.iron_plate

becomes:

iron-plate

and loads:

__base__/graphics/icons/iron-plate.png

Custom Icons

Custom icons must be placed inside your mod's graphics folder.

Requirements:

• Must be a .png
• Must be 64x64 pixels
• Filename must match the icon name

Example:

your-mod/
└── graphics/
    └── advanced-machine.png

Usage:

icon = "advanced-machine"

BlizzLib loads:

__your-mod__/graphics/advanced-machine.png

Color System

BlizzLib supports colors using:

• Color names
• RGB tables
• Factorio color tables

Supported color names:

red
blue
yellow
green
pink
cyan
black
white
gray

Example:

color = "red"

RGB format:

color = {1, 0, 0}

Factorio format:

color = {
    r = 1,
    g = 0,
    b = 0
}

Creating Item Groups

Blizz.create_item_group()

Creates an item group.

Example:

Blizz.create_item_group({
    name = "my-group",
    icon = "group-icon",
    order = "a"
})

Properties:

Creating Item Subgroups

Blizz.create_item_subgroup()

Creates an item subgroup.

Example:

Blizz.create_item_subgroup({
    name = "my-subgroup",
    group = "my-group",
    order = "a"
})

Properties:

Creating Items

Blizz.create_item()

Creates an item prototype.

Example:

Blizz.create_item({
    name = "advanced-chip",
    icon = "advanced-chip",
    subgroup = "intermediate-products",
    order = "a",
    stack_size = 100
})

Properties:

Fuel Items

Items can be configured as fuel.

Example:

Blizz.create_item({
    name = "bio-fuel",

    fuel = {
        value = "10MJ",
        category = "chemical",
        emissions = 0.5
    }
})

Fuel properties:

Creating Fluids

Blizz.create_fluid()

Creates a fluid prototype.

Example:

Blizz.create_fluid({
    name = "coolant",
    icon = "coolant",
    color = "cyan",
    subgroup = "fluids",
    order = "a"
})

Properties:

Creating Recipes

Blizz.create_recipe()

Creates a recipe prototype.

Example:

Blizz.create_recipe({
    name = "advanced-chip",

    ingredients = {
        {"item", "iron-plate", 5},
        {"item", "copper-plate", 3}
    },

    results = {
        {"item", "advanced-chip", 1}
    },

    time = 5,
    recipe_type = "crafting",
    unlocked = false
})

Properties:

Ingredient Format

Format:

{"type", "name", amount}

Example:

{"item", "iron-plate", 5}

Result Format

Format:

{"type", "name", amount}

Example:

{"item", "advanced-chip", 1}

Creating Technologies

Blizz.create_tech()

Creates a technology prototype.

Example:

Blizz.create_tech({
    name = "advanced-machines",

    cost = 100,
    time = 30,

    sciences = {
        {"automation-science-pack", 1}
    },

    effects = {
        {"unlock-recipe", "advanced-machine"}
    }
})

Properties:

Technology Effects

Unlock Recipe

{"unlock-recipe", "recipe-name"}

Unlocks a recipe.

Give Item

{"give-item", "item-name", amount}

Gives an item when researched.

Patching Technologies

Blizz.patch_tech()

Modifies an existing technology.

Example:

Blizz.patch_tech("automation", {
    add = {
        {"unlock-recipe", "new-recipe"}
    }
})

Properties:

Removing Effects

Example:

Blizz.patch_tech("automation", {
    remove = {
        "old-recipe"
    }
})

Changing Existing Prototypes

BlizzLib can modify existing Factorio prototypes.

Blizz.change_item()

Example:

Blizz.change_item("iron-plate", {
    stack_size = 200,
    order = "a"
})

Properties:

Blizz.change_recipe()

Example:

Blizz.change_recipe("iron-gear-wheel", {
    time = 2
})

Properties:

Blizz.change_fluid()

Example:

Blizz.change_fluid("water", {
    color = "blue"
})

Properties:

Blizz.change_tech()

Example:

Blizz.change_tech("automation", {
    cost = 50,
    time = 20
})

Properties:

Current Status

This documentation is a work in progress.

More features, examples, and explanations will be added later.