Battlemap Grid

You've got a gorgeous AI battlemap and now you need a grid on it. That's the part every D&D/tabletop player has done in GIMP once, sworn never to repeat, and this node exists to retire that chore for good. Feed it any image, tell it square, vertical hexagon, or horizontal hexagon, and it draws a clean anti-aliased grid right over the top. It's the finishing step of the classic ComfyUI battlemap pipeline: generate a base map, run it through img2img to texture it, then stamp a grid and a compass on the result.

How it works

The node overlays the grid on your existing image - it never touches the map content itself. Drawing is done with aggdraw, which is why the lines look crisp instead of the pixel-staircase garbage plain PIL gives you at 1px wide. The grid is centered on the image and drawn outward in both directions, so it's symmetric no matter your map size.

For hex maps it borrows a classic hex-tiling algorithm (credited in the source to Elmer de Looff's variable-scope.com post), which renders every hexagon as its own polygon. "vertical hexagon" stacks hexes into vertical columns; "horizontal hexagon" lays them in horizontal rows. Pick whichever matches your VTT's grid setting and move on.

The inputs that matter

There are ten of them but you'll actually touch four:

• grid_side - the cell size in pixels. 64 is the default and roughly works for a 1024px-wide map; too small and it's spaghetti, too big and players can't tell their square from their neighbor's.
• grid_type - square, vertical hexagon, or horizontal hexagon.
• line_width - 1 to 20, keep it at 1–2 or the grid visually swallows the art.
• red / green / blue / alpha - the line color as RGB plus alpha. White is the default, which reads well on most maps; on a snowy scene you'll be glad these exist.

The two optional inputs are the clever part: orig_grid_width and orig_grid_height. If you know the map's original grid count (say 24×32), passing them in makes the node recompute grid_side so the overlay stays aligned even after you've upscaled the image 4×. Wire them straight from Map Generator's grid width / grid height outputs and the grid lands on the cells instead of drifting.

How to install it

It's a tiny pack with no model files to download. Via ComfyUI Manager, search ComfyUI_BattlemapGrid and install. Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/fmatray/ComfyUI_BattlemapGrid

One real gotcha: the pack has no requirements.txt, but the grid code imports aggdraw, which isn't part of ComfyUI's stock environment. Without it the whole pack fails to import and all four Battlemaps nodes silently disappear from your menu. Install it into the same Python that runs ComfyUI:

path/to/ComfyUI/venv/bin/pip install aggdraw

Then restart ComfyUI. You'll find the node under the Battlemaps category.

Common issues

• No Battlemaps nodes in your menu at all - that's the aggdraw import failure above, not bad luck.
• Grid misaligned with the map after upscaling - you're either not passing orig_grid_width/height, or you resized non-uniformly. The node only auto-fits when the width/height scaling ratio is within ~1% of each other; anything else and you're better off setting grid_side to the exact pixel size of a cell yourself.
• Grid off-center - it's always centered on the image, so if you cropped the map to a region, re-center or regenerate the grid after cropping.

A niche tool for a niche hobby, but for its one job it's exactly right: wire image in, wire image out, done.