🧱 Devlog: Building with Shadows – A Journey into Minifantasy Asset Automation

If you're a Minifantasy fan, these tools will be coming to itch.io very soon.

🌿 Discovering Minifantasy

It started with a search for the right aesthetic — something with personality, consistency, and enough variety to support a whole world. That’s when I found Minifantasy by Krishna Palacio, a massive pixel art ecosystem that ticks every box: modular tiles, animated characters, spell effects, structures, world biomes, UI elements — you name it. Every pack is loaded with beautifully crafted 16x16 or 32x32 pixel art, rich in charm and bursting with potential.

You can feel the love in every frame. It’s clear Krishna isn’t just churning out art — this is a growing universe, supported by years of consistent vision and community feedback. Each asset pack builds on the last, with support for terrain blending, animations, RPG mechanics, and tactical combat tiles — the kind of stuff that gets game devs dreaming big.

So naturally, I wanted to build something serious using these assets. And that’s when reality hit.

🧠 Going Deep (and Getting Lost)

The more I explored the full library of Minifantasy, the more I noticed how complex the organizational structure was becoming. Not because it’s bad — it’s actually quite thoughtful — but because there’s just so much of it, and it’s authored for flexible use rather than strict production pipelines.

• Sprites might live in different folders than their shadows.

• Shadows might follow different naming conventions per pack (e.g., _Shadow, _Shadows/, _layer 6, pluralization).

• Folder structures vary: some use subfolders per character, others per animation or theme.

• A lot of assets are sliced out already… but others are still in sprite sheets or have special formatting quirks.

It’s great for visual browsing, but when you want to ingest it into a structured game engine, stuff breaks down fast. You can’t just “load a folder of assets” and assume it will Just Work™.

There are thousands of files, and you don’t always know which ones are meant to be combined, which are standalone, and which are just variations. Manually organizing or preprocessing this for production is time-prohibitive — especially for tools that expect per-sprite transparency, metadata, or animation timing.

🎯 The Core Problem: Shadows & Structure

One pain point we identified early on: base sprites and their shadows are often separated — either as different files or in entirely different directories. Sometimes it’s:

• GoblinAttack.png paired with GoblinAttackShadow.png

• Sometimes it’s Krampus/Attack.png + _Shadows/Krampus/Attack.png

• Other times it’s just layer 6 files buried three levels deep with no naming convention.

These shadows aren’t decorative — they’re baked into the animation and essential for the finished look. You need to combine them with the base sprite for most production uses. So doing that manually? Not scalable.

🧪 The Plan: Automating Sprite + Shadow Combining

We decided to tackle one piece of the pipeline first: create a tool that scans a directory tree, finds base sprites and their matching shadows, combines them into a new image, and saves it to a mirrored folder structure. And if a sprite doesn’t have a shadow, just copy it over anyway.

This sounds simple until you realize artists name files however they want. So we had to develop a matcher that could work across asset packs, detect intent, and avoid false positives — like pairing unrelated files just because they’re vaguely similar.

🔍 The Matching Gauntlet: 9 Cases of Chaos

We cataloged 9 different matching cases, including:

1. _Shadow suffix (e.g. GoblinAttackShadow.png)

2. _Shadows/ folder sibling (e.g. Creatures/_Shadows/Goblin.png)

3. Mirrored folders (e.g. Animations/Attack.png ↔ _Shadows/Animations/Attack.png)

4. Singular vs plural (Skeleton.png ↔ SkeletonsShadow.png)

5. Layer suffix (e.g. _layer 6.png)

6. Subfolder drift (e.g. base in /Characters/, shadow in /Effects/)

7. Filename prefixing (e.g. FireSpell.png ↔ Shadow_FireSpell.png)

8. Underscore-only matches (e.g. DiabloAttack.png ↔ Diablo_Attack_Shadow.png)

9. Fallback heuristics (when none of the above work, compare base filename tokens and path fragments)

This wasn’t just string matching. It was fuzzy logic built around the patterns we observed across dozens of Minifantasy packs. It had to detect not just file name similarity, but structural intent — “this shadow belongs to that base sprite” — without being brittle.

⚙️ Building the Tool

We built the tool using the File System Access API in the browser, so we could:

• Traverse full folder trees recursively with user permission

• Preview, log, and filter matches dynamically

• Export combined images using canvas

• Preserve folder structure in the output

• Optionally include unmatched “shadowless” base sprites

It wasn’t all smooth sailing.

We hit snags like:

• Loop scoping issues where matched pairs weren’t persisting between iterations

• Silent JavaScript errors (thanks to orphaned continue statements and rogue syntax like fileObj[i];a)

• Folders vanishing mysteriously because matched paths weren’t deduplicated properly

• Async UI issues where the progress bar wouldn’t update unless we yielded control manually

But we powered through, thanks to aggressive logging, line-by-line debugging, and yes — a little help from AI.

🧠 Design Principles We Followed

To make the tool robust, we baked in a few key design philosophies:

• Heuristic-Driven Matching: Assume the artist is inconsistent, and build fuzzy logic accordingly.

• Scope Isolation: Keep loop state and match cache separate and persistent.

• Path Integrity: Combine not just based on names, but folder structure and full relative paths.

• Optional Copying: Treat unmatched sprites as first-class citizens when opted in.

• No Duplicates: Ensure nothing gets double-processed or accidentally re-used.

🎉 The Payoff

After implementing the tool, validating against a massive folder of Minifantasy assets, and patching up all edge cases, we hit our target:

• ✅ All base + shadow pairs matched and combined correctly

• ✅ Shadowless files preserved when requested

• ✅ Output folder count = input folder count (no more missing children)

• ✅ Exported images are ready for ingestion into a game engine

This tool became the first building block of a larger Minifantasy ingestion pipeline — one that will eventually support metadata tagging, animation previews, and game-engine-ready JSON output.

📚 Final Thoughts

Using Krishna Palacio’s work is a dream creatively — but it still requires an engineer’s discipline to bring it into a game project at scale. These assets are massive in scope and flexible by nature, which makes them ideal for prototyping but tricky for production.

But by identifying one specific challenge (shadow pairing), breaking it into its root causes, and building a solution from the ground up, we made a meaningful improvement in how usable this incredible library can be at scale.

If you're a Minifantasy fan, these tools will be coming to itch.io very soon.