Cursor Forge

Your art in. A shippable Windows cursor pack out.

Building a Windows cursor scheme by hand is four problems that all look trivial until

you try them.

1. The .cur / .ani format

.cur is an .ico variant that hijacks two header fields to store the hot-spot, so you

cannot just save an ICO with Pillow. .ani is a RIFF/ACON container with per-frame icon

chunks and jiffy timing. Getting both right is a day of reading hex.

2. Hot-spots that scale

A hot-spot is defined per embedded size. Get it wrong and the click point drifts as

Windows picks a larger bitmap.

3. The 32px problem

Windows renders cursors at 32x32 unless you embed bigger sizes. Art that looks great at

512px turns into mush at 32px.

4. "Is it actually sharp?"

Windows will bilinearly interpolate your 32px bitmap up to 96px instead of using the

96px bitmap you embedded. It looks fine in a screenshot and blurry on a real desktop.

Most people don't find out until a customer complains.

This is the pipeline that solves all four. It is the one used to build the shipped

17-role scheme included in the download.

WHAT YOU GET

scripts/ the full pipeline, plain Python, no build step
xcur.py .cur / .ani / .reg / install.ps1 writers
make_pack.py one command: asset folder -> installable pack + zip
chibi.py illustration -> 32px pixel sprite (not a naive downscale)
demo_src.py procedurally drawn cursors, so you can test with zero assets
verify_pack.py pixel-exact verification, per role per size
win_probe.py ask Windows which bitmap it actually picked
examples/ a complete shipped scheme, to diff your output against
docs/ 4 documents: quickstart, the .cur/.ani format gotchas,
how the verification metric works, install/uninstall
LICENSE MIT -- generated packs are yours, no attribution, no royalty

Every output pack contains:
- 17 .cur / .ani files (every Windows cursor role, plus the Win10 precisionhair alias)
- install.ps1 + a double-click launcher (no admin rights needed)
- a .reg fallback, for machines where security software blocks .bat
- a preview sheet -- every cursor at true 32px, zoomed
- README.txt -- end-user install AND restore instructions
- a zip, ready to upload

Ships to Chinese customers too. One flag switches the four end-user-facing files

(launcher / .reg / preview / README.txt) into Chinese, filenames included. Everything

aimed at you -- script output, --help, docs, this page -- is English either way.

WHY IT IS NOT JUST A RESIZE SCRIPT

Resizing is the easy 10%. Two parts are the reason this exists.

Pixel-art conversion, not downscaling.

chibi.py goes de-fringe -> area-average (BOX, not LANCZOS) -> colour reduction -> 1px

hard outline. LANCZOS ringing grows a grey halo on hard edges -- visible dirt at 8x

zoom. Alpha is forced binary, because semi-transparent pixels become grey fuzz at 32px.

Proof, with a number.

verify_pack.py makes Windows hand back the bitmap it actually selected (LoadImage ->

GetIconInfo), then compares it pixel by pixel against your palette. The metric is the

mid-tone ratio: among opaque pixels, the share whose colour is not in your palette --

pixels Windows invented. Semi-transparent edge pixels are excluded on purpose:

anti-aliasing is not blur.

Embed every size you display, and the report reads 0.0%:
included scheme, 17 roles x 14 sizes embedded worst cell 0.0% (238 of 238)
same art, only 32 and 48 embedded worst cell 15.3% (IBeam at 112px)

Either way you get the number before your customers do, not after.

REAL NUMBERS (measured, not estimated)

Build the demo pack (17 roles x 2 sizes), zip included 0.95 s
Same, with all 14 sizes embedded 2.88 s
Cursor roles covered 17 (+ precisionhair alias)
Sizes verified per role 14 (32 through 256)
Worst mid-tone ratio, included scheme 0.0%
Download size of this product 862 KB
Dependencies Python 3.10+, Pillow

WHAT IT DOES NOT DO

- It will not draw your art. You bring the art; it handles everything after that.
- It will not make a busy, high-detail illustration readable at 32px. chibi.py gives
you twelve size/crop variants precisely so you can see which ones survive before
committing to a full set.
- Verification needs Windows (it calls real Win32 APIs). Pack generation does not.

WHO IT IS FOR

- Artists shipping their own cursor packs, tired of hand-exporting .cur files
- Desktop-customisation developers who want a repeatable build
- VTuber / character artists turning a character into a full desktop asset set
- Anyone who has shipped a pack and then found out it looked blurry at 125% DPI

REQUIREMENTS

Python 3.10+, Pillow. Windows for the verification steps. No compiled dependencies, no

service to sign up for.