You have the prop, you have the pixels, and now you need xLights to understand what you built. Start with the right model file. Then make the numbered path in that file agree with the actual lights.
Our advice: prove that match on the bench. A slow chase takes very little time, and it is much easier to fix a wiring mistake before the prop is mounted outside.
Get the model for the exact prop you bought
Match the product, size, node count and revision. A file for a similar-looking snowflake or character can have a completely different pixel path. Keep the original download so you have something to return to if you customize it.
For our props, start with the CoroWorks xLights model downloads. You can also find the model link on the individual product page. Unzip the download before importing the included .xmodel file.
For example, the CoroWorks Santa listing identifies its pixel count and printed path. Check those against the prop in front of you. With a left/right design such as the CoroWorks Nutcracker, check orientation too: the current download contains one supplied model with its staff on the viewer's right, not separate files for both orientations.
Import the file into your own layout
In Layout, use the import-model tool, draw a placement area and choose the local .xmodel. The download-model tool offers participating vendors' models through xLights itself. That list is useful, but it does not contain every prop sold. The official import guide covers both options.
Give the prop a name you will recognize at setup time, such as Santa Left. Save your layout. If this is an existing show, make a backup before replacing a working model.
The imported file defines the prop. You still have to connect that definition to your controller and output. Downloading a model does not assign a cable in your yard.
Make sure you are looking at the same side
Open Wiring View and check the viewing direction. xLights documents the default as a rear view; its context menu lets you select the front view. That matters when you turn a prop around to push pixels. See the model and wiring-view reference.
Find node 1, identify the input cable and trace a few obvious features before filling every hole. On a CoroWorks prop with a printed pixel path, compare the supplied file with that path. Do not decide that left and right match until you have checked which side you are viewing.
Take a front photo and a back photo with the input visible. Those two pictures are useful if you need help later, and they keep a simple orientation question from turning into an evening of guesswork.
Count the data path, not the bags of pixels
A node is an addressable lighting point. A model's physical string settings describe how the lights are divided among inputs; strands can describe sections where a string folds through the shape. The model settings and glossary explain the terms.
Two 50-node strings connected into one continuous 100-node data path can be configured as one 100-node string. Two separate 50-node inputs are a different arrangement. Both contain 100 pixels, but their controller assignments are different.
If you are filling the prop with EVO pixels, verify the selected spacing, connector and electrical requirements before building the chain. Packaging quantity alone does not tell xLights how you wired the prop.
Match the port and the order
Assign the model to the output you will actually use. When several props share a data chain, put them in the same order as the physical wiring. Adding power farther down the chain does not create another data output.
Use Controller Visualizer where supported, resolve its errors and upload the supported configuration changes. If a model takes more ports than you expected, check its string settings before moving cables.
Prove the wiring with a chase
Disconnect power before changing connections. Once everything is correctly connected, run modest-brightness red, green and blue tests, followed by a slow chase. Watch the first node, a few recognizable features and the final node. The xLights Test tool can target selected nodes.
A whole prop turning blue does not prove the numbered path is right. If the chase jumps to the wrong arm or face section, stop at that point and compare the file with the wiring.
Check file version, view direction and starting point first. If you intentionally built a different path, save a separate model and follow the custom-model instructions. Keep the original and repeat the test afterward.
Still stuck? Send us the product name, model filename, order information and front/back photos through Mattos support. Show us where the chase first goes wrong, and we have a much better place to start.
Keep learning
- xLights for Beginners: Set Up and Test Your First Pixel Prop
- xLights Controllers, Ports, Channels, and Universes Explained
- Move Your xLights Show to Falcon Player: A Setup Checklist
Browse all Mattos education and support guides.
Reviewed October 29, 2026.
