DEV Community: Michael Z

Hidden in Plain Sight - Steganography

Michael Z — Mon, 25 Aug 2025 20:07:41 +0000

To us, a flower looks like a splash of color. To a bee, it’s a visual map. Many flowers have ultraviolet patterns invisible to humans but clear to pollinators. These markings act like landing guides, directing bees straight to nectar.

UV flowers, insects disguised as leaves, octopuses blending into coral... Secrets can sit in the open, plain and boring, until you know the key that reveals their hidden meaning.

Nature has been “hiding” information this way for millions of years. Humans, too, learned the same trick: the best way to conceal a message is not just behind locks or codes, but inside something that looks completely ordinary.

The Romans, for example, wrote with milk that dried invisible, leaving a letter that looked blank until heated. To most, it was an innocent sheet of parchment, but to the intended recipient, it revealed a secret.

Over the centuries, methods like this grew more sophisticated, and with the rise of the digital age, steganography found entirely new opportunities.

Today, billions of images are viewed online every day and some of them may be carrying secrets. Let’s explore the fascinating world of steganography.

Steganography comes in many forms and, similarly to encryption, relies on the sender and receiver agreeing on a method. For example, "the first letter of each word reveals the password."

The difference with cryptography is this: with encryption, you know there’s a hidden message. With steganography, you may be completely unaware that one exists.

For instance, hiding the password "SynwiL" using cryptography might produce something like 4MJJ0NwTSiJJdBp+g9Skrw== whereas steganography could encode it in a sentence like: See you next week in London.

But humans are clever, and simple text-based methods can be easily uncovered.
We need something bigger, way bigger, where tiny bits can be changed without anyone noticing. Painters sometimes hide their signature in the eyes of a portrait, perhaps we can do something similar with digital images.

Large images come with many pixels, and pixels come with many bytes.

For example, a 1920x1080 image has over 2 million pixels. A 24-bit color BMP image uses 3 bytes (red, green, blue) per pixel, totaling over 6 million bytes.

Each pixel can display 16.7 million different colors (2^(3*8)) and the human eye cannot distinguish between subtle differences. This is exactly what we can exploit: by changing the least significant bit (LSB) of a byte, we can embed a secret message in an image.

However, there are a few precautions:

Tools can detect statistical anomalies, so it’s wise to first encrypt the message. This ensures that even if discovered, the message remains unreadable.
More sophisticated algorithms exist to mitigate these risks, but we won’t cover them today.

Choosing which bits to flip is also crucial. Sequential changes are too obvious, and the receiver still needs to reconstruct the message. This rules out simple methods and true randomness, leaving us with pseudo-randomness. Using a PRNG (pseudo-random number generator) with a shared seed and tool, both sender and receiver can deterministically select the same seemingly random bytes. This is powerful: even if the seed is compromised, the algorithm to generate the numbers remain a mystery.

But enough with theory, let's see how this looks in action.

Embedding

To embed the message into a file, we first encrypt it, and then turn it into the individual bits.
We also wrap the code in a special signature so we can identify when the message is fully read when extracting:

var BMP_HEADER_BYTES = 54 // we must not change these
var START = "1::"
var END = ":>0$"

encryptedPayload := encrypt(payload)
// wrap payload in start and end tags
payloadBytes := []byte(START + encryptedPayload + END)

// turn payload into bits
var bitStringBuilder strings.Builder
bitStringBuilder.Grow(len(payloadBytes) * 8)
for _, b := range payloadBytes {
  bitStringBuilder.WriteString(fmt.Sprintf("%08b", b))
}
payloadBits := bitStringBuilder.String()

// check image is large enough
availableBits := len(file) - BMP_HEADER_BYTES
if len(payloadBits) > availableBits {
  log.Fatalf("payload is too large to embed in this image.")
}

"payloadBits" is now a string that has the entire payload encrypted and encoded in binary.

We now initialize our "random" number generator. It returns a function that returns the next position for the given seed and file. We look more in depth at this later.

getNextPosition := startRng(seed, file)

Now we loop through each bit of the payload, take the byte from the file at the determined position, and replace its final bit with our new payload bit.

for _, bit := range payloadBits {
  position := getNextPosition()
  // retrieve bits from the next position in the file
  binaryStr := byteToBinaryString(file[position])
  // replace LSB
  newBits := binaryStr[:len(binaryStr)-1] + string(bit)
  // write bits back to the file
  file[position] = binaryStringToByte(newBits)
}

We write the file again and that's all there is for for embedding.

Extracting

To extract the message again, we do the same process in reverse.

In an infinite loop, we go through each position using the same rng function and collect the bits. Each 8 bits, we can save one byte. Once we reach the END marker, we break the loop.

getNextPosition := startRng(seed, file)

byteBuffer := ""
var payloadBytes []byte
extractedBits := 0
maxBitsToExtract := len(file) * 8 // Absolute theoretical maximum

for {
  // Prevent infinite loop if END marker is not found
  if extractedBits > maxBitsToExtract {
    log.Fatal("Extraction limit reached without finding END marker. Seed likely incorrect.")
  }

  position := getNextPosition()
  // extract LSB from position
  binaryStr := byteToBinaryString(file[position])
  byteBuffer += binaryStr[len(binaryStr)-1:]
  extractedBits++

  // once we have one full byte...
  if len(byteBuffer) == 8 {
    // ... append byte to our final payload
    charByte := binaryStringToByte(byteBuffer)
    payloadBytes = append(payloadBytes, charByte)
    byteBuffer = ""

    payload := string(payloadBytes)
    // another safety check
    if len(payload) == len(START) && payload != START {
      log.Fatal("Start of the message does not match. Seed/Salt likely incorrect.")
    }
    // break if end marker was detected
    if strings.HasSuffix(payload, END) {
      break
    }
  }
}
payload := string(payloadBytes)

// trim start and end markers and decrypt the message

PRNG

"startRng" returns "getNextPosition". This is so it can keep track of specific variables like the counter and previous position used. "getNextPosition" creates a unique seed using the previous position and counter to avoid repeating the same positions. It also uses the image's meta data to make the positions unique for each image.

func startRng(seed string, file []byte) func() uint64 {
    seen := make(map[uint64]bool)
    counter := 0
    var previousPos uint64

    return func() uint64 {
        for {
            imageSize := len(file)
      // create a unique seed
            uniqueSeed := seed + strconv.FormatUint(previousPos, 10) + "$#" + string(file[:BMP_HEADER_SIZE]) + string(imageSize) + ":" + strconv.Itoa(counter)
            pos := prng(uniqueSeed, imageSize)
            previousPos = pos
            counter++
      // safety check to avoid reusing positions
            if !seen[pos] {
                seen[pos] = true
                return pos
            }
        }
    }
}

// based on the unique seed, get the position within the available image size
func prng(seed string, imageSize int) uint64 {
    modifyableImageSize := imageSize - BMP_HEADER_SIZE
    hasher := sha256.New()
    hasher.Write([]byte(seed))
    seedHashStr := hex.EncodeToString(hasher.Sum(nil))[0:16]
    seedHash, err := strconv.ParseUint(seedHashStr, 16, 64)

    if err != nil {
        log.Fatal(err)
    }

    return seedHash%uint64(modifyableImageSize) + uint64(BMP_HEADER_SIZE)
}

It's surprisingly simple! For the full code, check out https://github.com/MZanggl/stego-go/tree/main.

Using Binary To Solve the Poisoned Barrel Puzzle

Michael Z — Mon, 11 Nov 2024 13:09:52 +0000

A king has 100 barrels of wine, but one of them is poisoned. The poison only shows symptoms after 1 day, and he needs the wine soon after that.

Not wanting to take the risk, he decides to have prisoners test the wine. How many testers does he need to identify the poisoned barrel in just one round of testing?

Try solving it yourself, or read on for the solution!

Initial Steps

The intuitive answer might be 100 testers, or perhaps 99, assuming that if no one shows symptoms, the final barrel would be the poisoned one. But in reality, we can manage with far fewer testers.

Let’s start small to see how this might work by looking at a simplified example with just three testers:

Barrel	Tester 1	Tester 2	Tester 3
B1	x
B2		x
B3			x

In this setup, each tester only drinks from a single barrel. But the table demonstrates that there is clearly room for more tests to be made! What if we allow testers to combine efforts by tasting from multiple barrels?

Barrel	Tester 1	Tester 2	Tester 3
B1	x
B2		x
B3			x
B4	x	x
B5	x		x
B6		x	x
B7	x	x	x
B8

With this setup, we can now identify barrels based on unique combinations of testers who show symptoms. For example, if only Tester 1 shows symptoms, it’s Barrel 1; if both Testers 1 and 2 show symptoms, then it’s Barrel 4, and so on.

Binary Encoding

For each barrel, each tester either drinks from it or doesn’t. This creates two possible states per tester, which we can encode in binary.

Let’s rewrite our previous table using binary (1 for drinking, 0 for not drinking):

Barrel	Tester 1	Tester 2	Tester 3
B1	1	0	0
B2	0	1	0
B3	0	0	1
B4	1	1	0
B5	1	0	1
B6	0	1	1
B7	1	1	1
B8	0	0	0

Now, if we reorder the table by binary counting and count from zero, we get:

Barrel	Tester 1	Tester 2	Tester 3
B0	0	0	0
B1	0	0	1
B2	0	1	0
B3	0	1	1
B4	1	0	0
B5	1	0	1
B6	1	1	0
B7	1	1	1

This table is now simply a mapping between decimal and binary! Each bit represents a tester, and each unique combination tells us which barrel they drank from.

How Many Testers Are Needed for 100 Barrels?

Each additional tester (binary digit) doubles the number of barrels we can cover:

With 3 testers, we cover "2³=8" barrels.
By doubling the barrels a few times "2⁶=64" almost gets us there.

To cover all 100 barrels, we need "2⁷=128" combinations — so 7 testers are enough.

Alternatively, the formulaic approach would be to use a logarithm: "log2(100)≈6.64" which rounds up to 7.

But there's an even easier solution, since we've created a mapping between decimal and binary above, all we need to do is convert the number 100 to binary (1100100), count the bits (7), and we get our answer!

Scaling Up

What's even more interesting is how efficiently this solution scales. For example, if you had 1,000 barrels instead of 100, you would only need 10 testers, and for 1,000,000 barrels, just 20 testers will be sufficient!

And if you still insist on getting 100 testers on board, well now you can test a whopping 1,267,650,600,228,229,401,496,703,205,376 (one quintillion) barrels!

JSON Extensions for writing config files and parsing data

Michael Z — Wed, 06 Nov 2024 13:44:50 +0000

JSON is a rather simple format, this makes it easy to use, understand, and parse.
But sometimes you need a bit more than that, let's look at some common JSON extensions.

EJSON

Extended JSON is exactly what it sounds like. This dialect of JSON supports additional data types like dates and even lets you add your own types.

Here's an example showing the difference between regular JSON and EJSON when it comes to serializing and re-parsing objects containing dates.

const EJSON = require('ejson')

const event = {
  name: 'test',
  created_at: new Date()
}

const stingifiedJSON = JSON.stringify(event)
const stingifiedEJSON = EJSON.stringify(event)

// stringified
console.log(stingifiedJSON) // {"name":"test","created_at":"2024-11-06T00:00:00Z"}
console.log(stingifiedEJSON) // {"name":"test","created_at":{"$date":1730851200000}}

// re-parsed
console.log(typeof JSON.parse(stingifiedJSON).created_at) // string
console.log(EJSON.parse(stingifiedEJSON).created_at instanceof Date) // true

This is extremely useful for re-parsing serialized data, for example when sending it over the network.
EJSON is what MongoDB uses under the hood (in addition to BSON, a binary format of JSON).

Among the JSON extensions listed in this article, this is the only one that regular JSON is able to parse as well!

NDJSON

Newline-Delimited JSON is commonly used for streaming one JSON object at a time.

This is how it looks like:

{"name":"test","created_at":"2024-11-02T00:00:00Z"}
{"name":"test 2","created_at":"2024-11-04T00:00:00Z"}
{"name":"test 3","created_at":"2024-11-06T00:00:00Z"}

What's different to regular JSON is the lack of wrapping the data in an array and the lack of commas after each line (since it's newline delimited). This makes it a perfect candidate for streaming.

Apart from streaming JSON, I've also seen this format being used (together with EJSON) in NoSQL clients to export and import documents.

JSONC / JSON5

For the next one there's a variety of implementations each adding its own flavor. Let's look at JSON5 as it's the most complete one.

They all try to achieve the same goal: a human-readable, loosened JSON format for managing config files.

JSON5 allows you to add comments, trailing commas, line breaks, unquotes keys, among many other things.

{
  // You can add comments!!
  unquoted: '< unquoted keys!',
  singleQuotes: 'I can use "double quotes" here',
  lineBreaks: "Supports line breaks!\
No \\n's!",
}

As you can see, JSON extensions come in all shapes and sizes. Some meant to be used by applications, others allow devs to more easily create config files.
Next time you need to serialize/parse JSON, see if one of those extensions makes sense for your use case!

Rule Changing Poker Game "Balatro" recreated in JavaScript - Behind the Code

Michael Z — Sun, 26 May 2024 11:53:10 +0000

"Balatro" is a rogue-like poker game that comes with all sorts of modifiers to change the rules mid game and allow you to score higher points. There's significant interactivity among various effects that occur and its developer even describes the game as being held together with hopes and dreams.

Let's put on our poker face and see if, armed with the hindsight of the finished game, we can ace the development of its core mechanics, or if we'd be better off flushing our code down the drain?

Terminology

As always, before we start coding, let's get the terminology straight.

Hand ranking refers to the poker hand played (flush, straight, full house, three of a kind, etc.)
Played cards are the cards placed on the table (up to 5)
Scoring cards are the played cards contributing to the score (e.g. in 5 of spades, 5 of hearts, 7 of spades, the hand ranking is "pair" and only the first two cards count as scoring cards)
Jokers refer to special cards acquired during gameplay that don't need to be played but have an effect on either the rules or the scoring of the game

How the Game works

In case you haven't played the game, I'll break down one possible round of poker in Balatro:

the user plays the cards: 9 of spades, jack of clubs, queen of clubs, and king of hearts
the user previously added the following five jokers to his arsenal:
straights can contain a gap
straights and flushes only require four cards
copies joker ability from the joker to the right
retriggers face cards
Face cards get turned into spades

Let's see how the scoring goes for the above:

We only played four cards and have a gap in there (missing the 10), but because we have joker 1 and 2 applied, this still counts as a straight.
Face cards are also turned into spades so we have a flush as well. Hence the final hand ranking is a straight flush.
We get an initial score for the poker hand played (for example 50 chips + 8x multiplier).
We then go through each scored card and add its value to the score (e.g. 9 chips for the 9 of spades)
Thanks to the "retrigger face cards" joker, face cards are scored an additional time...
And thanks to the "copy joker ability", a third time as well!
We then calculate the final score: 139 chips * 8 multiplier = 1398

There are even jokers that multiply your multiplier which are often the secret to winning later rounds that require a high score to beat.

Coding

Before we get to the fun part, which is the jokers, we need to set up the basic functionality to score points.

Let's create the PlayCard class which we use to create the poker cards:

let lastPlayCardId = 0

const numberedCards = ['2', '3', '4', '5', '6', '7', '8', '9', '10']
const faceCards = ['jack', 'queen', 'king']
// we use this to sort and identify straights
const cardRanks = [...numberedCards, ...faceCards, 'ace']

class PlayCard {
  constructor(name, suit) {
    lastPlayCardId++
    this.uid = lastPlayCardId
    this.name = name
    this.suit = suit
  }

  isFace() {
    return faceCards.includes(this.name)
  }

  isNumbered() {
    return numberedCards.includes(this.name)
  }

  getRank() {
    return cardRanks.indexOf(this.name)
  }

  points() {
    if (this.isNumbered()) {
      return Number(this.name)
    }
    return 10
  }
}

Determine Hand Rankings

Next, let's determine the hand ranking that was played. We can use this code for it:

// a library of mine to simplify data manipulation
const { given } = require('flooent')

// hand rankings are listed from best to worst
const handRankingOptions = {
  // ...we just show the bottom too for now
  'pair': {
    chips: 10, // how many chips you score with a pair
    mult: 2, // how many multipliers get added when you score with a pair
    level: 1, // the level of hand ranking (can be leveled up)
    minCards: 2, // the number of cards required for this hand ranking to be valid
    matches(playedCards, pairs) {
      if (pairs.length === 1) {
        return { scoringCards: pairs[0] }
      }
    }
  },
  'highest': {
    // ...
    matches(playedCards) {
      return { scoringCards: [playedCards.at(-1)] }
    }
  }
}

function determineHandRanking(playedCards) {
  const playedCardsSorted = given.array(playedCards)
    .sortAsc(card => card.getRank())
    .valueOf()

  // collect all pairs needed for various ranking checks like full house or pairs
  const pairs = given.array(playedCards)
    .groupBy('name')
    .values()
    .filter(pair => pair.length > 1)
    .valueOf()

  for (const handRanking of Object.keys(handRankingOptions)) {
    const option = handRankingOptions[handRanking]
    if (playingCardsSorted.length < round.handRankings[handRanking].minCards) continue
    // if hand ranking matches, return the scoring cards and hand ranking
    const result = option.matches.call(handRankingOptions, playedCardsSorted, pairs)
    if (result) {
      // skip if not enough cards -> prevents flush with less than 5 cards
      if (result.scoringCards.length < round.handRankings[handRanking].minCards) continue
      return { scoringCards: result.scoringCards, handRanking }
    }
  }
  // will never reach here as "highest" will always return the highest card played at last
}

With this, we have a basic implementation to identify the hand rankings. Below are the remaining rankings.
We will need to modify the code later again to accomodate for specific jokers. What's really useful here is to write tests as you code along to not run into regressions.

const handRankingOptions = {
  'straightFlush': {
    // ...
    matches(playedCards, pairs) {
      const straightResult = this.straight.matches.call(this, playedCards)
      if (!straightResult) return
      return this.flush.matches.call(this, given.array(straightResult.scoringCards))
    }
  },
  'fourOfAKind': {
    // ...
    matches(playedCards, pairs) {
      const fourOfAKind = pairs.find(pair => pair.length === 4)
      if (fourOfAKind) {
        return { scoringCards: fourOfAKind }
      }
    }
  },
  'fullHouse': {
    // ...
    matches(playedCards, pairs) {
      const threeOfAKind = pairs.find(pair => pair.length === 3)
      if (threeOfAKind && pairs.length === 2) {
        return { scoringCards: playedCards }
      }
    }
  },
  'flush': {
    // ...
    matches(playedCards) {
      if (given.array(playedCards).unique('suit').length === 1) {
        return { scoringCards: playedCards }
      }
    }
  },
  'straight': {
    // ...
    matches(playedCards) {
      if (given.array(playedCards).map((c, idx) => c.getRank() - idx).unique().length === 1) {
        return { scoringCards: playedCards }
      }
    }
  },
  'threeOfAKind': {
    // ...
    matches(playedCards, pairs) {
      const threeOfAKind = pairs.find(pair => pair.length === 3)
      if (threeOfAKind) {
        return { scoringCards: threeOfAKind }
      }
    }
  },
  'twoPair': {
    // ...
    matches(playedCards, pairs) {
      if (pairs.length === 2) {
        return { scoringCards: pairs.flat() }
      }
    }
  },
  // ...pair and highest (see in previous code example)
}

Scoring

Now that that's out of the way we can create a function to handle what happens after the user has played the cards. This will be the injection point for our joker effects later. Let's first create the Score class:

class Score {
  chips = 0
  mult = 0
  scoreBreakdown = []

  constructor(handRankingOption) {
    // initialize score with the determined hand ranking
    this.scoreEffect({ type: 'chips', operation: 'add', value: handRankingOption.chips })
    this.scoreEffect({ type: 'mult', operation: 'add', value: handRankingOption.mult })
  }

  scoreCard(card) {
    this.scoreEffect({ type: 'chips', operation: 'add', value: card.points() })
  }

  scoreEffect(effect) {
    if (effect.operation === 'add') {
      this[effect.type] += effect.value
    } else if (effect.operation === 'multiply') {
      this[effect.type] *= effect.value
    }
    this.scoreBreakdown.push(effect)
  }

  total() {
    return this.chips * this.mult
  }
}

This class takes care of the calculations for us and saves a breakdown of every score change. This breakdown is powerful since it's easy to compare the score like this in tests without manually calculating and comparing the final score.

function calculateScore(playedCards, jokers) {
  const { scoringCards, handRanking } = determineHandRanking(playedCards)

  const score = new Score(handRankingOptions[handRanking])

  // add each card's points to the score
  for (const card of round.scoringCards) {
    score.scoreCard(card)
  }

  return { score }
}

And like this we have our very very basic poker functionality. Now, to the fun part!

Jokers

So turns out, there isn't just one type of joker, in fact I identified 4 different types. This means, we need 4 different injection points to apply the joker's effects.

A restriction I set for this excercise is not littering the code with if conditions for joker effects. The logic for the jokers should be solvable within the joker classes themselves. Ideally, this should make the code more easily extensible and modifyable, but just like boss blinds in the game, such restrictions also make challenges like this more interesting to solve in general.

The injection points are as follows:

function calculateScore(playedCards, jokers) {
  const round = new Round(playedCards, jokers)

  // 👇 Jokers that modify the setup, like changing rules/played cards.
  // E.g.: straights can contain gaps
  round.jokers.forEach(j => j.modifySetup?.(round))

  round.determineHandRanking()

  // 👇 Jokers that modify the scoring cards or ranking after it was determined
  // E.g.: Every played card counts in scoring
  round.jokers.forEach(j => j.modifyScoring?.(round))

  const score = new Score(round.getHandRankingOption())

  for (const card of round.scoringCards) {
    score.scoreCard(card)
    // 👇 Jokers that run for specific cards and are triggered one by one
    // E.g.: Add x4 to Mult for each face card scored
    round.jokers.forEach(j => j.scoreExtraPerCard?.(round, score, card))
  }

  // 👇 Jokers that run per round to add to the score
  // E.g.: Add x4 to Mult if scored using three cards or fewer
  round.jokers.forEach(j => j.scoreExtraPerRound?.(round, score))

  return { round, score }
}

Now, it would be possible to condense the last 2 or even 3 joker types into just the "scoreExtraPerRound"-type Joker. But the order in which joker effects are applied matters, so the score would only be calculatable after sorting the score breakdown accordingly which would also require more information. Let's hold off on that for the time being.

Looking at the code, we've also established the "Round" class which is as high as we go in this demo.

There's no need for "Game", "Ante", or "Blind" to play around with jokers. That's why you also see this mix of classes and stand-alone functions. We simply want to put our focus on the core part of the game, the rest's just there to help with that for now.

Back to the "Round" class. This class will hold vital information that jokers can access and mutate!

class Round {
  handRankingOptions = deepcopy(handRankingOptions) // copy to allow mutations by jokers
  handRanking = ''
  scoringCards = []

  constructor(playedCards, jokers) {
    this.playedCards = playedCards
    this.jokers = jokers
  }

  getHandRankingOption() {
    return this.handRankingOptions[this.handRanking]
  }

  determineHandRanking() {
    const { scoringCards, handRanking } = determineHandRanking(this) // "determineHandRanking" was changed to take an instance of Round as its argument
    this.handRanking = handRanking
    this.scoringCards = scoringCards
  }
}

Now we have everything set up, and all that's left is to create jokers!

Let's create our very first one, I think it speaks for itself!

class Joker {} // could add base methods down the line

class FibonnacciJoker extends Joker {
  scoreExtraPerCard(round, score, card) {
    if (['2', '3', '5', '8', '10', 'ace'].includes(card.name)) {
      score.scoreEffect({ type: 'mult', operation: 'add', value: 4 })
    }
  }
}

The test lets you see the score break down in which you can observe that after 5 and 8 were added, a 4x multiplier was added thanks to the joker!

describe('FibonnacciJoker', () => {
  it('adds 4x multiplier for each number in the fibonacci sequence', () => {
    const jokers = [new Joker.FibonnacciJoker]

    const cardsPlayed = [
      new PlayCard('5', 'spade'),
      new PlayCard('6', 'diamond'),
      new PlayCard('7', 'heart'),
      new PlayCard('8', 'club'),
      new PlayCard('9', 'club')
    ]

    const {score} = calculateScore(cardsPlayed, jokers)
    expect(score.getEffectsBreakdown()).toEqual([
      { operation: 'add', value: 5, type: 'chips' },
      { operation: 'add', value: 4, type: 'mult' },
      { operation: 'add', value: 6, type: 'chips' },
      { operation: 'add', value: 7, type: 'chips' },
      { operation: 'add', value: 8, type: 'chips' },
      { operation: 'add', value: 4, type: 'mult' },
      { operation: 'add', value: 9, type: 'chips' }
    ])
  })
})

"score.getEffectsBreakdown()" is a utility method that will return the score breakdown without the two initial chip + mult scores.

"scoreExtraPerRound" jokers work similarly in that given a certain condition is met, it will add a specific amount to the final score:

class ContainsThreeOrFewerCardsJoker extends Joker {
  scoreExtraPerRound(round, score) {
    if (round.scoringCards.length <= 3) {
      score.scoreEffect({ type: 'mult', operation: 'add', value: 20 })
    }
  }
}

Hey, we can even implement our very own jokers!

class AnswerToEverythingJoker extends Joker {
  scoreExtraPerRound(round, score) {
    if (given.array(round.playedCards).sum(c => c.points()) === 42) {
      score.scoreEffect({ type: 'mult', operation: 'multiply', value: 42 })
    }
  }
}

These two types of jokers can also contain their own state, like this joker which will add an additional x1 to mult for every time the current hand ranking is played:

class PlusOneForPlayingHand extends Joker {
  gameState = {
    timesPlayed: {}
  }

  scoreExtraPerRound(round, score) {
    this.gameState.timesPlayed[round.handRanking] = this.gameState.timesPlayed[round.handRanking] ?? 0
    this.gameState.timesPlayed[round.handRanking]++

    score.scoreEffect({ type: 'mult', operation: 'add', value: this.gameState.timesPlayed[round.handRanking] })
  }
}

There's also "roundState" which gets reset in the Round's constructor. This way we can implement retrigger jokers without causing an infinite loop if two such jokers are applied at the same time (as we have to retrigger all the other jokers as well):

class RetriggerLowNumbersJoker extends Joker {
  roundState = {
    triggered: {}
  }

  scoreExtraPerCard(round, score, card) {
    if (!['2', '3', '4', '5'].includes(card.name)) return
    if (this.roundState.triggered[card.id]) return
    this.roundState.triggered[card.id] = true

    score.scoreCard(card)
    round.jokers.filter(j => j.id !== this.id).forEach(j => {
      j.scoreExtraPerCard?.(round, score, card)
    })
  }
}

Regarding "modifyScoring" jokers, I only have one so far which is the "all played cards count in scoring". It's as simple as this:

class AllCardsCountJoker extends Joker {
  modifyScoring(round) {
    round.scoringCards = round.playedCards
  }
}

Much more interesting is the first type "modifySetup" as it allows for changing the rules of the game!

modifySetup Jokers

The first one is quite simple. It swaps the suit to spade for any face card played (before we determine the hand ranking):

class FaceCardsAreSpadesJoker extends Joker {
  modifySetup(round) {
    round.playedCards = round.playedCards.map(card => {
      if (card.isFace()) {
        return new card.constructor(card.name, 'spade', card.effects)
      }
      return card
    })
  }
}

To show how it works with other jokers, let's add another joker that adds a 4x multiplier for each card of the suit spades:

class MultForSpadeJoker extends Joker {
  scoreExtraPerCard(round, score, card) {
    if (card.suit === 'spade') {
      score.scoreEffect({ type: 'mult', operation: 'add', value: 4 })
    }
  }
}

As you can see in this test, we now get the extra multipliers for achieving a pair with the two played cards:

it('applies effect of MultForSpadeJoker for non-spade cards if FaceCardsAreSpadesJoker is set', () => {
  const jokers = [new Joker.MultForSpadeJoker, new Joker.FaceCardsAreSpadesJoker]

  const cardsPlayed = [
    new PlayCard('jack', 'heart'),
    new PlayCard('jack', 'heart'),
  ]
  const {round, score} = calculateScore(cardsPlayed, jokers)
  expect(round.handRanking).toBe('pair')
  expect(score.getEffectsBreakdown('mult')).toEqual([
    {"operation": "add", "type": "mult", "value": 4},
    {"operation": "add", "type": "mult", "value": 4}
  ])
})

Next, let's look at our final three jokers, they all work in conjunction with each other and we have to change some of the hand ranking logic for that to work out.

The first joker will allow us to create straights and flushes using only four cards. For this, we simply mutate the "minCards" property.

class SmallStraightFlushJoker extends Joker {
  modifySetup(round) {
    round.handRankingOptions.straight.minCards = 4
    round.handRankingOptions.straightFlush.minCards = 4
    round.handRankingOptions.flush.minCards = 4
  }
}

We are straight up mutating objects in the instance of "round" within the joker here. Usually you'd try to avoid mutations if possible but in this very instance I give it a pass as it's literally the joker's job to mutate the round's setup. But it wouldn't be too hard to migrate this to more "pure" code.

Using this joker already breaks our code to identify straights and flushes as it should still count when there's an invalid 5th card in the mix. Time to fix it!

Let's first look at the old "flush" code:

matches(playedCards) {
  if (given.array(playedCards).unique('suit').length === 1) {
    return { scoringCards: playedCards }
  }
}

To fix this, we shouldn't check if there's just one suit available, instead, we check for the suit with the most cards and return those. The "determineHandRanking" function already checks for us if the minimum cards were played.

matches(playedCards) {
  const scoringCards = given.array(playedCards)
    .groupBy('suit')
    .values()
    .sortDesc(cards => cards.length)
    .first()

  return scoringCards ? { scoringCards } : false
}

With this, the next flush-related joker is "Hearts and Diamonds count as the same suit, Spades and Clubs count as the same suit" is trivial to implement.

To do so, we can replace the "matches" method with a custom one which reduces the four suits into just two:

class ReducedSuitsJoker extends Joker {
  modifySetup(round) {
    const redSuits = ['heart', 'diamond']
    round.handRankings.flush.matches = function(playedCards) {
      const scoringCards = given.array(playedCards)
        // This is the only change
        .groupBy(c => redSuits.includes(c.suit) ? 'red' : 'black')
        .values()
        .sortDesc(cards => cards.length)
        .first()

      return scoringCards ? { scoringCards } : false
    }
  }
}

Finally, we have the joker "Allows Straights to be made with gaps of 1 rank".

For memory, this is the old logic for straights:

matches(playedCards) {
  if (given.array(playedCards).map((c, idx) => c.getRank() - idx).unique().length === 1) {
    return { scoringCards: playedCards }
  }
}

This one is indeed a bit tricky having to consider both the "only 4 cards" and "can contain a gap" jokers.

Let's first look at the new code to allow for 4 cards to be played:

isNextValid(previous, next) {
  return previous.getRank() + 1 === next.getRank()
},
matches(playedCards) {
  let scoringCards = []
  for (const card of playedCards) {
    const previous = scoringCards.at(-1)
    if (!previous || this.straight.isNextValid(previous, card)) {
      scoringCards.push(card)
    } else if (scoringCards.length === 1) {
      // reset as first card must have been wrong, second chance with the remaining 4 cards
      scoringCards = [card] 
    }
  }
  return { scoringCards }
}

This new "matches" method is a lot more procedural but allows for a fifth invalid card in the beginning, middle, or end.
We also broke out the actual comparison between previous and next into a new method "isNextValid".

Now we can easily implement the "can contain gaps" joker by overriding only the tiny method "isValidNext" accordingly!

class SkipNumberStaightJoker extends Joker {
  modifySetup(round) {
    round.handRankingOptions.straight.isNextValid= function(previous, next) {
      return (!previous || (previous.getRank() + 1 === next.getRank()) ||  (previous.getRank() + 2 === next.getRank()))
    }
  }
}

We could do the same with flush but I thought its code was very straight forward compared to identifying straights.

And here you can see a test with four different jokers combined!

it('can combine various straight and flush jokers together', () => {
  const jokers = [new Joker.SkipNumberStaightJoker, new Joker.SmallStraightFlushJoker, new Joker.FaceCardsAreSpadesJoker, new Joker.ReducedSuitsJoker]

  const cardsPlayed = [
    new PlayCard('7', 'spade'),
    new PlayCard('9', 'spade'),
    new PlayCard('10', 'club'),
    new PlayCard('jack', 'heart'),
  ]
  const {round} = calculateScore(cardsPlayed, jokers)
  expect(round.handRanking).toBe('straightFlush')
})

Conclusion

And with that, we have completed the basic integration of Balatro's Joker system! The real game offers even more features such as card modifiers, blinds, etc. But I hope you got a good look into the game's mechanics and that you will give the game a try!

Adonis.js V6 - It's even better!

Michael Z — Mon, 06 May 2024 12:36:20 +0000

It's been 3.5 years since I created the series TDD course with Adonis.js using Adonis.js version 4.
Since then Adonis.js has gone through major releases, primarly the switch to TypeScript. I haven't used either Adonis.js v5 or v6, so I thought it would be interesting to try to recreate parts of the TDD course in the latest version by cross checking my old series with the up-to-date documentation.

Like back then, we will create an application that lets you manage threads, similar to a site like reddit.

During the making I realized how similar the versions are to each other, which is a good thing btw, so I will start by showing the final version and then the different parts it's made of.

Setup

You start off by initiating the project using the following command:

npm init adonisjs@latest adonis-tdd-v6

You can choose between web, api, and slim. we choose the api kit for this example which is meant for REST APIs. Web would be for fullstack applications.

Comparison to V4:

The setup has been streamlined by no longer requiring the global adonis cli.
Testing no longer requires any additional installing and configurations

Writing our first test

Also explained here: https://docs.adonisjs.com/guides/http-tests

We start off by creating a test. While we can create files manually, Adonis.js also comes with easy to use commands to speed up development.

Execute node ace make:test thread and then choose functional, as we want to test an API route.

In this test, we make an API request to "/threads" and then assert that the response status is 200:

// tests/functional/thread.spec.ts

import { test } from "@japa/runner";

test.group("Thread", () => {
  test("can create threads", async ({ client }) => {
    const response = await client.post("/threads").json({
      title: "test title",
      body: "body",
    });

    response.assertStatus(200);
  });
});

We then proceed to create the actual controller using node ace make:controller threads and add the store method to the class:

// app/controllers/threads_controller.ts

export default class ThreadsController {
  async store() {}
}

and we register this controller in the routes file:

// start/routes.ts

import router from "@adonisjs/core/services/router";
import ThreadsController from "#controllers/threads_controller";

router.post("threads", [ThreadsController, "store"]);

Running the tests via npm test, npm t, or node ace test should already show a passing test.

Difference to V4:

Tests no longer require the "trait" function.
Controllers are now explictly imported in the routes file rather than a stringifed "ThreadController.store" which is great as it allows for faster navigation and prevents typo errors.
Files now use snake case instead of Pascal case

Creating the model

Now our test isn't doing anything yet so let's add the creation of threads.

We create the model using node ace make:model Thread -m. The flag -m also creates the database migration file to create the table.

We update the test to add the thread assertion:

// tests/functional/thread.spec.ts

import { test } from "@japa/runner";

test.group("Thread", () => {
  test("can create threads", async ({ client }) => {
    const response = await client.post("/threads").json({
      title: "test title",
      body: "body",
    });

    response.assertStatus(200);

    // 👇 Changes
    const thread = await Thread.firstOrFail();
    response.assertBodyContains(
      thread.serialize({ fields: ["id", "title", "body"] })
    );
  });
});

Run the test and it will tell you that the table doesn't exist. Adonis V6 uses sqlite by default and it's already set up for us. You can check out config/Database.ts for the configurations.

DIfference to V4:

no manual installation and set up of sqlite.

Now to make the table exist in this sqlite db, we have to run the database migrations at the start of tests.

This can be done in tests/bootstrap.ts as explained here: https://docs.adonisjs.com/guides/database-tests

// tests/bootstrap.ts

import testUtils from "@adonisjs/core/services/test_utils";

export const runnerHooks: Required<Pick<Config, "setup" | "teardown">> = {
  setup: [() => testUtils.db().migrate()],
  teardown: [],
};

Running the tests now will no longer complain that the table doesn't exist, but it will fail because "Thread.firstOrFail()" didn't return any data. So let's make our controller action create the thread!

// app/controllers/threads_controller.ts

import type { HttpContext } from "@adonisjs/core/http";
import Thread from "#models/thread";

export default class ThreadsController {
  async store({ request, response }: HttpContext) {
    const thread = await Thread.create(request.only(["title", "body"]));
    return response.json(thread);
  }
}

This part is identical with V4. Don't worry about the missing validation and authorization for this example, suffice to say, Adonis.js also has first class support for it.

The tests now fail with Cannot define \"title\" on \"Thread\" model, since it is not defined as a model property so let's set up our model fields!

In the migration file, add the title and body fields like this:

// database/migrations/<timestamp>_create_threads_table.ts

import { BaseSchema } from "@adonisjs/lucid/schema";

export default class extends BaseSchema {
  protected tableName = "threads";

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments("id");
      // 👇 Changes
      table.text("body").notNullable();
      table.string("title").notNullable();

      table.timestamp("created_at");
      table.timestamp("updated_at");
    });
  }

  async down() {
    this.schema.dropTable(this.tableName);
  }
}

We also declare the fields in the model:

// app/models/thread.ts

import { DateTime } from "luxon";
import { BaseModel, column } from "@adonisjs/lucid/orm";

export default class Thread extends BaseModel {
  @column({ isPrimary: true })
  declare id: number;
  // 👇 Changes
  @column()
  declare body: string;
  // 👇 Changes
  @column()
  declare title: "string;"

  @column.dateTime({ autoCreate: true })
  declare createdAt: DateTime;

  @column.dateTime({ autoCreate: true, autoUpdate: true })
  declare updatedAt: DateTime;
}

With this change, the tests should be green again!

Changes to V4:

To achieve type safety, we now need to specify the columns on the model as well.

Delete threads

Let's add another test to delete threads in our functional test file:

// tests/functional/thread.spec.ts

test("can delete threads", async ({ client }) => {
  const thread = await Thread.create({
    title: "\"test title\","
    body: "test body",
  });

  const response = await client.delete(`threads/${thread.id}`);
  response.assertStatus(200);
});

Back in routes.ts we can replace writing out each route by using "router.resource" which will follow the convential CRUD routes and names (see details in docs):

// start/routes.ts

router.resource("threads", ThreadsController).only(["store", "destroy"]);

Next, we add the actual controller action as a method in the class:

// app/controllers/threads_controller.ts

async destroy({ params }: HttpContext) {
  const thread = await Thread.findOrFail(params.id)
  await thread.delete()
}

That works, but let's also test there are zero threads left in the DB.

// tests/functional/thread.spec.ts

const threads = await Thread.all();
assert.equal(threads.length, 0);

changes to v4:

it seems v6 is missing the Model.getCount() method to easily do a count(*). Hope it will be added back.

Running this will fail as there is still one thread apparently.
Let's try running this test in isolation:
node ace test --tests 'can delete threads'

Hey it works! This makes sense because the thread from the other test is still there.
We need to set up that the DB is reset after each test as well.

To do this, we need to add this to our test file:

// tests/functional/thread.spec.ts

import { test } from "@japa/runner";
import Thread from "#models/thread";
import testUtils from "@adonisjs/core/services/test_utils";

test.group("Thread", (group) => {
  group.each.setup(() => testUtils.db().withGlobalTransaction());

  // ...
});

This is very similar to V4, and again I wished if we could just set up something like this once in bootstrap.ts. Hey, I even prepared a PR for it back then https://github.com/adonisjs/vow/pull/58.

But it's nothing we can't create ourselves.

For example, you could create a snippet for this, your own npm/ace command, or you could simply abstract this if you wanted in a new utility file:

// tests/db.ts

import testUtils from "@adonisjs/core/services/test_utils";
import { Group } from "@japa/runner/core";
import { test } from "@japa/runner";

export { test } from "@japa/runner";

export const group = (groupTitle: string, callback: (group: Group) => void) => {
  return test.group(groupTitle, (group) => {
    group.each.setup(() => testUtils.db().truncate());
    return callback(group);
  });
};

Now we can just write tests like this:

// tests/functional/thread.spec.ts

import { test, group } from "#tests/db";

group("Thread", () => {
  test("create threads", async ({ client }) => {});
});

But generally, I like not deviating too much from the framework.

Factories

In our tests we will need to create many fake instances of threads, like in the thread deletion test. Let's refactor this part a little using factories so we won't have to update this test again in the future when we add new fields.

First we create the factory for our thread table using: node ace make:factory thread and add the title and body columns:

// database\factories\thread_factory.ts

import factory from "@adonisjs/lucid/factories";
import Thread from "#models/thread";

export const ThreadFactory = factory
  .define(Thread, async ({ faker }) => {
    return {
      title: faker.lorem.sentence(),
      body: faker.lorem.text(),
    };
  })
  .build();

With this, in the test, we can now refactor

// tests/functional/thread.spec.ts

const thread = await Thread.create({
  title: "test title",
  body: "test body",
});

to just:

// tests/functional/thread.spec.ts

import { ThreadFactory } from "#database/factories/thread_factory";

const thread = await ThreadFactory.create();

Note that because everything is TypeScript now, you can just type ThreadF... and it should auto suggest ThreadFactory so you don't have to write out the import statements for factories.

For the creation, where we pass title and body to the api client, we can also utilize the factory and the make method, which will only new up an instance but not persist it in the database (unlike create):

// tests/functional/thread.spec.ts

const input = await factories.threads.make();
const response = await client
  .post("/threads")
  .json(input.serialize({ fields: ["title", "body"] }));

auth middleware

So far any user can create threads, let's add some authorization to the routes.

First we create the new test:

// tests/functional/thread.spec.ts

test("unauthenticated user cannot create threads", async ({ client }) => {
  const input = await factories.threads.make();
  const response = await client
    .post("/threads")
    .json(input.serialize({ fields: ["title", "body"] }));

  response.assertStatus(401);
});

Next we add the auth middleware to our routes:

// start/routes.ts

import { middleware } from "#start/kernel";
import router from "@adonisjs/core/services/router";
import ThreadsController from "#controllers/threads_controller";

router
  .resource("threads", ThreadsController)
  .only(["store", "destroy"])
  .use("*", middleware.auth());

That's basically it, but there's two tiny more steps to set up session based auth setup for testing:

We add the plugin to tests/bootstrap.ts:

// tests/bootstrap.ts

import { authApiClient } from "@adonisjs/auth/plugins/api_client";
// 👇 Changes
import { sessionApiClient } from "@adonisjs/session/plugins/api_client";

export const plugins: Config["plugins"] = [
  assert(),
  apiClient(),
  pluginAdonisJS(app),
  authApiClient(app),
  // 👇 Changes
  sessionApiClient(app),
];

We also create a new file in the root directory to store environment variables for the test environment:

// .env.test

SESSION_DRIVER = memory;

The new test is passing now while the others fail.
To fix the other tests we need to send the API request with an authenticated user.

To do this, we first set up the user table.

A migration for users was created automatically, you can find in the database/migrations folder.

Let's create a factory for users:
node ace make:factory user

// database\factories\user_factory.ts

import factory from "@adonisjs/lucid/factories";
import User from "#models/user";

export const UserFactory = factory
  .define(User, async ({ faker }) => {
    return {
      full_name: faker.internet.userName(),
      email: faker.internet.email(),
      password: faker.internet.password(),
    };
  })
  .build();

and we can now add the user to our two failing tests, for example:

// tests/functional/thread.spec.ts

const user = await UserFactory.create();

const response = await client.delete(`threads/${thread.id}`).loginAs(user);

and it works! Sure it's not optimal that any user can delete any thread, but we are getting there...

Relationships

Next, we'll be linking the threads and user models together by adding the "user_id" to threads.
One user can have many threads. Instead of manually linking user_id (which we can totally do), we can encode the relationship in Adonis.js.

We first update the controller to create the thread through the user model:

// app/controllers/threads_controller.ts
export default class ThreadsController {
  async store({ auth, request, response }: HttpContext) {
    const thread = await auth
      .user!.related("threads")
      .create(request.only(["title", "body"]));
    return response.json({ thread });
  }

  // ...
}

And we update both the user and the threads model to add the relationship and the new field:

// app/models/user.ts

import { BaseModel, column, hasMany } from "@adonisjs/lucid/orm";
import type { HasMany } from "@adonisjs/lucid/types/relations";
import Thread from "./thread.js";

export default class User extends compose(BaseModel, AuthFinder) {
  // ...other columns

  @hasMany(() => Thread)
  declare threads: HasMany<typeof Thread>;
}

// app/models/thread.ts

export default class Thread extends BaseModel {
  // ...other columns

  @column()
  declare userId: string; // Note we define the fields in camel case
}

Next, we add the user_id and foreign key to the migration file:

// database/migrations/<timestamp>_create_threads_table.ts

table.integer("user_id").unsigned().notNullable();
table.foreign("user_id").references("id").inTable("users");

The only part that's missing now is to add user_id to the factory as well for tests.
What's interesting is we can also define our relationship there:

// database\factories\user_factory.ts

export const UserFactory = factory
  .define(User, async ({ faker }) => {
    return {
      full_name: faker.internet.userName(),
      email: faker.internet.email(),
      password: faker.internet.password(),
    };
  })
  // 👇 Changes
  .relation("threads", () => ThreadFactory)
  .build();

And now we update our existing threads to use "UserFactory.with('threads')" instead of the "ThreadFactory" so it auto-establishes the relationship for us.

// tests/functional/thread.spec.ts

test("can delete threads", async ({ assert, client }) => {
  const user = await UserFactory.with("threads").create();

  const response = await client
    .delete(`threads/${user.threads[0].id}`)
    .loginAs(user);
  response.assertStatus(200);
  const threads = await Thread.all();
  assert.equal(threads.length, 0);
});

Closing

I'm really happy with Adonis.js V6! The documentation is very fleshed out, the development process is streamlined, the simple to use APIs from back then are all still here, it's fun to write code with it, and the type system is stellar.

I know this is missing some parts from the original TDD course like validation but I'm confident you can do it from here ;)

I do wish a plugin existed to sync models with factories and possibly migrations so there's not so many files to update when adding a field. I was able to hack together a "auto factory builder" quickly. Let me know if you are interested and I can share it!

Rethinking best developer practices

Michael Z — Mon, 19 Feb 2024 05:52:22 +0000

SRP (Single Responsibility Principle)

The single responsibility principle (SRP) is a common way to check whether your function, library, etc. is doing more than it should. “It should do one thing, and one thing well”.

In general, this is a good principle to follow. A function like “saveUser” should not be responsible for also sending out emails. It’s a good feeling to be able to trust that the code is doing its job as expected.

But SRP should not be in the way of creating a user-friendly API. What you often find is that libraries are too focused on the first half of the phrase “doing only one thing”, and neglect the second half “doing it well”.

For example, if you create a routing library, and most users need to be able to accept JSON, don’t make them install additional libraries to do so. Pay attention to user integrations and developer experience, and pave the way for them. Otherwise, while your library is only doing one thing, it’s not doing it particularly well.

Use the best tool for the job

This is such a common thing to hear, it has to be true, right?

It depends. If you develop a feature that requires a new type of technical solution, instead of adding even more software to your stack, at least consider using the existing software you already have at your disposal to solve your problem.

You might get slight benefits with “the best tool”, but is that benefit worth it for the needs of your application? That’s what you have to figure out. Be it web-sockets vs. polling, queues vs. cron jobs, SQL vs. Redis, sessions vs. JWT, SCSS vs. CSS, etc.

Every new software you introduce comes with costs as well. Its basics, best practices, edge cases, and constraints have to be understood by the team. It has to be documented, extra knowledge has to be transferred to new employees, it has to be kept secure and up to date, it may require an additional build step, it makes local development harder/slower, it increases the global complexity, it may be difficult to add automated test to it, it may require more servers/memory/CPU, additional monitoring, it can introduce another source of failure, it might cause unexpected outages in the middle of the night, etc.

Try using less software instead.

DRY (Don't repeat yourself)

The right abstractions in the right places are great.

Without them, you constantly have to make decisions about small things and repeat yourself in many places.

But you don’t want to abstract too early, so what’s a good rule of thumb on knowing when to make that abstraction?

WUSALT > WET > DRY

There is a common term in software development called DRY (Don’t repeat yourself). This, however, is often the wrong approach.

Instead, go WET (Write everything twice).

I guess that’s also not 100% correct. If you are skilled in the language, framework and domain, then there are many things you may as well write DRY right away.

But WUSALT (Write unfamiliar stuff at least twice) is not as catchy an abbreviation.

Generally, DRY code can easily lead to premature abstractions. And once you need similar functionality, you realize that your abstraction has not considered all these additional use cases, and you have to rewrite it from scratch. Only that this time you first have to un-structure the old abstraction before you can restructure. Un-structuring is often a lot harder than structuring it.

By writing things at least twice, you get exposed to these additional use cases.

Best of all, maybe that “second time” will never come and you saved yourself a lot of time by not writing that abstraction.

Stoic Driven Development

Michael Z — Thu, 25 Jan 2024 14:51:52 +0000

If Marcus Aurelius and his philosophical peers were modern-day software engineers, what wisdom might they impart? Let's dive into the stoic-driven developer mindset:

1. What stands in the way becomes the way

Approach new technologies and frameworks with humility. Technical lead Marcus Aurelius advises us to resist the temptation to judge based solely on prior experience or hearsay. Rather than seeing new libraries or methodologies you will be using in your new job as obstacles, view them as opportunities to expand and diversify your skillset. Embrace new approaches and paradigms, transforming challenges into learning experiences.

It is impossible for a man to learn what he thinks he already knows.

2. Be tolerant with others and strict with yourself

Scrutinize your own work diligently, however, be open to different perspectives during code reviews. While maintaining high standards, recognize the value of diverse approaches and avoid unnecessary clashes over personal coding styles.

3. Don't expect that all feature requests are good, but that your code goes well with all feature requests

Echoing Junior developer Epictetus, keep your code open for extension but closed for modifications. Nothing ever happens without change, and as all things in this world, so do requirements change. Embrace the inevitable change in your solutions and leave in some wiggle room to accommodate future enhancements.

4. You don't have to have an opinion about this

Not everything requires a strong opinion or emotional investment. Maintain a level-headed approach, avoiding unnecessary conflicts over preferences in code reviews, post mortems, and tech choices.

5. Everything that happens, happens as it should, and if you observe carefully, you will find this to be so

In the predictable realm of software engineering, view problems as solvable puzzles. Internalize the understanding that software, unlike human emotions, or evolution, follows a logical flow. Debugging becomes a methodical process when approached as a series of traceable and reproducible data flows.

Data gets taken from one place (user input, database, API, fs, ...), it gets manipulated, and moved somewhere else (database, email, API, etc.). That's all that happens, so when investigating a problem you know the outcome already and can work back from there.

The same is also applicable to development. Start by thinking "how do I move this data from here to there" rather than fixating on a preconceived solution.

6. If someone can prove me wrong and show me my mistake in any thought or action, I shall gladly change.

This is the stoic idea of "Strong opinions held weakly." Be open to constructive criticism, and willingly adapt your approach when presented with evidence or insights that challenge your preferences.

7. Focus on What You Can Control

Epictetus believed in concentrating on the aspects of your project that you can influence and improve. Complaining about a company policy to your peer won't fix said policy, and it will drain the finite energy you have for the day that you could have used for something more productive instead.

The same should be considered in planning out new features. Rather than delegating them to external teams, strive to own your software journey to allow for independent changes in the future.

8. Memento Mori: Remember You Will Debug

Accept that bugs and issues are inevitable. By acknowledging the impermanence of perfect code, you become better equipped to handle setbacks. Approach bugs with the mindset that they are a natural part of the development lifecycle.

9. We suffer more often in imagination than in reality.

Remember that it's not things that upset us, it's our judgement of it. Recognize that your judgment, more than the problem itself, can contribute to unnecessary stress.

Senior React.js Engineer Senecar advises against overreacting and planning to migrate the entire project upon stumbling on tech debt. Senecar practiced this daily the time he took over a redux-based GraphQL project. You can approach it step by step, line by line, ticket by ticket, and leave the code a little better than you found it.

^ Image generated with DALL-E.

And there you have it, hopefully you found some enjoyment and truth from this light-hearted article! If you want to get serious with this philosophy look no further than Marcus Aurelius' book "Mediations", or Epictetus' "The Manual", they are quite fascinating to read!

Twitter API suspended? Here's how to fix it

Michael Z — Sun, 25 Jun 2023 04:34:34 +0000

A bunch of Twitter API clients which upgraded from v1 API to the free v2 API were suddenly suspended. The portal tells you to file an appeal, however all "contact support" links lead to a dead end.

I believe the reason this changed is due to a change in the permission model, might be a bug as it's very unintuitive as you will see in a minute.

How to fix it

Go to the Developer Portal and delete the suspended app
create a new app under the existing project
If you generate authentiation tokens, notice how after creating them it says they are "read only", not allowing you to tweet (which is the only thing you can do with the free API)
Go to settings and scroll down to "User authentication set up"
Change the permissions to "read and write", under callback and website URL you can put anything as it doesn't matter.
This will generate oauth keys but you won't need them
Now to go back to "Keys and tokens" and (re)generate both the keys and token, even if you created them before already
That's it, now you should see the access token has "read and write" permissions and you can add the new keys to your application!

Puzzle Classic "Baba is You" recreated in JavaScript - Behind the Code

Michael Z — Wed, 01 Mar 2023 01:03:47 +0000

"Baba is You" is a unique and innovative puzzle game that offers players the ability to dynamically change the game's rules as they progress through each level. The game presents its rules as blocks that players can manipulate. In other words, it's a low-code puzzle game.

How the Game works

To get a better understanding of the mechanics, let's break down how to win and lose in this level:

The player controls Baba, the sheep-like creature you see stuck inside a block of walls.
The "WALL IS STOP" rule is active, preventing Baba from moving out.
By moving to the left, the player can push the "WALL" block and break up the "WALL IS STOP" rule, allowing Baba to move through walls.
Breaking up the "BABA IS YOU" rule results in a loss as there is nothing left that "IS YOU".
Pushing up the "WIN" block creates the "FLAG IS WIN" rule.
To win the level, the player must move Baba to the flag while the "FLAG IS WIN" rule is active.

This is just one way to beat this level. An alternative solution would be to move the blocks around to create the vertical rule "BABA IS WIN" while keeping the horizontal "BABA IS YOU".

In later levels, you might be required to

Push the text block WALL in place of BABA, so it creates the rule "WALL IS YOU" -> You now have control of all WALL objects
Create the rule "WALL IS FLAG", this will turn all wall objects into flags

Everytime I played on the game, the itch to figure out how it was developed grew and grew. So, I finally decided to scratch that itch by recreating it in JavaScript.

Terminology

Before we start coding, let's get the terminology straight.

Blocks refer to any object or text on the game grid
"Nouns" are blocks that represent elements such as WALL, BABA, or FLAG and can have properties.
Operators are linking verbs such as IS, AND, or ON. They link nouns with other nouns or properties
Properties are verbs like STOP, WIN, PUSH, MELT, and adjectives like HOT, which can be linked with nouns.
An "object" is the actual game element, such as the sheep-like creature Baba or the walls that Baba was trapped in
"Text" refers to the textual representation of an object and is used to make up the rules of the game.

Coding

Now, to the fun part!

The Level

A level consists of a three dimensional array to hold the grid. Row, cell, layer, or x, y, z.
We need that final dimension as multiple blocks can be on top of each other in a single cell (like Baba on top of the flag).

For example:

[
  [[text(Baba)]], [[text(IS)]], [[text(YOU)]],
  [[BABA, FLAG]]
]

Now creating a big level in this format is painful. Instead I lay out the level on a a spreadsheet, then copy the cells as csv. The class "Level" takes that stringified CSV and deserializes it at the start of the game into the structure you see above.

cells ending with ! represent the actual objects, while others represent text blocks
you can place multiple blocks in a cell by separating them by a space like ,BABA! FLAG!,

new Level(`
,,,,,,,,,
,BABA,IS,YOU,,,FLAG,IS,,
,,,,,,FLAG!,,WIN,
,,,,,,,,,
,WALL!,WALL!,WALL!,WALL!,WALL!,,,,
,WALL!,,,,WALL!,,,,
,WALL!,,WALL,BABA!,WALL!,,,,
,WALL!,,IS,,WALL!,,,,
,WALL!,,STOP,,WALL!,,,,
,WALL!,WALL!,WALL!,WALL!,WALL!,,,,
`)

For each move the player makes, we serialize the current state of the board back into that format and save it in a timeline array. This allows for"undoing a move", just like in the game.

undo() {
  const previousBoard = this.timeline.pop()
  if (!previousBoard) return
  this.board = deserializeBoard(previousBoard)
  this.updateRules()
}

Blocks

Let's look at how blocks are defined on the code-side.

First, the base class. It's not used directly, but we will inherit nouns, operators, and properties from this class:

class Block {
  constructor(level, position) {
    this.id = this.constructor.name.toUpperCase()
    this.level = level
    this.position = position
  }

  getRow() {
    return this.level.board[this.position.row]
  }

  getCell() {
    return this.getRow()[this.position.cell]
  }
}

And here's the base classes for the individual categories (nouns, operators, and properties):

class Noun extends Block {
  type = 'noun'
  hasProperty(property) {}
}

class Operator extends Block {
  type = 'operator'
}

class Property extends Block {
  type = 'property'

  static onBeforeLand() { return true }
  static onAfterLand() {}
}

Now, to create an actual operator, noun, or property, we simply extend from these classes:

class Baba extends Noun {}
class Is extends Operator {}
class You extends Property {}
class Hot extends Property {}
class Push extends Property {}
class Text extends Property {
  // to reference the actual object. 
  // e.g. The ref for the text BABA is an instance of the object BABA
  ref = null
}

Properties have two event listeners "onBeforeLand" and "onAfterLand", which is all we need to express every interaction between blocks.

Let's see some interactions in action!

Block Interactions

Here's the logic for the DEFEAT property:

if block A touches a block with the property DEFEAT, block A gets deleted:

class Defeat extends Property {
  static onAfterLand(movingBlock, blockWithProperty, { direction, level }) {
    level.deleteBlock(movingBlock)
  }
}

For an interaction between blocks with certain properties, let's look at HOT and MELT.

If block A is HOT and it touches block B with the property MELT, block B gets deleted. We can express it like this:

class Melt extends Property {}

class Hot extends Property {
  static onAfterMove(movingBlock, blockWithProperty, { direction, level }) {
    if (movingBlock.hasProperty('melt')) {
      level.deleteBlock(movingBlock)
    }
  }
}

block.hasProperty is a method on the Noun class that checks if there's a rule "noun-of-block IS given-property":

class Noun extends Block {
  type = 'noun'
  hasProperty(property) {
    return this.level.rules.some(rule => {
      const [noun, operator, ruleProperty] = rule
      return noun === this.id && operator === 'IS' && ruleProperty === property.toUpperCase()
    })
  }
}

We'll look at how the rules are detected at the end as it's the most complex part of the game.

How to move...

We've seen how blocks interact with each other. Let's check out what happens when the player moves on the grid and how the events on the properties are triggered:

class Level {
  move(direction) {
    // avoid moving if the game is already won/lost
    if (this.progress !== 'running') return false;

    // push the current state into the timeline to allow for undoing
    this.timeline.push(serializeBoard(this.board))

    // get all movable blocks on the board
    const movableBlocks = this.getBlocksWithProperties(['you', 'move'])
    this.moveBlocks(direction, movableBlocks)

    // check if the user won/lost -> we look at it later
  }
}

So in essence, we retrieve all movable blocks and call the method "moveBlocks". Let's look at that:

moveBlocks(direction, blocks) {
  const eventOptions = { level: this, direction }
  // for each block...
  // make sure it doesn't exceed the boundaries of the board
  if (!block.canMove(direction)) {
    return false
  }

  const { landingCell, rowIndex, cellIndex } = this.getNextPosition(block, direction)

  // landing cell can have multiple layers. Like Baba on top of Flag
  for (const landingBlock of landingCell) {
    // if block is ROCK and "ROCK IS PUSH", this returns ["PUSH"]
    for (const property of landingBlock.getRuleProperties()) {
      // if any property hinders moving, abort
      if (!property.onBeforeLand(block, landingBlock, eventOptions)) {
        return false
      }
    }
  }

  // move the block by deleting it from the current position and adding it to the new one
  this.deleteBlock(block)
  const blocksInCell = this.board[rowIndex][cellIndex].push(block)
  block.position = { row: rowIndex, cell: cellIndex, z: blocksInCell - 1 }

  this.updateRules()

  // call onAfterLand
  landingCell.forEach(landingBlock => {
    landingBlock.getRuleProperties().forEach((property) => {
      property.onAfterLand(block, landingBlock, eventOptions)
    })
  })


  this.emit('after:move') // allow the UI to rerender
  return true
}

Here you can see both the "onBeforeLand" and "onAfterLand" events being triggered!

Together with this, let's see how the PUSH property is implemented.

Rules such as "ROCK IS PUSH" make rocks pushable.

class Push extends Property {
  static onBeforeLand(movingBlock, blockWithProperty, { direction, level }) {
    return level.moveBlocks(direction, [blockWithProperty])
  }
}

Did you catch it?

If Baba stands in front of a pushable rock and moves in its direction, level.moveBlocks() will trigger the "onBeforeLand" event on "Push", which will once again trigger level.moveBlocks on the rock. We've got recursion!

This is neat because it allows us to very easily do a recursive collision check.

Say, Baba is standing in front of three text blocks "BABA" "IS" "YOU", which are positioned at the very right of the board.
If you try to move to the right, it will recursively attempt to push each block until "onBeforeLand" on the "YOU" block will return false, which will prevent all of these blocks from moving due to this line:

// if any property hinders moving, don't move at all
if (!property.onBeforeLand(block, landingBlock, { level: this, direction: direction })) {
  return false
}

Complements/Transformations

There is a special type of rule that transforms objects. We looked at rules like "ROCK IS PUSH" which adds an ability to the rock. But you can also link two nouns.

"ROCK IS BABA" for example will turn all rock objects on the board into a Baba object. We can perform this transformation after a move like this:

for (const [subject, complement] of complements) {
  // get all ROCK objects
  for (const block of this.getBlocksFor(subject.id)) {
    // replace them with new BABA objects
    const instance = new complement.constructor(this, block.position)
    block.getCell()[block.position.z] = instance
  }
}

We get the complements from the rules, which we will look at later.

Detecting the game's progress

For winning, we can use an event listener on the Win property:

class Win extends Property {
  static onAfterLand(movingBlock, blockWithProperty, { level }) {
    if (movingBlock.hasProperty('you')) {
      level.progress = 'won'
      level.emit('has:won')
    }
  }
}

After every move, we also call "onAfterMove" on every block with a rule again. This is to check for rules like "BABA IS YOU AND WIN" or "BABA IS HOT AND MELT"
At that time, we also check the number of blocks with the property "YOU" and mark the progress as lost if no block is left.

UI Integration

This was the last thing I worked on, as I initially just created unit tests to test the game logic. This allowed me to instantly catch regressions and allow for safe refactoring.

test('can read vertical rules', () => {
  const level = new Level(`
    BABA,,FLAG
    IS,,IS
    YOU,,WIN
  `)

  expect(level.rules).toEqual([
    ['TEXT', 'IS', 'PUSH'], // this is an implicit rule set by default
    ['BABA', 'IS', 'YOU'],
    ['FLAG', 'IS', 'WIN'],
  ])
})

For the UI, we make our code emit events at key moments, like "after:move" to rerender the board, "has:won" to detect when the user has won, or "after:update:rules" when the rules are updated (to render the current ruleset).

We also register some keyup event listerers to allow for moving and undoing!

level.on('has:won', () => {
  alert('you have won!')
})
level.on('after:move', renderBoard)
level.on('after:update:rules', renderRules)

window.addEventListener('keyup', event => {
  const keyDirections = { ArrowUp: 'up', ArrowDown: 'down', ArrowLeft: 'left', ArrowRight: 'right' }
  if (keyDirections[event.key]) {
    level.move(keyDirections[event.key])
  }

  if (event.key === 'z') {
    level.undo()
  }
})

As for renderBoard we simply loop through the board and render the blocks on a CSS grid element, nothing special here.

For the game assets, I scraped the GIFs from the official wiki and named them after their corresponding words. While this is sufficient for experiments like this, it is important to note that using copyrighted material without permission could result in infringement issues if you plan to publish or distribute this.

Rules

The hardest part is detecting the rules of the game, since there are so many possible combinations to consider:

Rules can appear both vertically and horizontally
We must detect both rules between nouns and properties, as well as subject complements
"BABA AND ROCK AND WATER IS PUSH" makes all Baba, Rock, and Water blocks pushable
"BABA IS YOU AND PUSH" makes Baba controllable and pushable.
"BABA AND ROCK IS PUSH AND MELT" makes... you guessed it

We want to encapsulate all this complexity in one function so we don't need to deal with all these rules elsewhere.

So if you have rules like "BABA IS WATER" and "BABA AND ROCK IS PUSH AND HOT", the method "updateRules" should create the following four rules:

["BABA IS PUSH", "ROCK IS PUSH", "BABA IS HOT", "ROCK IS HOT"]

as well as the following complement: ["BABA", "WATER"]

To begin, we start by finding all noun text blocks, as these are the starting points.

class Level {
  updateRules() {
    // this rule is always present
    const rules = [['TEXT', 'IS', 'PUSH']]
    const complements = []

    // rules always start with nouns, so let's collect all:
    const nounTextBlocks = this.getBlocksFor('text')
      .filter(block => block.ref.type === 'noun')

    function addRule(block, axis) {
      // ...
    }

    // check both horizontally and vertically
    for (const textBlock of nounTextBlocks) {
      addRule(textBlock, 'row')
      addRule(textBlock, 'cell')
    }

    // remove any duplicates using https://github.com/MZanggl/flooent
    this.rules = unique(rules, rule => rule.join(' '))
    this.complements = complements
  }
}

This code provides a solid starting point. For each noun found, the "addRule" function is called for both the horizontal and vertical axes. Now, let's dive into how the "addRule" function works.

Consider the rule "BABA AND ROCK IS PUSH AND WATER". We can split this into two parts: the subject "BABA AND ROCK" and the predicate "PUSH AND WATER". The key here is to identify the "IS" operator as that's where the split happens!

The "subject" side should not contain any properties, as "BABA AND PUSH IS ..." would not make sense. We begin by collecting all adjacent text blocks that fit the sequence:

function addRule(block, axis) {
  const ruleBlocks = [block]
  let position = { ...block.position }
  const subjectSequence = [['noun'], ['operator']]
  const predicateSequence = [['property', 'noun'], ['operator']]
  let indexOfIsOperator = -1

  // loop and add blocks to "ruleBlocks" until the next cell is invalid
  while(true) {
    // increment the position on the x or y axis and find a text block there
    position[axis]++
    const nextTextBlock = this.board[position.row]?.[position.cell]?.find(block => block.id === 'TEXT')
    if (!nextTextBlock) break

    if (nextTextBlock.ref.id === 'IS') {
      // disallow multiple IS operators in a single rule
      if (indexOfIsOperator >= 0) break
      indexOfIsOperator = ruleBlocks.length
    } else {
      // check if the sequence matches to 
      // avoid bogus rules like "BABA ROCK IS" or "BABA AND IS"
      const parity = indexOfIsOperator === -1 ? subjectSequence : predicateSequence
      const remainder = ruleBlocks.length % 2
      if (!parity[remainder].includes(nextTextBlock.ref.type)) break
    }

    ruleBlocks.push(nextTextBlock)
  }
  // ... quick interruption
}

We now have a ruleBlocks array that contains valid text blocks to make up a rule. However, we still need to handle cases such as "BABA AND ROCK IS PUSH" and detect complements/transformations like "BABA IS ROCK".

To achieve this, we can simply discard the AND operators, split the array into the "subject side" and "predicate side", and then cross join both sides.

To split the array at the position of "IS," we can use the "point" API provided by flooent.

const [subjectBlocks, predicateBlocks] = point(ruleBlocks, indexOfIsOperator).split()

// we expect every operator except IS to be AND, so we can just discard them
const discardAND = block => block.ref.id !== 'AND'

// cross join - if one side is empty, nothing gets added
for (const subjectBlock of subjectBlocks.filter(discardAND)) {
  for (const predicateBlock of predicateBlocks.filter(discardAND)) {
    // subject block is always a noun, if predicate block is also
    // a noun, it goes to the complements, otherwise, it's a rule
    if (predicateBlock.ref.type === 'noun') {
      complements.push([subjectBlock.ref, predicateBlock.ref])
    } else {
      rules.push([subjectBlock.ref.id, "IS", predicateBlock.ref.id])
    }
  }
}

Conclusion

And with that, we have completed the basic integration of "Baba is You"! Although I haven't provided the full solution in this article, I hope this has provided a solid foundation for readers to piece together the presented code and potentially extend it with more advanced mechanics.

However, it's worth noting that the real game is both affordable and easily accessible, with the added bonus of including a level editor. Therefore, unless your goal is purely for learning and experimentation purposes, it may not make much sense to recreate the game from scratch. Regardless, I hope this article has provided some insight into the game's mechanics and how they can be implemented using JavaScript.

Namespaces are just fine - No need to destructure every object in JavaScript

Michael Z — Mon, 13 Jun 2022 11:16:36 +0000

An increasingly common practice in JavaScript is destructuring. This is great to get rid of otherwise generic terms like in the following examples.

Destructuring objects:

/*❌*/ const results = await fetch('users')
/*❌*/ results.users
/*✔️*/ const { users } = await fetch('users')

Destructuring arrays:

/*❌*/ const results = await validate(request)
/*❌*/ if (!results[0]) throw results[1]
/*✔️*/ const [isSuccessful, error] = await validate(request)
/*✔️*/ if (!isSuccessful) throw error

These are very good use-cases for destructuring!

But then there is the other side of the coin:

const { user: { city }} = results

The variable “city” had a perfect home with the namespace “user”. It’s very clear that “user.city” is the city belonging to the user. With the nested destructuring technique, you lose these benefits.

This overdestructuring can also lead to name clashes, which would require renaming the variable:

const { city } = location
const { user: { city: userCity }} = results

“userCity” vs. “user.city”. Is this difference worth the added complexity and loss of intent?

Compare these two code statements that could follow the above example:

/*❌*/ if (city === userCity) {}
/*✔️*/ if (location.city === user.city) {}

In multi-line statements, over-destructuring can also confuse the reader as to which side of the assignment the reader is currently on (left side or right side):

const {
  user: {
    city: userCity
  },
  location: {
    city: locationCity
  }
  ...rest
} = {
  ...cache,
  user: await getUser()
  date: now()
}

Not enough? How about some inlined TypeScript types to mix things up:

const {
  user: {
    city: userCity
  },
  location: {
    city: locationCity
  }
  ...rest
} = {
  ...cache,
  user: await getUser()
  date: now()
} : {
  user: {
    id: string;
    city: string
  }
  date: number,
  location: {
    id: string;
    city: string;
  }
}

Namespaces are just fine. In fact, they are very helpful in communicating where a variable belongs to. And best of all, you get all of it out of the box.

Code reviews - Are you checking for this?

Michael Z — Thu, 03 Feb 2022 01:08:58 +0000

What do you look for when you review your peer's code? Is it that the new code is consistent with the existing codebase? Do you check for typos? Existence of tests? Correct formatting? Documentation? That the code logic is correct and easy to grasp?

While some of the above can be automated, these may all be important things to check in your daily code reviews.

And while developers love their code patterns and clean code, there is one aspect in code reviews that should be prioritized: The business requirements.

Take this piece of code for example:

const title = article.title
return containsProhibitedWord(title)

Yes, suggesting that the variable "article.title" can be inlined is a good idea. But don’t let that distract you too much, as changing the syntax doesn’t fix the fact that the article body also needs to be checked.

That’s why it is important to not only review syntax and architecture, but also the actual implementation of the requirement.

Note that sometimes, it's after a refactor that you realize the inconsistency with the business requirements because the code is now easier to understand and follow.

Reverse-engineering frontend (Cuphead's film-grain effect)! Can you?

Michael Z — Sun, 23 Jan 2022 22:10:02 +0000

For quite a while I've been thinking how cool it would be to have a website in the style of the fantastic game Cuphead. How would that even look like? Then, out of nowhere, either Netflix, or Cuphead's team - not sure, releases https://cupheadcountdown.com.

Immediately, I noticed the film-grain effect on the website and wanted to have it ;)

If you are not sure what I mean, it's this: https://rqnmd.csb.app/

Let me share with you how I extracted it from their website.

I invite you to try it out for yourself, maybe you come up with a different approach!

If you want to go straight to the end, there you go: https://github.com/MZanggl/film-grain

Let's get started!

Checking the HTML

As usual with these things, opening the "Elements" tab in devtools was the first step to solving this puzzle.

Immediately I noticed it was using Nuxt.js due to elements like <div id="_nuxt">, not relevant yet, but it's at least an indication that the JavaScript will be most likely compiled and not a walk in the park to read.

Going inside <main> I found the accurately-named element <div class="filmGrain"> containing a canvas.
It was spanning the entire page with pointer-events turned off so you could still click around.

<style>
  .filmGrain {
    width: 100%;
    height: 100%;
    position: absolute;
    top: 0;
    left: 0;
    pointer-events: none;
  }

  .filmGrain canvas {
    width: 100%;
    height: 100%;
    mix-blend-mode: multiply;
    position: relative;
  }
</style>

<div class="filmGrain">
  <canvas></canvas>
</div>

Unfortunately it's not so easy to look into a canvas, so that's where the next challenge lies.

Finding the relevant code for painting the Canvas

By focusing on the <canvas> element in the devtools "Elements" tab, you can access it in the console using $0.

Trying out various context types, I found out that it's using webgl.

$0.getContext('2d') // null
$0.getContext('webgl') // bingo!

With this knowledge it's easier to find the relevant code in the compiled JavaScript.

In the "Sources" tab, I right-clicked on "www.cupheadcountdown.com" > "Search in Files" and searched for "webgl".
This yielded 3 results which I checked, after using my browser's "pretty print" option on the bottom left.

The third result looked very promising, here's a snippet from said code (compiled & pretty printed):

this.enable = function() {
    o.animID = requestAnimationFrame(o.render),
    window.addEventListener("resize", o.onResize)
}
,
this.disable = function() {
    cancelAnimationFrame(o.animID),
    window.removeEventListener("resize", o.onResize),
    o.animID = null
}
,
this.render = function(time) {
    o.animID = requestAnimationFrame(o.render),
    o.skipFrame++,
    o.skipFrame >= 10 && (o.skipFrame = 0,
    r.d(o.gl.canvas, .5),
    o.gl.viewport(0, 0, o.viewport.x, o.viewport.y),
    o.gl.useProgram(o.programInfo.program),
    r.e(o.gl, o.programInfo, o.bufferInfo),
    o.uniforms.time = .001 * time,
    o.uniforms.color1 = [o.color1.r, o.color1.g, o.color1.b],
    o.uniforms.color2 = [o.color2.r, o.color2.g, o.color2.b],
    o.uniforms.resolution = [o.viewport.x, o.viewport.y],
    r.f(o.programInfo, o.uniforms),
    r.c(o.gl, o.bufferInfo))
}

Reverse-Engineering the compiled code

The code was fairly readable, frankly I had no idea what all these one-letter variable names were for... Though the frequently used variable o was easy as it was declared just at the top of the function as var o = this;. It's the Vue component instance.

With this, I laid out the code in a class, and I got most of it looking like regular code again.

class GrainRenderer {
  render(time) {
    this.animID = requestAnimationFrame(this.render.bind(this));
    this.skipFrame++;
    this.skipFrame >= 10 && (this.skipFrame = 0);
    r.d(this.gl.canvas, 0.5);
    this.gl.viewport(0, 0, this.viewport.x, this.viewport.y);
    // ...
  }
}

What's interesting about the above code is that the variable names for a class are not shortened (this.skipFrame) and so it's very easy to comprehend all the other code. This is important for later.

Now it's to find out what the variable names "r", "h", and "c" stand for...

"r" is being used all over the place and contains lots of functions like "r.d", "r.c", or "r.f".
"c" and "h" are only being used once this.programInfo = r.b(this.gl, [c.a, h.a]);.

I realized the code is using requestAnimationFrame so the "render" method will run in a constant loop. This is where I now set a breakpoint and triggered the browser's debugger by focusing on the cupheadcountdown.com tab.

Luckily, c.a and h.a turned out to be just strings. Strings containing GLSL language, which is used for rendering webGL.

The code for c.a is simply:

attribute vec4 position;

void main() {
    gl_Position = position;
}`;

while the other string was a lot bigger. It was what entailed the actual code to render the film-grain effect. The devs conveniently left comments in the code:

// Random spots
// Vignette
// Random lines
// Grain

What's "r"...

Now to the final hurdle...

Stepping into some of r's functions with the debugger turned out that it's a rabbit-hole. Rather than digging deep, this got me thinking. Would they really go to such lengths or is this maybe a library? This is where the non-compiled variable names comes into play (like "this.programInfo").

Searching for webgl "programInfo" yielded a few promising results. And finally, the documentation of twgl.js looked like it contained all the relevant functions.

it's quite doable to map most functions by comparing the arguments the functions took, the order in which the code was executed, as well as the variable names.

// cuphead
this.programInfo = r.b(this.gl, [c.a, h.a]);
//twgl.js docs
const programInfo = twgl.createProgramInfo(gl, ["vs", "fs"]);

// cuphead
this.bufferInfo = r.a(this.gl, {
    position: [-1, -1, 0, 3, -1, 0, -1, 3, 0]
})
// twgl.js docs
const arrays = {
  position: [-1, -1, 0, 1, -1, 0, -1, 1, 0, -1, 1, 0, 1, -1, 0, 1, 1, 0],
};
const bufferInfo = twgl.createBufferInfoFromArrays(gl, arrays);

// cuphead
o.gl.useProgram(o.programInfo.program),
r.e(o.gl, o.programInfo, o.bufferInfo),
// ...
r.f(o.programInfo, o.uniforms),
r.c(o.gl, o.bufferInfo))
// twgl.js
gl.useProgram(programInfo.program);
twgl.setBuffersAndAttributes(gl, programInfo, bufferInfo);
twgl.setUniforms(programInfo, uniforms);
twgl.drawBufferInfo(gl, bufferInfo);

The only difficult one was r.d(o.gl.canvas, .5). So I stepped into the function with the debugger and found this code:

function ze(canvas, t) {
    t = t || 1,
    t = Math.max(0, t);
    const e = canvas.clientWidth * t | 0
      , n = canvas.clientHeight * t | 0;
    return (canvas.width !== e || canvas.height !== n) && (canvas.width = e,
    canvas.height = n,
    !0)
}

With this, I opened twgl.js' GitHub page and looked for for "Math.max". After a bit of searching I finally found this code: https://github.com/greggman/twgl.js/blob/42291da89afb019d1b5e32cd98686aa07cca063d/npm/base/dist/twgl.js#L4683-L4695. Got it!

And voila, puzzle solved.

Closing

This was a fun little challenge, I hope you could take something away from it. Even it's just that you should definitely play and (soon) watch Cuphead ;)

Would you have approached it differently?