I Built a Cloud Caravan Merchants Progression System as a cloud Marketplace

Every cloud platform has a marketplace. AWS has the AWS Marketplace, Azure has its own, GCP too. They're places where you find specialized vendors offering services you can't build yourself — and the more you buy, the more they offer you.

We built that in Minecraft: Cloud Caravan Merchants. Three specialized traders that travel with donkeys carrying loot chests, offer 5 base trades each, and evolve into Elite merchants when you complete their missions — unlocking premium trades including Elytra, Tridents, and Totems of Undying.

🎮 The learning angle: The Elite progression system mirrors how cloud marketplace vendors work — start with basic offerings, prove you're a serious customer (complete trades), and unlock enterprise-tier products. The 3 merchant types map to cloud specializations: infrastructure (Packet Runner), platform (Protocol Broker), and application layer (Quantum Courier).

3 Merchants — 3 Cloud Layers

Merchant	Color	Specialty	Cloud Layer
Packet Runner	Cyan	Raw materials & resources	Infrastructure (IaaS)
Protocol Broker	Orange	Equipment & upgrades	Platform (PaaS)
Quantum Courier	Purple	Runes, tomes & magic	Application (SaaS)

Each spawns with a donkey carrying a loot chest with starter items. It's a welcome package — like free tier credits when you sign up for a cloud platform.

The Spawn Egg — Full Caravan Unit

The custom spawn egg doesn't just spawn a merchant. It spawns the entire unit:

1. Merchant entity (custom type, wandering trader model)
2. Donkey (tamed, with chest)
3. Loot in the chest (via loot table)
4. Leash connecting donkey to merchant

@Override
public ActionResult useOnBlock(ItemUsageContext context) {
    // 1. Spawn merchant
    CloudMerchantEntity merchant = merchantType.create(world);
    merchant.setPosition(pos.getX() + 0.5, pos.getY(), pos.getZ() + 0.5);
    world.spawnEntity(merchant);

    // 2. Spawn donkey with chest
    DonkeyEntity donkey = EntityType.DONKEY.create(world);
    donkey.setTame(true);
    donkey.setHasChest(true);

    // 3. Fill chest via NBT (inventory must be properly sized)
    NbtCompound donkeyNbt = new NbtCompound();
    donkey.writeNbt(donkeyNbt);
    donkeyNbt.putBoolean("ChestedHorse", true);
    NbtList itemsList = new NbtList();
    // ... add loot items to NBT
    donkey.readNbt(donkeyNbt);
    world.spawnEntity(donkey);

    // 4. Leash
    donkey.attachLeash(merchant, true);
}

The Donkey Chest Bug — A War Story

Fun debugging story: donkeys in 1.20.1 have a SimpleInventory field called items. When you call setHasChest(true), it's supposed to expand the inventory from 2 slots (saddle + armor) to 17 slots (+ 15 chest slots). But the expansion happens in onChestedStatusChanged(), which recreates the inventory.

If you try to put items in the chest BEFORE the inventory is properly sized, you get ArrayIndexOutOfBoundsException. If you put them AFTER spawning, the inventory might not be synced to the client yet.

The solution: write the chest contents via NBT. Set ChestedHorse: true and Items: [...] in the NBT compound, then call readNbt(). This forces the entity to reconstruct its inventory with the correct size AND the items already in place.

Elite Progression — The Loyalty Program

Complete all 5 base trades (use them until sold out) and the merchant evolves:

Base (5 trades) → Elite ★ (7 trades) → Elite ★★ (9 trades) → Elite ★★★ (11 trades)

Each promotion:

• Adds 2 new trades with premium items
• Changes the merchant's name to gold with stars
• Triggers a Totem of Undying particle burst
• Adds ambient END_ROD particles

private void checkElitePromotion() {
    int requiredTrades = 5 + (eliteLevel * 2);
    if (completedTrades >= requiredTrades && eliteLevel < 3) {
        eliteLevel++;
        applyEliteName(); // "★★ Protocol Broker ★★"
        addEliteTrades(this.getOffers(), eliteLevel);
        // Celebration particles
        world.spawnParticles(ParticleTypes.TOTEM_OF_UNDYING, ...);
    }
}

Elite Trades — Premium Vanilla Items

Cycle	Packet Runner	Protocol Broker	Quantum Courier
★	Quantum Shards, Spyglass	Netherlink Plating, Enchanted Golden Apple	Deployed Runes, Ender Eyes
★★	Cloud Edge Pearls, Echo Shards	Cloudsteel Plating, Trident	Grimoire of Architect, XP Bottles ×16
★★★	Nether Star, Totem of Undying	Netherite ×2, Elytra	Quantum Runes ×16, End Crystals

The endgame trades offer items that are normally very hard to obtain (Elytra, Trident) in exchange for Cloud Credits and rare materials. It's the cloud marketplace premium tier.

Natural Spawning — The Caravan Arrives

Every ~1 hour of real time, there's a 15% chance a caravan spawns 48-96 blocks from a random player:

private static void spawnCaravan(ServerWorld world, BlockPos pos, Random random) {
    int caravanSize = 1 + random.nextInt(3); // 1, 2, or 3 merchants
    // Shuffle types to avoid duplicates
    List<MerchantType> available = new ArrayList<>(List.of(MerchantType.values()));
    Collections.shuffle(available);

    for (int i = 0; i < caravanSize; i++) {
        // Spawn merchant + donkey at offset positions
        spawnUnit(world, pos, available.get(i), i * 2.5);
    }
}

A full caravan (3 merchants) gives you access to all specializations at once. It's like a cloud conference — all the vendors in one place.

Never Despawn — Persistent Infrastructure

Unlike vanilla wandering traders that disappear after 40 minutes, Cloud Merchants are permanent:

this.setPersistent();
this.setDespawnDelay(Integer.MAX_VALUE);

Once you find (or spawn) a merchant, they stay forever. They're your infrastructure — you invested in them, they stick around.

Custom Textures — Visual Identity

Each merchant uses a recolored wandering trader texture generated with Python PIL:

def recolor(data, hue_shift):
    """Shift hue of non-skin pixels"""
    for pixel in data:
        if not is_skin_tone(pixel):
            h, s, v = rgb_to_hsv(pixel)
            h = (h + hue_shift) % 1.0
            pixel = hsv_to_rgb(h, s, v)

• Packet Runner: cyan shift (networking)
• Protocol Broker: orange shift (fire/security)
• Quantum Courier: purple shift (quantum/magic)

Rune Table Recipes — Mod Interop

We also added recipes for the Rune Crafting Altar (from the Runes mod):

Rune	Altar Input	Output	Savings
Packet	Cloud Shard + Redstone	×2	-1 Lapis, +1 output
Protocol	Packet Rune + Blazing Shard	×2	-1 Gold, +1 output
Quantum	Protocol Rune + Quantum Shard	×2	-1 Ender Pearl, +1 output

This is mod interop — using another mod's crafting system to provide alternative recipes. Like using a third-party service that's cheaper than building your own.

Lessons Learned

Challenge	Solution
Donkey chest inventory size	Write items via NBT, not direct slot access
Entity renderer missing = crash	Register renderer in ClientModInitializer
Wandering trader despawn timer	Override with MAX_VALUE despawnDelay
Spawn egg model missing	template_spawn_egg parent model
Trade completion tracking	NBT persistence (CompletedTrades, EliteLevel)

Series Wrap-Up

Over 8 posts, we went from "what if AWS services were Minecraft swords" to a full tech-magic mod with:

• 7 cloud-themed swords with unique abilities
• 28 spells across 9 spellbooks
• 4 armor sets with set bonuses
• Multiblock machines with BFS energy networks
• 7 villager professions with a Cloud Credits economy
• 3 Caravan Merchants with Elite progression
• Full compatibility with 650+ mod modpacks

The mod teaches cloud computing by making you experience the concepts. You don't read about Auto Scaling — you feel your damage stack. You don't study fault tolerance — you dodge attacks with Quantum Armor. You don't memorize service tiers — you progress through them.

That's the power of game-based learning. And we built it all with AI as a co-pilot.

---

The complete mod is on GitHub. Clone it, build it, play it.

Connect with me:

• LinkedIn
• X/Twitter
• GitHub
• Dev.to

I'm Carlos Cortez, this is Breaking the Cloud, and this series proved that the best way to learn cloud is to play it. See you in the next adventure! 🎮☁️⚔️