path: root/docs/random/shenzhen_io_review.md

# Shenzhen I/O Game Review

I don't usually game.<sup>[citation needed]</sup>

Sometime in 2021, in my first days of university, I felt bored and bought
this game. Also out of vanity to show how different I am from my league of
legends roommates. (it didn't work because i got stuck at assignment eight
and gave up, until december 2023 when i decided to give it another spin
now that i've made a few PCBs and written some assembly in real life)

## What is this game

[Shenzhen I/O](https://www.zachtronics.com/shenzhen-io/) is a "nerd puzzle
game" (my words) by Zachtronics.

You move to Shenzhen and work as an employee at 龙腾 (Longteng), where you
combine chips into circuits that meet client specifications. In each level
(assignment), you are given a canvas like this one:

![Blank circuit board next to a waveform viewer and part
selector](img/shenzhen_io_review/canvas.png)

Then you complete these tasks, in the general order:

- Drag parts from the sidebar
- Connect parts with each other and I/O pins on the sides
- Write assembly for the programmable chips
- Simulate and debug until output matches expected waveform

The assembly language in question is invented specifically for the game.
The chips are fictional, too. It doesn't actually require prior embedded
systems knowledge. A few differences from real-life embedded systems:

- No need to explicitly power the chips
- No need to worry about clock cycles
- Everything seems to use decimal, not binary
- Hardly any boolean operations
- Voltage levels range from 0 to 100
- ADC/DAC are perfectly accurate
- Integers range from -999 to 999
- MCUs have two registers max (`acc` and `dat`), and no SRAM
- XBus, the asynchronous protocol, seems too complicated for one clock
  cycle
- Multidriver problems are handled simply by `input = max({outputs})`, and
  can be abused

And mostly importantly, the debugger is something I wish I had in real
life. You can literally step through the instructions! Imagine if you were
able to freeze time, poke an ATmega328P and know which loop it's stuck in.

That said, I'm not the best at this game. Hell, I'm not even _good_, as
I have created abominations like:

<details markdown="1">
<summary>Spoiler</summary>
![Circuit with five MCUs and wires that almost fill the entire canvas](img/shenzhen_io_review/traffic_signal.png)
</details>

After you complete each assignment, the game shows you where you are among
all the players. The data I got was:

![Three histograms, showing my data float much worse than
average](img/shenzhen_io_review/traffic_signal_histograms.png)

The current best for three metrics on the leaderboard are:

- Lowest cost: 6 yuan (mine costs 20)
- Power usage: 123 (mine uses 1.7K)
- Lines of code: 9 (mine has 45)

As you can see, my solution is far from good in whichever way, but
nevertheless it works. This is because there are so many ways to solve
a problem, and to optimize a solution.

That said, am I going to optimize my solution? No.

## Why is it fun

Like all puzzle games, it is fun because it's intellectually challenging.
It's not the kind of Genshin Impact minigame.

Another reason is the plot. For most of the game's target audience, living
in Shenzhen would be a foreign experience, and it's a lot of fun reading
coworkers (both Chinese and from abroad) react to projects and life. The
game's UI involves a mail client, where you receive emails from your
supervisors and coworkers, and honestly that's half the fun.

(lets ignore the fact that most chinese companies dont discuss everything
over email)

<details markdown="1">
<summary>Spoiler alert!</summary>

My favorite emails are:

- When you designed a vape as merchandise for musician Cool Dad, who, once
  the vapes were manufactured, got arrested for possession of
  amphetamines. Also, Carl absolutely _roasted_ Cool Dad's music.
- When you designed a laser/illuminator apparatus for law enforcement
  weapons and Carl responded with brutal sarcasm out of moral concerns.
  I kinda wonder if the correct move is _not_ to design it, but it's too
  late.
- When Joe proposed a haunted doll implemented with unmarked chips of
  unknown origin, and was then forbidden from venturing further in the
  field of "ghost electronics"
- When a Japanese company claims to have developed a "traditional yarrow
  stalk _I Ching_ divination" with "MEMS technology"
</details>

## Why is it hard

### You have to read the datasheet

The game comes with no manual; instead it ships a PDF containing all the
datasheets and supplementary materials. Fortunately they are much easier
to understand than those in real life. And they are (mostly) typeset very
well. Much more pleasant to the eye than many actual industrial
datasheets. In the one case it isn't, it's definitely intentional for
a "sketchy" vibe.

### Chips are intentionally underpowered

We know modern chips are extremely powerful. So powerful it would render
the game pointless. So the chips and assembly language in this game are
intentionally limited. The smaller chip only holds 9 instructions, the
larger one 14.

I sometimes find it hard to implement any meaningful logic with such an
underpowered chip. Once I found a solution that was 15 lines long, but
I had to split them in two chips, and then I had to write extra code so
they could communicate, which is another 10+ lines of overhead.

Hardware-wise, the chip has 6 pins max, and you can't just use _any_ pin,
because some pins are "simple", and some are "XBus".

### Conditional instructions are cursed

There's no actual "conditional branch". Give the chip a condition (e.g.
`teq acc 1` tests if `acc == 1`) and it sets a global state (+/-). Then
you can prepend a +/- to an instruction so that it only runs in the state.
The global state makes it really hard to emulate nested `if` statements.
Pretty sure there were actual ISAs that used this mechanism, but I always
get confused on this logic.

### Labels count as lines?

If you wanted to jump to an instruction, you have to label the line, like

```
loop:
  add 1
  jmp loop
```

It should make sense to any programmer that labels are not real. They are
just a fancy way to refer to the line number it precedes, and thus should
not count as a line. But in the above code it does, because the text area
only has so many rows. This leaves me with one less line for actual
instructions. It took me way too long to realize that this is legal:

```
loop: add 1
  jmp loop
```

The datasheet never mentioned this! I was looking at the
[leaderboard](https://www.reddit.com/r/shenzhenIO/wiki/index/) when
I found out.

### Canvas size is limited

The wire traces take a significant amount of space and there is only one
side, so no vias. They will sometimes block pins. The only way to cross
two wires is to use a bridge, which only comes in one size and direction.
I have more than once made a circuit that looks like an absolute jumbled
mess. Like what even is this

<details markdown="1">
<summary>Spoiler</summary>
![Circuit with four bridges](img/shenzhen_io_review/sandwich_machine.png)
</details>

There was one level where I just _can't_ get the wires to go where they
should. I tried every direction possible to route the wires, but there's
either not enough horizontal space or enough vertical space. The most
disgusting thing is this kind of notch that you can't route wires through.
These notches made two hours of my life miserable. I almost gave up.

![Tiny notch in circuit board with wires around it, but not through it](img/shenzhen_io_review/shoes_notch.png)

Then I downloaded a solution from the leaderboard, only to find that, like
in real life, you can route traces _below_ the chips. _Nobody mentioned
that!_ There was nothing in the manual that explicitly said this was ok,
nor was there any hint in the game. The hack is only accessible if you
hold Tab, which enters "show wires" mode, and the chips become translucent
so you can route traces underneath.

<details markdown="1">
<summary>Spoiler</summary>
Normal view:

![Circuit board with chips and wires](img/shenzhen_io_review/shoes.png)

When holding Tab:

![Same circuit but wires under chips are visible](img/shenzhen_io_review/shoes_wires.png)
</details>

I doubt this assignment is possible without this kind of hack. Anyway,
I deleted the leaderboard solution and made my own version, and I'm never
looking back.

## Hardest assignments

These are a list of assignments that I felt stuck on for more than an
hour.

<details markdown="1">
<summary>Spoiler</summary>

- Virtual reality buzzer (the level that led me to quitting in 2021)
- Precision food scale
- Traffic signal
- Color changing shoes (titled "Would you believe it?" in game)
</details>

Again, I'm not good at this. If I had to find an excuse, it would be that
I try my best to come up with the most elegant solution possible, however
many lines it takes. I'd use a divide & conquer approach that's as
symmetric as possible, which is not always optimal, and sometimes uses up
too much of space and makes a mess of wires.

## A nitpick on the awkwardness of languages

The game is created by a bunch of Americans, for, I suppose, a primarily
English-speaking audience. Despite this, the game and the datasheets are
available in both English and simplified Chinese. The problems are:

- The Chinese does not sound Chinese
- The English does not sound Chinese

If you tried to play the Chinese version as a Chinese person, as I have,
you will find the Chinese dialog awkward. The translator did their best,
but it sounds un-Chinese.

They are grammatically correct, but I find this sort of conversation out
of place in a Chinese workplace. However, I would prefer if real life
workplace conversations sounded like this. Light-hearted without much
客套话 (formalities). Let's hope society evolves that way.

On the other hand, if you play in English, you'll find that your Chinese
coworkers have extraordinarily high English competency, atypical of
current day Shenzhen (but the game is set in the future, so one can hope).

## Minigame: Shenzhen Solitaire

Early in the game a coworker introduces a solitaire-style game with
Mahjong-themed cards. It's a way to relax when I'm stressed out solving
a puzzle. I like it so much that I [rewrote it in
Rust](https://git.sr.ht/~fkfd/shenzhen_solitaire).

## Conclusion

At the time of writing, I have not finished the game (yet). So far it's
really enjoyable. I did stress myself out a handful times halfway; that
was because I was not treating it as a game. Once I accepted the fact that
I'm just a casual player and being unable to solve the puzzles does not
result in any loss of self worth, I was again ready to have fun.