DEV Community: João L.

If your "Unsubscribe" link requires users to login, you're training them to fall for phishing attacks

João L. — Wed, 07 Jan 2026 14:16:31 +0000

This is an opinion piece based on real events.

It's a tale as old as Unix time. You never asked for these marketing e-mails -- you never select that checkbox out of principle! And yet, companies simply ignore it and send you unwanted communication.

Most marketing e-mails nowadays have a convenient Unsubscribe link at the bottom. Well, maybe not convenient; maybe it's 5pt light gray font, but it's usually there! You click, maybe sometimes you need to confirm with a button, and that's that.

The bad, the ugly!

Some companies require users to sign-in to modify their notification settings. The reason is obvious - this adds just enough friction that a lot of users don't bother and leave it as it is. But many will indeed try to sign-in and unsubscribe.

If a user is ready to sever their relationship with a company, they already deem it very low value. They are very unlikely to watch out for the usual phishing e-mail tricks like suspicious URLs or the e-mail of the sender. Their defenses are likely to be relaxed because it's a low risk action. So when the company asks for their login credentials, they might just provide them without thinking.

By requiring users to sign-in before they can unsubscribe from unwanted e-mails, these companies are normalizing this behaviour. A well crafted phishing marketing e-mail could lead to credential theft. Not only is this poor design and a dark pattern, this is a security risk!

Call to action

When an unsubscribe link asks me to authenticate, I close the tab and mark the message as spam.

I do this deliberately, and I strongly suggest others to do the same. Requiring credentials for a low-value action trains users to associate marketing emails with login prompts, which is indistinguishable from common phishing techniques. Once that pattern is normalized, credential harvesting becomes easier.

This is the feedback loop companies create for themselves. If enough users follow my approach, it reduces sender reputation and harms email deliverability across major providers.

Meow Mountain - postmortem of a 13KB game

João L. — Tue, 16 Sep 2025 13:04:49 +0000

Another JS13k Games just ended and I was able to preserve my 8-year streak of participating in this game jam. In this essay, I'd like to share some of the "low-tech tech" I've used—many of these are low-level development techniques that help me create tiny games.

About the game
Game concepts
- ♻️ Ideas that didn't make it
- Main concept
  - 📖 Story Engine
- Reusable components
  - 👾 Sprites
  - 🔠 Font
  - 👻 Emoji icons
  - 🔉Sound effects
  - 🎼 Music
- Other game features
  - 🤖 NPC AI
  - 🗺 Map generation
Final notes

About the game

This year's "black cat" theme inspired me to create a grid-based adventure game. Over the years, I've explored different genres, learning new game development concepts in the process.

Meow Mountain tells the story of a magical cat who is the protector of a mountain. After taking too long of a nap, the cat accidentally let the magic barrier protecting the mountain from evil spirits collapse. As a result, the villagers inhabiting the mountain stopped tending to the cat altars scattered around the mountain. These altars are essential to the cat's magical abilities, so our protagonist must repair all altars, restore the barrier, and bring peace back to the mountain.

Game concepts

Ideas that didn't make it

This was my first time developing a grid-based game, as well as my first adventure game. The time and size restrictions meant many ideas I had for lore and game mechanics were left on the cutting room floor.

🧙‍♀️ Shapeshifting witch 🐈‍⬛

Initially, the cat was going to be a witch who could transform into a cat to discreetly sneak around the mountain without being seen by villagers. The witch would use her magic powers to help the villagers by improving their harvests, clearing trails they needed to travel between villages, or ensuring they had access to food and water. These side-quests would then motivate the villagers to make offerings at the cat altars, which would provide magic power to the witch. In retrospective, this game mechanic was obviously far too complex to implement alongside everything else.

👨‍🌾 Villagers AI 🏘

Another idea I initially wanted to explore was creating an AI for the villagers. The villagers in the game just wander aimlessly around their village (more on this below). My initial goal was for them to live in houses and having daily routines and jobs. They would leave home each day to go to their workplace, and some could travel between villages. Sadly, none of this made it into the game, so their movements are mostly random.

📋 Goals and Achievements ✅

I also envisioned a more detailed goals & achievements system that players could consult to know what they needed to do next. Because the quest system ended up much simpler (repair the obelisk and the statues) this was no longer a priority. I still show a "new goal" pop-up, which has been well received, but there's no way to review current objectives.

🪄 Magic abilities 🔥

Finally, I planned for the player to be able to use magic for things other than restoring the magic barrier. I had envisioned conjuring spells and special attacks that would aid in side-quests and fighting spirits. Conversely, I wanted the different spirits to also have different powers and attack patterns.

I do wish to find the motivation and time to continue improving my game, and possibly revisit these ideas.

Main concept

I've been wanting to make a Zelda-style RPG game for a while. This year I finally felt confident I could pull it off. The game has a simple story: the protagonist fell into a long nap and the world fell into chaos. The main quest is to repair the barrier by finding the magic obelisk. When the player attempts to restore the barrier, they learn they've run out of magic, so something must be wrong with the cat altar. After repairing the cat altar, the player discovers this isn't enough to restore all their magic, and they must find all altars.

Story Engine

I've used dialogs to guide the player step by step.

I created a simple reusable "story engine" that consumes a storyline data structure and keeps track of dialogs and game events. It's quite rudimentary, as this was my first time implementing something like this. I made creating a clear storyline and onboarding a priority this year because one recurring issue in JS13k is that games confuse players without lengthy manuals. But as they say:

Ain't nobody got time for that.
-- Plato or Einstein or something.

History shows that people don't like reading instructions. So the game starts with soft exposition. The player learns about the existence of spirits, and that this means that the magic barrier has disappeared.

This also introduces the player to the protagonist's combat abilities. Technically, the first spirit (and in fact, all others) doesn't need to be killed. Running away is a viable strategy in this game.

Whenever possible, I tried showing instead of telling. The protagonist finds themselves surrounded by thick bushes. Technically, players are free to cut through the grass and leave the home meadow, but a subtle path tries to guide them toward the cat statue. Once the first statue is cleared, the main actions should be obvious: scratch, repair the obelisk, and repair the statues. I left two other mechanics unexplained for players to discover: teleporting from other statues to the home statue, and "sleeping" at home to restore health.

The game occasionally shows a few more dialogs to guide the player, but game progress is primarily tracked by the magic gauge. Once that gauge is full, it means the player has restored their magic power and can restore the barrier once again.

Reusable components

Over the years, I've learned how to implement various game features. While modern game engines handle most things related to sounds, images, physics, etc., in JS13k you can't afford to use a large, general-purpose game engine. This means much of the core engine functionality has to be carefully optimized.

Following are some reusable blocks I've developed and improved over the years.

Sprites

I've written before about how I've made games without any image files (read more here). There are different ways to achieve this. Images can be procedurally generated (e.g., the minimap in Meow Mountain), drawn using canvas primitives (e.g., all the background images in Market Stree Tycoon, as well as the UI elements in Meow Mountain), or encoded as part of the source code.

I was inspired by xem some years ago to streamline icon creation. When I made Market Street Tycoon, I created my Mini Pixelart Editor, an online pixelart editor focused on creating pixelart with a limited palette, and then generating a string-encoded version of the sprite along with the necessary JavaScript to decode it.

This served me well in recent years since my games were never very image-heavy. However, Meow Mountain has dozens of sprites, including several animations. My sprite editor became too cumbersome to use, so I reverted to plain old PNGs. PNGs compress well when using a limited palette, so this worked for a while. However, I soon felt the need to free up precious bytes from my game.

I wrote scripts to help encode my PNGs into simpler strings, similarly to what the Mini Image Editor did. In general terms, this is how it works:

The first script reads a spritesheet and chops it into individual images
The second script converts an image into an array of values and a list of colors:
- The list of colors contains all colors present in the image
- The array of values contains the index of each color in the palette
- [[1,0,0,0,0,0,0,0],['#000000']] represents a 3x3 transparent image with a black pixel in the corner
The third script encodes this information into a string:
- Since the image has only 2 colors (black and transparent), we only need 1 bit per pixel
- Our array becomes the number 10000000 in binary, which in base 32 is 40

One advantage of this method is that color information is now detached from pixel information, so I can reuse the same game palette throughout. Reusing the same sprite in different colors also becomes trivial. For my 16x16 icons, I achieved around 40% reduction in sprite size, even accounting for the extra decoding code.

I'm hoping to further streamline sprite management into a reusable npm package.

Font

Similar to sprite rendering, I've been using a pixel font where each character is a string-encoded sprite. Since text is just a single color, each letter can be thought of as a 1-bit sprite. For this game I used a 5x5 pixel font. However, unlike last year, I improved the rendering to allow for non-square glyphs. Until now, my fonts were always monospaced.

To make font editing simpler, I use my Mini Font Editor, which is a fork of the mini pixelart editor adapted for creating pixelart fonts.

The encoded font looks like this:

export const tinyFont = '6v7ic,6trd0,6to3o,6nvic,55eyo,2np50,2jcjo,3ugt8,34ao,7k,glc,1,opzc,3xdeu,3sapz,8rhfz,8ri26,1bzky,9j1ny,3ws2u,9dv9k,3xb1i,3xbmu,2t8g,2t8s,26ndv,ajmo,fl5ug,3x7nm,n75t,54br,59u0e,53if,rlev,4jrb,1yjk4,4eav,55q95,18zsz,mi3r,574tl,1aedd,ljn9,a1bd,4f1i,a1fs,549t,53ig,5832,1dwsh,6iw6,6ix0,cbsa,6gix,6fk4,aky7,7mbws,cvtyq,deehh,2sfi3'.split(',');

and just like the sprites, each string like 6v7ic is a base 32 number, which when converted to binary represents a 1-bit array of black and transparent pixels.

The rendering logic is slightly different from sprites, but I'm hoping to bring both together in the same reusable npm package.

Emoji icons

This year I also explored using pixel-art emoji icons as a way to save precious bytes. After all, an emoji costs 2-3 bytes, while a single multi-color icon costs tens of bytes.

The problem is that if you just try to render emoji in canvas, you get a blurry anti-aliased mess. What if we could somehow pre-process emoji to restrict the color palette and eliminate color and alpha anti-aliasing? You can find my experiments over on code pen.

The downside of this method is that devices and browsers use different emoji fonts. Unless we load an actual emoji font, we lose control of how parts of the game look. However, I believe this goes against the spirit of JS13kGames (though others might disagree). This was my first attempt at this approach, so the code might not be the most efficient or elegant.

/**
 * Quantizes rgba color values to 8bit.
 */
const quantizeToPalette = (r: number, g: number, b: number, a: number) => {
  // 1-bit transparency
  if (a < 128) {
    return [0, 0, 0, 0]; // transparent
  }
  const qr = Math.round(r / 51) * 51;
  const qg = Math.round(g / 51) * 51;
  const qb = Math.round(b / 51) * 51;

  return [qr, qg, qb, 255];
};

/**
 * Converts an emoji to a pixelated image by quantizing the colors
 * to 8 bit and the transparency to 1 bit.
 */
export const emojiToPixelArt = (
  emoji: string,
  fontSize = 10,
): HTMLImageElement => {
  // Some emoji are a bit bigger than the font
  const spriteScale = 0.25;
  const spriteSize = Math.floor(fontSize * (1 + spriteScale));
  const padding = Math.floor(fontSize * spriteScale / 2);

  // Create temporary canvas
  const [_, tmpCtx] = createCanvasWithCtx(spriteSize, spriteSize);

  // Draw emoji in chosen font size
  tmpCtx.font = `${fontSize}px sans-serif`;
  tmpCtx.textBaseline = 'top';
  tmpCtx.clearRect(0, 0, spriteSize, spriteSize);
  tmpCtx.translate(-1, 0);
  tmpCtx.fillText(emoji, padding, padding);

  // Read pixels
  const imgData = tmpCtx.getImageData(0, 0, spriteSize, spriteSize);
  const data = imgData.data;

  // Create new image data with quantized colors
  const outImg = tmpCtx.createImageData(spriteSize, spriteSize);
  const outData = outImg.data;
  for (let i = 0; i < data.length; i += 4) {
    const [r, g, b, a] = quantizeToPalette(
      data[i],      // red
      data[i + 1],  // green
      data[i + 2],  // blue
      data[i + 3],  // alpha
    );
    outData[i] = r;
    outData[i + 1] = g;
    outData[i + 2] = b;
    outData[i + 3] = a;
  }

  // Create a new canvas to draw the quantized image
  const [outCanvas, outCtx] = createCanvasWithCtx(spriteSize, spriteSize);
  outCtx.putImageData(outImg, 0, 0);

  // Create an image element from the canvas
  const img = new Image();
  img.src = outCanvastoDataURL();
  return img;
};

Sound effects

Sound effects are small audio clips used in games. Meow Mountain has various sound effects for moving, attacking, taking damage, etc. Since sound files are typically very large, JS13K game developers usually produce sounds by rendering a sound wave and playing it with the Web Audio API. My "sound player" looks like this:

export const playSound = (f: (i: number) => number) => {
  // Create a new audio buffer.
  // This buffer has 96000 samples (audio "pixels")
  // and 48000 samples per second. More samples
  // per second allows for higher sound quality.
  const m = audioCtx.createBuffer(1,96e3,48e3);

  // Create an audio buffer, that will contain
  // the sound data.
  // Access a single channel data for mono sound.
  // For stereo, more channels can be used.
  const b = m.getChannelData(0);

  // This function expects an f() function,
  // which generates a sound wave for each sample i
  for(let i = 96e3; i--;) b[i] = f(i);

  // The buffer source object controls the 
  // playback.
  const s = audioCtx.createBufferSource();

  // We connect the buffer to the source
  // and connect source to the audio destination
  // which by default is your device's speakers.
  s.buffer = m;
  s.connect(audioCtx.destination);

  // Start the audio.
  s.start();
};

The f() wave function can be any function that consumes i and returns a number.
For example, f(i) => Math.sin(i) returns a pure sine wave. The function that plays a step sound in Meow Mountain looks like this:

export const step = playSound((i: number) => {
  const n = 2e3;
  return i > n ? 0 : 0.15 * (Math.random() * 2 - 1) * Math.sin((Math.PI * i) / n);
});

Math.sin((Math.PI * i) / n) provides a certain pitch to the sound, while (Math.random() * 2 - 1) provides random noise.
Noise helps the wave sound more "natural" and less like a pure wave.
In this example, 0.15 is used to reduce the amplitude of the wave (the sound volume) to 15%.

Music

To play music, I use an audio worklet.
Worklets are small browser workers that run in the background doing work on a separate thread, preventing the main JavaScript thread from being blocked.
For example, to produce continuous music at a sample rate of 44000Hz, we would need to interrupt the main thread 44000 times per second. In comparison, the typical game cycle updates at 60Hz. Moving music processing to a background worker frees up significant resources for the rest of the game.

Audio Worklets are a special kind of background worker that handles audio processing and has access to special Web Audio APIs not available in regular JavaScript, namely the AudioWorkletProcessor class. I'm writing a longer article specifically about creating music with Web Audio, so stay tuned. In essence, it works the same as I described in the sound effects section. A wave function generates a stream of values that form a wave. In this case, we continue producing successive waves in different frequencies and amplitudes, forming a melody. In Meow Mountain, the wave function looks like this:

const SAMPLE_RATE = 40000;
const NOTE_LENGTH = SAMPLE_RATE / 4;
const BaseSound = (
  pitchOffset: number,
  sustainTime: number,
  volume: number,
  s: (t:number, p:number) => number,
) => (value: PitchLength) => {
  const [pitch, length] = value || [0, 1];
  let t = 0;
  const p = 2 ** ((pitch - pitchOffset * 12) / 12) * 1.24;
  const decay = Math.pow(0.9999, 2 / (length));
  return function render() {
    if (pitch === 0) return 0;
    ++t;
    if (t >= (length * NOTE_LENGTH)) {
      return undefined;
    };
    const sustain = t <= length * NOTE_LENGTH * sustainTime ? 1 : Math.pow(decay, t - length * NOTE_LENGTH * sustainTime);
    return s(t,p) * sustain * volume;
  };
}

The base sound function provides an envelope for each note, with sustain and decay times.
But the timbre of this sound is given by the s() parameter, which can be something like (t,p) => Math.tan(Math.cbrt(Math.sin((t * p) / 30))).
Explaining why I used tangent, cube root, or sine in this example is beyond the scope of this article.
I encourage you to experiment with wave functions to hear how they sound.

Other game features

Now that we've explored some general technical concepts that can be reused in other games, let's dive into some game-specific features.

NPC AI

This was my first time implementing any sort of autonomous NPCs in a game. The algorithms are very rudimentary and probably quite inefficient.

The villager

The villager spawns somewhere within the radius of the village and then follows this algorithm:

Look around for empty directions to move to
If it has a previous direction, move in that direction again with 80% chance
Otherwise pick another possible direction
Superstition subroutine:
- Look ahead 3 cells
- While player is in one of those cells, increase superstition
- Repeat until player is not present
- Otherwise, continue moving
Continue moving for a whole cell grid, then go to step 1

As I mentioned above in "Ideas that didn't make it," I wanted complex villagers with proper paths, jobs, and homes. For this first version, I decided that just moving randomly was enough. However, this did mean that sometimes villagers get lost in the forest far away from their home village. In particularly unlucky cases, villagers can get stuck in the player's path, making it impossible to finish the game.

The spirit

The spirits spawn somewhere in the vicinity of the cat altar they haunt. They use the pixel-emoji rendering described above. There are
9 spirit species with increasing strength.

They use a simple breadth-first algorithm to find a path to the player.

Look around in a 10x10 square for the player
If the player is found, use breadth-first search to find an empty path from the spirit to the player, going around obstacles
- Other spirits are not seen as obstacles by the algorithm, allowing spirits to "gang up" on the player
- Take one step towards the player
If the player is not found, stay still
Repeat

Again, this might not be the most efficient. Namely, the BFS algorithm is very simple and makes it fairly easy to evade spirits as they have a tendency to move up and down before moving left or right. An improvement would be to move in the general direction of the player first, or to allow them to move diagonally.

Map generation

I wanted to create a grid-based map that felt organic and not monotonous. At the same time, I needed the map generation to be deterministic to avoid cases where some players would find themselves on impossible-to-win maps (although somehow this ended up happening in the final version anyway due to poor testing). For this, I used a deterministic pseudo-random number generator based on a seed.
To do this in a size-efficient way, I developed a map-rendering algorithm:

Create a 160x160 grid
Fill the whole grid with trees
Clear out cells along a list of paths in the map:
- A path is a series of coordinates and widths like [x, y, w]; for example [[10, 10, 2], [10, 20, 2], [20, 20, 3]] is a path with 3 vertices and 2 edges, where the first segment has a width of 2 and the second segment has a width of 3
- For each path, apply a level of random jittering to the edges, making them look more organic
- Each path can also contain bushes in random cells
Clear out a list of circles in the grid:
- Similar to the paths algorithm, large circular clearings are cleared for some of the villages
Place the villages on the map from a list of villagers:
- Randomly place a number of houses within the village radius
- Randomly place a number of villagers
- Randomly place bushes
Place the cat altars on the map from a list:
- Clear a 3x3 area around the altar and fill it with bushes
- This prevents the altar from being surrounded by trees, ensuring the player has access to it
Place the Obelisk in the center of the map
Place the starter spirit
Place the cat

Final notes

In general, there's nothing revolutionary here. I was able to pack quite a bit of content into the game within the size limit. In retrospect, quite a few things could have been optimized if I had more time, especially things I implemented early on when I wasn't yet settled on all the game mechanics. The map generation is quite messy and overcomplicated at times. The NPCs could have been a bit smarter.

If you're curious about my code, the source is available on my GitHub. https://github.com/lopis/meow-mountain. If you want to check the game out, play it here.

🎵 JavaScript music! 🎸 JS13K Games Community Soundtrack 2024 🎹

João L. — Mon, 30 Sep 2024 12:39:04 +0000

Just like we did last year, the JS13K Games community has put together an album with some of the melodies and sounds of this years entries.

These songs were all generated using javascript and the Web Audio API. You can find links to the respective games in each song.

Gotchas while developing a tiny web game

João L. — Thu, 26 Sep 2024 17:22:37 +0000

Another year, another JS13K Games edition is over, the game jam where you have to develop a game under 13KB (here's mine 🙌). This strict size limitation means that we often have to implement most things from scratch, as most game engines are prohibitively large. This means that we're constantly reimplementing the metaphorical wheel, which leads to fresh new bugs.

As always, we're encouraged to playtest our colleagues' games. The following is a list of a few gotchas, in very limited depth, which I've collected while testing games this year.

1. Players don't have the same fonts as you

This should be obvious, but each computer has a different set of fonts installed. This means text will look different for other players. It's not just that individual letters look different, but the whole size occupied by them is different, both in width and height, regardless of font size. Don't rely on text having the same size for other players.

The above screenshot from the great game Dungeon Of Curse is an example of this. The title screen is cut off because the font is unexpectedly wide in my system.

Because embedding whole font files is too expensive, many developers simply create tiny fonts for their own games. But if you go the easy route and use system fonts, be sure to leave enough wiggle room for chunkier fonts.

2. There are screens with very high refresh rates.

For the longest time, most screens have had refresh rates of 60Hz. And so when calling requestAnimationFrame on javascript, you would expect to get 60 updates per second. However, higher refresh rates are very common nowadays, ranging from 75Hz to 120Hz or even 400Hz.

This is important to keep in mind because if you update your game state equally on each frame while disregarding the actual frame rate, your game might become too fast. So you either have to limit your game's refresh rate, or make it so that updates in your game depend on the time interval between updates.

I'm not going to pretend I'm an expert — this issue caught me off guard during this jam — so here is a helpful link on the subject:

https://gafferongames.com/post/fix_your_timestep/

3. Beware of accessibility features

It's honestly already hard enough to fit a whole game in 13kb and to build it in just a month. But there are people out there who struggle with using technology every day. They sometimes use accessibility features in their browser or OS which might clash with the games we create.

One such case is the feature "search as you type", which causes typing to initiate finding in the page. This can be circumvented by calling preventDefault() while the player is controlling your game with the keyboard.

It's up to you whether and how much you want to prepare for computers with diverse setups. Just keep in mind that not paying attention to those details might mean your game is completely broken for some players, and it's unfair to blame them for it.

4. Voice synth

"window.speechSynthesis is undefined"

This was a weird one. In case you're not familiar with it, the Web Speech API is a web API that lets you reproduce voice

Apparently on some systems (like mine) this is disabled or absent. It can be toggled in Firefox in about:config under media.webspeech.synth.enabled.

I didn't penalize any game when this happened, despite their games crashing catastrophically. But the fix is as easy as verifying that speechSynthesis with conditional chaining: window?.speechSynthesis.

And do keep in mind that the browser is actually using the voice synthesizer of the operating system. No OS voice synthesizer installed, no speechSynthesis.

4.1 Incorrect voice language

Even if the user has a voice synthesizer, has it enabled on the browser, and even if window.speechSynthesis is defined, you're still not off the hook! To everyone's surprise, there are people out there with devices in languages other than English (</s>).

When calling getVoices() to use the voice synthesizer, you might not be provided an English voice. Or perhaps not as the primary voice. Hilarity ensues when you try to read an English sentence in another language.

5. Browser compatibility is still important

Talking about different setups, many people seem to think that Chrome is the only Internet browser around these days. Or worse, that whoever doesn't use a Chromium-based browser deserves a worse experience.

I'm a strong apologist of the open Web and the current Chrome monoculture is harming it. Google shouldn't get to decide what becomes a standard and what doesn't.

It's your job as a developer to make sure your code runs correctly on the different browsers.

6. People are even more diverse than computers!

While computers and browsers are diverse, people are even more! While developing a game, you will develop strong biases that can be hard to get rid of without external help. Is the game goal clear enough? Is it too hard, or does it ramp up in difficulty too fast? Are people used to playing games with just their keyboards anymore?

Besides the generous help of playtesters from our community, this year we were lucky to have access to Poki as a playtesting tool. This experience truly humbled me.

Out of 20 playtesting sessions, 15 players quit within 5 seconds because they didn't understand that the game didn't use the mouse
If the goal isn't clear without reading instructions, you already lost 90% of the players motivation to try your game. I'm not exaggerating. Like in cinema, you should show, not tell, as no one likes cheap exposition.
Most players will not read things unless they realize they have to; they must be given time to accommodate to that mindset.
Players have different backgrounds; while game concepts might be obvious for you, they won't be obvious for everyone.
A little hand-holding in the beginning is very useful, as letting the player win a little improves their engagement
However, too much hand-holding or lack of game progression and the game gets boring fast.

Introducing the first JS13K Games Community Soundtrack

João L. — Mon, 23 Oct 2023 15:54:51 +0000

The best games all have something in common: great soundtracks.
But I'm sure I don't need to tell you that great game soundtracks don't need big budget philharmonic compositions to e fun experiences. In fact, many fun games have simple tunes created in Javascript using a myriad of tools, or even programmed by hand directly using the Web Audio API.

Despite the tough size constraints, the top games in JS13K wouldn't reach the top if they didn't also get top marks in the audio category. Some of the games offered complex, dynamic, and catchy soundtracks that seamlessly blended with the gameplay.

This year our community decided to extend our cooperation a bit longer. We're banding together to collect these tunes and create the first ever JS13K Games Community Soundtrack.

Join the project

Did you participate in this year's competition? Has your game included a melody that deserves to be heard on loop? I'd like to invite you to join us over on slack to join our group and share your music. If you need help extracting or recording your music, you'll find some helping hands on slack too.

A tiny pixel art game using no images

João L. — Wed, 13 Sep 2023 10:49:00 +0000

As is usual this time of the year, I participated in the Js13Games game jam where we have 1 month to create a game that fits under 13KB.

I didn't have a lot of time this year for a variety of reasons, but I tried my best to complete something. This year's theme was "XIII Century". I didn't want to do the obvious and focus on wars and knights, both because that seemed too obvious and also because creating games about violence is just not my jam (pun intended). So I thought I would do something about merchants and trading.

This year I wanted to challenge myself to learn more about WebGL. And because images are often the densest part of these games (each tiny image can easily gobble up a couple precious KBs!), I wanted to create a game with images that were fully generated by code. This post talks about my experience with making pixel art in the web canvas.

Concept art

Not actual gameplay!

I idealized a stand in a market where the player would be selling the goods they purchased before. The play could choose the price and arrangement of items. Barrels could hold liquids like beer or conserves like olives, while the boxes could present fruits, bread and other objects.

I called the game Market Street Tycoon because I dreamed that the game would have progressing levels where the player would control all the shops in the market. Alas that was a bit too much for my free time during the month-long competition.

I started with drawing some concept art. GIMP is a pretty alright pixel art editor. I decided to create a game with the same resolution as the Gameboy Color, 160 x 144. This decision has several implications. On one hand it leaves little space to write text and add controls, and anything drawn will have very little detail. On the other hand, pixel art this small is great to mask your bad drawing skills. It's also much easier to develop a game with a fixed resolution.

Pixel art in the canvas

The web canvas is notoriously inhospitable for pixel art. Unless one takes care to align everything very neatly to the pixel grid, you can expect very blurry lines. While there are options to disable anti-aliasing of images, the same isn't possible for drawing shapes or text.

Using the native 2D rendering functions won't be enough. Yes, it's possible do draw sharp rectangles, but ellipses and lines won't render sharply when zoomed in. Even when drawing rectangles, there are some quirks in the way certain browsers do it.

Rectangles and borders

In the example above, I'm rendering a 20px x 20px square with a black 1px stroke. Not only does the stroke render 2px wide, but it is also semi-transparent. This is because, although the square is aligned to the grid, the stroke is centered in the edge of shape, so the stroke goes half pixel to each side. Standard DPI computers can't deal with half-pixels, so that's what we get. Also, you might have noticed that it looks different in Firefox and Chrome. I had this problem initially when drawing the bricks in the background of the game.

My quick solution was to simply draw 2 squares, one rendering inside the other.

x = 20, y = 20, width = 20, height = 20
ctx.fillStyle = 'black';
ctx.fillRect(x, y, width, height);
ctx.fillStyle = 'white';
ctx.fillRect(x + 1, y + 1, width - 2, height - 2);

The sharp eye might have noticed the obvious limitation of this approach: it draws opaque rectangles. This means it's not possible to draw transparent rectangles on top of other things. But for my use case of drawing bricks in the background, that's perfectly acceptable. In fact, I only need to draw the "stroke" as a single screen-sized dark backdrop to speed things up.

Placing pixels on the canvas

There are two common ways to draw individual pixels. The first one is to form an ImageData object with the desired dimension and fill in its data.

ctx.fillStyle = "yellow"
ctx.fillRect(20, 20, 20, 20)
// copies a section of the canvas into imagedata
let imageData = ctx.getImageData(20, 20, 20, 20)
let i = 0
while (i < 20) {
  imageData.data[4 * 21 * i] = 0       // red channel
  imageData.data[4 * 21 * i + 1] = 0   // green
  imageData.data[4 * 21 * i + 2] = 0   // blue
  imageData.data[4 * 21 * i + 3] = 255 // alpha
  i++;
}
// places the image data back into the canvas
ctx.putImageData(imageData, 20, 20);

The reason why we need to use getImageData and then putImageData is because, even though most pixels of the image data are transparent (alpha channel = 0), when we put the data back in the canvas, it replaces whatever was in that position.

It's also confusing what we're doing in the while in the example above. imagedata.data is a one-dimensional array, but our image is two-dimensional, so we need to map x and y to the index of the array.

The second method doesn't require any mapping, and can draw "pixels" directly on the canvas. Essentially, the second method draws a tiny rectangle for each pixel. The following snippet renders the same yellow square from before.

ctx.fillStyle = "yellow"
ctx.fillRect(20, 20, 20, 20)
ctx.fillStyle = "black"
posx = posy = 20
for (let i = 0; i < 20; i++) {
    ctx.rect(posx + i, posy + i, 1, 1)
}
ctx.fill()

I'm pretty sure this is terribly inefficient, but it is also really intuitive because it uses the same functions (i.e. rect) used to draw the bricks, the menus, the buttons etc. For that reason, I mostly used this approach for drawing pixel art.

Drawing pixelated lines

I didn't want to reinvent the wheel here. Surely someone has created a line-drawing algorithm. I looked around for algorithms and did find different ones with varying complexity. After spending sometime trying to make them work for my use case, I sat down and decided that this has to be simple enough... So I reinvented the wheel.

  drawLine(x0: number, y0: number, x1: number, y1: number, color: string) {
    // It's necessary to start from rounded coordinated
    let x = Math.round(x0);
    let y = Math.round(y0);
    x1 = Math.round(x1);
    y1 = Math.round(y1);

    // Calculate the deltas
    let dx = x1 - x0;
    let dy = y1 - y0;
    let dmax = Math.max(Math.abs(dx), Math.abs(dy));
    // Either dx or dy will equal 1
    // and the other will be less than 1
    dx = dx / dmax;
    dy = dy / dmax;

    const points = [ ];
    this.context.fillStyle = color;
    while(dmax--) {
      // The points won't have whole coordinated;
      // We'll round them later.
      points.push([x, y]);
      x += dx;
      y += dy;
    }

    this.context.beginPath();
    points.map(([px, py]) => {
      // We round the coordinates when drawing the pixel.
      this.context.rect(Math.round(px), Math.round(py), 1, 1);
    });
    this.context.fill();
  }

And to draw the clock, I use cos and sin to draw lines that start in the center of the clock and go around in a circular motion.

this.context.beginPath();
this.context.fillStyle = WHITE2;
this.drawCircle(WIDTH / 2, 8, 7);
this.context.fill();
// t between 1 and 0
const angle = 2 * Math.PI * t - Math.PI/2;
const xc = WIDTH / 2;
const yc = 8;
const r = 6;
this.drawLine(xc, yc, xc + r * Math.cos(angle), yc + r * Math.sin(angle), BLACK);

Drawing pixel art icons

Despite the click-bate-y title of this article, I did use "images" in the game to draw the little icons for the apples and etc. But instead of image files, they are represented by a compressed string that codifies the position of the pixels and their color in a palette of 8 colors.

Here I've used xem's mini pixel art editor.

Xem's code is strongly minified, so I had to rewrite it slightly to understand what was going on. I minimize all my code later, so I like to always keep my source code tidy.

  // Adapted from https://xem.github.io/miniPixelArt/
  // An icon looks like this: '@X@@C@RSERRBWRGx@'
  drawIcon(icon: string, x: number, y: number) {
    const imageData: number[] = [];

    [...icon.data].map(c => {e
      // Decodes each character
      const z = c.charCodeAt(0);
      imageData.push(z&7);
      imageData.push((z>>3)&7);
    });

    // Draw the pixels
    for (let j = 0; j < icon.size; j++) {
      for (let i = 0; i < icon.size; i++) {
        if (imageData[j * icon.size + i]) {
          const index = 3 * (imageData[j * icon.size + i]-1);
          this.context.fillStyle = '#' + PALETTE.substring(index, index + 3);
          this.context.fillRect(x + i, y + j, 1, 1);
        }
      }
    }
  }

Drawing text

For this i simply used xem's mini pixel font. This is pretty ingenious. First the text is rendered in a separate canvas in black and white, but anti-aliased. Then the pixels are read from it and converted to black or white depending on a threshold of brightness. Finally, the text is drawn on the game pixel-by-pixel.

The advantages of this method is that I don't need to include a pixel font in my game - I'm using your system's fonts! I also can leverage using unicode to provide symbols for my game.

The downside is that is doesn't look great!

Some letters can be hard to read and their shape isn't consistent. Finally, drawing all these pixels is, again, terribly inefficient.

Final notes

It was a lot of fun to make pixel art with the canvas. I look back at my older games and this one looks so much better. I'm particularly proud of the slick curtains animation.

This article is by do means a tutorial or an explanation of bad practices. This project was built under strong constraints (game size limit and 1 month deadline) and these are simply the solutions I found for my problems.

If you're still curious about the code of the game, you can check the source out on my github: https://github.com/lopis/market-street-tycoon. If you want to play the game, you can do so here: https://js13kgames.com/entries/market-street-tycoon

Update

In the time since publishing this article, I went back and redid the way I draw fonts in an easy and cheap (in kb) way. It's not without drawbacks. I hope to write a bit about it too. If there's interested, let me know in the comments!

Creating a tiny zen game using Kontra

João L. — Thu, 01 Jun 2023 06:16:43 +0000

Note: I forgot to post this article, and almost 2 years have passed since. This game was submitted for the 2021 competition.

Another year has passed and with it another JS13K game jam has come to an end. If you're not familiar with this game jam, the challenge is to create a web game that fits in under 13KB (zipped), including code, and assets. This year's theme was "space", so it made me think of something like "dimension". My interpretation of this theme was to create an empty space where some agents would roam and interact.

The game concept

I had lots of ideas for this game, but not so much time to implement them. Even though the competition runs for 1 month, work got in the way, and then I was away with my family for some time too. I imagine an agent-based game where each agent was an ant explored the area around the ant nest. I envisioned a game map with predators, food and obstacles.

The main game mechanic that I wanted to focus on was the ability of ants to use chemical signals to follow each other- If you want to learn more about ants, watch these videos.

Basically, each time an ant moves, she leaves a chemical trail behind. Other ants are able to pick up on this trail. The more ants follow a trail, the more they reinforce it, and the more ants tend to follow that path.

While implementing these ant-like behaviours, I became so obsessed with watching my creations move around and follow that I ended up focusing my whole game on the concept of ant watching, and creating a relaxing artistic experience.

The Algorithm

I went back and forth thinking about how to better represent the ant space. I initially tried to use a square or hexagonal grid where ants would move in discreet steps. The chemical trails would also only exist in discreet locations in space. The problem with using a grid if that it would make the trails too restricted and ugly, and animating the ants would be more annoying. Furthermore, maintaining the 3-dimensional array to represent that hex grid and all its data got very ugly, very fast.

The solution I came up with was to use the actual canvas as a data store for the trails. The ants's position is kept by Kontra (the game engine) and the ants "paint" the blue trail on the canvas on each update.

Each ant follows a very rudimentary algorithm:

If the "blueness" ahead is high, move forward
If the "blueness" on the right if high, turn slightly to the right
If the "blueness" on the left if high, turn slightly to the left
Else, continue forward with a chance of turning slightly to the side randomly.

The "blueness" of a pixel, as the name indicates, is how blue a pixel is. The more ants leave a trail on a place, the bright the blue color, and the higher its blueness. In a future iteration of this experiment, ants would leave trails of different colors to mean different things. In natural, ants leave different chemical trails to mean "just exploring" or "i found food". By using the 3 RGB channels of each pixel on the canvas as separate data, I could theoretically have overlapping trails of different types.

But for now, all my ants do is explore, so all trails are blue.

Nonetheless, even with this very rudimentary algorithm, the emergent behavior of dozens of ants was already quite interesting to watch. I played around with the values a lot to try to fine tune how the "ant art" looked; the final version use these values:

The "trail radius" was set to 2 pixels
When looking ahead or to the sides, the ant looks about 4 pixels in that direction (the "lookout distance", twice the "trail radius")
When inspecting the sides, the ant looks 60 degrees to the right and left (the "lookout angle")
When turning to the sides, the ant only turns 30 degrees (half of the "lookout angle").

Animation

I wanted ants that were more than black dots on the screen, so I tried to learn how ants walk. Essentially they walk 3 legs at a time.

I used Inkscape to create a basic model of the ants, and then moved their legs a little. I figured 8 frames for the whole movement should be enough, given the small size of the sprites. Using Kontra, it was trivial to implement the sprite animation. You just provide the sprite dimensions, the frame rate, and the frames that correspond to each animation, and the engine does the rest.

Kontra

Kontra is a lightweight library for creating javascript games. It's the first time I have used any sort of game engine in this competition, but I found it immensely helpful in allowing me to quickly prototype my game without worrying about the basics.

Kontra provides a game loop, a sprite-based character system, events, input controls, as well as helpful utilities to check if sprites are colliding and move them easily.

The documentation is a bit lacking at times, but for such a tiny library, it's really not that much of a problem.

Next steps

Maybe because this was a very relaxing game to make and play, for the first time I actually feel like continuing the development of this project. Here are some extra ideas I have.

Sense of direction

I want to improve the sense of direction of the ants. In the real world, ants seem to know in which direction home is on a trail. My ants just follow the path mindlessly. One way to do this would be to make the strength of the trail weaker as they move forward, creating a tendency for ants to return home vs move farther away.

Feed the ants

I want ants to explore the space with a purpose. I want to add bits of food that they want to carry home. For this I will need to create a different trail for them to follow that indicates the presence of food.

Smarter explorers

Some ants in nature follow an interesting exploration algorithm: if they bump into many ants, turn more frequently; if they don't, follow a more straight line. This simple tactic allows ants to cover a bigger area more efficiently without a map. They will naturally venture outwards.

It's ♿️ Global Accessibility Awareness Day!🌈 Have you done your part?

João L. — Wed, 17 May 2023 15:51:54 +0000

Accessibility comes in many shapes and forms, and doesn't benefit just those with chronic disabilities. It's also often the burden of the developers to learn and "apply accessibility" as an after though, but everyone has responsibilities.

The third Thursday of May is Global Accessibility Awareness Day! How are you helping your company creating more accessible products? Is your workplace accessible?

Who's responsible for accessibility in software development?

João L. — Wed, 17 May 2023 15:00:00 +0000

It's Global Accessibility Awareness Day! So in the spirit of a11y day, I have a question for you:

In software development projects, namely those with UIs, who's responsible for paying attention to the accessibility of said UIs? Is it the project manager? Or is it the designer? The software developer? Perhaps the QA engineer? As you can probably guess, everyone has their own responsibilities.

I asked my colleagues to answer two questions: what is your role, and how does it contribute to developing an accessible product?

Product Manager
Product Designer
Content Designer
Frontend Engineer
Mobile Engineer
QA Engineer
A11y Champion
Final Notes
- Backend Engineer
- IT Admin
- User support

Product manager

As a product manager, I define a vision, strategy and roadmap for our products, based on the overall company direction.

My daily tasks include prioritising features and requirements,
coordinating collaboration with other teams when needed, writing acceptance criteria (AC), analysing trends and patterns in the industry and analysing customer feedback and analytics data.

I ensure that accessibility is part of the "definition of done" of a project or feature by planning for the necessary capacity for implementing accessible features. I review projects regularly to stay up-to-date with the latest accessibility principles. I work with the company's accessibility experts - mostly developers - to establish a baseline of accessibility requirements.

Product Designer

As a product designer, I help keep our design system alive and up-to-date. This includes not only creating new components, composing layouts and design interactions and animations, but also establishing and following design principles across the organization.

These design principles include a set of accessibility guidelines that must be followed when creating design system (DS) components, as well as when developing feature work. I routinely review these components in terms of color contrast, font size, spacing, copy, and navigability, to make sure they follow the established guidelines.

I also lead user surveys and user tests that allow me to see how real users use our products, and how they perceive different prototypes.

Content Designer

I strive to understand how content (i.e. text, image or otherwise) influences user behaviour. I'm responsible for creating and shaping the content strategy and user experience in the different mediums (web, mobile, socials). My role blends creativity, storytelling, and data-driven insights to create cohesive and persuasive digital experiences.

By considering accessibility guidelines and incorporating practices such as alt text for images, proper heading structure, descriptive text in links and buttons, succinct and clear copy, I help make information accessible to a broader audience, enhancing the overall user experience for people with diverse needs.

Frontend Engineer

As a developer, I bring designs to life through code following the acceptance criteria. I write automated tests to validate my implementation, but also manually test it before a release. I also review my colleague's code, and participate in design reviews and project planning.

I'm responsible for staying up-to-date with web accessibility standards. I use semantic HTML and ARIA labels, paying special attention to the interactive elements of our pages, like forms or dynamic content. Sometimes, special labels need to be added specifically for screen reader users.

Finally, I set up a11y automation tools like Lighthouse to assure high code quality throughout the team, which flag various accessibility issues like color contrast and HTML problems.

QA Engineer

My main role is being the quality coach of the team. I establish cross-project QA guidelines, create templates for QA mind maps, create testing plans for developers, and establish cross-project acceptance criteria, like target browser versions.

I also write automated tests, namely end-to-end acceptance tests, e.g. using tools like browserstack. Manual QA of whole projects is also often my responsibility.

I ensure that accessibility requirements are included in the product ACs as well as in the technical ACs. I also use tools that report several a11y issues in the browser like WAVE while testing products.

Mobile Engineer

As a mobile engineer, I create and maintain our company's mobile apps. I create new features based on a design, and fix bugs reported to us. It's my responsibility to understand mobile UX patterns. I communicate effectively with PM, Leads and Team Member regarding expectations, and participate in project planning.

I must ensure that elements are easily discernible by color and contrast regardless of the users' theme. I identify where alt texts are needed for elements which are either directly relevant (e.g. buttons) or which is only represented graphically. A big part of this is knowing the semantics of each type of element.

I also perform manual accessibility QA using the native screen reader, using alternative navigation methods, using apps without looking at the screen, or with a single hand.

Accessibility Champion

The "Accessibility Champion" can be anyone in the company, really.

As the Accessibility Champion, I campaign for inclusive design at every step of product development, as well as in other company functions. To do that, I keep up-to-date with the community standards and strive to learn as much as possible about the topic. The Accessibility Champion can be an abled person.

I organize cross-team and cross-discipline workshops. For example, I invite experts to increase company knowledge on a11y, and to show us how accessibility features are used both on computers and smartphones. I also write cross-team documentation and guidelines, and try to mentor new champions from different teams.

Final Notes

Without trying to be exhaustive, this is should give you an idea of who's responsible for accessibility in a company: everyone. I'll leave you with a few other examples:

Backend Engineer

I try to think about how different users will use the products I develop, e.g. accessing content in different languages and locations. I try to involve users early on to ensure proper terminology is used during project definition. I also believe good code documentation is important for the accessibility of my own colleagues.

IT Admin

My responsibility is to provide my colleagues with the hardware, software, user accounts and other technical faculties they need to perform their work. Because I don't interact directly with our users, my main concern when it comes to accessibility is to fullfil the requirements of those with a11y needs. This could be making sure our video calls software transcripts are correctly set up, or provisioning special hardware.

User support

My daily tasks include answering user requests, building up our help center, and facilitating feedback. I strive to use inclusive and easy language, and to make the help center more intuitive and accessible. It's important to establish guidelines on how to respond to user feedback in an inclusive manner.

12 things I learned as a volunteer programming teacher

João L. — Tue, 06 Jul 2021 09:54:08 +0000

For the past semester, I've joined the ReDI School of Digital Integration as a volunteer teaching Introduction to Programming using Python. ReDI's students are mainly refugees and migrants who want to learn digital skills, so their backgrounds are very diverse. Most of them had never written a single line of code before.

This was not my first experience with teaching. I had taught high-school students to program using the visual programming tool Alice for 2 weeks. I've also taught short workshops before. However, this was my first time teaching a whole semester.

These are 12 things I learned over this semester. I wrote this article over the course of last months, and they are not written on any particular order, other than whatever occurred to me first.

1. Avoid imaginary "non sense" program examples.

my_var = my_custom_function(some_value, a, b, c)

People who never learned programming before don't yet have the same mental model as a seasoned programmer. They are already struggling with the abstractions. If you use nonsense programs that don't mean anything, it's even harder to understand fundamental concepts. They are distracting. What is my_var? Is it a function from python? And what about my_custom_function? Do I need this function to create a custom function?

2. Reduce abstraction of examples

favourite_singers = ['Justin Bieber', 'Lana Del Rey']

People respond better to examples based on real concepts like food, cities, or famous people. Everyone will understand that favourite_singers is a list of my favourite singers.

3. Avoid special syntax that was not taught yet

When teaching introductory programming to newbies, it's important to not overwhelm them with new syntax. Students get confused and frustrated if you keep telling them "just ignore this for now; I will talk about it later". Always try to build on what they learned before.

4. Careful with the special meaning of words

Programing is full of jargon. Many of the metaphors' meanings we use today have been lost to time. Take for instance the concept of "return" from a function. What does it mean to return? Return? Return what? From where? Where to? And to Whom?? Back in CS classes we learned about the runtime stack and how programs pass and retrieve data to a from other routines. But these people never heard about this before.

5. Mind people's backgrounds

If you are teaching to the general public, specially if you are teaching adults, don't assume they know physics, or that they remember their Math classes from 20 years ago. They might not remember what the value of the number Pi is, let alone what prime numbers are, or how to calculate areas or polygons.

If you want to use these concepts in your examples, introduce them clearly first.

6. Use the minimum viable code in examples

def max(a, b):
  if a > b
    return a
  print('this line still runs! :)')
  return b

As I mentioned before, students will invariably get hang up on unexpected bits of your code. For example, if you are teaching loops, avoid mixing if/else blocks, and vice versa. In the example above, do we need print('this line still runs! :)') for the function to return from the if? It might sound silly, but this was basically a confusing point in one class!

7. Your time is a scarce and valuable resource - use it wisely

In my case, I'm a volunteer teacher. I teach (or assist teaching) 2 hours per week, but am able to give a little bit more if a student needs some 1:1 help.

Spending some time explaining something to a student can be invaluable to their learning. But if you have 20 students, there's no way you can support them all.

It's hard, but giving students tools to learn by themselves is the only fair way. There will always be one or two students that will try to "monopolize" most of your time. It can become a bad habit, and they need to learn to solve problems by themselves.

8. Space for questions during class is good, but keep it strict

I tried to open the stage for questions about the last lesson, and about the homework. I believed that it would be useful to everyone and it would foster discussion.

Instead, I got sucked in to reviewing some piece of homework that would only benefit a single student. Another time, the "open stage" led to questions about topics from future classes. This was a time sink and not fair for the other 20 students in the call.

Allowing for questions is great, but you should make it clear about what the questions should be. If the current topic is last week's homework, I'm not answering questions about yesterday's class right now. But maybe we can talk shortly after class.

9. The students that ask the most questions, are probably the most advanced

The students that are totally overwhelmed will mostly likely stay quiet the whole time. The ones that make lots of questions, even if they sound totally lost, are probably the ones putting the most effort into understanding the topics and practicing.

10. It's really hard work

I never realized how much work it would be to prepare a 2-hour-long class. I've grown a lot of respect for teachers during this semester. I was only required to prepare a class every couple weeks, but it was quite laborious.

I always wanted to make more engaging classes and avoid boring bullet points. However, even a simple pop quiz can take a couple hours to prepare and test.

I also wanted to have the next class slides ready ASAP for students who like to read them beforehand. However that turned out to be quite hard to plan - I have a life and a full-time job who always got in the way.

11. Be ready to be disappointed

There will always be students who have a hard time keeping up with the course and the reasons for that can vary widely - from lack of time, to lack of interest. It's really demotivating and it made me feel like a bad teacher. Could I have done better early on to not let them fall behind?

Also, classes will never quite go the way you expect them. As I mentioned, students will get hung up on unexpected things and you need to be prepared to adapt the lesson on the spot.

12. Be ready to be amazed

Despite the struggles, people are amazingly creative. My students had to work on a group project for the last 3 weeks of the semester and I was worried if they would be able to do so. In the days before they started the project they seemed to confused and lost!

That's why I was seriously amazed by their drive, creativity and coordination, and how they were able to use the little knowledge of python we provided them and build very interesting prototypes. The final presentations were also very good and entertaining - so many great speakers in the class!

Final notes

I've always liked teaching, so this experience was very rewarding for me. This semester was completely remote and over Zoom, so not exactly ideal. On the other hand it allowed us to use fun tools like pop quizzes and polls.

If you want to give it a try, ReDI is usually looking for more teachers. I only committed to teach once every few weeks because I was one of 7 teachers. ReDI is currently present in Berlin, Munich, Copenhagen and NRW.

https://www.redi-school.org

Clicking Stuff in E2E tests - smooth scrolling, Electron flags, and Cypress

João L. — Fri, 19 Mar 2021 15:12:26 +0000

Cypress is an incredibly popular end-to-end test tool. It's very versatile and typically easy to setup and use. Writing tests in javascript is reasonably intuitive, following a syntax reminiscent of JQuery.

There are several such tools. Selenium is probably the oldest around, released in 2004. The way they work is they run a browser and simulate user input on it. This sounds fairly simple, but as anyone that worked with Cypress, Selenium, or any other e2e runner will tell you, it's evidently anything but simple.

In my (admittedly limited) experience, these programs have always been sort of big and complex, with quirky behaviour, as they are but a dev-friendly frontend to the chaos of the browser APIs. Invariably, wait statements begin to plague the spec, waiting for the DOM dust to settle before going for the next click.

My latest battle with Cypress at Ecosia included testing our simple snippet carousels:

The test Scenario

I set out to implement a rather simple test scenario:

- The mock data has 7 items (the UI shows 3);
- The last item is not visible initially;
- If I click "next", the first item should no longer be visible;
- If I then click "next" 3 more times, the last item should come into view;
- If I then click "previous", the last item should no longer be visible;
- If I then click "previous" 3 more times, the first item should come into view;

For starters, I wrote a simpler version of the test scenario, which simply clicks "next" 4 times and checks if the first item is no longer visible, and the last one is.

...
.get('.snippet-item')
.scrollIntoView()
.should('have.length', 7);

.get('.carousel-nav-button-next')
.click().click().click().click().click()

.get('.news-snippet-item').first()
.should('not.be.visible')
.get('.news-snippet-item').last()
.should('be.visible');

I ran this test, fully confident in my abilities, and the test failed. When I loaded up Cypress' GUI, I noticed that the click events were firing but nothing was happening.

Then it occurred to me that maybe our smooth scrolling was at fault? We use scrollIntoView in javascript with the option behavior: smooth in this carousel. Cypress is supposed to wait for the element to be clickable before firing another click, but I was starting to see that the behaviour of this framework was less than deterministic.

Disabling the smooth scrolling, the clicks events seemed to fire correctly. But how could I disable smooth scrolling just for Cypress?

Disabling smooth scrolling just for Cypress

It turned out it's quite easy to detect Cypress. There is a runtime global window.Cypress that one can check:

const scrollOptions: {
    behavior: (typeof window === 'undefined' || window.Cypress) ? 'auto' : 'smooth',
}

This would work, but it's really not ideal. We should not have our application code contain code related to our e2e test Framework. My next idea was to use some sort of browser flag that would disable smooth scrolling.

There's no such thing as a browser flag to disable smooth scrolling

There is an accessibility feature present in any modern browser called "reduced motion preference". This preference will affect several animations in the browser chrome. You can (and should!) also use it to reduce the amount of animations in your applications, or tone them down. It doesn't, however, disable smooth scrolling on its own.

You can detect that this feature is enabled via CSS or Javascript using media queries.

const prefersReducedMotion = typeof window === 'undefined' ? true :
    window.matchMedia('(prefers-reduced-motion: reduce)').matches;

const scrollOptions =  {
    behavior: prefersReducedMotion ? 'auto' : 'smooth',
};

Furthermore, Firefox and Chrome can both be launched in "prefers reduced motion" mode by passing a flag. Cypress allows you to pass these flags using their browser launch API.

on('before:browser:launch', (browser = {}, launchOptions) => {
  const REDUCE = 1;
  if (browser.family === 'firefox') {
    launchOptions.preferences['ui.prefersReducedMotion'] = REDUCE;
  }
  if (browser.family === 'chromium') {
    launchOptions.args.push('--force-prefers-reduced-motion');
  }
  return launchOptions;
});

I tested this in Cypress' GUI and confirmed that smooth scrolling was effectively disabled. My trust in my abilities was restored. I could see the light at the end of the tunnel!

Electron doesn't support that

It turns out Cypress doesn't use Chrome nor Firefox by default. The included browser, and the one we use in our CI, is Electron. "But Electron is just Chrome", I hear you say. That is only partially true. Electron is a wrapper, and not all features and APIs are exposed the same way as in Chrome.

According to Cypress' browser launch API docs, the "prefers reduced flag" is not part of the list of flags and preferences I can pass to Electron.

From reading some helpful github discussions, I finally found that some extra flags can be passed to Electron using "app switches". Those switches are described further down in the docs. So I tried with the flag I wanted, by passing an environment variable to cypress in my package.json script:

{
  "scripts": {
    "test:e2e": "ELECTRON_EXTRA_LAUNCH_ARGS=\"--force-prefers-reduced-motion\" cypress run --project ./e2e-tests"
  }
}

And this worked! Not as elegant as I would have hoped, but it did the trick. If there's a way to enable this switch in code, instead of using env vars, please let me know.

Running the test without smooth scrolling

Implementing my test should be smooth sailing henceforth. Without smooth scrolling, the clicks were registered correctly in Cypress' GUI.

I ran this test in the headless browser and it worked. Hurrah. Oh wait, there was an extra click() there by mistake. Silly me. I dropped the extra click(), feeling still sure of my mental capabilities. But, as you are surely aware due to the fact that you're still only 70% through this article, the story didn't end here. The test failed.

A friendly frontend to chaotic browser APIs

All devs, at some point, have moments where they doubt everything they know. So I spun the app up locally and clicked repetitively on the "next" button while counting the number of clicks on my fingers. Then I counted the fingers and there were 4 fingers. So I confirmed I had not lost my mind yet.

I tried adding a .wait(500) before the click, but that didn't help. So I headed to the Internet.

I found a stack overflow thread where people made some odd suggestions. One was to add .trigger('mouseover') before each click (?!). Another was to to replace the failing .click() with .click().click() (been there, done that). But the top answer suggested using .click({ force: true }).

Using force worked. Until I returned the next day and it didn't work anymore. I can't tell you why it was working, nor why it stopped, but it did, then it didn't. I'm glad it didn't because the solution was hacky and simply didn't sit right with me. Specially since it was ill-defined behaviour that would surely come bite me in the back in the future.

I was seriously tempted to just use .click().click() and leave it at that. Would I be able to live with it? Sure. Would I be able to sleep at night? Probably. But it's just wrong and I still had some sense left in me.

At this point I asked my 2 colleagues if they could spare ""a m i n u t e"" because Cypress was acting up.

Cypress will be Cypress?

It's easy to blame Cypress for being a horrible tool brought upon us by Beelzebub himself. But as I mentioned before, Cypress provides a friendly interface to the very chaotic browser environment. Brushing aside any dreams of moving the team to The Next Great Thing™️, we started figuring out what was wrong and how we could tackle the issue.

We considered that the click event might not be installed by the time the first click happens. However, wait() would have solved this, and it doesn't explain why a second click works. But it does seem like the .click() that always missed was sort of "waking up" the component.

Further tests showed that this also happened when clicking on the previous button, even after clicking the next button. I wish I had an explanation for this behaviour, but that's unfortunately not the case. I do, however, have a working solution for the problem.

Working solution for the problem

We developed a solution that tries to ensure that the element is ready to be clicked, and call the next click once ready again. It sounds overkill, it looks overkill, but this was the only way we found that was bullet proof. It's also quite elegant:

const clickOnControl = (selector, times, callback) => {
  if (times > 0) {
    cy.get(selector).then(($next) => {
      cy.wrap($next).click().then(() => {
        clickOnControl(selector, times - 1);
      });
    });
  } else if (callback) {
    callback();
  }
};

The final e2e test looks simple and elegant as it should:

const getItems = () => cy.get(byTestId(`snippet-card`));
getItems();
getItems().should('have.length', 7);
getItems().first().should('be.visible');
getItems().last().should('not.be.visible');
cy.get(byTestId('result-snippet-control-previous')).should('not.be.visible');
cy.get(byTestId('result-snippet-control-next')).should('be.visible');

clickOnControl(byTestId('result-snippet-control-next'), 1,
  () => {
    getItems().first().should('not.be.visible');
    getItems().last().should('not.be.visible');
    cy.get(byTestId('result-snippet-control-previous')).should('be.visible');
    cy.get(byTestId('result-snippet-control-next')).should('be.visible');
  },
);

clickOnControl(byTestId('result-snippet-control-next'), 3,
  () => {
    getItems().first().should('not.be.visible');
    getItems().last().should('be.visible');
    cy.get(byTestId('result-snippet-control-previous')).should('be.visible');
    cy.get(byTestId('result-snippet-control-next')).should('not.be.visible');
  },
);

clickOnControl(byTestId('result-snippet-control-previous'), 1,
  () => {
    getItems().first().should('not.be.visible');
    getItems().last().should('not.be.visible');
    cy.get(byTestId('result-snippet-control-previous')).should('be.visible');
    cy.get(byTestId('result-snippet-control-next')).should('be.visible');
  },
);

clickOnControl(byTestId('result-snippet-control-previous'), 3,
  () => {
    getItems().first().should('be.visible');
    getItems().last().should('not.be.visible');
    cy.get(byTestId('result-snippet-control-previous')).should('not.be.visible');
    cy.get(byTestId('result-snippet-control-next')).should('be.visible');
  },
);

Final Notes

I remember when I first learned about Cypress in a frontend meetup some years ago. It really was sold to me as an amazing tool that was super easy to use. I have great respect for the creators and maintainers of Cypress, and it seems like they are very active and helpful on github too. But the amount of headaches we get, and the brittleness of our e2e tests,makes us start seriously considering The Next Great Thing™️.

Writing Vue Storybook stories in markdown

João L. — Mon, 15 Feb 2021 08:51:44 +0000

Important note: this article was written for Storybook 6. Things have changed a little in Storybook 7. If you're interested in an update, let me know!

At Ecosia we started last year investing some resources into defining our Design System (DS). Building a DS allows us to focus on streamlining the design and implementation of our UIs, and to be more aware of the impact of our product design decisions. It helps our team move in unison when developing new products or refactoring old ones.

Moving from Vue Styleguidist?

Most of the frontend stack at Ecosia is built around with Vue. We also had a design style-guide built using Vue Styleguidist. Our style-guide is essentially a list of all the Vue components used across our frontend applications.

Vue Styleguidist is pretty straight forward and flexible. In our current setup, we can write component stories in Markdown with code examples right inside the Vue single-file component. Component props are picked up automatically. That means that even without docs each component gets a docs page.

While this worked great for developers, we found it a bit too bare bones. For the past year there were a series of features we desired that would mean too much custom work to implement them. We also found some limitations in the markdown docs, for instance regarding the use of the store.

Enter Storybook

Storybook. has been around for a long time. It started as "React Storybook" but has grown immensely, and now supports several frameworks. (Fun fact: like Storybook, Vue Styleguidist is also built using React). Storybook users can take advantage of a very active community and rich library of addons.

Out of the box:

Easy theming using a theme API without the need for CSS;
2 base themes: light and dark;
Allows complex and custom organization of the pages, including nested stories and sections;
Easy creation of plain text docs besides code documentation;
Test/visualize each component individually, or all together in a pretty docs page;
Zoom feature for individual stories

With storybook-maintained addons:

Ally features (e.g. including audits (https://github.com/storybookjs/storybook/tree/master/addons/a11y), and color blindness simulation)
Responsive design simulation (we can set our list of device dimensions)
Event and behaviour manipulation
Event tracking

With community addons:

Dark mode switcher
Easier themes
Easier documentation
Generation of docs from code
...???

Writing stories - Why not CSF/MDX?

CSF is the recommended way to write component stories in Storybook. However, it's hard to create examples for components with state, e.g. radio buttons. MDX, which is the format recommended for the docs addon, has the same issue. And both of them require that I write my stories as a string (due to Vue not being a 2st class citizen in Storybook) which is less than ideal to say the least. Here's an example of a story from the MDX documentation of addon-docs:

<Story name='basic' height='400px'>{{
  components: { InfoButton },
  template: '<info-button label="I\'m a button!"/>',
}}</Story>

@josephuspaye came up with the brilliant idea of creating a simple Webpack loader to load Vue files into a CSF story. This approach has a series of advantages:

Each individual story is pure Vue.js instead of a string
State of the story is handled just like in any vue component
Syntax for styles or scripts is the same as other components and completely isolated from storybook

I identified the following shortcomings in the solution:

The source of the vue file is not picked up by addon-docs or addon-source;
Stories are written in CSF which is much less elegant than MDX, which is markdown containing JSX.
CSF doesn't let you write text between each example, so the documentation with CSF would be all code examples with no change to textual docs

Markdown All the way

I wanted the documentation of my stories to be as lean as possible. The end result looks like this:

<Meta title="Components/Button"
  component={ButtonComponent}
/>

# Buttons

This is the *button component*.
It can be grouped in a button group or
used individually.

<Preview>
  <Story name='HorizontalGroup' inline
    parameters={params(HorizontalGroup)}>
    {story(HorizontalGroup)}
  </Story>
</Preview>

The story function is based on @josephuspaye's implementation with some changes.

Storybook provides the addon-source which display the source code of each individual story. As convenient as it is, it won't work with our setup because addon-source works automagically by loading the source of each story file. Because the source of our stories is found in the vue files, we must load them instead and display them in a custom source panel.

First we need to indicate which files we want to load with this new "source loader". The way I did it was to add a tab <include-source /> at the end of the each story to which I want the source code to be present:

// This is a single story for a Button Group
<template>
  <div>
    <Button variant="solid-primary">
      Primary
    </Button>
    <Button variant="outline-primary">
      Secondary
    </Button>
  </div>
</template>

<script>
import Button from './button';

export default {
  name: 'ButtonExample',
  components: { Button },
};
</script>

<include-source/>

Then we create the actual loader:

const fs = require('fs');

module.exports = function (source, sourceMap) {
  // Read the referenced file and remove the <include-source/> block, so it doesn't
  // show up in the source code that will be shown in the UI
  const fileContent = fs
    .readFileSync(this.resourcePath, 'utf8')
    .replace(/<include-source.*\n/, '');

  // Generate a function that'll receive the Vue component and attach the source
  this.callback(
    null,
    `export default function (Component) {
            Component.options.source = ${JSON.stringify(fileContent)};
        }`,
    sourceMap
  );
};

Then, we tell webpack to use this loader when loading the include-source block type. You could use another test here, such as filtering the story.vue extension, but I found the include-source approach gives me more control and is not really cumbersome to use.

// main.js

config.module.rules.push({
  resourceQuery: /blockType=include-source/,
  loader: path.resolve(__dirname, 'source-loader.js'),
});

Now, we need to tell storybook to use the value added to Component.options.source by the loader. There are two places where we want to be able to read the source code of the story: the addon-docs code panel, and the individual source panel.

Recalling the MDX code above, you can see I have two functions story and params:

<Preview>
  <Story name='HorizontalGroup' inline
    parameters={params(HorizontalGroup)}>
    {story(HorizontalGroup)}
  </Story>
</Preview>

The story function simply wraps the story component in a function. If we were using the CSF format, this would be the place to set any additional parameters - namely the source code of the story.

/**
 * This is a convenience function that wraps the story in a function.
 * It can be used to set aditional parameters in CSF stories.
 * For MDX stories, params much be set in the params() function.
 */
export const story = (StoryComponent) => {
  const storyExport = () => StoryComponent;

  return storyExport();
};

The params function creates a parameters object to be applied to the story component in MDX and it's where the content of the source tab can be set. This is necessary, otherwise addon-docs just displays story(HorizontalGroup) as the source code of the story. You could also set this directly in the MDX, but I found this approach allowed for a cleaner MDX syntax.

export const params = (StoryComponent) => {
  const storyParams = {
    docs: {
      inlineStories: true,
      source: {
        code: StoryComponent.source,
      },
    },
  };

  return storyParams;
};

Ideally, I would love to be able to simplify the markdown even more like the following, and hide all the boilerplate:

<Preview>
  <MyStoryComponent name='HorizontalGroup' story={HorizontalGroup} />
</Preview>

Unfortunately, the way that addon-docs works, this code is nore really actual JSX, but is instead partially parsed by the MDX loader, which internally expects a certain code structure. Any attempts at removing the boilerplate resulted in storybook crashing or rendering empty stories.

This is also the reason why the official source code panel addon addon-source doesn't work with our approach. The internals of that addon expect us to follow a righteous path, but we have rebelled against the oppressing docs. For that reason, we need to create our own source panel. The following addon is adapted from the one used in @josephuspaye's solution.

// source-addon.js
import React from 'react';
import { addons, types } from '@storybook/addons';
import { useParameter } from '@storybook/api';
import { AddonPanel, SyntaxHighlighter } from '@storybook/components';


const ADDON_ID = 'vueStorySource';
const PARAM_KEY = 'docs';
const PANEL_ID = `${ADDON_ID}/panel`;

// The SourcePanel component (React)
const SourcePanel = ({ active }) => {
  // Use the params from addon-docs
  const docsParams = useParameter(PARAM_KEY, null);
  const source = docsParams && docsParams.source && docsParams.source.code;

  return active && source ?
    React.createElement(
      SyntaxHighlighter,
      {
        language: 'html',
        showLineNumbers: false,
        copyable: true,
        padded: true,
        format: false,
      },
      source
    ) :
    null;
};

// Register the addon
addons.register(ADDON_ID, () => {
  const render = ({ active, key }) => React.createElement(
    AddonPanel,
    { active, key },
    React.createElement(SourcePanel, { active })
  );

  addons.add(PANEL_ID, {
    type: types.PANEL,
    title: 'Source',
    render,
    paramKey: PARAM_KEY,
  });
});

// manager.js

// Register our custom addon
import './util/source-addon';

Final notes

It's unfortunate that Vue is still a second class citizen in Storybook, but it's still worth exploring all the possibilities provided by this platform. Storybook community and maintainers are very active on github which really helps keeping solutions flowing.

If you want to explore the code I created for this article, head off to my github repository.

DEV Community: João L.

If your "Unsubscribe" link requires users to login, you're training them to fall for phishing attacks

The bad, the ugly!

Call to action

Meow Mountain - postmortem of a 13KB game

Contents

About the game

Game concepts

Ideas that didn't make it

🧙‍♀️ Shapeshifting witch 🐈‍⬛

👨‍🌾 Villagers AI 🏘

📋 Goals and Achievements ✅

🪄 Magic abilities 🔥

Main concept

Story Engine

Reusable components

Sprites

Font

Emoji icons

Sound effects

Music

Other game features

NPC AI

The villager

The spirit

Map generation

Final notes

🎵 JavaScript music! 🎸 JS13K Games Community Soundtrack 2024 🎹

Gotchas while developing a tiny web game

1. Players don't have the same fonts as you

2. There are screens with very high refresh rates.

3. Beware of accessibility features

4. Voice synth

4.1 Incorrect voice language

5. Browser compatibility is still important

6. People are even more diverse than computers!

Introducing the first JS13K Games Community Soundtrack

Join the project

A tiny pixel art game using no images

Concept art

Pixel art in the canvas

Rectangles and borders

Placing pixels on the canvas

Drawing pixelated lines

Drawing pixel art icons

Drawing text

Final notes

Update

Creating a tiny zen game using Kontra

The game concept

The Algorithm

Animation

Kontra

Next steps

Sense of direction

Feed the ants

Smarter explorers

It's ♿️ Global Accessibility Awareness Day!🌈 Have you done your part?

Who's responsible for accessibility in software development?

Table Of Contents

Product manager

Product Designer

Content Designer

Frontend Engineer

QA Engineer

Mobile Engineer

Accessibility Champion

Final Notes

Backend Engineer

IT Admin

User support

12 things I learned as a volunteer programming teacher

1. Avoid imaginary "non sense" program examples.

2. Reduce abstraction of examples

3. Avoid special syntax that was not taught yet

4. Careful with the special meaning of words

5. Mind people's backgrounds

6. Use the minimum viable code in examples

7. Your time is a scarce and valuable resource - use it wisely

8. Space for questions during class is good, but keep it strict