Previously I wrote about Getting Started with Minecraft Modding; this is a continuation of that topic.

In learning to mod Minecraft, an early idea I had was to have a set of special worker villagers that gather resources for me and bring them to a central warehouse. Rather than just have them deposit into random chests, I wanted to add a sense of collaboration between the villagers. Still, I needed some central point that the workers would use for exchanging resources. The kiosk block is my way to do it. Workers deposit items that they want to store in the kiosk. They also communicate a list of resources they need such as pickaxes. A kiosk worker is in charge of the warehouse and fetches the required items as needed while storing the things dropped off at the kiosk.

The kiosk is basically a custom chest: it behaves exactly like a chest but has a custom texture and an ID within the game so the workers treat it as the kiosk and not just any other chest (while it's just a chest, it's semantically different).

Background

Blocks in Minecraft are all descendants of the BlockBehavior class. The KioskBlock extends the BaseEntityBlock which adds the ability for the block to store state per instance via BlockEntity. The basic block classes set up shared properties for all blocks of the given type.

Block entities are state stored on blocks per position / instance. In the case of the kiosk (and chests), the items stored in the kiosk must be managed by a descendant of BlockEntity. The BaseContainerBlockEntity is what chests are descended from so KioskBlockEntity extends that in order to get the chest-like menus and behaviour.

The Mod Base Class

The base class of the mod should be set up by the template or mod generator. I think I renamed mine from ExampleMod. It needs to have an id() method that is used to create the custom block for the mod.

You should see it implements ModInitializer, sets a MOD_ID string and declares the id() function.

The fabric.mod.json declares the entrypoints object that may need renaming to match your main mod class.

The Kiosk Block

The Fabric Documentation explains how to create a custom block. The first article is Creating Your First Block.

The basic steps are:

• Create a class to keep the mod item ids
• Create a class that registers the mod block
• Call the block initializers from the main mod class onInitialize() method.
• Set BlockBehaviour.Properties with strength, sound type, etc.
• Add the block to the creative tab
• Add a translation
• Customise the model and texture
• Add a state definition
• Add block drops
• Set harvesting tool
• Set mining levels

The tutorial doesn't go into much depth on the properties since it's a big topic. Here's what I set:

BlockBehaviour.Properties.of()
    .strength(5.0f, 6.0f)
    .noOcclusion()
    .setId(ModBlockItemIds.KIOSK.block())

The strength makes it so I don't accidentally one-shot break the kiosk. The noOcclusion thing is to prevent certain sides of the kiosk from becoming transparent since I made it a weird shape. The mod crashed without the setId() call.

For the model and texture I used Blockbench. There are tutorials on YouTube etc that will teach you to use it. When done, click "File -> Export -> Export Block/Item Model" to get the model.json file. Also, for the texture, right click on the texture file and do a "Save As" to get a PNG file.

I didn't add a harvesting tool or set mining levels.

The Fabric documentation has pages going into more details about the Block Models and Block States. For the Kiosk block, I didn't need anything special so it's all default. I did put a few things into the Block Entity though.

Block Entity

The Fabric Tutorial for Block Entities explains how to extend BlockEntity. For the kiosk, I extended BaseContainerBlockEntity because the kiosk is basically a chest. I didn't use RandomizableContainerBlockEntity which is what chests actually extend because I don't need the random loot - kiosks don't randomly spawn with items in them.

The documentation includes an example of making the block entity count clicks. The kiosk block has different functionality.

First I set the chest size to 27 and implemented the mandatory overrides:

public class KioskBlockEntity extends BaseContainerBlockEntity {
    private static final int SIZE = 27;
    private NonNullList<ItemStack> items = NonNullList.withSize(SIZE, ItemStack.EMPTY);

    @Override
    public int getContainerSize() {
        return SIZE;
    }

    @Override
    protected NonNullList<ItemStack> getItems() {
        return this.items;
    }

    @Override
    protected void setItems(NonNullList<ItemStack> items) {
        this.items = items;
    }

    @Override
    protected AbstractContainerMenu createMenu(int containerId, Inventory inventory) {
        // threeRows is hardcoded to SIZE slots; changing SIZE requires a different ChestMenu factory or a custom menu.
        return ChestMenu.threeRows(containerId, inventory, this);
    }
}

There's also a name translation for the chest menu:

    private static final Component DEFAULT_NAME = Component.translatable("container.supplychain.kiosk");

    @Override
    protected Component getDefaultName() {
        return DEFAULT_NAME;
    }

And in src/main/resources/assets/supplychain/lang/en_us.json, I added the translation entry under the existing block name translation (that is added when creating the block):

{
    "block.supplychain.kiosk": "Kiosk",
    "container.supplychain.kiosk": "Kiosk"
}

The kiosk also manages the "warehouse" stock. When a special kiosk worker adds and removes items from the kiosk, it updates the stock ledger as well. The stock levels are used by other workers to trigger when to get more resources or craft more items.

It's pretty standard java:

    private final Map<Item, Integer> stock = new HashMap<>();

    public int getStockCount(Item item) {
        return this.stock.getOrDefault(item, 0);
    }

    public void incrementStock(Item item, int amount) {
        if (amount <= 0) return;
        this.stock.merge(item, amount, Integer::sum);
        setChanged();
    }

    public void decrementStock(Item item, int amount) {
        if (amount <= 0) return;
        int current = this.stock.getOrDefault(item, 0);
        int next = Math.max(0, current - amount);
        if (next == 0) {
            this.stock.remove(item);
        } else {
            this.stock.put(item, next);
        }
        setChanged();
    }

    public void resetStock() {
        this.stock.clear();
        setChanged();
    }

    public Map<Item, Integer> getStockSnapshot() {
        return Collections.unmodifiableMap(this.stock);
    }

While the focus of the tutorial is the BlockEntity class, there is some interaction with the BaseEntityBlock subclass when it comes to block interaction. I implemented something similar to the tutorial, partly for logging the stock but it was required for doing the chest interaction:

    // In class KioskBlock (not KioskBlockEntity):
    @Override
    protected InteractionResult useWithoutItem(BlockState state, Level level, BlockPos pos, Player player, BlockHitResult hitResult) {
        if (!level.isClientSide() && level.getBlockEntity(pos) instanceof KioskBlockEntity kioskBlockEntity) {
            SupplyChain.LOGGER.info("[Kiosk@{}] stock: {}", pos, kioskBlockEntity.getStockSnapshot());
            player.openMenu(kioskBlockEntity);
        }
        return InteractionResult.SUCCESS;
    }

There are a couple of tutorials about customising chest-like blocks on the Fabric website: Block Containers and Container Menus.

There are a few other convenience things in the class that I won't mention yet.

In the "Saving and Loading Data" side of things, I save the stock:

    private static final Codec<Map<Item, Integer>> STOCK_CODEC =
        Codec.unboundedMap(BuiltInRegistries.ITEM.byNameCodec(), Codec.INT);

    @Override
    protected void loadAdditional(ValueInput input) {
        super.loadAdditional(input);
        this.items = NonNullList.withSize(this.getContainerSize(), ItemStack.EMPTY);
        ContainerHelper.loadAllItems(input, this.items);
        this.stock.clear();
        input.read("Stock", STOCK_CODEC).ifPresent(map -> this.stock.putAll(map));
    }

    @Override
    protected void saveAdditional(ValueOutput output) {
        super.saveAdditional(output);
        ContainerHelper.saveAllItems(output, this.items);
        output.store("Stock", STOCK_CODEC, this.stock);
    }

The Codec is generally the way the game serialises and deserialises data. There are standard simple codecs like Codec.INT which will handle an integer number. The BuiltInRegistries.ITEM.byNameCodec() function returns the codec that will convert an "Item" to a string that is unique e.g. "minecraft:oak_log" and vice versa. It is a function instead of a static lookup because some items are registered dynamically e.g. the kiosk block itself. The unboundedMap combines the other two codecs to read and write a map that has the item as a key and integer as the value.

For data synching, the chest base class does the work so I didn't need to implement anything. For the stock, I did add calls to setChanged() but since the kiosk doesn't send the stock to the client, there was no need for getUpdatePacket().

Likewise, I didn't add any tickers.

So that wraps it for the Kiosk block. This allowed my workers (not yet explained in this series) to exchange items and store things in a warehouse.

From time to time, I get inspired to go back to Minecraft and maybe start a "forever world" with lore and an expansive network of bases linked by roads or Nether portals or railways etc... However, I find the game to be a bit lonely - the NPCs are pretty limited. But I'm also not a social gamer, I just think it's fun when the gameplay has some interesting characters around to add some life. It would be cool to have some custom villagers living at my bases that do a bit more and maybe have a bit of personality.

I'm not much of Java programmer so I'd never seriously considered any Minecraft modding. However, we live in an age where learning a language and code base is greatly accelerated if you have access to an LLM so it became possible for me to upskill in this area.

Choosing a Framework

The two major players in modding seem to be Forge and Fabric. Forge is older and more complete. Fabric is light-weight and updates faster when new versions come out.

I chose the Fabric framework because I generally distrust frameworks that try to do too much for you. While they are more convenient to get started with, I find that once you are mature and experienced, they become a limitation and you find yourself having to mod the framework itself to get outside of the box it puts you in.

Having said that, I didn't actually try Forge so I'd be open to giving it a go some time to see what it's really like.

The downside of Fabric is that it's bare-bones - you have to figure out things and build infrastructure for yourself ... which actually suites me perfectly.

Installing Fabric

I run Linux for developing but I game on Windows. This is a bit inconvenient but I worked around it ok. The actual Fabric mod loader was pretty easy to install, just follow the instructions. Also I installed the Fabric API which is the base mod that provides all the hooks that your mod will use.

The dev environment was a little trickier. The first step was getting the right Java version. For Minecraft 26.1, I used Java version 25 (I can't remember how I landed on that version). I run Debian so the apt command was sudo apt install openjdk-25-jdk.

After this, I cloned the Fabric Example Mod , deleted the .git dir and reinitialised it as a new repo using git init. I probably should have used the template generator as per these Creating a Project instructions but I didn't see that until later on.

I didn't bother too much with the IDE stuff. I use VSCode but just stick to the file tree and text editing. I prefer to build and run other tools on the command line. Give the IDE stuff a look though - it will probably make it easier. Instructions are on that Creating a Project page that you should have just read. As I previously mentioned, I've made life hard for myself by developing on a headless Linux server and running desktop on Windows. It's probably just better to commit to one or the other instead of trying to play in both worlds.

The dev environment uses Gradle as the build system. It conveniently installs some dependencies as well. The Develop instructions have an example gradle.properties file which gets you started.

Before I could get too far, I wanted to have the Minecraft sources to look at as well as the Fabric API sources. The Fabric API is just a git clone: fabric-api. There is a Gradle command that actually decompiles Minecraft and produces the sources: ./gradlew genSources. This outputs two jar files deep in a subdirectory of the project. The idea is that the IDE should pick these up and know how to search them when you want to find sources. But because I'm difficult, I didn't want to set up my IDE for that. Instead: fd 26.2-sources.jar .gradle is the magic command to locate them. I then created a minecraft-sources dir and unpacked the jar files using the unzip command. Don't put that in your git repo btw, I don't think Microsoft would be cool with you distributing their code.

Build, Run, Debug and Learn Using an Agent

I was then able to build my first mod using ./gradlew build. I can't remember exactly what I did first, I think I worked through some of Creating Your First Item. The build command creates a .jar file in ./build/libs. I scripted a scp command to copy that onto my Windows PC at "$env:APPDATA\.minecraft\mods\" and fired up Minecraft to try it out. Note that it's handy to have VSCode open to "$env:APPDATA\.minecraft\logs\latest.log" so you can watch it crash.

At the start of this article, I mentioned using LLMs, this is the point at which I started leaning on one pretty heavily to figure out what to do. To start with, it's handy to drop crash dumps into the agent to diagnose what they mean and figure out what to fix. I also found the agent very good for explaining the Minecraft code base and the Fabric API so I could figure out what to do. Personally I wanted to learn this as much as I could so I would query the agent to locate files that dealt with interesting areas and give me code walkthroughs. I then wrote my best attempt at the mod and used the agent to fix my mistakes. I find this an effective way to learn.

In the next few posts, I'll talk about what my mod does and how it works: My Minecraft Mod: Kiosk Block.

It's hard to be a software developer at the moment without engaging with LLMs. Many workplaces are introducing the technology to their workflows in various ways as senior leadership is sold on promises of 10x productivity and developers are threatened with obsoletion if they don't embrace token maxing.

Meanwhile the big AI companies are rolling out data centres into any spare patch of earth close enough to a power station and water source. Energy consumption of data centres is significant and growing having an impact on nearby communities as well as contributing to overall energy demand at a time where it's crucial to be tackling climate change. Water consumption is also an issue and simply recycling water isn't on the cards. The problem of AI scraper bots is a significant burden on Internet infrastructure.

Then there are the ethical issues. Training of LLMs requires "large" volumes of "language" to form the "model". It's not just written language though - all forms of media are up for grabs: spoken language, music and visual art are all made into models. LLM companies have violated copyrights of countless creators to train their models. While the legal arguments can go around and around, no one can deny that the overwhelming majority of authors never anticipated that their work could become part of an LLM and so never could have had feelings or made decisions about that possibility. The LLM companies have not given creators a chance to make that decision, they have denied them agency.

On the generation side of things, LLMs are being used to replace creators. There is a strong economic incentive to use an LLM for creative work instead of employing a creator. LLM outputs have become known as "AI slop": derivative, surface quality works that fulfil the commercial goal of drawing someone's attention. While commercial creation is not the ambition of the majority of creators, it has been the thing that pays the bills and allowed people to develop skills for making true art that enriches our culture.

So basically LLMs suck. Right? So why am I using them, not just at work, but in my home projects too? Part of the problem for me personally is that I'm implicated through my profession. I use LLMs at work, all day, every day, and if I don't like it, my options are to change careers. Maybe I could find a company to work at that hasn't adopted AI yet, but that would be temporary. AI is here and it's not going away. A year ago I was resisting. A year ago I believed the bubble would burst and it would all come crashing down. We would then return to the better version of the world that existed before LLMs. I feel like I've read a "AI is over" / "the bubble has burst" article every day for the last year and yet every day I show up at work and Claude Code is still there, happy to do my bidding and my industry continues to be more and more reliant on it.

I like writing code. I like doing things with computers. I always have. In a way, I've always wanted LLMs. As a kid I dreamed of building my own R2D2 and C3PO - It's why I wanted to be a software developer and engineer. I got a thrill when K9 saved day on Doctor Who. I groaned with the crew of the Enterprise as Data attempted to learn how to tell a joke. Now I have something like that technology. It's awesome! It's truly like a miracle. I just wish that it hadn't come at such a cost.

I'm in the position where I can benefit greatly from AI for personal skill development. I could choose to boycott it and forego the benefits it offers but that sacrifice will not change anything except to make me angry at other people who don't make that same trade. My chosen path is to use AI as responsibly as I can and accept that modern life involves hypocrisy and guilt. Like the cartoon: We should improve society somewhat.

So while I maintain a political stance against what is going on with AI big tech right now, I have chosen to use AI for my own benefit where it makes sense and doesn't violate too many of my ideals. A guiding principal for me is that if I really care about the quality of something, then I will not generate it with an LLM - especially writing. (The converse is that when I'm consuming, if I can detect LLM generated content, then I form the opinion that the publisher is insulting me.) But I make full use of LLMs for tasks where it has proven to be truly useful.

For software development, LLMs are truly exceptional. Having access to an LLM agent is like having the highest ranked contributors to Stack Overflow sitting next to you. I use an LLM agent to guide me through unfamiliar code bases, generate boilerplate code and proof-of-concept solutions, generate tests, self-review code and debug stack dumps. It does all of these things within minutes if not seconds where it would usually take me hours.

Where I avoid using AI is for generating whole solutions at once. I find that if it does too much unsupervised, while it might eventually converge on working code, that code will be unreadable bloated garbage full of layers of contradictions. The token maxers will tell you the solution to that problem is bigger contexts and more agents (ie. spend more money) but I have found a cheaper solution that works great and is far more enjoyable for me: I call it using my own brain. I don't think I'll ever reach the point where I find joy in watching a machine do the part of my job that I most enjoy which is designing the solutions. I feel for people (including in my own profession) where that has already been taken away from them.

For home use, I have a subscription to MiniMax which is a cheap price-capped Chinese model with ok benchmarks (similar to GPT-5.6 Luna or Deepseek V4 Pro). It's smart enough for my needs at the right price. I would much prefer to run a local model but that is beyond my means at the moment.

I hope this has been helpful to others trying to find their way through this time and I hope that we can give each other grace for the positions we arrive at when it comes to AI.

In the previous post I explained how to add the mask layer to the pokemon card. Now we will look at the glare layer.

The glare layer is pretty subtle but adds a kind-of spotlight effect making the card seem to reflect light as it moves. This is accomplished using a div that sits in front of all the layers and blends in a radial-gradiant background that moves with the mouse.

Here's the HTML. The new element has class card__glare:

<div class="card" id="holocard">
    <div class="card__rotator">
        <div class="card__front">
            <img src="/images/matt-pokemon.png" width="330" height="460" />
            <div class="card__shine"></div>
            <div class="card__glare"></div>
        </div>
    </div>
</div>

In the CSS, the div is styled with background-image: radial-gradiant:

.card_glare {
    background-image: radial-gradient(
        circle at var(--pointer-x) var(--pointer-y),
        rgb(255, 255, 255) 0%,
        rgba(134, 138, 141, 0.33) 45%,
        rgba(51, 51, 51, 0.9) 130%
    );
    opacity: 0.5;

    mix-blend-mode: hard-light;
    filter: brightness(.9) contrast(1.75);
}

Note the use of --pointer-x/y variables which are set by javascript to percentage values from the top left corner. The opacity is static in this case. Other cards vary the opacity so that the glare layer becomes invisible towards the center of the card and is stronger when the mouse moves to the edges. That gives a metallic effect where as the effect for this card is more of plastic.

Here's what it looks like on its own (you might need to hover the mouse to make it show up)

And here it is on the card. This is very close to the finished card. There are some more subtle details in the actual pokemon-cards-css files but we've covered the basics here and hopefully you learned as much as I did!

In the previous post I explained how to add holographic shine to the pokemon card. Now we will look at the mask layer.

This was a fun area to learn about. For background, read Introduction to CSS masking at MDN.

The TL;DR is, make an image where the bright white parts are what you want to let through and the transparent parts are what you want to block. For the holographic image, that means the parts you want to see look holographic should be white and the parts where you don't want holographic stuff should be transparent.

Here is the mask image I made in GIMP (transparent areas will show as grey):

It is applied to the shine layers using CSS:

.card__shine,
.card__shine::after {
  -webkit-mask-image: url(/images/matt-pokemon-mask.png);
  mask-image: url(/images/matt-pokemon-mask.png);
  -webkit-mask-size: cover;
  mask-size: cover;
  -webkit-mask-position: center center;
  mask-position: center center;
}

Now is a good time to blend this over the top of the actual card image. This is not world class art work sorry. I used a Snapchat filter to make myself look animated and then used Inkscape to add a border and some text.

Uncomment the previously commented image url:

<div class="card_demo4" id="holocard_demo4">
    <div class="card__rotator_demo4">
        <div class="card__front_demo4">
            <img src="/images/matt-pokemon.png" width="330" height="460" />
            <div class="card__shine_demo4"></div>
        </div>
    </div>
</div>

There's also a bit of css work still to do because the shine layer is positioned below the image instead of behind it. We need to do a bit of z-index and position work in the CSS. The display: grid and grid-area: 1/1 make the divs stack. The transform and z-index ensure the shine layer is in front. The mix-blend-mode: color-dodge property makes the shine layer blend with the image nicely.

.card__rotator_demo5 * {
  width: 100%;
  display: grid;
  grid-area: 1/1;
}

.card__shine_demo5,
.card__shine_demo5::after {
  transform: translateZ(1px);
  z-index: 3;
  mix-blend-mode: color-dodge;
  ...other stuff...
}

We're almost done but there's one more layer to go to add a subtle reflection to make the surface appear glossy. Glare Layer - Pokemon cards CSS

In the previous post I explained how to create a basic 3D card in JS/CSS. This post is about the "shine" layers used to create the holographic effect.

There is one main element in the HTML with class .card__shine and then a pseudo-element is created: ::after. Some cards also have a ::before layer too.

The HTML is similar to the previous post but now there's the <div class="card__shine"> element:

<div class="card" id="holocard">
    <div class="card__rotator">
        <div class="card__front">
            <!-- <img src="" width="330" height="460" />  -->
            <div class="card__shine"></div>
        </div>
    </div>
</div>

Let's look at each CSS layer one at a time. The cards all differ in technique so each one needs to be looked at individually but the one I used for this website has two identical layers that slide in opposite directions as the mouse moves.

The basic background image is some texture grain.webp:

Then a rainbow layer is blended onto it:

.card__shine {
  background-image:
    url("/pokemon-cards-css/img/grain.webp"),
    repeating-linear-gradient(
        0deg,
        rgb(255, 122, 117) 5%,
        rgb(255, 237, 97) 10%,
        rgb(168, 255, 97) 15%,
        rgb(133, 255, 247) 20%,
        rgb(122, 149, 255) 25%,
        rgb(216, 117, 255) 30%,
        rgb(255, 122, 117) 35%);

  background-blend-mode: screen, hue, hard-light;
  background-size: 500px 100%, 200% 700%;
  background-position: center, 0% var(--background-y);

  filter: brightness(.8) contrast(2.95) saturate(.65);
}

Note that there is a --background-y variable now. This is controlled by javascript and makes the rainbow slide around with the mouse pointer. We'll set --background-x while we're here because that's used soon. Actually --pointer-x and --pointer-y will be used later as well. They are the same as the background variables but I think Simon wanted to keep them semantically different in the code.

    // These lines are added to the interact function that we previously defined
    card.style.setProperty('--pointer-x', `${pointerXPc}%`);
    card.style.setProperty('--pointer-y', `${pointerYPc}%`);
    card.style.setProperty('--background-x', `${pointerXPc}%`);
    card.style.setProperty('--background-y', `${pointerYPc}%`);

Next we blend in another layer that also moves with the mouse pointer and creates diagonal bands of light:

.card__shine {
  background-image:
    ...stuff from before...
    repeating-linear-gradient(
        133deg,
        rgb(14, 21, 46) 0%,
        rgb(143, 163, 163) 3.8%,
        rgb(143, 193, 193) 4.5%,
        rgb(143, 163, 163) 5.2%,
        rgb(14, 21, 46) 10%,
        rgb(14, 21, 46) 12%);

  background-blend-mode: screen, hue, hard-light;
  background-size: 500px 100%, 200% 700%, 300% 100%;
  background-position: center, 0% var(--background-y), var(--background-x) var(--background-y);

  filter: brightness(.8) contrast(2.95) saturate(.65);
}

Yet another layer is blended in, a radial-gradiant that provides a bit of glare but I couldn't tell the difference. Later on we'll add more glare but I think this was supposed to be like the light reflecting off the foil at the back of the card.

  .card__shine {
    background-image:
    ... previous stuff ...
    radial-gradient(
      farthest-corner circle
      at var(--pointer-x) var(--pointer-y),
      rgba(0, 0, 0, 0.1) 12%,
      rgba(0, 0, 0, 0.15) 20%,
      rgba(0, 0, 0, 0.25) 120%);
  }

  background-size: 500px 100%, 200% 700%, 300% 100%, 200% 100%;
  background-position: center,
    0% var(--background-y),
    var(--background-x) var(--background-y),
    var(--background-x) var(--background-y);

Now we get to the pseudo element ::after. It shares the same css as the .card__shine layer but overrides the background-position and background-size properties so that it moves in the opposite direction. The filter and blend modes are different too so that they interact - sometimes cancelling and sometimes boosting the glow. I don't know why, but it's important to set content: ""; and display: grid;, otherwise the ::after layer doesn't show.

.card__shine::after {
  content: "";
  display: grid;

  background-position:
    center,
    0% var(--background-y),
    calc( var(--background-x) * -1) calc( var(--background-y) * -1),
    var(--background-x) var(--background-y);
  background-size: 500px 100%, 200% 400%, 195% 100%, 200% 100%;

  filter: brightness(1) contrast(2.5) saturate(1.75);
  mix-blend-mode: soft-light;
}

If it looks blank, then hover the mouse over it. My browser shows an empty box until the interact function is called. Maybe it's a z-index issue.

Next: Mask Layer of Pokemon cards implemented in CSS and javascript

A friend suggested that I create a pokemon card of myself for my website. When we were googling Pokemon cards and CSS, the top hit was Simon Goellner's Pokemon Cards Gallery which led us to the pokemon-cards-css GitHub project. I was pretty excited by this and immediately wanted to understand how it worked. Simon has posted a comprehensive Wiki site that explains the architecture of the effect which helped me get a grasp of things but I also learned a lot by looking at the card in the Firefox inspector and trying to reverse engineer the effect myself.

Here are some things to look at and steps I followed to integrate this into my website without using Svelte since this website is very static.

I won't go into everything because there are so many details. The more I look at this effect, the more impressed I am at how much attention to detail there is! So this explanation will just cover the big ideas that I learnt.

Part 1: Movement

I'm going to divide this up into multiple posts because it takes awhile to explain. Each concept is a bit of work so in the interests of getting other stuff done, I'll make this a series.

First of all, to see the holographic effect, the card needs to move and catch the light. Simon has published a stand-alone component for this but I went for something even simpler. Also, the architecture with all the details is explained on the wiki. Given a basic card HTML div, you can make it rotate in response to the mouse with some pretty basic JS:

<div class="card" id="holocard">
    <div class="card__rotator">
        <div class="card__front">
        </div>
    </div>
</div>

Here are the styles that rotate the card__rotator element (and everything inside it). The rotation is controlled using --rotate-x and --rotate-y which are set by the javascript.

.card {
    border: gray solid 1px;
    width: 330px;
    height: 460px;
    perspective: 600px;  /* has to be on the parent element */
}

.card__rotator {
    /* The rotate-x/y variables changed in the javascript make the div move */
    transform-style: preserve-3d;
    transform: rotateY(var(--rotate-x)) rotateX(var(--rotate-y));
}

.card__front {
    width: 330px;
    height: 460px;
    background-color: grey;
}

Here is the most basic javascript to react to mouse pointer events:

const card = document.getElementById('holocard');

/* A simple function to keep a value inside expected bounds */
function clamp(v, min, max) {
    return Math.min(Math.max(v, min), max);
}

/* Interact is called by mouse events */
function interact(e) {
    /* Calculate the cursor position as x/y coordinates normalised to 100% values */
    const rect = card.getBoundingClientRect();
    const x = e.clientX - rect.left;
    const y = e.clientY - rect.top;
    const pointerXPc = clamp((x / rect.width) * 100, 0, 100);
    const pointerYPc = clamp((y / rect.height) * 100, 0, 100);
    /* rotation is set to a scaled value based on the x/y position */
    card.style.setProperty('--rotate-x', `${(pointerXPc - 50) * -20/50}deg`);
    card.style.setProperty('--rotate-y', `${(pointerYPc - 50) * 20/50}deg`);
}

function interactEnd(e) {
    card.style.setProperty('--rotate-x', '0deg');
    card.style.setProperty('--rotate-y', '0deg');
}

card.addEventListener('pointermove', interact);
card.addEventListener('pointerleave', interactEnd);

And the result is a card you can hover the mouse over.

Next: Add the Shine Layer

Many organisations use some combination of feature branches and feature flags. But how do you decide what combination will work for your organisation?

In researching for this article, I came across this blog post at Rollgate which pretty much covers everything that was on my mind. Feature Flags vs Feature Branches: When to Use Each.

So I will do a bit of a TL;DR of that article and conclude with a few of my own observations. Here are the main points:

It's not either/or, feature flags and feature branches solve two different but related problems: Feature branches allow control over code integration. Feature flags allow control over feature release.

Feature branches provide code isolation and allow checks before the feature goes into main. But they can be a burden if allowed to live for too long. I certainly relate to the "all-or-nothing release" comment. I've seen it too many times: the feature languishes in a branch, unable to be released until every idea that any stakeholder had about the feature has been implemented and second guessed and in all that time, not a single customer has seen it and even internal stakeholders have only glimpsed it in sprint demos but not been able to interact with it.

Feature flags give the flexibility to release anytime but introduce more complexity, expand the testing exponentially and can go stale.

The largest tech companies in the world use feature flags and feature branches: Google, Netflix, Meta and Spotify.

The rest of the article goes into more details on the nuts and bolts of implementing a feature flag service, git branching strategy and ways to prevent pitfalls such as stale feature flags.

Here are a few thoughts I had based on my experiences in this area:

In embedded software, feature flags have some added complexities. Since the software is versioned and needs to be rigorously tested, the cost of feature flags is greater. Typically embedded firmware updates come with a migration scheme that must upgrade the configuration. The migrations are now more complex because the different combinations of feature flags must be considered as well.

In embedded software, there are limited tools for feature flags. The solution is more than likely to be a in-house rolled solution involving hidden configuration flags. This also means there won't be dashboards and other tools to track which flags are running at any time. Explicit logging will be needed to ensure that support engineers can interrogate which feature flags were enabled at the time of a bug. If there are automated tools for collecting device state in the context of a failure, ensure feature flag states are included.

The complexity added to CI by feature flags can't be understated. It's not just about testing the feature itself but if that feature interacts with another feature, then the other feature must now be tested twice or some decision needs to be made about leaving some tests out and how to balance the risk.

Vertical slicing of features is essential for keeping feature branches short lived. A feature flag actually enables this. If the stakeholders are in an all-or-nothing mindset about feature delivery, then the small iterations of the feature can be merged to main safely behind a feature flag, avoiding a long lived feature branch.

Further Reading

Don’t Branch that Code! Feature Flags vs. Feature Branches

Feature Flags vs. Feature Branches

Feature flags vs feature branches in continuous delivery

Many organisations keep their code in multiple repositories which can create challenges when trying to develop using continuous integration.

Let me explain. imagine you have an embedded Linux system with some proprietary packages running on it: A web UI front end, a REST API that the Web UI talks to, various CLI tools and daemons that interact with the hardware.

You develop each of these packages in their own repository and they have self-contained CI tests which use mocks for any interactions with other parts of the system.

The day comes that you realise the manual end-to-end build and test steps you're doing are not scalable. You need to set up a CI system that will build a system image and run end-to-end tests on PRs before they are merged.

But there's a big problem now because of coupled changes across repositories. You want to update the Web UI but it depends on a change to the REST API which is in a different repository. How do you test that? You have to make the CI build two PRs from different repos and combine them. How can you automate it?

Before I talk about some answers, a quick note about coupling. Coupling is where a piece of software depends on some other piece of software behaving a certain way. It is actually how all software works. But when most developers talk about coupling as a problem, they are referring to coupling that breaks application programming interface (API) contracts. APIs are how software systems can be coupled safely. Most of the time when I'm talking about coupling here, I'm meaning the general sense of two packages that interact, not necessarily breaking APIs.

Coupling of packages is not really unique to embedded Linux systems, it will happen in any end-to-end testing in CI when applications of multiple repos need to depend on each other. To solve the issue, you have three main approaches:

1. Migration through multiple commits: Make multiple commits using backwards compatibility. You add support for the new work but ensure it can still also work the old way. Then you upgrade the dependent system to make use of the new way, then you remove the support for the old way.

2. Orchestration and composition: An orchestration layer is introduced to your CI that can be made aware of dependencies between commits and configure the build to compose the PRs across multiple repos.

3. Use a monorepo: Anything that is causing coupling issues should just be put into one big repo. For an embedded Linux system, this would mean having your Yocto layer and proprietary applications all in the one repo with only a few independent and very stable packages staying in their own repos.

The downside of migration through multiple commits is that the commits all have to go through CI and get reviewed. It adds a lot of overhead to a potentially small change and depending on how slow your test and review stages are, it could be prohibitively expensive.

One theoretical benefit of migration through multiple commits is it creates a disincentive to couple changes together. Developers are challenged to avoid changing APIs where possible. In practice, this is impossible. Some repositories are naturally coupled - even if they are very different code bases e.g. you might have a C back-end and Javascript front-end in different repositories that are often dependent because some change in the back-end needs to also be reflected in the front-end.

Orchestration and composition is supported to some extent in CI tools. There is usually some facility to trigger other workflows and pass payloads between them but it always seems pretty fragile to me. The configurations are complex and seem to be add-ons rather than designed in from the start. In my experience it is not a reliable approach. If you're in a position where you are choosing which CI system to adopt, then put composability on a must-have features list.

Monorepos are the more traditional systems I've seen. They are the simplest case. There are a few disadvantages though:

• They become massive! The monorepo grows and grows and it's difficult to trim them back. Cloning them can take a very long time and use a lot of bandwidth if you're using cloud services.
• They enable code that breaks API boundaries. Once the barriers to coupled packages are removed, developers will start writing code that violates API design principles. Not on purpose but because of time pressures or by mistake. It is up to the senior engineers to now police the system with more vigilance or come up with some automated checks.

So what's the answer? I think it's a combination of the three options. A rule I've heard before is that "code that changes together should stay together". The idea is usually for architecture but it can apply to repository organisation as well. The default should be to isolate packages in their own repositories and build out a pretty flexible API early on so that ongoing changes are minimised. If the nature of the package is that it has to change in sync with another package more often than not, then consider merging the two repositories. Once you have packages sharing a repository, introduce review checklists and automation that alert or prevent developers from breaking APIs.

I've been thinking a lot about release branches. Many software companies are not really doing releases anymore with continuous deployment / delivery and SaaS offerings but in the embedded world, firmware is developed and packaged as versioned files that must be rigorously tested with the aim that they will be deployed and perhaps never upgraded or only infrequently upgraded when critical security updates are required.

This means that many companies don't have to worry about release branches. For us embedded developers, the way release branches are managed can have a big impact on the ability to support customers with hotfixes and patch releases as well as timely delivery of feature releases.

The three most talked about git "flow" methods that I can find are GitFlow, GitHub-Flow and GitLab-Flow. Of these, only gitflow and Gitlab-flow are suitable for embedded development. I'll briefly explain github-flow anyway.

What are we trying to achieve?

It's worth taking some time to understand why git branching is important. Collaboration is fundamental to software development and git / scm is at the heart of the collaboration when it comes to code.

Some features these flows try to optimise for:

• Minimise the time code spends in branches. When code is in branches, it quickly drifts from the main branch as other code is merged in. The longer it stays in a branch, the harder it is to reconcile at merge time.

• Some form of tagged release. Whether using a release branch or not, all git flows have some point at which the code is released. This is important when it comes to support. The developers supporting the software must know which range of commits are in each release so they know which code a customer is running by knowing the release version.

• Isolation of releases. While code is being prepared for release, most organisations are also developing the next round of features. The release should happen in parallel and be isolated from changes that result from the features under development.

Different flow styles

GitFlow is the original "flow" method that started the conversation. In 2010, software developer Vincent Driessen blogged about how he uses git branches and in particular how this helps manage releases. He called it GitFlow.

By his own amendment in 2020, GitFlow is not suited to more modern practices such as continuous delivery since it adds overheads such as release processes and hotfixes.

Some other things to note about GitFlow:

• It mentions decentralised development where developers pull from each others repositories to share code. I have rarely worked that way. In practice most companies use a central server and if there is sharing, it is through branches. This often also results in rewriting of history to hide WIP commits, a practice that git didn't support very well in 2010 but is commonplace now.

• It assumes you are only supporting the most recent release. The main branch is considered the stable release. If you need to make a hotfix, you branch from head of the main branch which is the most recent release. There are no long lived release branches that let you amend an older release. In embedded software, there are often customers who can't upgrade to the latest release, whether it be due to hardware limitations or integrations with other systems, those customers often need a patch release targeted at their older software.

• It promotes use of --no-ff commits. This can be a contentious topic amongst developers. Many developers advocate for linear git commit history where merges are performed using rebase and fast-forward (--ff-only). This might also be a product of 2010s thinking where rebasing was a more dangerous operation.

GitHub-Flow is maybe the more common flow style in use now. It is suited to continuous delivery. It is simply feature branch -> PR -> main. The main branch is just tagged as a release whenever development has reached some point that the developers are happy with or when a particularly featureful PR has landed.

For embedded development, GitHub-Flow lacks some important features:

• Embedded software releases require rigorous testing that often takes days if not weeks. It is not practical to perform that kind of validation for every PR (unless you have really good automation).

• There is no way to make hotfixes or patch releases. For reasons discussed above, many customers of embedded software require patch releases.

GitLab-Flow bridges the gap between GitFlow and GitHub-Flow. It is very similar to GitHub-Flow in its most basic form but documents a release branching strategy for versioned software.

In GitLab-Flow, the main branch and feature branches are used with PRs just like in GitHub-Flow. When it comes time for release, a release branch is created from main. As the release branch is tested, any problems found are fixed in main and then cherry-picked to the release branch. Once released, the release branch is tagged. If hotfixes or patch releases are needed, the required fixes are cherry-picked from main to the release branch and tested. Once stable, the release branch is tagged again.

Some features of GitLab-Flow development with release branches:

• There are fewer branches. The main branch is used more and some continuous integration styles are possible. Developers do feature branches and PRs just as they do for continuously delivered applications.

• Supports patch releases on multiple released versions in a sane way. It would be a pain if a customer wanted to skip a patch release e.g. they want 3.1.3 but not the previous fix 3.1.2 but that would be very rare and still possible by branching the release branch.

• There is a lot of cherry-picking.

What is a code freeze?

A long time ago when it was hard to make branches in repositories, organisations would have a code freeze before release. This is where development on new features stops, the main branch is locked and only bugfixes for the release are allowed. The whole team focuses on the release. While this practice is outdated for most software development, it is still used to some extent for embedded projects. A simple reason is where regression testing an embedded product is labour intensive and all developers are required for testing and bugfixing. it might not be worth going through the process of a release branch when there is no other development happening during the release phase.

Should release branches be closed?

GitFlow promotes closing release branches once the release is merged. A stable branch contains the most recently released code at its head. This simplifies matters and makes automating some release processes easier. GitLab-Flow promotes keeping release branches open until the release is no longer supported. For embedded development, it is better to have the option of supporting the older releases so keeping release branches around should be planned for and a strict naming convention should be adhered to. Tooling can be developed to aid managing the branches.

Cherry-picks vs merging

GitFlow promotes merging the release branch to the development branch. In that scenario, fixes during release testing go onto the release branch directly and future regressions are prevented by merging the release branch back to develop when done.

GitLab-Flow promotes fixing all bugs in the main branch and cherry-picking from the main branch to the release branch so that the main branch never misses out on the bugfix. Cherry-picks are more risky than branch merges because they rely on knowing which commits have the desired fixes. Sometimes developers make mistakes and don't label things properly or they sneak a bugfix into a different commit or even accidentally fix a bug in one commit but they think it was resolved by another. There can be dependencies between commits that require conflict resolution. Often the original developer must be consulted to resolve those issues. Releases can be hectic which puts pressure on developers and can lead to mistakes.

Despite that, in some cases, cherry-picks are the better trade-off, especially when a linear git history is prioritised. For example, merges involving submodules and multiple repositories can be just as error prone.

Multiple Repositories and Submodules

Many organisations maintain multiple repositories and submodules to share code between different products. This poses a few problems when it comes to releases.

The first question is whether to lock releases in the repositories all together. This would mean that release branches are created in all the repositories and the references are to the heads of those release branches. The advantage of this is the multiple repositories don't all need their own release life-cycles. If this approach is used, then take care to make the naming scheme product specific, otherwise different products releasing using the same shared repository will have name clashes and confusion will reign.

If the repository releases are decoupled, then they should be in a state where they are either very stable or they are treated like a kind-of in house vendor library. Releases of these repositories will need to be coordinated in response to the needs of the various products that reference them. The disadvantage of this approach is that if a bugfix is needed in the repository, then the product release is delayed until the internal release of the repository can be made (it might be very quick if it supports continuous delivery).

Branching of repositories that reference other repositories is complicated. For example, when the upper repository is branched, it still refers to the main branch of the submodule. The submodule must also be branched for bug fixes and the reference in the upper repository updated. This second step is often forgotten so it is recommended to create automated processes to ensure it is done.

If you choose to avoid cherry-picks and instead decide to merge the release branch back into main, then submodules also cause issues. Imagine you have made several fixes in the submodule and updated the upper repository several times. Now you want to merge back to main. If you are using --no-ff, it's not so bad. The submodule should be merged first and the when merging the upper repository, git will find the merge commit and update the reference. When using rebase and fast-forward, it's not so easy. As soon as you rebase the submodule, you change history. This breaks the upper module references to the submodule. You need to find the upper repository reference updates and reconcile them with the new history. In most cases it's easier to rewrite the upper repository references updates so they all but the last one is removed. This rewriting of history is error prone but some developers believe it is worth it to preserve a linear main branch.

A little plug for Mermaid

Mermaid is a diagramming tool that supports documentation as code. The diagrams are mostly human readable code that can be committed to git alongside README.md files. It happens to support Git diagrams which is really cool and how I made the diagrams for this blog post.

GitFlow mermaid:

gitGraph
    commit
    branch develop
    checkout develop
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout develop
    merge feature
    branch release
    checkout release
    commit
    commit
    checkout main
    merge release tag: "3.2.0"
    branch hotfix
    checkout hotfix
    commit
    checkout main
    merge hotfix tag: "3.2.1"
    checkout develop
    commit

GitHub-Flow with release tag mermaid:

gitGraph
    commit
    branch feature
    checkout feature
    commit
    checkout main
    commit
    checkout feature
    commit
    checkout main
    merge feature
    commit tag: "3.2.1"

GitLab-Flow with release branch mermaid:

gitGraph
    commit
    branch feature
    checkout feature
    commit
    checkout main
    commit
    checkout feature
    commit
    checkout main
    merge feature
    commit
    branch release
    checkout release
    commit
    commit tag: "3.2.1"
    checkout main
    commit

Further Reading

Mastering GitHub Release Branches & Versioning: A Complete Guide

Comparing Git workflows: What you should know: GitFlow