New post: random/shenzhen_io_review

9 files changed, 269 insertions, 0 deletions

diff --git a/docs/random/img/shenzhen_io_review/canvas.png b/docs/random/img/shenzhen_io_review/canvas.png
new file mode 100644
index 0000000..6961448
--- /dev/null
+++ b/docs/random/img/shenzhen_io_review/canvas.png
diff --git a/docs/random/img/shenzhen_io_review/sandwich_machine.png b/docs/random/img/shenzhen_io_review/sandwich_machine.png
new file mode 100644
index 0000000..3259e07
--- /dev/null
+++ b/docs/random/img/shenzhen_io_review/sandwich_machine.png
diff --git a/docs/random/img/shenzhen_io_review/shoes.png b/docs/random/img/shenzhen_io_review/shoes.png
new file mode 100644
index 0000000..03ed4ce
--- /dev/null
+++ b/docs/random/img/shenzhen_io_review/shoes.png
diff --git a/docs/random/img/shenzhen_io_review/shoes_notch.png b/docs/random/img/shenzhen_io_review/shoes_notch.png
new file mode 100644
index 0000000..55d8d2e
--- /dev/null
+++ b/docs/random/img/shenzhen_io_review/shoes_notch.png
diff --git a/docs/random/img/shenzhen_io_review/shoes_wires.png b/docs/random/img/shenzhen_io_review/shoes_wires.png
new file mode 100644
index 0000000..4321716
--- /dev/null
+++ b/docs/random/img/shenzhen_io_review/shoes_wires.png
diff --git a/docs/random/img/shenzhen_io_review/traffic_signal.png b/docs/random/img/shenzhen_io_review/traffic_signal.png
new file mode 100644
index 0000000..d7ead83
--- /dev/null
+++ b/docs/random/img/shenzhen_io_review/traffic_signal.png
diff --git a/docs/random/img/shenzhen_io_review/traffic_signal_histograms.png b/docs/random/img/shenzhen_io_review/traffic_signal_histograms.png
new file mode 100644
index 0000000..1e2f45e
--- /dev/null
+++ b/docs/random/img/shenzhen_io_review/traffic_signal_histograms.png
diff --git a/docs/random/index.md b/docs/random/index.md
index 7190d22..f670959 100644
--- a/docs/random/index.md
+++ b/docs/random/index.md
@@ -21,3 +21,4 @@ Nevertheless, occasionally I leave a permanent trace along the way.
 - [Playlist to put on on my deathbed](deathbed_playlist.md)
 - [Of Potato Chips And Food Globalization](potato_chips.md)
 - [2 Bugs 1 Day](2bugs1day.md)
+- [Shenzhen I/O Game Review](shenzhen_io_review.md)
diff --git a/docs/random/shenzhen_io_review.md b/docs/random/shenzhen_io_review.md
new file mode 100644
index 0000000..e4287cb
--- /dev/null
+++ b/docs/random/shenzhen_io_review.md
@@ -0,0 +1,268 @@
+# 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.