Beginners' Help Please

[Bloody Spy!]

Does anyone know of any good online sources for help with what the commands do and how to use them successfully to solve the puzzles?
I have a strong science background, and I've loved a wide variety of puzzle games, but I'm finding the Shenzhen I/O manual to be way above my head and less than useful (no offence to Zachtronics - honestly).
I know there are walkthroughs on Youtube, but I want to learn how the game works so I can complete the puzzles myself without "cheating".

Any constructive advise would be greatly appreciated, as I would really love to diversify my interest in puzzle games by playing (successfully) Shenzhen I/O.

Thank you! :)


(N.B. I've invested about 2 hours in the game so far, but this has been mainly offline due to internet connection problems and Steam doesn't seem to log offline hours)

[ShadowCluster]

The useful pages are page 4 (List of all instructions), and page 15-16 (All basic instructions). Unfortunately the best way to learn is to just start solving and experimenting. You can learn a lot from others but it doesn't do much unless you start using them yourself.

[Bloody Spy!]

Thanks for your reply, ShadowCluster.
I guessed those pages were the most useful ones for beginners. The trouble I'm having is knowing how to put them together into something coherent and functional. I think you're right: I am going to have to experimenting with a lot of trial and error :(
It's a shame there wasn't someting of an optional tutorial for us lay-people.

[lisamariefan]

The tutorial are the puzzles themselves, IMO. While the game is freeform some puzzles will work better with certain components. Also, experimentation is key

Barring that, there are definitely some good guides here though I haven't technically really looked over any of them personally.

Also, if none of that sounds all that helpful add me as a friend and I can definitely assist you gently. I think the whole "beat all puzzles in the main campaign" achievement should be a credibility voucher for "I can help."

[Gabedamien]

I think there are some things which can be explained for those with no programming experience, which will not spoil the game at all, but help total beginners at least make some headway on their own.

On the surface, Shenzhen I/O is a game of writing an assembly-like language to control fictional micro-controllers (the MC4000 and MC6000 components). There are other components which may help some puzzles or be necessary for others (RAM, ROM, logic gates, etc.), and connecting everything in a sensible way is also part of the challenge, but the core of the gameplay lies in writing code and dealing with extreme restrictions (very few input/output ports, very little memory for values, very little space for code, very few commands, etc.).

Here are the things I think that will help a non-programmer, or even high-level programmer, to understand when dealing with this kind of very low-level programming:

1. A microcontroller (or "chip") can send or receive data via *ports*. There are two kinds of ports in Shenzhen I/O: "simple" ports (`p0`, `p1`) and "data" ports (`x0`, `x1`). More on this later.

2. A microcontroller can store numerical values internally. The MC4000 can store one value (`acc`); the MC6000 can store two (`acc` and `dat`).

3. For both internal data storage, and external reception / sending (aka input/output or I/O), the code you write needs a way to label all these potential chunks of information. In computer circuit design, the spaces on the chip that can hold information or communicate with other chips are known as *registers*. In Shenzhen I/O, registers are labeled with addresses like `acc`, `dat`, `p0`, `x1`, `a0`, `d0`, etc. So any time you see "register" in the manual, think "something I can refer to by its label" or rather its *address*.

4. Math is always done to the value in the `acc` (for "accumulator") register. If you want to perform some calculations, you have to `mov` a value to `acc`, then perform the math operation, and the result will be stored in `acc`.

5. When manipulating values, you can either use a numerical literal directly (e.g. `add 5`, which adds 5 to `acc` and stores the result back into `acc`) or you can use the value located at some address (e.g. `add p0`, which adds whatever value is coming into the `p0` port to `acc` and stores the result in `acc`).

6. Shenzhen I/O has an odd time counting mechanism. Basically, the steps in the verification tab are broken into discrete "time units". These time units are supposed to be *much longer* than the time it takes for your chips to loop through their code, so if in order to see what behavior a chip has over multiple time units, it will need to use the `slp` ("sleep") or `slx` ("sleep until input") commands. Otherwise, your program just keeps looping over and over again millions of times, and the simulation stops the time unit progression to point out that your chip is far too busy.

7. Simple ports (`p0`, `p1`) are basically like analog power lines. They vary between 0 and 100, and can be checked whenever, as many times as you want. You can "set and forget" them as well, outputting a power level that persists over time.

8. Data ports (`x1`, `x3`) are trickier. They act like digital and discrete packets of information. They can transmit numbers between -999 and +999. The trick is that in order to *send* an xbus value, some other component must try to *receive* an xbus value on that same connection, *within the same time unit*. Huh? Details: you can send from component A and receive at component B as many times as you want within one time unit (see 6 above), so long as B tries to "read" as many times as A tries to "send". The sending and receiving doesn't have to happen literally simultaneously; you can send from A 5 times, and then read from B 5 times. HOWEVER, if any component is trying to read or write on xbus but the other connected components are sleeping, that will stop the system. Coordinating xbus communication is a slightly weird and potentially complex part of Shenzhen I/O.

9. Many times in programming, you want different behavior based on some kind of condition. "If acc is 0, then add 1, else set p0 to 50" – that sort of thing. Again, Shenzhen I/O has a slightly opaque and definitely challenging conditional statement system. Basically, condition tests set an internal switch to + or -. Every line of code that follows is executed depending on whether it is prefaced by +, -, or nothing. Example: `teq dat 5` means "Test if the `dat` register equals 5". If that is true, then every line of code after that gets run IF it starts with +, or nothing; lines starting with - are skipped. Conversely, if `dat` does NOT equal 5, then lines beginning with + are skipped, and lines starting with - or nothing are run. The internal "flag" (+/-) that gets set by conditionals is not directly visible, but while you run the system you will see statements become greyed out based on the current flag status.

I hope that helps…

[Gabedamien]

PS I will also say that Shenzhen I/O is at times > deliberately < obtuse. To some extent, the writing (emails, manual) is designed to be similar to the kinds of varied documentation and communication that developers and engineers face daily. In my daily working life I deal all the time with poor documentation or even no documentation, fuzzy specifications, etc. Sometimes that's part of the fun and challenge of being an engineer – reverse-engineering things or filling in the gaps – and often it is just frustrating. Shenzhen I/O as a game is well-constructed as a love letter to electrical engineering, software development, hobbyist and professional ads & documentation for varying components, etc.; they poke fun at this kind of imperfect information, but always in a way that is intended to be fair for the player. The difficulty curve is very punishing if you have never programmed at all, or even if you have never programmed in assembly. For context, assembly languages are extremely "low level", meaning they deal far more with the vagaries of how the machine works (you need to move this number from this bucket to this bucket) than abstract concepts (I want to check if something is divisible by 7).

If you find Shenzhen I/O even remotely enjoyable and interesting, I HIGHLY RECOMMEND the book "Code" by Charles Petzold. It assumes zero programming or computer knowledge, and begins with first principles ("what if you want to communicate secret messages with the kid next door using a flashlight?") and walks the reader up through encodings, binary, relays, transistors, logic gates, integrated circuits, computer architecture, assembly, compilers, graphics, etc. It's a terrific book for both non-programmers and programmers. No affiliation, I just think it's a great book.

[Zednaught]

I'll agree that the tutorial elements in this game are certainly lacking, to the game's detriment. The manual makes up for it a bit, but it's written in a certain way that assumes some coding familiarity. The obfuscation is deliberate, to give that sense of discovery.

That said, I was in the same boat as you, with no experience coding, but eventually with some of the helpful people on this board I was able to beat the main campaign and even design my own game using the sandbox feature. Now that I have time, I should go back and finish the bonus campaign.

Feel free to message me if you have any questions.

[lisamariefan]

An additional note I would like to make on the simple pins and xbus pins, and how it relates to wiring things.

You can split both simple and xbus wires. When you split a simple out, it will "broadcast." That is to say, it will be seen by both recieving nodes simultaneiously, and will not change after being read, but rather only after being set again.

On splitting xbus wires: There's something very important you must understand about the slx instruction. It just keeps a chip from executing until data is AVAILABLE to be read. A chip doesn't have to actually be the one reading from XBus to be able to break free from the slx command. You can make that the job of another chip.

[Bloody Spy!]

That's really good to know, Zednaught. I'm glad I'm not the only one who's been in this boat. Normally, I'm really good at puzzles so it was very disheartening when I kept banging my head against the wall on only the second puzzle.
I think the only reason I managed to solve the first one is because of a YouTube review I saw of Shenzhen I/O a little while before deciding to buy it! xD

Thank you for your offer, lisamariefan. I'd be very happy to receive any help that you're kind enough to give :)

Wow! Thank you so much for everything you've explained to me, Gabedamien. As soon as I get the chance I really look forward to putting it into practice.

[Krondelo]

I'm with you man, especially considering I'm a fairly knowledgable programmer. Yet I know very little or have experience with Assembly or any machine code. I got stuck on the second puzzle for a long time. Now I've finally got a grasp on what I'm supposed to be doing, and I have a general idea of how to do it. The problem now that I'm on puzzle 4 and 5 is I can't figure out how the inputs and outputs work, and which controller to use!?

Let me know when you get there and we can discuss.

[Bloody Spy!]

Sure thing, Krondelo.
It'll take me a while though, as I won't have much computer time for the next week and a bit. But I'll let you know as soon as I get there. Most likely, you'll have been able to move on by then :D

[Krondelo]

Haha no problem man! Best of luck.