Could we get a blueprint string "docstring" or "comment"?

[pokemane]

I tried a couple different searches to see if this had been suggested before and didn't see anything, but I don't get on the forums very often so I could very well be wrong. Regardless...

TL;DR

I think it'd be a good usability and "share-ability" improvement for blueprint strings if there was a provision for a "docstring" or comment in the final blueprint string output.

What ?

I'd like to be able to put a comment in my blueprint strings, and be able to see comments in blueprint strings from others.

It doesn't even have to be added as a feature in the GUI I don't think, though that would be nice as an eventual feature. Just something that you can add at in the beginning of a bp string, perhaps wrapped in c-style

Code: Select all

/* block comment */

markers or similar. That way it's there for those who would want to use it but won't be an added step for most users. Further I think it would be a good way to store "blueprint comments" that would show up in the GUI, if you guys ever want to go that far with it.

Why ?

I think this would be a QoL improvement specifically for sharing blueprints, since your own library follows you everywhere. The way I've seen them shared most is as a Pastebin link with a title, or as a text file with a short descriptive name. With embedded "docstrings" or comments, the blueprint string could contain descriptive information within itself. It would be easier to share/archive/peruse without having to jump into the game or an online tool to get an idea of the content and purpose of the blueprint, and you'd be able to package more descriptive information than would otherwise be possible with just a filename or pastebin paste title. It would also allow those sites or tools to display the comments/description with the blueprint render, and would likely enhance the experience with those tools.

[Shuriken255]

I think adding description for blueprint would be nice, and i guess it should be visible in the blueprint gui, not just a comment in BP string.
Just a little text on the bottom would be enough, i don't think it requires some fancy style or something. Just text to leave some info about blueprint's features or requirements.

I mostly create blueprints that require exact amount of ore that must be delivered by belt per second to keep it running fine and keep ratio safe. For example: 12.31 for iron, 4.02 for copper, 2.31 for coal. There also may be some important information that you need to say in description like replacing few belts to change result or enable/disable/switch some functions that blueprint may offer. I think Factorio blueprints need that function and it would be really glad if this will be added to Factorio.

[steinio]

This doesn't sound hard to implement. The export is a json so it can carry this information.

[pokemane]

I think adding description for blueprint would be nice, and i guess it should be visible in the blueprint gui, not just a comment in BP string.
Just a little text on the bottom would be enough

Agree. It'd be a lot easier and more clear about the origin/purpose of the comment string if there was a GUI element to go along with it. I just left it as a "maybe" because I know how much they've talked about the number of GUI elements and the GUI rewrite and I have no idea about the work involved

Thanks for the feedback!

[AileTheAlien]

This doesn't sound hard to implement. The export is a json so it can carry this information.

If you mean that the blueprint srting is JSON, then this wouldn't actually work. The JSON spec doesn't allow for comments. However, they could export it to something like YAML or XML, though.

[steinio]

This doesn't sound hard to implement. The export is a json so it can carry this information.

If you mean that the blueprint srting is JSON, then this wouldn't actually work. The JSON spec doesn't allow for comments. However, they could export it to something like YAML or XML, though.

No, if you have a look at the end of the uncompressed blueprint string from this blueprint (https://factorioprints.com/view/-L3ZdpQPZ7CJ3Un5XAy4), you see some attributes like item and label at the end.
There only needs the "comment": "" attribute to be added.

Code: Select all

{
    "blueprint": {
        "icons": [
            {
                "signal": {
                    "type": "virtual",
                    "name": "signal-S"
                },
                "index": 1
            },
            {
                "signal": {
                    "type": "virtual",
                    "name": "signal-R"
                },
                "index": 2
            },
            {
                "signal": {
                    "type": "item",
                    "name": "power-switch"
                },
                "index": 3
            }
        ],
        "entities": [
            {
                "entity_number": 1,
                "name": "substation",
                "position": {
                    "x": -6.5,
                    "y": -0.5
                }
            },
            {
                "entity_number": 2,
                "name": "accumulator",
                "position": {
                    "x": -4.5,
                    "y": -0.5
                },
                "control_behavior": {
                    "output_signal": {
                        "type": "virtual",
                        "name": "signal-A"
                    }
                },
                "connections": {
                    "1": {
                        "green": [
                            {
                                "entity_id": 3,
                                "circuit_id": 1
                            },
                            {
                                "entity_id": 7,
                                "circuit_id": 1
                            }
                        ]
                    }
                }
            },
            {
                "entity_number": 3,
                "name": "decider-combinator",
                "position": {
                    "x": -1.5,
                    "y": -1
                },
                "direction": 2,
                "control_behavior": {
                    "decider_conditions": {
                        "first_signal": {
                            "type": "virtual",
                            "name": "signal-A"
                        },
                        "second_signal": {
                            "type": "virtual",
                            "name": "signal-L"
                        },
                        "comparator": "<",
                        "output_signal": {
                            "type": "virtual",
                            "name": "signal-S"
                        },
                        "copy_count_from_input": false
                    }
                },
                "connections": {
                    "1": {
                        "red": [
                            {
                                "entity_id": 5
                            }
                        ],
                        "green": [
                            {
                                "entity_id": 2
                            }
                        ]
                    },
                    "2": {
                        "red": [
                            {
                                "entity_id": 8,
                                "circuit_id": 1
                            }
                        ]
                    }
                }
            },
            {
                "entity_number": 4,
                "name": "constant-combinator",
                "position": {
                    "x": 1,
                    "y": -1
                },
                "direction": 2,
                "control_behavior": {
                    "filters": [
                        {
                            "signal": {
                                "type": "virtual",
                                "name": "signal-U"
                            },
                            "count": 90,
                            "index": 1
                        }
                    ]
                },
                "connections": {
                    "1": {
                        "red": [
                            {
                                "entity_id": 7,
                                "circuit_id": 1
                            }
                        ]
                    }
                }
            },
            {
                "entity_number": 5,
                "name": "constant-combinator",
                "position": {
                    "x": 0,
                    "y": -1
                },
                "direction": 2,
                "control_behavior": {
                    "filters": [
                        {
                            "signal": {
                                "type": "virtual",
                                "name": "signal-L"
                            },
                            "count": 30,
                            "index": 1
                        }
                    ]
                },
                "connections": {
                    "1": {
                        "red": [
                            {
                                "entity_id": 3,
                                "circuit_id": 1
                            }
                        ]
                    }
                }
            },
            {
                "entity_number": 6,
                "name": "power-switch",
                "position": {
                    "x": 2.5,
                    "y": -0.5
                },
                "control_behavior": {
                    "circuit_condition": {
                        "first_signal": {
                            "type": "virtual",
                            "name": "signal-S"
                        },
                        "constant": 1,
                        "comparator": "="
                    }
                },
                "connections": {
                    "1": {
                        "green": [
                            {
                                "entity_id": 8,
                                "circuit_id": 2
                            }
                        ]
                    },
                    "Cu0": [
                        {
                            "entity_id": 1,
                            "wire_id": 0
                        }
                    ],
                    "Cu1": [
                        {
                            "entity_id": 9,
                            "wire_id": 0
                        }
                    ]
                }
            },
            {
                "entity_number": 7,
                "name": "decider-combinator",
                "position": {
                    "x": -1.5,
                    "y": 0
                },
                "direction": 2,
                "control_behavior": {
                    "decider_conditions": {
                        "first_signal": {
                            "type": "virtual",
                            "name": "signal-A"
                        },
                        "second_signal": {
                            "type": "virtual",
                            "name": "signal-U"
                        },
                        "comparator": "≥",
                        "output_signal": {
                            "type": "virtual",
                            "name": "signal-R"
                        },
                        "copy_count_from_input": false
                    }
                },
                "connections": {
                    "1": {
                        "red": [
                            {
                                "entity_id": 4
                            }
                        ],
                        "green": [
                            {
                                "entity_id": 2
                            }
                        ]
                    },
                    "2": {
                        "red": [
                            {
                                "entity_id": 8,
                                "circuit_id": 1
                            }
                        ]
                    }
                }
            },
            {
                "entity_number": 8,
                "name": "decider-combinator",
                "position": {
                    "x": 0.5,
                    "y": 0
                },
                "direction": 2,
                "control_behavior": {
                    "decider_conditions": {
                        "first_signal": {
                            "type": "virtual",
                            "name": "signal-S"
                        },
                        "second_signal": {
                            "type": "virtual",
                            "name": "signal-R"
                        },
                        "comparator": ">",
                        "output_signal": {
                            "type": "virtual",
                            "name": "signal-S"
                        },
                        "copy_count_from_input": false
                    }
                },
                "connections": {
                    "1": {
                        "red": [
                            {
                                "entity_id": 3,
                                "circuit_id": 2
                            },
                            {
                                "entity_id": 7,
                                "circuit_id": 2
                            }
                        ],
                        "green": [
                            {
                                "entity_id": 8,
                                "circuit_id": 2
                            }
                        ]
                    },
                    "2": {
                        "green": [
                            {
                                "entity_id": 8,
                                "circuit_id": 1
                            },
                            {
                                "entity_id": 6
                            }
                        ]
                    }
                }
            },
            {
                "entity_number": 9,
                "name": "medium-electric-pole",
                "position": {
                    "x": 6,
                    "y": 0
                }
            }
        ],
        "item": "blueprint",
        "label": "SR Power Latch",
        "version": 68720656384
    }
}

[AileTheAlien]

That would work for a comment visible in the game. It would not however, be a 'comment' in the JSON itself, which was the OP's suggestion.

[Zavian]

That would work for a comment visible in the game. It would not however, be a 'comment' in the JSON itself, which was the OP's suggestion.

Well if the devs were going to do this, then I think the comment should be visible (and preferably editable) in game (eg visible as part of the tooltip when you mouseover a blueprint).

[steinio]

That would work for a comment visible in the game. It would not however, be a 'comment' in the JSON itself, which was the OP's suggestion.

You are right.

[Impatient]

+1

[pokemane]

That would work for a comment visible in the game. It would not however, be a 'comment' in the JSON itself, which was the OP's suggestion.

You are right.

If there was a way (read: a way the devs would be happy with) to exclude such a comment field from the compression, or otherwise preserve or copy it, so that it could be visible in both deflated and "normal" form that'd be ideal I think. If it was copied during the deflation and pasted in at the head of the string or something, it could then just be ignored on re-inflation or importing with a tool because the comment would already be present in the final json object.

[AileTheAlien]

It's not the compression that's the problem; JSON just doesn't allow for proper "comments". I'm assuming the devs didn't hand-roll their own JSON code, so it should be relatively easy to swap out for a different format. Inststead of JSON, use YAML or XML or some other format that isn't as limited.

[Shuriken255]

It's not the compression that's the problem; JSON just doesn't allow for proper "comments". I'm assuming the devs didn't hand-roll their own JSON code, so it should be relatively easy to swap out for a different format. Inststead of JSON, use YAML or XML or some other format that isn't as limited.

I still don't get why is it so hard to make blueprint json look like this:

Code: Select all

        "item": "blueprint",
        "label": "Blueprint's name",
        "description": "Some description of this blueprint that you may see in text field",
        "version": 68720656384

And then get "description" string and use it to set text for some text field the same way they use "label" string to name blueprint item.
P. S. I actually don't know how long json strings may be, however even 255 symbols would be good for giving some short information. (in my case)

[steinio]

It's not the compression that's the problem; JSON just doesn't allow for proper "comments". I'm assuming the devs didn't hand-roll their own JSON code, so it should be relatively easy to swap out for a different format. Inststead of JSON, use YAML or XML or some other format that isn't as limited.

I still don't get why is it so hard to make blueprint json look like this:

Code: Select all

        "item": "blueprint",
        "label": "Blueprint's name",
        "description": "Some description of this blueprint that you may see in text field",
        "version": 68720656384

And then get "description" string and use it to set text for some text field the same way they use "label" string to name blueprint item.
P. S. I actually don't know how long json strings may be, however even 255 symbols would be good for giving some short information. (in my case)

Because the question is about a docstring readable inline with the blueprint string without importing it.

Had also read the topic several times to get it.

[pokemane]

Yeah the original intent was to be able to see a description of the content of the BP string without having to open the game or paste the string into some other service.

But it also dovetails nicely with in-game-viewable comments/descriptions like other people have talked about, so there's that. I certainly wouldn't mind this part.