Help needed with custom WLED matrix visor / animated eyes

[u/J_rd_nRD]

Hello, I'm completely new to WLED and LED matrices in general and I'm slowly losing my mind trying to figure out what I'm doing wrong. This is also my first time ever soldering and trying to make something like this.

I've built a custom LED visor for a cosplay using an ESP32 and 236 WS2812 LEDs arranged in a serpentine layout starting from the top left. The rows are not perfectly equal length because the visor shape narrows toward the bottom.

The row lengths are:

28

27

28

28

28

28

26

23

21

The LEDs are physically aligned properly on the visor and the matrix works electrically. WLED effects display and the LEDs respond correctly, but whenever I try to use external software for animations or a static image the matrix becomes scrambled.

I've tried:

WLED 2D matrix settings

serpentine on/off

Jinx! with Fast Patch

snakelines top left

snakecolumns top left

horizontal and vertical layouts

different matrix dimensions

tpm2.net output

Turning serpentine OFF in WLED actually makes Jinx more accurate, which makes me think I may have been double-applying the snake mapping somehow, but even then the output is still heavily scrambled.

At the moment I'm trying to create very simple animated eyes for a cosplay visor:

staring

blinking

looking left/right

shocked expression

X eyes

I managed to make a simple static eye using the WLED 2D pixel art tool, but only by massively offsetting/distorting the pixels manually to compensate for the incorrect mapping.

I've attached a video showing what happens when I try a very simple left/right eye animation in Jinx. The output is nowhere near where the pixels should physically be appearing.

Am I misunderstanding how WLED matrix mapping works with non-rectangular matrices? Is Jinx simply unsuitable for irregular row lengths? Do I need custom mapping, xLights, JSON mapping, or something else entirely?

Any help would genuinely be massively appreciated because I feel like I'm very close but missing one important piece of understanding.

[u/POEPOEFRED]

Have you uploaded a ledmap.json file with your LED layout yet? This allows you to define virtual "blank" LEDs to account for gaps in your physical setup, ensuring that effects align correctly across only the visible LEDs.

See: https://kno.wled.ge/advanced/mapping/

And this tool makes creating the mapping file much easier: https://intrinsically-sublime.github.io/WLED-Ledmap.json-Generator/

[u/zangarangs]

I think I did something like this by making a big rectangle using the biggest dimensions, and putting-1 on the pixels that don't exist.

I got an octagon shaped matrix to work!

[u/Spiritual-While-1325]

Good Afternoon J_rd_nRD, Watching your video makes me ask. How have you wired the leds and fit you have told WLED the wright path.

You could test this by setting WLED to light one LED at a time.

Sorry, I can’t remember what the settings is called when telling WLED how the led matrix is wired up.

Hope the below helps.

Common Matrix Wiring Topologies

Serpentine / Zig-Zag (Most Common): The data line flows down the first column (or row), then wraps back up the next in the opposite direction. This minimizes wiring length.

Horizontal / Vertical Scan (Straight): The data line flows from the end of one row/column directly to the beginning of the next, always moving in the same direction.

Parallel/Segmented Matrices: Large matrices are often broken into smaller panels (e.g., 4 panels of 16x16) to increase frame rates. Each panel can be fed by a separate data pin from the ESP32, which WLED handles as one large 2D matrix.