Factorio Forums

Hello everyone!

I hope, this place is the right one for my proposal (don't kill me for my bad english...). for the case you think, another sub forum is more suitable for it, please let me know

A central problem in talking about circuit networks is, that there is no compact way to show someone a complex network. You just can take pictures and explain combinator by combinator, what they are doing and why it is useful to do it this way. For smaller networks, it is no problem to handle this, but the bigger your circuit network will be, the more you need to write to explain what happens in your network.

I would like to introduce an unambiguous and formalized language for circuit networks to allow talking about complex circuits networks in a compact way and i'm interested, if i am the only one who needs something like that. It would be amazing, if this post can be a starting point to create a way to talk about circuit networks more easily, without needing screenshots, long explanations or blueprints and a running factorio instance...

This would be my proposal:

Basic naming rules for entities

• Every entity in a circuit network needs a unique name.
• Entities of the same type should have a similar name.

Proposal
Entity will be named with a prefix based on the type. The first letter should be always a capital letter

• Constant Combinator -> C
• Arithmetic Combinator -> A
• Decider Combinator -> D
• Other Parts -> ONameOfEntityType (e.g. 'OLamp', 'ORailSignal', etc...)

Because every entity needs a unique, but similar name, numbering entities with the same type would be a suitable way to name entities, e.g.

• A100 (Arithmetic Combinator 100)
• C2 (Constant Combinator 2)
• D34 (Decider Combinator 34)
• OLamp334 (Lamp 334)

The number can be freely chosen as long as it is unqiue within the described set of circuit network

As it is usual, that combinators are connected to other entities (otherwise circuit networks would be lame... ), there is a need to find a way to specify, how they are connected.

Basic convention for describing a connection between two entities

• It has to be specified, which wire color is used to connect the two entities
• It has to be specified, if the input was used or the output
• When there are more than one connection, you need to separate them with a speparator like a comma
• for every input-connection you need to specify an output connection of another entity

Proposal
After defining an entity, you specify the connections in square brackets. The announced connections are separated with a comma.

A connection is defined with a beginning small 'i' (input) or 'o' (output), followed with a small letter for the color of the connected wire.

Example 1:

1. A10 [irOMiner23]
   Arithmetic Combinator 10 input is connected to Miner 23 via red wire.
2. OMiner23 [orA10]
   Output of miner 23 is connected to Arithmetic Combinator 10 via red wire.

Example 2:

1. C45 [ogA10, ogA11]
   Output of Constant Combinator 45 is connected to Arithmentic Combinator 10 and Arithmentic Combinator 11 via green wire
2. A10 [igC45, orD20]
   Input of Arithmentic Combinator 10 is connected to Constant Combinator 45 via green wire and output is connected to Decider Combinator 20 via red wire.
3. A11 [igC45, orD20]
   Input of Arithmentic Combinator 11 is connected to Constant Combinator 45 via green wire and output is connected to Decider Combinator 20 via red wire.
4. D20 [irA10, irA11, ogOLamp12]
   input of Decider Combinator 20 is connected to Arithmentic Combinators 10 and 11 via red wire and its output is connected to Lamp 12 via green wire.
5. OLamp12 [igD20]
   input of Lamp 12 is connected to Decider Combinator 20

Basic conventions for describing configuration of an entity

You need to specify a way to easy communicate what is configured in each entity.

• Every configuration is described in usual brackets
• Signalnames will start with a capital 'S' and a Name of the type (e.g. "SCrudeOil" or "SG")
• The input and output of an entity is separated with "->". If there is no input or output, the side of configuration stays empty
• If an entity output allows a change of the output signal, it should be called with an 'as' followed by the name of the new signal
• If there are more than one signals may be displayed comma-separated
• Decider Combinators may be expressed as formula
• Arithemtic Combinators may be expressed as formula
• Constant Combinators may be expressed as formula
• Other entitities needs standardization based on the possibilities they supporting

Examples:

• D667 ( SCrudeOil <= 50000 -> SCrudeOil as SA )
  If Signal Crude Oil is lighter or equal 50000, send amount of Crude Oil as Signal A to output
• D668 ( SCrudeOil > 100000 -> as SB = 1)
  If Signal Crude Oil is greater than 100000, send 1 as Signal B to output.
• A23 (SMetalPlates * 4 -> SMetalPlates )
  Multiply incoming Signal for Metal Plates with 4 and send this amount as Signal for Metal Plates to output
• C89 ( -> SA = 100, SB = 400)
  Send 100 as Signal A and 400 as Signal B to output.
• OLamp14 ( SA = 1 -> Activate )
  Active Lamp 14 if Signal A is equal to 1

Standard Convention to describe an entity with its configuration and connections

Basically defining an entity should follow this syntax

==> EntityName[Connections](Configuration)

Example, based on Example 2 i mentioned earlier:

• C45[ogA10, ogA11](-> SA = 100)
  Output of Constant Combinator 45 is connected to Arithmentic Combinator 10 and Arithmentic Combinator 11 via green wire. Send Signal A with Value 100 to the output.
• A10 [igC45, orD20]( SA * 2 -> SA )
  Input of Arithmentic Combinator 10 is connected to Constant Combinator 45 via green wire and output is connected to Decider Combinator 20 via red wire. Multiply Signal A with 2 and send new value as Signal A to output
• A11 [igC45, orD20]( SA + 100 -> as SB )
  Input of Arithmentic Combinator 11 is connected to Constant Combinator 45 via green wire and output is connected to Decider Combinator 20 via red wire. Add 100 to Signal A and send new value as Signal B to output
• D20 [irA10, irA11, ogOLamp12]( SA >= SB -> as SC = 1)
  input of Decider Combinator 20 is connected to Arithmentic Combinators 10 and 11 via red wire and its output is connected to Lamp 12 via green wire. If Signal A is greater or equal than Signal B, then send Signal C with value 1 to output.
• OLamp12 [igD20]( SC = 1 -> Activate )
  input of Lamp 12 is connected to Decider Combinator 20. Activate lamp if Signal C is equal 1.

Same Example without comments would look like this:
C45[ogA10, ogA11](-> SA = 100), A10[igC45, orD20](SA * 2 -> SA), A11[igC45, orD20](SA + 100 -> SB), D20[irA10,irA11,ogOLamp12](SA >= SB -> as SC = 1), OLamp12[igD20](SC = 1 -> Activate)

To be fair, this short explanation is complicated by itself and you need to learn the formalism, but the advantage is you don't need to take screenshots or blueprints to describe your network. And much more important is the fact that you don't need long explanations how you connected the entities with each other and how you configured them. If you think, your circuit network behaves unexpected, you can share your network and other people can simply support answers like "A36 is wrong, you need config ( SH + 14 -> as SA )".

What you are thinking about it?

It's good to be clear about how you will set up circuits and create some kind of formal language for this. However, I don't feel such a convention or language will get widespread use. It's about communication. You propose people use this convention if they talk about their circuits. But people will just not do it. They will continue to just post screenshots, a few words if you're lucky, and if you're very lucky a blueprint.

There is not enough pressure to invent such a convention. It's nice to have a proper description, but in the last 10 years we've managed with what has just been posted. Blueprints and screenshots are the materialization of circuit ideas, not a language on paper.

A formal language defined this way totally reminds me of sendmail configuration files, which look like chicken walking across the keyboard: If it comes to myself, I draft my non trivial circuit ideas with on the spot made up descriptions not completely different to what you propose. After I made myself clear what I want and how I will do it with a very rough draft, I fire up Factorio and create the draft in map editor and flesh it out.

Afterwards, I never again look at the draft, because the real circuits became very different to what I drafted. And I never feel like it to create a formal description. It's just not interesting, because I feel nobody ever will read it. If I post it somewhere, nobody will really use it. They look at the screenshot, they might perhaps import and test the blueprint, but I'm quite sure they will never read any formal description. Instead, if someone is interested, he will try to inspect the inner working of the circuit himself by importing the blueprint.

It is much more helpful in my opinion if I mark parts in a screenshot and describe the whole contraption, or parts of it, on a higher level:

"this is a counter, and resets if a used up fuel cell is pulsed from that inserter over there"
"this is working as a whitelist, reset if signal R is pulsed"
"this is a latch"
"this moves items according to what you define in that constant combinator"
"this is a filter. The filter works by shift left a 1 by 31 bit, add the input, then filter positive numbers in the decider combinator, because the shifted 1 makes numbers appear negative due to the two's complement representation"

Made me think of chess moves notations. Took centuries for people to agree on one and there is arguably less information to encode that people could disagree on the format.

I like the idea, but when reading the proposal, i'm even more lost than when trying to put things apart in editor mode to understand a blueprint.
Giving a number/ID to combinator without having a picture to me is difficult to grasp.

It would seem more intuitive to me to have the 2 parts in the other order, first having the ID of entities/settings, as a list, and then describe the wiring reusing the previous list index.

What i think may be impossible using only 2 such notations parts would be to try and describe something like a connected sushi mess . As for those the position of the belts on the map is important to understand what's going on, not only the wiring/logical connexion and settings on the entity. Which belt is located after or before the other one, and which one side load to which other one. It's a niche case but it can also be the case for power switches or roboport/chest.

If you add that, you have the same information i think than in the blueprint (not including title commentaries and bookstructure). I suppose that the blueprint are already attempting to densify as much as possible the way the information is stored, and it may be the case that a notation, to really be able to describe a circuit, would need no less informations than the blueprint, or close. ( isn't the code-convention an attempt at re-inventing the blueprint ? ).

In such case, it may be necessary to drop the belts interactions and other things that need their position on the map to be documented for the circuit to be understood from the notation to have a chance at making it "shorter". It would allow to describe logic circuits, without considering wiring distances, electricity access, logisitic zone coverage, belts pipes rails positions/connexions. By not attempting to represent those, the "circuit network logic" cannot be represented fully, but what's left that can be represented, can be under a more compact form than the blueprint. ( that's a reasonning, not like an assertion sorry if it sound like this, i may have not considered some dimensions).

I think some players/modders already developped some kind of convention of their own when making third party code that interact with blueprints, for vizualisation on web browsers, or generating some from outside-of-the-game programs, maybe some of the experience is documented somewhere ?

I agree with Tertius and mmmPI, this probably wont take off. For exact replication there's blueprints, for other conversations the syntax will be made up on the spot. Also, for larger contraptions this gets unwieldy very quickly.

But I'll attempt a bit of a review:

• distinction between arithmetic, decider and constant is obvious from the operations, no need for A, D, C indication, naming aside
• put configuration next to the combinator name, wiring can get arbitrarily long
• in the configuration the leading S for signal names is unnecessary most of the time, only single digits could be signal or number (maybe use S and/or # when the distinction is needed)
• having both "->" and "as" to split input from output is redundant, one of them (or anything else that could be interpreted as "implies" or "results in") will suffice
• your example of "D667 ( SCrudeOil <= 50000 -> SCrudeOil as SA )" is in fact nonsensical since the gui only allows for setting one output signal, so either "crude oil" or "A". And since this is a decider: is this supposed to be output 1 or input count? You can't pass on the value of "crude oil" onto "A".
• wiring can get arbitrarily complex, tying it to a single combinator might make sense for a star layout, but describing the set of connected in/outputs is probably simpler
• if I read your post right, you forbid connecting inputs with only other inputs, same with outputs. However, you can see this being done in blueprints to correctly join the overall inputs and outputs; possibly even with both colors to designate that the input or output can take either wire color.

As an example, here's a random blueprint from another thread:
Combinators:

1. 0 - each -> each
2. each >> 2 -> each
3. 0 + each -> each
4. each << 30 -> each
5. each ^ 2 -> each
6. each ^ 2 -> each
7. each < 0 -> each 1
8. each or -2^31 -> each
9. each and -2^31 -> each
10. each << 31 -> each
11. each < 0 -> each 1
12. each or -2^31 -> each
13. each and -2^31 -> each
14. each << 31 -> each
15. 0 - each -> each
16. 0 + each -> each
17. each = -2^31 -> each input
18. each > 0 -> each input
19. each = -2^31 -> each input
20. each > 0 -> each input

Wires:

• red & green: 1i, 3i
• red & green: 2i, 4i
• red: 1o, 5i
• green: 2o, 5i, 6i
• red: 3o, 6i, 7i, 8i, 11i, 12i
• green: 3o, 7i, 8i
• red: 4o, 13i, 14i
• green: 4o, 9i, 10i, 13i, 14i
• red: 5o, 15i
• red: 6o, 16i
• green: 7o, 9o, 10o, 17i
• red: 8o, 9o, 18i
• green: 11o, 13o, 14o, 19i
• red: 12o, 13o, 20i
• red & green: 15o, 16o, 17o, 18o, 19o, 20o

Using your syntax, having to add extra poles for inputs and output and specifying each wire only from one combinator:

• OPole1, OPole2
• A1 [irOPole1, igOPole1, orA5](0 - Seach -> Seach)
• A2 [irOPole2, igOPole2, ogA5, ogA6](Seach >> 2 -> Seach)
• A3 [irOPole1, igOPole1, orA6, orD7, orA8, orD11, orA12, ogD7, ogA8](0 + Seach -> Seach)
• A4 [irOPole2, igOPole2, orA13, orA14, ogA9, ogA10, ogA13, ogA14](Seach << 30 -> Seach)
• A5 (Seach ^ 2 -> Seach)
• A6 (Seach ^ 2 -> Seach)
• D7 (Seach < 0 -> Seach = 1)
• A8 (Seach or -2^31 -> Seach)
• A9 (Seach and -2^31 -> Seach)
• A10 (Seach << 31 -> Seach)
• D11 (Seach < 0 -> Seach = 1)
• A12 (Seach or -2^31 -> Seach)
• A13 (Seach and -2^31 -> Seach)
• A14 (Seach << 31 -> Seach)
• A15 [irA5, orOPole3, ogOPole3](0 - Seach -> Seach)
• A16 [irA6, orOPole3, ogOPole3](0 + Seach -> Seach)
• D17 [igD7, igA9, igA10, orOPole3, ogOPole3](Seach = -2^31 -> Seach input)
• D18 [irA8, irA9, orOPole3, ogOPole3](Seach > 0 -> Seach input)
• D19 [igD11, igA13, igA14, orOPole3, ogOPole3](Seach = -2^31 -> Seach input)
• D20 [irA12, irA13, orOPole3, ogOPole3](Seach > 0 -> Seach input)
• OPole3

Tell me when you've reassembled this… To discuss what this does is probably impossible from just the above lists.
I think I prefer sharing the actual blueprint

Nidan wrote: ↑Thu May 09, 2024 1:23 am [*] 0 - each -> each
Tell me when you've reassembled this… To discuss what this does is probably impossible from just the above lists.

I will have to try later because i got stuck : is this a "0" as the digit 0 as value, or is this "0" the signal "0" the digit that represent a channel ?

mmmPI wrote: ↑Thu May 09, 2024 3:33 am

Nidan wrote: ↑Thu May 09, 2024 1:23 am [*] 0 - each -> each
Tell me when you've reassembled this… To discuss what this does is probably impossible from just the above lists.

I will have to try later because i got stuck : is this a "0" as the digit 0 as value, or is this "0" the signal "0" the digit that represent a channel ?

The number. Based on the proposed method, the signal would be "S0".




That said, as to the OP: nope. While some of that I do already, I'm not writing out "SCrudeOil" etc. Also, as pointed out a couple times, the whole thing reads like code. Many people can't deal with that.

FuryoftheStars wrote: ↑Thu May 09, 2024 4:57 pm The number. Based on the proposed method, the signal would be "S0".

Ok, you are correct ,it's mentionned in the description, but why no 0# ? x)

That's not exactly the notation i proposed, and it's what i'm going to blame if the reproduction is not the same as the description :

Copy blueprint

Edited to fix the mistakes hopefully

Nidan wrote: ↑Thu May 09, 2024 1:23 am Tell me when you've reassembled this… To discuss what this does is probably impossible from just the above lists.

I have reassembled this, it should have been obvious in retrospect that without any constant combinators or instruction for attaching the blueprint to something else, it can do a whole range of things, from nothing at all if you just look at it, to any of the individual operation if you attach randomly; It may do some more interesting stuff. But those even with the blueprint i can't tell, there many points to potentially attach to try them all without clue. It may also contain mistake which would make it difficult to ananlyse input out to try and understand why things are this way.

mmmPI wrote: ↑Sun May 12, 2024 4:59 pm I have reassembled this, it should have been obvious in retrospect that without any constant combinators or instruction for attaching the blueprint to something else, it can do a whole range of things, from nothing at all if you just look at it, to any of the individual operation if you attach randomly; It may do some more interesting stuff. But those even with the blueprint i can't tell, there many points to potentially attach to try them all without clue. It may also contain mistake which would make it difficult to ananlyse input out to try and understand why things are this way.

The second version had extra power poles for in- and output. But considering that there aren't any looping wires the choices for in- and output are limited. Also note I wrote

• if I read your post right, you forbid connecting inputs with only other inputs, same with outputs. However, you can see this being done in blueprints to correctly join the overall inputs and outputs; possibly even with both colors to designate that the input or output can take either wire color.

which should make it obvious where in- and outputs are.

From just placing your blueprint (but not building it, not in an /editor save currently) I can spot three mistakes: The green output wire from combinator 3 / A3 is missing, you used signal 0 rather than number 0 (which is ambiguous in the first version), and combinators 10 and 14 / A10 and A14 should use >> rather than << (my mistake).
Regarding the function, for now I'll say it does something useful, and you (mmmPI) were active in the (obvious?) thread I took the bp from.

Nidan wrote: ↑Sun May 12, 2024 6:28 pm The second version had extra power poles for in- and output. But considering that there aren't any looping wires the choices for in- and output are limited.

I agree, for the blueprint to be used the choices are limited and a little effort could help me find how to use it for its intended purpose.
"but"
for the purpose of a hypothetical notation that would serve the purpose of discussing circuit's logic, one would need to consider that it is not always the case that things are used for their intented purposes, and someone could be asking for help to make a blueprint work ,describe it with a notation and it would seem fine for you, and the problem be in reading the input or output right. ( like me currently )

• if I read your post right, you forbid connecting inputs with only other inputs, same with outputs. However, you can see this being done in blueprints to correctly join the overall inputs and outputs; possibly even with both colors to designate that the input or output can take either wire color.

I had not thought this was adressed to me because i was not feeling like my post meant such interdiction. I had not thought of a literal definition for describing the wiring, just that conceptually it would be easier in the definition of the connexions to reference the entity described in a previous list, swapping the order.

It was possible to follow instruction system function, it 's quite difficult, probably harder to write them if the blueprint is untangled and hard to read, source of much errors x).
I realized when making it that some combinators are set up the same way, there could be some data compression by giving each combinator an ID, and listing their ID next to a list of operations.

5) each ^ 2 -> each
6) each ^ 2 -> each

would become

5,6) each ^2 -> each

Nidan wrote: ↑Sun May 12, 2024 6:28 pm From just placing your blueprint (but not building it, not in an /editor save currently) I can spot three mistakes: The green output wire from combinator 3 / A3 is missing, you used signal 0 rather than number 0 (which is ambiguous in the first version), and combinators 10 and 14 / A10 and A14 should use >> rather than << (my mistake).
Regarding the function, for now I'll say it does something useful, and you (mmmPI) were active in the (obvious?) thread I took the bp from.

I read Fury's post, and wanted to build the blueprint accordingly, but i did the opposite mindlessly when opening the game
I'm more used to s0 sE or [3] to name them as channel than 0# to identify as a digit. but also more used to use S0 and not 0# in actual circuit condition where it is used in the blueprint.

If i was to recognize the blueprint from another thread that would be unfair to say i understand it from the notation x). But now that you mention it, i think it is a random number generator, i remember the use of ^2 for a contraption around that size and dealing with "each" channel. If so that's a tough one to check if it working as intented x).

rldml wrote: ↑Wed May 08, 2024 3:35 pm A central problem in talking about circuit networks is, that there is no compact way to show someone a complex network. You just can take pictures and explain combinator by combinator, what they are doing and why it is useful to do it this way. For smaller networks, it is no problem to handle this, but the bigger your circuit network will be, the more you need to write to explain what happens in your network.

I would like to introduce an unambiguous and formalized language for circuit networks to allow talking about complex circuits networks in a compact way and i'm interested, if i am the only one who needs something like that. It would be amazing, if this post can be a starting point to create a way to talk about circuit networks more easily, without needing screenshots, long explanations or blueprints and a running factorio instance...

There is the Verilog2factorio compiler.

I've made the Combinassembly language, github | live demo. It's not meant for arbitrary circuits but it is meant for being readable and to do arbitrary computations in familiar assembly style programming and execution model. It is very simple and could be made even more readable, but at that point maybe something more like a high level language that compiles to Combinassembly would be a better way to spend that effort.

I'm considering making a general factorio Hardware Descriptor Language (HDL) like you are proposing. But I wouldn't use your syntax, it's not very readable. And it has to be machine compilable for it to be useful.

mmmPI wrote: ↑Sun May 12, 2024 7:26 pm

• if I read your post right, you forbid connecting inputs with only other inputs, same with outputs. However, you can see this being done in blueprints to correctly join the overall inputs and outputs; possibly even with both colors to designate that the input or output can take either wire color.

I had not thought this was adressed to me because i was not feeling like my post meant such interdiction.

It wasn't, it is part of my commentary on OPs suggested notation. However, it could therefore serve as a hint.

I realized when making it that some combinators are set up the same way, there could be some data compression by giving each combinator an ID, and listing their ID next to a list of operations.

5) each ^ 2 -> each
6) each ^ 2 -> each

would become

5,6) each ^2 -> each

That would've shortened things quite a bit as combinators 7-10, 17, 18 are the same as 11-14, 19, 20.

If i was to recognize the blueprint from another thread that would be unfair to say i understand it from the notation x). But now that you mention it, i think it is a random number generator, i remember the use of ^2 for a contraption around that size and dealing with "each" channel. If so that's a tough one to check if it working as intented x).

The task was aimed towards OP, but since I asked what function the bp serves and you reacted to it, I might as well mention that you might be aware of the source. It's not an RNG; the reason I added "(obvious?)" was the use of "each" in each combinator.

Nidan wrote: ↑Sun May 12, 2024 8:15 pm The task was aimed towards OP, but since I asked what function the bp serves and you reacted to it, I might as well mention that you might be aware of the source. It's not an RNG; the reason I added "(obvious?)" was the use of "each" in each combinator.

I edited the bp to fix the 3 mentionned points. I went throught my "pair wise operation" book, which is the one you published plus some of the wonky addition i made but i don't have something similar. I sort of feel there are 2 sides, maybe a part to deal with negative and positive number differently, that i mistook for the 2 side of the mean square method for RNG.

It's ok if you don't spoil the answer it'd be a puzzle for later x), i thought since you took some time to write some blueprint with a notation i proposed it was only fair to try and decode. Thinking doing things in pratice tells a different story.

mmmPI wrote: ↑Mon May 13, 2024 5:57 am I went throught my "pair wise operation" book, which is the one you published plus some of the wonky addition i made but i don't have something similar.

You're on the right track there. Is your copy older than the latest burst of conversation in that thread?

Nidan wrote: ↑Mon May 13, 2024 6:54 am You're on the right track there. Is your copy older than the latest burst of conversation in that thread?

Yes but i tried to keep it up to date with the new additions, i must have missed something that wouldn't be the first time