Merging chests Factorio mod

Since 5.0.0 the mod has support for other contributors to create merged variants of chests they created. This readme is trying to explain this process.

Adding support for another chest

Create a mod which is dependant on "WideChests >= 5.0.0" and mod with the chest which should be mergable.

Settings stage

MergingChests.create_mergeable_chest_setting

Call MergingChests.create_mergeable_chest_setting to register new chest to create mod settings to make the chest mergable.

This function has two arguments:

• chest_name (type string) - name of the chest entity prototype
• options (type object) - Object for modifying default behaviour. Has following properties
  • disable_chest (type boolean) - Removes possibility to merge 1xN and Nx1 chests. Defaults to false.
  • disable_warehouse (type boolean) - Removes possibility to merge chests into warehouses. Defaults to false.
  • disable_chest (type boolean) - Removes possibility to merge chests into trashdumps. Defaults to false.
  • default_value (type string) - Default value for the created mod setting. Defaults to maximum not disabled option. Possible values:
    • none
    • chest
    • warehouse
    • chest-warehouse
    • trashdump
    • chest-trashdump
    • warehouse-trashdump
    • chest-warehouse-trashdump
  • order (type string) - Used to allow sorting the created mod settings. Final mod setting's order will be either 01-{order}-01 or 99-{order}-01 (if there are some custom settings enabled, see below). Defaults to chest_name parameter.
  • size_settings (type boolean) - Creates additional mod settings for setting maximum width, height, area and whitelist specifically for this mergable chest. Defaults to false.
  • inventory_settings (type boolean) - Creates additional mod settings for setting inventory size multiplier and inventory size limit specifically for this mergable chest. Defaults to false.
  • threshold_setting (type boolean) - Creates additional mod setting for warehouse threshold specifically for this mergable chest. Defaults to false.
  • circuit_connection_setting (type boolean) - Creates additional mod setting for circuit connector position specifically for this mergable chest. Defaults to false.

Following translations should be provided:

• [chest-name] WideChests_wide-chest-name
  • If options.disable_chest was not set
• [chest-name] WideChests_high-chest-name
  • If options.disable_chest was not set
• [chest-name] WideChests_chest-name-warehouse
  • If options.disable_warehouse was not set
• [chest-name] WideChests_chest-name-trashdump
  • If options.disable_trashdump was not set
• [mod-setting-name] WideChests_mergeable-chest-chest-name
• [mod-setting-name] WideChests_max-chest-width-chest-name
  • If options.size_settings was set
• [mod-setting-name] WideChests_max-chest-height-chest-name
  • If options.size_settings was set
• [mod-setting-name] WideChests_max-chest-area-chest-name
  • If options.size_settings was set
• [mod-setting-name] WideChests_max-chest-area-chest-name
  • If options.size_settings was set
• [mod-setting-name] WideChests_whitelist-chest-sizes-chest-name
  • If options.size_settings was set
• [mod-setting-name] WideChests_mirror-whitelists-chest-name
  • If options.size_settings was set
• [mod-setting-name] WideChests_inventory-size-multiplier-chest-name
  • If options.inventory_settings was set
• [mod-setting-name] WideChests_inventory-size-limit-chest-name
  • If options.inventory_settings was set
• [mod-setting-name] WideChests_warehouse-threshold-chest-name
  • If options.threshold_setting was set
• [mod-setting-name] WideChests_circuit-connector-position-chest-name
  • If options.circuit_connection_setting was set
• [string-mod-setting] WideChests_mergeable-chest-chest-name-none
• [string-mod-setting] WideChests_mergeable-chest-chest-name-chest
• [string-mod-setting] WideChests_mergeable-chest-chest-name-warehouse
• [string-mod-setting] WideChests_mergeable-chest-chest-name-trashdump
• [string-mod-setting] WideChests_mergeable-chest-chest-name-chest-warehouse
• [string-mod-setting] WideChests_mergeable-chest-chest-name-chest-trashdump
• [string-mod-setting] WideChests_mergeable-chest-chest-name-warehouse-trashdump
• [string-mod-setting] WideChests_mergeable-chest-chest-name-chest-warehouse-trashdump
• [string-mod-setting]

And these if options.circuit_connection_setting was set: WideChests_circuit-connector-position-center-center-chest_name

• [string-mod-setting] WideChests_circuit-connector-position-right-top-chest_name
• [string-mod-setting] WideChests_circuit-connector-position-right-middle-chest_name
• [string-mod-setting] WideChests_circuit-connector-position-right-bottom-chest_name
• [string-mod-setting] WideChests_circuit-connector-position-left-top-chest_name
• [string-mod-setting] WideChests_circuit-connector-position-left-middle-chest_name
• [string-mod-setting] WideChests_circuit-connector-position-left-bottom-chest_name
• [string-mod-setting] WideChests_circuit-connector-position-bottom-right-chest_name
• [string-mod-setting] WideChests_circuit-connector-position-bottom-middle-chest_name
• [string-mod-setting] WideChests_circuit-connector-position-bottom-left-chest_name

MergingChests.delete_chest_name_settings

Call MergingChests.delete_chest_name_settings if your mod removes some vanilla chest.

For example:

MergingChests.delete_chest_name_settings('wooden-chest')
MergingChests.delete_chest_name_settings('iron-chest')
MergingChests.delete_chest_name_settings('steel-chest')

Data stage

Call MergingChests.create_mergeable_chest to create merged chest prototypes.

This function has two arguments:

• entity_data (type object) - Has following properties:
  • chest_name (type string) - name of the chest entity prototype. Have to be same as one called during setting stage
  • override_prototype_properties (type object) - Object which will be appended to all merged chest prototypes of this mergable chest. Used to override default properties. Defaults to empty object.
• segments_data (type object) - Object describing individual segments of the merged chest sprites. See below for more details.

Segments data

Segments data object has following properties:

• wide_segments
• high_segments
• warehouse_segments
• trashdump_segments

All of them have following properties:

• entity - required
• shadow - optional

Merged chest sprite is created from individual segments drawn next to each other. This is basic 9-sliced sprite. There are these segments:

• top_left - One put into top left corner
• top - Many put along top edge
• top_right - One put into top right corner
• left - Many put along left edge
• middle - Many put to fill in the middle of the chest
• right- etc.
• bottom_left
• bottom
• bottom_right

There are also these special segments

• top_center - One put in the middle of the top edge
• left_center - One put in the middle of the left edge
• center - One put in the middle of the chest
• right_center - etc.
• bottom_center

Each segment has following properties:

• filename - Required
• width - Required
• height - Required
• x
• y
• frame_count
• scale
• shift
• tint

To reduce redudancy it is also possible to move required properties from individual segments to the segments collection. The data in individual segments takes precedence.

The properties are the same except width and height. They are replaced with widths (object of left, middle and right properties) and heights (object of top, middle and bottom).

Each sprite segment can also be a list of segments instead. Random segment from the list will be taken every time a segment is placed into final sprite.

local segments = {
    wide_segments = {
        entity = {
            top_left = {
                y = 12
            },
            top = {
                x = 45
                y = 12,
                filename = 'override filename'
            },
            middle = {
                {
                    x = 85,
                    y = 96
                },
                {
                    x = 185,
                    y = 196
                }
            },
            -- other segments

            filename = 'filename used for all segments except "top"',
            widths = {
                left = 45,
                middle = 64,
                right = 85
            },
            heights = {
                top = 81,
                middle = 64,
                bottom = 34
            }
        }
    }
}

For more info I'd suggest taking a look at types at the start of /scripts/sprite_generation.lua

Prepared segment data

There is MergingChests.steel_chest_segments which has default segment data for steel chest. Use these if you don't want to bother with custom segment data.

There are also variants for logistic chests in WideChestsLogistic mod:

• MergingChestsLogistic.passive_provider_chest_segments
• MergingChestsLogistic.active_provider_chest_segments
• MergingChestsLogistic.storage_chest_segments
• MergingChestsLogistic.buffer_chest_segments
• MergingChestsLogistic.requester_chest_segments