Getting Started with Shenzhen I/O
The Shenzhen I/O manual that ships with Zachtronics' game is not particularly friendly to people who have never written assembly before. It assumes you already understand things like two's complement representation, why you'd ever use a branch instruction, and how bit-manipulation works in practice. If that describes you, you are going to have a rough time with the first three levels. I spent about six hours on the Craps game puzzle before I realized I was reading the manual wrong. The example code snippets use an editor that looks like a spreadsheet. You do not write code line by line in a traditional text file. You place instructions into a grid of memory addresses, and each row is a discrete line of assembly that executes sequentially unless a branch instruction interrupts the flow. That structural detail is mentioned once in the manual and then never again, which is frustrating when you are trying to figure out why your infinite loop is infinite.
Shenzhen I O Manual
Here is the core structure of the assembly language you need to know cold before you open the puzzle editor. The chip has a small set of registers. ACC is your accumulator, your primary arithmetic register. IN and OUT hold input and output pin values. There is also SP for the stack pointer and BP for the base pointer, which you will only encounter if you need subroutines. Most beginner puzzles can be solved without subroutines at all. The instruction set is lean. You get MOV to move data around, ADD and SUB for arithmetic, AND OR XOR NOT for bitwise operations, ROL ROR for shifting, and JMP JB JBE JE JNE for branching. There is also CALL and RET if you decide to structure your code like a human being. PUSH and POP exist for the stack. There is no LOOP instruction, no DIV or MOD, and no direct way to multiply. This omission is intentional and will bite you on puzzles that require coordinate math or timing calculations. The real trick nobody emphasizes enough is that input pins change state independently of your code running. The chip samples inputs at the start of each cycle. If you are reading a button press or a sensor value, your code needs to poll it in a loop because the hardware does not interrupt you. I wasted an entire evening on the Matrix puzzle trying to make it respond reactively. It turns out you just poll the input pins inside a repeating conditional check. The manual mentions polling once in passing. Most players figure it out the hard way.
When you compile code, the software outputs a .cih file. That is the chip image you place in the world. You can also export .schematic files for the bus wiring part of each level. The wiring is often where people stall out because the chip code is simple but connecting ten components with the right signal routing takes patience and a decent understanding of which pins do what. If you want the actual PDF manual, it comes bundled with the game in the support docs folder. You can also find it on the Steam page under the help section. The version included in the game is the authoritative one. Community wikis are useful for puzzle solutions but they often contradict or incompletely summarize the instruction set, so cross-reference anything you read there against the actual manual before you commit to an approach. A counter-intuitive point about the assembly is that branch prediction does not matter here. Your branches always execute exactly when you tell them to. There is no pipeline to stall, no speculative execution to worry about. This makes the code easier to reason about than real ARM or x86 assembly, but it also means every instruction literally costs one cycle. If your puzzle has a cycle budget, you cannot afford redundant checks or lazy code. I learned that the hard way on the final puzzle of the first act, where I exceeded the cycle limit by three because I used a MOV to copy a register value into itself as a debugging holdover. Three cycles over budget on a constrained puzzle is an automatic fail. Delete useless instructions ruthlessly.
Get the Full Details
Another thing beginners consistently miss is how the bus addressing works. Each external component connects to the chip via address lines and data lines. The chip reads from or writes to an address, not a pin directly. So if your schematic shows a component at address 0x00, you write to MEM[0x00] or read from it. Confusing pin numbers with memory addresses causes code that compiles fine but does nothing in the simulation. I caught this on my third puzzle when my output LEDs stayed dark despite perfectly valid arithmetic. The chip was reading from the correct address but writing to the wrong one because I had misread the schematic legend. Always verify your address mappings against the component datasheets inside the game before you submit. The manual's coverage of subroutines is adequate but terse. CALL pushes the return address onto the stack, executes the routine, and RET pops it back. The stack has limited depth, and if you nest calls too deep without returning, you will overflow it. The game does not give you a clear stack overflow error. It just corrupts your control flow and your code hangs. Keep subroutine nesting to one level unless the puzzle specifically demands recursion, which almost none of them do. For people who want to go further after finishing the campaign, the manual includes a brief appendix on the full instruction encoding table. It is not required reading for normal play but it helps if you want to understand what the compiler is actually emitting. The .asm source files that the compiler produces are human readable and worth studying. They reveal patterns that the puzzle solutions gloss over.
I do not recommend skipping straight to community solution dumps. The puzzles are designed so that struggling with the constraints teaches you how to think in this architecture. The Craps level alone teaches you more about finite state machines than most introductory courses do. Sit with it. Read the manual slowly. Test small code fragments in the editor before you paste them into a full solution. Your first few chips will look terrible. That is normal. By puzzle seven you will write cleaner code in twenty minutes than you did in two hours at the start.
