Chessistics/research/programming_puzzle_games_report.md

# Programming & Automation Puzzle Games: Detailed Research Report

---

## 1. ZACHTRONICS GAMES -- MECHANICAL DEEP DIVES

Zachtronics (founded by Zach Barth, 2011) defined the "Zachlike" genre: open-ended puzzle games where players build solutions from simple, combinable components with no single correct answer. The studio's games were designed and released with puzzles that the designers themselves often hadn't optimally solved.

Sources: [Zachtronics Wikipedia](https://en.wikipedia.org/wiki/Zachtronics), [GDC Talk: Open-Ended Puzzle Design](https://www.gdcvault.com/play/1025715/Open-Ended-Puzzle-Design-at), [Gamasutra/GameDeveloper coverage](https://www.gamedeveloper.com/design/video-zachtronics-approach-to-open-ended-puzzle-design)

---

### 1.1 SpaceChem (2011)

**Core Concept:** Players build chemical reactors by programming two "waldoes" (robotic manipulators, colored red and blue) that move along paths on a grid, manipulating atoms into molecules.

**How Players Program:**
- Players lay out paths (tracks) on a grid for each waldo to follow
- Instructions are placed on grid cells along the path
- When a waldo passes over an instruction cell, it executes that instruction
- The two waldoes run simultaneously as two parallel "threads"
- Paths are loops -- waldoes cycle through their path continuously

**Instruction Set:**
- **Grab / Drop** -- Pick up or release an atom/molecule at the waldo's position
- **Rotate CW / CCW** -- Rotate a grabbed molecule 90 degrees around the waldo's position
- **Bond+ / Bond-** -- Create or remove bonds between adjacent atoms (only works on designated bonding pads)
- **Fuse / Fission** -- (Special reactor types) Combine atomic numbers or split atoms
- **Sync** -- Pause one waldo until the other waldo hits its own Sync instruction (coordination primitive)
- **Input / Output** -- Request a new input atom or dispatch a completed molecule
- **Sense** -- Detect what element is at a position (for conditional branching via path splits)

**Programming Concepts Taught Organically:**
- In-order execution (instructions execute as the waldo crosses them)
- Loops (paths are inherently circular)
- Parallelism (two waldoes running simultaneously)
- Synchronization (Sync instruction)
- Subroutines (multi-reactor levels where one reactor's output feeds another)
- The system is Turing-complete

**Optimization Metrics:**
- **Cycles** -- Time steps to produce required output quantities
- **Reactors** -- Number of reactor modules used (in multi-reactor levels)
- **Symbols** -- Total number of instruction symbols placed

**Accessibility Issues:**
- Extremely steep difficulty curve; only ~2% of players reached the end
- The 40+ hour campaign had an "oppressive" difficulty arc
- The demo was 4 hours long, which hurt impulse purchases
- Abstract mechanics were hard to learn -- Barth noted the game was "stupidly difficult"
- Metrics collection was broken (only uploaded on game start), so they couldn't even measure where players got stuck

Sources: [SpaceChem Wikipedia](https://en.wikipedia.org/wiki/SpaceChem), [SpaceChem Wiki: Instructions](https://spacechem.fandom.com/wiki/Instructions), [SpaceChem Postmortem on GameDeveloper](https://www.gamedeveloper.com/design/postmortem-zachtronics-industries-i-spacechem-i-), [Programming in SpaceChem](http://gangles.ca/2011/06/19/programming-in-spacechem/)

---

### 1.2 Infinifactory (2015)

**Core Concept:** First-person 3D factory building. Players place modular blocks to create assembly lines that transform input materials into required output shapes.

**How Players Program:**
- Instead of programming instruction sequences, players place physical blocks in 3D space
- Items don't move on their own -- conveyor belts, pushers, and other blocks provide movement
- The "programming" is spatial: arranging components so materials flow, merge, weld, and emerge as the correct shape
- This is more "physical computing" than code -- players think about timing, collision, and spatial routing

**Available Block Types:**
- Conveyor belts (directional movement)
- Pushers (push items in a direction)
- Welders (fuse adjacent items)
- Rotators (spin items)
- Sensors (detect presence)
- Lifters (vertical movement)

**Optimization Metrics:**
- **Cycles** -- Time to complete production run
- **Footprint** -- 3D space occupied by the factory
- **Blocks** -- Number of components placed

**Accessibility:**
- More intuitive than SpaceChem due to the tangible, physical metaphor
- 3D visualization makes it easier to understand what's happening
- Still challenging but the spatial/physical framing helps non-programmers engage
- Different cognitive demand: spatial reasoning rather than abstract logic

Sources: [Infinifactory Wikipedia](https://en.wikipedia.org/wiki/Infinifactory), [Zachtronics Infinifactory page](https://www.zachtronics.com/infinifactory/), [Infinifactory Assembly Line Antics review](https://game-wisdom.com/critical/infinifactory-assembly-line-antics)

---

### 1.3 TIS-100 (2015)

**Core Concept:** Players program a fictional corrupted 1970s computer by writing assembly code in interconnected nodes.

**How Players Program:**
- The machine has 12 nodes arranged in a grid
- Each node holds up to 15 lines of assembly code
- Each node has one register (ACC), one backup register (BAK), and directional ports (UP, DOWN, LEFT, RIGHT, ANY, LAST)
- Players write actual text-based assembly instructions
- Nodes pass values to each other through ports (message-passing architecture)
- Communication is blocking: a write waits until the receiving node reads

**Instruction Set:**
- **MOV src, dst** -- Move value between registers or ports
- **ADD src / SUB src** -- Arithmetic on ACC
- **NEG** -- Negate ACC
- **JMP label** -- Unconditional jump
- **JEZ / JNZ / JGZ / JLZ** -- Conditional jumps (zero, non-zero, greater, less)
- **SWP** -- Swap ACC and BAK
- **SAV** -- Copy ACC to BAK
- **NOP** -- No operation

**Optimization Metrics:**
- **Cycles** -- Instruction cycles to complete
- **Nodes** -- Number of compute nodes used
- **Instructions** -- Total instruction count across all nodes

**Accessibility:**
- The most "actual programming" of any Zachtronics game
- Ships with a fake printed manual (PDF) that players must read
- Very niche audience -- appeals primarily to people who enjoy or already understand assembly
- The parallel node architecture adds unique challenge beyond just coding

Sources: [TIS-100 Wikipedia](https://en.wikipedia.org/wiki/TIS-100), [TIS-100 Hacker's Guide](https://alandesmet.github.io/TIS-100-Hackers-Guide/assembly.html), [IEEE Spectrum: Assembly Language Games](https://spectrum.ieee.org/three-computer-games-that-make-assembly-language-fun)

---

### 1.4 SHENZHEN I/O (2016)

**Core Concept:** Players design circuit boards and program microcontrollers to build electronic products for fictional clients in Shenzhen, China.

**How Players Program:**
- Players place microcontroller chips (MCxxxx family) on a circuit board
- Wire chips together using two pin types: Simple I/O (analog signals 0-100) and XBus (digital packets)
- Write assembly code for each chip (max 14 lines per MC4000, more for MC6000)
- All chips execute simultaneously, one instruction per time step

**Instruction Set (MCxxxx family):**
- **mov src, dst** -- Copy value between registers, ports, or literals
- **add src / sub src / mul src** -- Arithmetic
- **not** -- Logical NOT (100 becomes 0, anything else becomes 100)
- **jmp label** -- Jump
- **slp N** -- Sleep for N time units (power saving)
- **slx P** -- Sleep until activity on port P
- **teq A B / tgt A B / tlt A B** -- Test operations that set +/- flags
- **nop** -- No operation
- **gen P X Y** -- Generate pulse (set pin high for X, low for Y)
- **dgt / dst** -- Digit extraction/setting

**Conditional Execution (Key Innovation):**
- ANY instruction can be prefixed with + or - to make it conditional
- + instructions execute only if the last test was true
- - instructions execute only if the last test was false
- This eliminates the need for if/else blocks, keeping code compact
- Conditional lines don't need to be adjacent to the test

**Chip Constraints:**
- MC4000: 2 registers (acc, dat), 14 lines of code, fewer I/O pins
- MC6000: 2 registers (acc, dat), 14 lines of code, more I/O pins
- Registers hold integers from -999 to 999 only

**Optimization Metrics:**
- **Cost** -- Total price of components used (different chips cost different amounts)
- **Power** -- Total instructions executed (sleeping uses no power)
- **Lines of Code** -- Total lines across all chips

**Debugging:**
- All code is always visible on the circuit board
- Signals visibly travel through wires in real-time
- Conditional code changes color based on test results
- Adjustable simulation speed
- The visual layout of the circuit board itself is part of the debugging experience

Sources: [SHENZHEN I/O Wikipedia](https://en.wikipedia.org/wiki/Shenzhen_I/O), [MCxxxx Family Programming Language Wiki](https://shenzhen-io.fandom.com/wiki/MCxxxx_family_programming_language), [MCxxxx Reference Card](https://steamcommunity.com/sharedfiles/filedetails/?id=780561888)

---

### 1.5 EXAPUNKS (2018)

**Core Concept:** Players program small autonomous agents called EXAs (Executable Agents) that traverse computer networks, manipulate files, and hack systems.

**How Players Program:**
- Write assembly-like code for each EXA
- EXAs physically move between "hosts" (computers in a network)
- Multiple EXAs can run simultaneously
- EXAs can carry files, communicate with each other, and replicate
- Global line limit shared across all EXAs (you allocate budget between them)

**Instruction Set:**
- **COPY src dst** -- Copy value between registers
- **ADDI/SUBI/MULI/DIVI/MODI** -- Arithmetic operations
- **LINK N** -- Travel to host connected by link N
- **GRAB fileID** -- Grab a file
- **DROP** -- Drop held file
- **FILE F** -- Read/write to held file via F register
- **SEEK N** -- Move file cursor by N positions
- **VOID F** -- Delete value at file cursor
- **MAKE** -- Create a new empty file
- **WIPE** -- Delete entire held file
- **TEST condition** -- Set test flag
- **TJMP / FJMP** -- Jump if test true/false
- **HALT** -- Destroy this EXA
- **REPL label** -- Replicate: create a copy of this EXA starting at label
- **KILL** -- Destroy another EXA in same host
- **MODE** -- Toggle communication mode (local vs global)
- **HOST R** -- Get name of current host

**Key Differences from SHENZHEN I/O:**
- No +/- conditional prefix; uses TJMP/FJMP (conditional jumps) instead
- REPL allows spawning copies of EXAs (fork-like)
- EXAs physically move through networks (spatial dimension)
- More registers and better register features
- File manipulation adds data structure complexity
- The global line limit means optimizing code length matters across all EXAs

**Optimization Metrics:**
- **Cycles** -- Time steps to complete
- **Size** -- Total lines of code across all EXAs
- **Activity** -- Total instructions executed across all EXAs

**Debugging:**
- Visual representation of EXAs moving through network nodes
- Can view and simulate all test runs before committing a solution
- Harder to debug than SHENZHEN I/O because EXA windows pop in and out of existence
- Watching little bots walk around the network provides clearer visual feedback than wire signals

Sources: [EXA Instructions Wiki](https://exapunks.fandom.com/wiki/EXA_instructions), [EXAPUNKS Optimisation Wiki](https://exapunks.fandom.com/wiki/Optimisation), [Steam Community discussions](https://steamcommunity.com/app/716490/discussions/0/1744469130475788473/)

---

### 1.6 Opus Magnum (2017)

**Core Concept:** Build clockwork alchemical machines that transform base atoms into complex compounds. An infinite workspace with mechanical arms on tracks.

**How Players Program:**
- Place arms (fixed, piston, multi-arm, track-mounted) on an infinite hexagonal grid
- Program each arm with a sequence of timed instructions
- All arms execute their instruction sequences simultaneously, cycling in a loop
- Position inputs/outputs anywhere on the board

**Instruction Set (per arm):**
- **Grab / Drop** -- Pick up or release an atom
- **Rotate CW / CCW** -- Pivot arm (and grabbed atom) 60 degrees
- **Extend / Retract** -- (Piston arms only) Change arm length
- **Advance / Retreat** -- (Track-mounted arms) Move along a track
- **Reset** -- Drop atom, return to starting position and orientation
- **Repeat** -- Copy-paste all prior instructions as a loop

**Arm Types:**
- Fixed arm (rotates only)
- Piston arm (extends/retracts + rotates)
- Double/triple arm (grabs at multiple points)
- Track-mounted variants of all above

**Cycle Synchronization:**
- All arms are padded to the same cycle length
- An arm won't restart its loop early -- it waits for the longest arm's cycle to complete
- This avoids manual padding but requires thinking about timing

**Special Mechanism Tiles:**
- Bonding/unbonding glyphs
- Calcification, duplication, projection, purification glyphs
- Multi-bond, triplex bond glyphs
- Each glyph performs a transformation when an atom is placed on it

**Optimization Metrics:**
- **Cost** -- Total gold cost of arms and tracks placed
- **Cycles** -- Time steps for one complete production run
- **Area** -- Hexagonal footprint of the entire machine
- (Production puzzles replace Area with **Instructions**)

**The GIF Export Feature:**
- Opus Magnum was specifically designed so solutions would look good as animated GIFs
- Built-in GIF recording lets players export their machines as seamlessly looping animations
- This drove enormous social media sharing and community engagement
- The visual, mechanical aesthetic made solutions inherently shareable without needing context

**Why Opus Magnum is the Most Accessible Zachtronics Game:**
- Infinite workspace (no space constraints for basic completion)
- No cost constraints to "just finish" a puzzle
- You can position inputs/outputs wherever you want
- Less "computer science" feeling -- more physical/mechanical
- "As hard as you want it to be" -- easy to find a working solution, hard to optimize
- Players who bounced off SpaceChem often succeed at Opus Magnum
- The real challenge is self-imposed optimization, not just completing puzzles

Sources: [Opus Magnum Wiki: Commands](https://opus-magnum.fandom.com/wiki/Commands), [Opus Magnum Wiki: Mechanisms](https://opus-magnum.fandom.com/wiki/Mechanisms), [Opus Magnum Wikipedia](https://en.wikipedia.org/wiki/Opus_Magnum_(video_game)), [PC Gamer: Perfectly solving Opus Magnum](https://www.pcgamer.com/perfectly-solving-opus-magnums-puzzles-is-impossible-but-thats-ok/), [Engadget: Building the perfect machine](https://www.engadget.com/2018-07-09-opus-magnum-zachtronics-irl.html), [Steam discussions on difficulty](https://steamcommunity.com/app/558990/discussions/0/1480982971158569651/)

---

### 1.7 The Histogram Comparison System

This is arguably Zachtronics' most important design innovation for player motivation.

**How It Works:**
- After completing any puzzle, three histograms appear
- Each histogram shows the distribution of all player solutions for one metric
- Your solution is marked on each histogram
- The X-axis is the metric value (lower is better); the Y-axis is player count
- Histograms are aggregated from all players via a central server

**Design Purpose:**
- Replaces traditional leaderboards, which only show the top few players
- Lets you see where you fall in the overall distribution
- Reveals whether you're average, above average, or near-optimal
- Creates motivation to optimize without directly competing with named individuals
- Shows the fundamental tradeoffs: being in the left tail on Cycles often means being in the right tail on Cost

**Psychological Effect:**
- Seeing your bar far to the right of the peak motivates "I can do better"
- Seeing your bar on the left peak provides satisfaction without pressure
- The multi-metric system means almost every player is "good" at something
- Over time, histograms shift left as the community optimizes, creating a living benchmark

**How Histograms Track:**
- They only include each player's personal best for that metric
- So the histogram trends toward spikes near the optimum over time, with a long tail
- This is different from tracking "most recent" solutions

**Adopted Beyond Zachtronics:**
- The histogram system has become a defining feature adopted by other "Zachlike" games
- Zachtronics even provided their histogram server infrastructure for some third-party games (e.g., Prime Mover)

Sources: [Steam Community histogram discussions](https://steamcommunity.com/app/558990/discussions/0/1700541698699585612/), [Biggiemac42 blog on optimization](https://btm.qva.mybluehost.me/optimizing-instructions-in-opus-magnum/), [Tracking global Opus Magnum records](https://biggieblog.com/tracking-the-global-opus-magnum-records/), [SpaceChem postmortem](https://www.gamedeveloper.com/design/postmortem-zachtronics-industries-i-spacechem-i-)

---

## 2. OTHER PROGRAMMING PUZZLE GAMES

### 2.1 Human Resource Machine (2015) & 7 Billion Humans (2018) -- Tomorrow Corporation

**Human Resource Machine:**
- Players control a single office worker who carries items between an inbox, outbox, and numbered floor tiles
- Metaphor for assembly language: the worker is the CPU register, floor tiles are memory addresses, inbox/outbox are I/O
- Visual drag-and-drop instruction tiles: INBOX, OUTBOX, COPYFROM, COPYTO, ADD, SUB, BUMP+, BUMP-, JUMP, JUMP IF ZERO, JUMP IF NEGATIVE
- Each puzzle asks you to transform input sequences into specific outputs
- Optimization: Speed (instructions executed) and Size (program length)
- Over 40 puzzles with escalating complexity
- Very accessible visual metaphor makes assembly concepts intuitive for non-programmers

**7 Billion Humans:**
- Sequel with parallel execution: all humans run the same program simultaneously
- Each human has individual state (position, held item) so the same code produces different behavior
- Adds spatial commands: STEP, SHOUT, LISTEN, PICKUP NEARBY, DROP
- IF statements allow branching based on local conditions
- The challenge shifts from sequential logic to emergent parallel behavior
- Much harder to reason about because you must predict how identical code behaves differently for each agent

Sources: [Human Resource Machine Wikipedia](https://en.wikipedia.org/wiki/Human_Resource_Machine), [7 Billion Humans Wikipedia](https://en.wikipedia.org/wiki/7_Billion_Humans), [Tomorrow Corporation](https://tomorrowcorporation.com/7billionhumans)

---

### 2.2 Baba Is You (2019) -- Hempuli

**Core Concept:** A Sokoban-like puzzle game where the rules themselves are physical objects in the level that the player can push around to change game logic.

**How It Relates to Programming:**
- Rules are expressed as word-tile sentences: NOUN + OPERATOR + PROPERTY (e.g., "BABA IS YOU", "ROCK IS PUSH", "FLAG IS WIN")
- Pushing word tiles changes the active rules immediately
- Syntax matters: "BABA IS WALL" is not the same as "WALL IS BABA"
- Logical compounding: "ROCK AND BOX IS FLOAT" applies to both objects
- You can create paradoxes, stack properties, change what "you" control mid-puzzle

**Programming Adjacency:**
- Teaches logical thinking about rules as code
- Variables (nouns), operators (IS, AND, HAS, ON), and properties (PUSH, STOP, WIN, MELT, HOT)
- Rule chaining and emergent interactions between rules
- Not literally programming, but exercises the same logical muscles

**Design Philosophy:**
- Levels were created by brainstorming a "cool" solution and then building constraints around it
- The designer (Arvi Teikari) noted the most satisfying puzzle moments come from "simple but hard-to-wrap-your-head-around situations" where solving means figuring out "that one neat trick"

Sources: [Baba Is You Wikipedia](https://en.wikipedia.org/wiki/Baba_Is_You), [Designing Baba Is You's rule system (GameDeveloper)](https://www.gamedeveloper.com/design/designing-i-baba-is-you-i-s-delightfully-innovative-rule-writing-system), [Game Informer review](https://gameinformer.com/review/baba-is-you/clever-puzzles-with-too-many-variables)

---

### 2.3 while True: learn() (2018) -- Luden.io

**Core Concept:** A visual programming puzzle game about machine learning, where players connect nodes to build data processing pipelines.

**Mechanics:**
- Data streams (colored shapes: red/green/blue + triangle/square/circle) flow from left to right
- Players place and connect ML-inspired nodes (decision trees, neural networks, support vector machines, etc.)
- Each node type processes and routes data differently
- Success requires getting the right data to the right output targets
- Press Play and watch data flow through your pipeline in real-time

**Learning Hook:**
- Nodes represent real ML concepts (expert systems, recurrent neural networks, autoencoders)
- Links to YouTube videos explaining the actual math and history
- Framing device: your cat is better at machine learning than you, and you're building a cat-to-human translator

**Design Approach:**
- Simple at core (sorting colored shapes), complexity layers on gradually
- Visual flow programming -- no code writing required
- The "watch it work" moment when data correctly flows through your network

Sources: [while True: learn() on Steam](https://store.steampowered.com/app/619150/while_True_learn/), [Zapier coverage](https://zapier.com/blog/while-true-learn/), [GIGAZINE review](https://gigazine.net/gsc_news/en/20210101-while-true-learn/)

---

### 2.4 Gladiabots (2019) -- GFX47

**Core Concept:** Program AI behavior trees for combat robots, then watch them fight.

**Mechanics:**
- AI is programmed using visual drag-and-drop behavior trees (no text code)
- The tree structure works like nested if/then conditionals
- Condition nodes evaluate the robot's situation (enemy distance, shield level, resource proximity)
- Action nodes determine behavior (attack, flee, collect resource, focus fire)
- Trees are read top-to-bottom; the first matching condition determines the action
- The same AI controls all robots of a given type

**What Makes It Work:**
- No code words at all -- purely visual/iconic interface
- Simple condition-action pairs scale to complex emergent behavior
- The satisfaction of winning fights with an AI you designed
- Asynchronous multiplayer: opponents can be offline
- Three game modes (elimination, domination, collection) test different AI strategies
- "Millions of possible combinations" from simple building blocks

**Programming Concepts Taught:**
- Priority-based decision making
- Behavior trees (used in real game AI development)
- Conditional logic
- Iterative debugging (watch fight, adjust AI, re-watch)

Sources: [Gladiabots Review (LearnCodeByGaming)](https://learncodebygaming.com/blog/gladiabots-review-tips-for-new-programmers), [Gladiabots official site](https://gladiabots.com/), [Gladiabots Wiki: BotProgramming Basics](https://wiki.gladiabots.com/index.php?title=BotProgramming_Basics), [Practicing Programming with Gladiabots](https://eugenesheely.com/practicing-programming-with-gladiabots/)

---

### 2.5 Colobot (2001, Gold Edition 2012+) -- Epsitec SA

**Core Concept:** An educational real-time strategy game where players program robots using CBOT, a language syntactically similar to C++ and Java.

**Mechanics:**
- Players write actual code in a built-in editor with syntax highlighting
- CBOT supports variables, functions, loops, conditionals, classes, and arrays
- Robots can be programmed to autonomously collect ore, refine materials, build structures, fight enemies
- The in-game editor pauses gameplay for code editing
- Color-coded syntax: orange for instructions, green for types, red for constants
- Object-oriented programming elements in the Gold Edition

**Mission Structure:**
- Multiple planets with escalating missions
- Each planet introduces new mechanics and programming challenges
- Separate programming exercises, challenges, and technique tutorials
- Two game modes dedicated to teaching the CBOT language

**Unique Position:**
- One of the few games that teaches actual text-based programming with real syntax
- The C++/Java similarity means skills transfer to real-world programming
- More "serious educational tool" than entertainment-first design
- Open-source Gold Edition is maintained by an international community

Sources: [Colobot Wikipedia](https://en.wikipedia.org/wiki/Colobot), [CBOT Language Wiki](https://colobot.fandom.com/wiki/CBOT_Language), [Official Colobot Community](https://colobot.info/)

---

### 2.6 The Farmer Was Replaced (2024)

**Core Concept:** Program a farming drone using a simplified Python-like language. Watch it automate farming tasks.

**Mechanics:**
- Text-based programming using Python-like syntax (if/else, for loops, while loops, functions)
- Start simple (plant grass) and scale to complex multi-crop farming with water management, soil tilling, and multi-drone coordination
- Continuous progression rather than isolated levels
- Harvested resources unlock a technology tree for new capabilities
- Press "execute" and watch the drone carry out your program

**Why It Works:**
- The satisfaction of pressing "execute" and watching the drone work
- Gentle introduction for complete novices
- Visual feedback makes abstract programming concepts concrete
- Continuous rather than level-based: success compounds

Sources: [The Farmer Was Replaced on Steam](https://store.steampowered.com/app/2060160/The_Farmer_Was_Replaced/), [DLCompare coverage](https://www.dlcompare.com/gaming-news/a-harvest-of-code-automating-the-farm-in-the-farmer-was-replaced), [Hacker News discussion](https://news.ycombinator.com/item?id=40719279)

---

### 2.7 Autonauts (2019) -- Denki

**Core Concept:** Teach robots to automate a colony by recording your own actions and having robots replay them.

**Mechanics:**
- "Record and Playback" teaching: click record on a robot, perform actions, stop recording
- The robot then repeats those recorded actions indefinitely
- Visual programming editor shows recorded actions as Scratch-like code blocks
- Players can edit the recorded programs: add loops, conditionals, refine behavior
- Bot memory limits constrain program complexity, upgradeable over time
- Basic commands: move, pick up, drop, use tool, interact

**Unique Design Feature:**
- The "follow me" recording mechanic is an extremely intuitive on-ramp
- You literally demonstrate what you want before abstracting it into code
- Bridges the gap between "doing" and "programming" naturally
- Similar to programming-by-demonstration in real robotics

Sources: [Autonauts Wiki: Programming](https://autonauts.fandom.com/wiki/Programming), [Autonauts on Steam](https://store.steampowered.com/app/979120/Autonauts/), [Thinky Games: Autonauts](https://thinkygames.com/games/autonauts/)

---

### 2.8 Other Notable Mentions

**Craftomation 101:** Program small robots (Craftomates) using visual code blocks to gather resources and craft items. Simple instruction set, satisfying to watch bots execute tasks.

**LightBot:** Foundational educational game where you program a robot's movement with simple commands (move forward, turn, jump). Introduces functions/procedures when puzzles exceed the main instruction area capacity.

**RoboRally (Board Game, 1994):** Richard Garfield designed this plan-then-execute board game where players program 5 movement cards per round. Chaos emerges when multiple robots' programs interact on the same board. Key ancestor of the "program then watch" genre.

Sources: [Craftomation 101 on Steam](https://store.steampowered.com/app/1724140/Craftomation_101_Programming__Craft/), [LightBot Academic Computing](https://academiccomputing.wordpress.com/2012/07/17/programming-games-lightbot/), [RoboRally Wikipedia](https://en.wikipedia.org/wiki/RoboRally)

---

## 3. ACTION SEQUENCE PROGRAMMING IN GAMES

### 3.1 Visual Programming vs. Text-Based

**Visual Programming Approaches:**
- **Block/node connection:** while True: learn(), Gladiabots, Autonauts, Craftomation 101
- **Path/track laying:** SpaceChem, Opus Magnum (instructions placed along paths or timelines)
- **Drag-and-drop instruction tiles:** Human Resource Machine, 7 Billion Humans, LightBot
- **Record and playback:** Autonauts (demonstrate actions, robot copies them)

**Text-Based Approaches:**
- **Custom assembly languages:** TIS-100, SHENZHEN I/O, EXAPUNKS
- **Simplified real languages:** The Farmer Was Replaced (Python-like), Colobot (C++/Java-like)

**Key Design Tradeoffs:**
- Visual programming has a lower barrier to entry but can become unwieldy for complex programs
- Text-based is more powerful and compact but intimidates non-programmers
- The most successful games find a middle ground: SpaceChem and Opus Magnum feel physical/visual while being Turing-complete
- Human Resource Machine brilliantly disguises assembly language with a visual metaphor

### 3.2 Loop/Repeat Mechanics

**Inherent Loops:**
- SpaceChem: Waldo paths are inherently circular; the program repeats by following the path loop
- Opus Magnum: All arm instruction sequences automatically cycle once the longest one completes
- TIS-100: Code loops to the beginning when execution reaches the last instruction

**Explicit Loop Instructions:**
- Human Resource Machine: JUMP instruction creates explicit loops
- SHENZHEN I/O: JMP instruction for loops
- Colobot/The Farmer Was Replaced: while/for loops from their host language syntax
- Autonauts: "Forever" loop block wraps recorded actions

**Repeat/Copy:**
- Opus Magnum's Repeat instruction copies all previous non-repeat instructions, creating an implicit loop without manually duplicating commands

### 3.3 Conditional Logic (If/Then)

**Test-and-Branch:**
- TIS-100: JEZ, JNZ, JGZ, JLZ (jump if zero/non-zero/greater/less than zero)
- EXAPUNKS: TEST + TJMP/FJMP (test, then jump-if-true or jump-if-false)
- Human Resource Machine: JUMP IF ZERO, JUMP IF NEGATIVE

**Conditional Execution (SHENZHEN I/O's innovation):**
- Any instruction prefixed with + only executes if last test was true
- Any instruction prefixed with - only executes if last test was false
- No jump/branch needed; conditions are inline

**Rule Manipulation (Baba Is You):**
- Rules are physically movable objects
- "If/then" is replaced by spatial arrangement of word tiles

**Behavior Trees (Gladiabots):**
- Priority-ordered condition-action pairs
- First matching condition fires; others are skipped

**Path Branching (SpaceChem):**
- The Sense instruction combined with path splits creates conditional routing

### 3.4 Debugging Tools

**Speed Control:**
- Nearly all programming games allow adjusting simulation speed (faster for testing, slower for debugging)
- SHENZHEN I/O and EXAPUNKS support quick pause/resume during execution

**Visual Feedback:**
- SpaceChem/Opus Magnum: Watch atoms move through the machine in real-time
- SHENZHEN I/O: Signals travel visibly through wires; conditional code changes color based on test results
- EXAPUNKS: EXAs visually move through network nodes; little bots walking around makes flow visible
- Human Resource Machine: Watch the worker physically carry items

**Step-Through:**
- Some games allow single-stepping (advancing one cycle at a time)
- TIS-100: Can step through cycles to see values in each node's registers

**Test Case Simulation:**
- EXAPUNKS lets you view and simulate all test runs individually before submitting a final solution
- SHENZHEN I/O shows expected vs. actual output waveforms

**Immediate Error Feedback:**
- SpaceChem: Collisions between molecules are immediately visible
- Opus Magnum: Arm/atom collisions cause visible failures
- Colobot: Syntax highlighting and compile errors in the editor

### 3.5 The "Watch It Execute" Satisfaction

This is one of the most universally praised aspects of programming games. The core loop is:

1. **Plan** -- Think about the problem, design a solution
2. **Build** -- Write code or place components
3. **Execute** -- Press the "go" button and watch
4. **Observe** -- See it work (satisfaction!) or fail (information!)
5. **Iterate** -- Fix problems, optimize, return to step 2

**What Makes Watching Satisfying:**
- Opus Magnum's clockwork machines are hypnotic -- arms rotating, atoms flowing, everything synchronized
- The Farmer Was Replaced: pressing "execute" and watching the drone do all the tedious work you'd otherwise do manually
- SpaceChem: Waldoes weaving past each other, molecules assembling -- a ballet of your design
- Autonauts: A colony of robots all doing their jobs, a civilization of your creation

**Key Design Insight:** The visual execution must be readable at a glance. Players need to quickly identify whether things are working or where they break. Games that nail this (Opus Magnum, SpaceChem) produce the strongest satisfaction loop. Games where execution is hard to follow (complex EXAPUNKS levels with many EXAs) lose some of that magic.

Sources: [Autonauts programming wiki](https://autonauts.fandom.com/wiki/Programming), [SpaceChem postmortem](https://www.gamedeveloper.com/design/postmortem-zachtronics-industries-i-spacechem-i-), [Various Steam community discussions]

---

## 4. WHAT MAKES PROGRAMMING GAMES FUN VS. FRUSTRATING

### 4.1 What Makes Them Fun

**The "Eureka" Moment:**
- The greatest satisfaction comes from figuring out "that one neat trick" (per Baba Is You's designer)
- Open-ended puzzles mean YOUR solution feels personal and creative
- No one told you the answer -- you genuinely solved it

**Open-Ended Design:**
- Having no single correct answer means there's always a valid way forward
- Players don't get stuck because their thinking doesn't match the designer's intended path
- Multiple optimization axes mean every player can be "good" at something

**The Implement-Debug-Optimize Loop:**
- Identical to real programming's inner loop, which is inherently flow-inducing
- Each step provides feedback and a sense of progress
- Optimization is endlessly replayable (there's always a better solution)

**Watching Your Creation Work:**
- The visual payoff of seeing a machine/program execute correctly
- Opus Magnum's GIF-ability turned this into a social experience
- The satisfaction of automation -- "I built something that works without me"

**Self-Directed Difficulty:**
- Games like Opus Magnum let you choose your challenge level
- Basic completion is accessible; optimization is for enthusiasts
- Histograms provide context without mandating competition

**The Optimization Metagame:**
- Tradeoffs between metrics create genuine strategic decisions
- A fast solution is often expensive; a cheap solution is often large
- Players naturally replay puzzles to improve specific metrics

### 4.2 What Makes Them Frustrating

**Difficulty Walls:**
- SpaceChem's 2% completion rate is the cautionary tale
- When puzzle difficulty outpaces the player's skill growth, frustration spikes
- 68% of players across all games admit to quitting due to excessive frustration

**Opaque Mechanics:**
- SpaceChem was "very difficult to learn because you couldn't see things as individual parts"
- When the relationship between instructions and outcomes isn't clear, debugging becomes guesswork
- Complex parallel execution (7 Billion Humans) is inherently hard to reason about

**Debugging Pain:**
- Having to "dig through dozens of lines of code to find that one character causing the problem"
- In EXAPUNKS, not being able to see all code/registers on screen at once
- When failure modes aren't visually obvious, iteration slows to a crawl

**Loss of Agency:**
- Fixed-solution puzzles feel more frustrating than open-ended ones
- Players who "usually make it 60-75% of the way through a Zachtronics game before it gets more hard than fun"
- When optimization feels required rather than optional, the fun evaporates

**Inadequate Tutorials/Onboarding:**
- SpaceChem's 4-hour demo was too long
- Without proper onboarding, players can become frustrated and stop playing
- The sense that failure is "unfair" rather than "earned" is the key frustration trigger

### 4.3 Key Design Lessons

1. **Make "just finishing" easy; make optimizing hard** (Opus Magnum's philosophy)
2. **Ensure every failure feels earned**, not arbitrary or unfair
3. **Provide visual feedback** that lets players quickly diagnose problems
4. **Multiple metrics** so every player can feel good at something
5. **Open-ended solutions** prevent the "I know what to do but can't find the designer's path" frustration
6. **Social comparison through histograms**, not leaderboards, motivates without demoralizing
7. **Let players skip puzzles** if stuck (later Zachtronics games improved on this)
8. **The "watch it execute" payoff must be proportional to the effort** of building the solution

Sources: [SpaceChem postmortem](https://www.gamedeveloper.com/design/postmortem-zachtronics-industries-i-spacechem-i-), [Steam community discussions on difficulty](https://steamcommunity.com/app/558990/discussions/0/1480982971158569651/), [Difficulty curve design (GameDeveloper)](https://www.gamedeveloper.com/design/difficulty-curves-how-to-get-the-right-balance-), [Hacker News: Zachtronics ten years](https://news.ycombinator.com/item?id=21175921), [Managing Difficulty in Puzzle Games](https://www.grogansoft.com/2022/01/01/managing-difficulty-in-puzzle-games/)

---

## 5. THE "TWO-LAYER" PUZZLE DESIGN

### 5.1 Macro vs. Micro in Game Design

**The Framework:**
- **Micro layer:** Moment-to-moment decisions, individual puzzle solving, tactical execution
- **Macro layer:** Long-term strategy, progression, resource management, meta-optimization

**The interplay between these layers** is described as a fundamental lever in game design. The best games nest micro decisions within macro systems, with micro providing immediate engagement and macro providing purpose and direction.

### 5.2 Examples in Programming/Automation Games

**SpaceChem:**
- Micro: Programming individual reactor waldoes (path layout, instruction placement, timing)
- Macro: Designing multi-reactor pipeline layouts where outputs feed inputs across reactors
- Boss levels introduce overworld pipe-routing puzzles on top of the reactor-level programming

**Factorio / Shapez:**
- Micro: Designing individual production lines, belt routing, inserter placement
- Macro: Factory layout, supply chain logistics, research progression, defense (Factorio only)
- Factorio adds combat/defense as a macro layer that creates resource pressure on the micro puzzle-solving
- Shapez strips away combat to make it pure puzzle: slice, rotate, color, merge shapes

**SHENZHEN I/O:**
- Micro: Writing assembly code for individual chips
- Macro: Circuit board layout, choosing which chips to use, wiring topology
- Product specifications create the macro "what to build" layer; chip programming is the micro "how to build it"

**EXAPUNKS:**
- Micro: Writing individual EXA programs
- Macro: Network topology navigation, deciding how many EXAs to deploy and where to send them, file management strategy

**Autonauts:**
- Micro: Programming individual bot behaviors
- Macro: Colony management, production chains, deciding what to automate next

### 5.3 Balance Strategies

**Factorio's Approach:**
- Both layers are always active and interleave constantly
- You zoom in to fix a belt arrangement, zoom out to notice a supply bottleneck, zoom in again to add a smelter array
- Combat pressure forces macro-level thinking (defense) that competes for resources with micro-level building

**SpaceChem's Approach:**
- Layers are somewhat sequential: solve individual reactors, then connect them
- But timing dependencies mean the micro solutions must work together at the macro level
- This creates a feedback loop where macro-level failures send you back to redesign micro solutions

**Opus Magnum's Approach:**
- Minimal macro layer -- each puzzle is self-contained
- The "macro" layer is optional optimization: replaying puzzles to improve on different metrics
- This is why it's the most accessible Zachtronics game: no strategic overhead

**The Key Tension:**
- Too much macro attention pulls focus from the satisfying micro puzzle-solving
- Too little macro structure makes the experience feel disconnected and purposeless
- The ideal balance lets players primarily engage with the layer they enjoy while the other provides context

Sources: [Macro and Micro: Designing the Two Layers (Games Alchemy Substack)](https://gamesalchemy.substack.com/p/48-macro-and-micro-designing-the), [Thinky Games: Factory builders and logic puzzles](https://thinkygames.com/features/a-satisfactory-result-how-factory-builders-use-logic-puzzles-to-revolutionise-the-management-genre/), [Puzzle Game Design Principles](https://gamedesignskills.com/game-design/puzzle/)

---

## 6. COMPARATIVE SUMMARY TABLE

| Game | Input Method | Loop Mechanic | Conditionals | Parallelism | Optimization Metrics | Accessibility |
|------|-------------|---------------|--------------|-------------|---------------------|---------------|
| SpaceChem | Visual paths + icons | Circular paths | Path branching via Sense | Two waldoes + multi-reactor | Cycles, Reactors, Symbols | Very Low (2% completion) |
| Opus Magnum | Timeline + hex grid | Auto-cycling sequences | None (pure sequencing) | Multiple arms | Cost, Cycles, Area | High (easiest Zachlike) |
| TIS-100 | Text assembly | JMP to top | JEZ/JNZ/JGZ/JLZ | 12 nodes in grid | Cycles, Nodes, Instructions | Very Low (programmer niche) |
| SHENZHEN I/O | Text assembly + circuit | JMP | +/- conditional prefix | Multiple chips | Cost, Power, Lines of Code | Low-Medium |
| EXAPUNKS | Text assembly | JMP + REPL | TEST + TJMP/FJMP | Multiple EXAs | Cycles, Size, Activity | Low-Medium |
| Infinifactory | 3D block placement | Conveyor loops | Sensor blocks | Implicit via layout | Cycles, Footprint, Blocks | Medium |
| Human Resource Machine | Drag-drop tiles | JUMP | JUMP IF ZERO/NEGATIVE | None (single worker) | Speed, Size | High |
| 7 Billion Humans | Drag-drop tiles | JUMP | IF conditions | All humans run same code | Speed, Size | Medium |
| Baba Is You | Push word tiles | None (manual steps) | Rule composition | None | None (pass/fail) | Medium-High |
| while True: learn() | Node connection | Data flows continuously | Node routing logic | Parallel data streams | Accuracy, speed | High |
| Gladiabots | Behavior tree nodes | Tree re-evaluated each tick | Condition-action pairs | All bots run same AI | Win/lose (competitive) | High |
| Colobot | Text code (CBOT) | while/for loops | if/else | Multiple robots | Mission completion | Low (actual coding) |
| The Farmer Was Replaced | Text code (Python-like) | while/for loops | if/else | Drone + helpers | Resource output | Medium |
| Autonauts | Record + visual blocks | "Forever" block | Conditional blocks | Multiple bots | Colony growth | High |

---

## 7. KEY RESOURCES

- **ZACH-LIKE** (book by Zach Barth): 400 pages of design documents covering all Zachtronics games, available on [Steam](https://store.steampowered.com/app/1098840/ZACHLIKE/) and [itch.io](https://zachtronics.itch.io/zach-like)
- **GDC 2019: Open-Ended Puzzle Design at Zachtronics**: [GDC Vault](https://www.gdcvault.com/play/1025715/Open-Ended-Puzzle-Design-at)
- **SpaceChem Postmortem**: [GameDeveloper](https://www.gamedeveloper.com/design/postmortem-zachtronics-industries-i-spacechem-i-)
- **Opus Magnum Optimization Blog**: [biggiemac42](https://btm.qva.mybluehost.me/optimizing-instructions-in-opus-magnum/)
- **Factory Builders as Logic Puzzles**: [Thinky Games](https://thinkygames.com/features/a-satisfactory-result-how-factory-builders-use-logic-puzzles-to-revolutionise-the-management-genre/)