Importing customized blueprints just got much easier

[Chindraba]

Something I read in the patch notes last month has intrigued me.

Version 2.0.25

Minor Features

• Dragging and dropping a blueprint file into the game window will import the file contents as a blueprint string.
  
• Dragging and dropping text into the game window on X11 will import the text as a blueprint string.

My current games have been without blueprints. I don't have anything against using prints, I just don't have a general purpose library of them built yet for 2.0, let alone Space Age, so nothing to import. One of the things I do with prints, which parameters will reduce the need for, is convert them to JSON and customize them. I even have a script made to convert the export string to JSON and to re-encode the JSON to Factorio's blueprint string format.

Yesterday I had occasion to make some tweaks to a few prints, and decided to skip the copy/paste of text and try the drag and drop method. What I forgot to do, and realized too late to change it, was to convert the JSON back into the encoded format.

It worked anyway!

After a bunch of experiments I've discovered that, provided it is valid JSON, the file used can be either minified or pretty formatted JSON. Further, the import string text box in the game will also accept both minified and formatted JSON.

The benefit to engineers who get involved in the manipulation of blueprint strings seems big. Now the export string can be decoded and saved as JSON. Edits can be made with ease, saving files of versions and variations as normal JSON, and the files can be directly imported without the hassles of re-encoding. Even better, the offline library can be kept in JSON, and readable, for future changes.

I've tested this in Linux using the base and expansion stand-alone versions as well as the base version in Steam. Today, to be sure it wasn't Linux only, I used the office computer, sadly Windows, and tested the stand-alone versions as well. I'm going to guess that it will also work in MacOS. In Linux, with the X11 ability to also drag in text strings, there is one caveat. Those strings do have to be minified.

To test it on your own copy of the game you can use this small blueprint. It is just a yellow splitter filtered to the cut-paste-tool item, which you cannot access from in-game, yet it is a valid 'item'.

{
  "blueprint": {
    "item": "blueprint",
    "label": "Cut Splitter",
    "icons": [
      {
        "index": 1,
        "signal": {
          "name": "cut-paste-tool"
        }
      },
      {
        "index": 2,
        "signal": {
          "name": "splitter"
        }
      }
    ],
    "entities": [
      {
        "entity_number": 1,
        "name": "splitter",
        "direction": 12,
        "output_priority": "left",
        "filter": {
          "name": "cut-paste-tool",
          "quality": "normal",
          "comparator": "="
        },
        "position": {
          "x": 1036.5,
          "y": -145
        }
      }
    ],
    "version": 562949955256321
  }
}

You can copy that and paste it directly into the game using the import string button's text box, or you can paste it into your text editor and save it as a file, then drag the file into the game. For Linux users with X11, the minified version is

{"blueprint":{"item":"blueprint","label":"Cut Splitter","icons":[{"index":1,"signal":{"name":"cut-paste-tool"}},{"index":2,"signal":{"name":"splitter"}}],"entities":[{"entity_number":1,"name":"splitter","direction":12,"output_priority":"left","filter":{"name":"cut-paste-tool","quality":"normal","comparator":"="},"position":{"x":1036.5,"y":-145}}],"version":562949955256321}}

The same print, in version 1.1 JSON would be:

{
  "blueprint": {
    "item": "blueprint",
    "version":281479278886912,
    "label": "Cut Splitter",
    "icons": [
      {
        "index": 1,
        "signal": {
          "type": "item",
          "name": "cut-paste-tool"
        }
      },
      {
        "index": 2,
        "signal": {
          "type": "item",
          "name": "splitter"
        }
      }
    ],
    "entities": [
      {
        "entity_number": 1,
        "name": "splitter",
        "direction": 6,
        "output_priority": "left",
        "filter": "cut-paste-tool",
        "position": {
          "x": 1036,
          "y": -145.5
        }
      }
    ]
  }
}

This also works, as Factorio can read older prints in newer versions, provided the item names match, of course. Matching item names is not guaranteed between 1.1 and 2.0, where many have been changed.

If you run on Linux, a blueprint export string can be converted to minified JSON with the Bash command:

echo "$blueprint_string" | cut -c2- | base64 -d | pigz -d

or

echo "$blueprint_string" | cut -c2- | base64 -d | zlib-flate -uncompress

Pretty print format only needs an extra piece:

echo "$blueprint_string" | cut -c2- | base64 -d | pigz -d | jq . >"$filename.json"

The pigz might not be installed, and the zlib-flate command is part of "qpdf" which probably is installed. The jq command may also need installing.

I'm sure there's something in Windows to do the same thing, but I've no clue what it might be. If the decoding and deflation can be accomplished in Windows, I believe the jq command is also available for install in Windows.


So, if you work with blueprints outside of the game, how much will this make life easier? It's going to be a game-changer for me.

[Fletch]

Yep, blueprint strings are ultimately just base-64 encoded, gzip-compressed, JSON files (with the first byte of the encoded string being a version number that you need to strip off) - the schema is documented here: https://wiki.factorio.com/Blueprint_string_format

Pretty neat that the game now allows importing the JSON file directly and bypassing the gzip/b64 encoding steps. I've confirmed the same works on Windows too -- though the game needs to be running in window-mode (not fullscreen) so you can actually do the drag-n-drop from explorer onto the game window. EDIT: You might be able to drag and drop onto the game's taskbar icon on windows.

FYI: everywhere you use "pigz", you can replace with "gzip" (pigz is a parallel-gzip implementation -- handy when you need to compress massive amount of data and you have lots of idle CPU cores -- decompression is still mostly single-threaded though). All the tools you used do have their windows counterparts.

[Chindraba]

Originally posted by Fletch:

Yep, blueprint strings are ultimately just base-64 encoded, gzip-compressed, JSON files (with the first byte of the encoded string being a version number that you need to strip off) - the schema is documented here:
...

FYI: everywhere you use "pigz", you can replace with "gzip" (pigz is a parallel-gzip implementation -- handy when you need to compress massive amount of data and you have lots of idle CPU cores -- decompression is still mostly single-threaded though). All the tools you used do have their windows counterparts.

Almost correct. The string is not gzip'ed, it is zlib compressed. That, unfortunately is not handled by gzip, in or out. FWIW, the documentation you linked to also says it's zlib deflate.

And, yes, the need for windowed mode does reduce the feature some. It is not, however, required. You can Alt+Tab to the file manager and still have the game "full screen". Minimize on focus loss is an option in the settings, and with that off the game will still be visible and will accept the drag/drop operation from Windows.

Dropping the file onto the taskbar icon doesn't work, holding it there, however, seems to raise the game again and then the drop does work. Still easier than opening the file in an editor, copying kilobytes, or megabytes, of text and pasting, slowly, into the in-game text box.

The beauty for me is that the file can be JSON, which I can edit repeatedly, and never have to recompress and re-encode again.

[Fletch]

Originally posted by Chindraba:

Almost correct. The string is not gzip'ed, it is zlib compressed. That, unfortunately is not handled by gzip, in or out. FWIW, the documentation you linked to also says it's zlib deflate.

Learned something new every day. Surprised that pigz handles something that gzip doesn't.

The beauty for me is that the file can be JSON, which I can edit repeatedly, and never have to recompress and re-encode again.

Exactly this. You can also backup blueprints in a git repo or something as its clear-text JSON and see its history/changes over time. Much cleaner that storing the b64/zlib blob in source control.

[Chindraba]

Originally posted by Fletch:

Exactly this. You can also backup blueprints in a git repo or something as its clear-text JSON and see its history/changes over time. Much cleaner that storing the b64/zlib blob in source control.

OMG. I completely forgot about git. Quit using it with BP's cause the blob was worthless. Even depends on the order of names in the JSON. That is at least able to be controlled, with some effort, using jq. With the raw JSON in the repo, git becomes worthwhile again.

Thanks for the reminder.