You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs
====
- layers: rework clearly explaining layers
backend
=======
network in:
- writePixels: Virtual layer — guard against out-of-range index and uninitialised slot
- handleDDP: Reject if the packet's pixel stride doesn't match the configured channel layout.
network out
- controls, min is 1 instead of 0
- onUpdate: Clamp controls to safe values
- loopDDP: DDP only defines RGB24 (3 ch) and RGBW32 (4 ch).
Copy file name to clipboardExpand all lines: docs/moonlight/drivers.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -112,7 +112,7 @@ Sends pixel data over the network to LED controllers and DMX fixtures. Supports
112
112
***Port**: Network port. Updated automatically when switching protocol; can be overridden manually.
113
113
***FPS Limiter**: Maximum frames per second sent. Art-Net spec recommends ~44 FPS; higher rates (up to ~130 FPS tested) work with most controllers.
114
114
***Universe size**: Channels per universe (max 512). Match the setting on your controller.
115
-
***Used channels***(read-only)*: Channels actually used per universe after rounding to whole lights (e.g. 510 for RGB at 512-channel universes).
115
+
***Used channels***(read-only)*: Channels actually used per universe after rounding down to a whole number of lights (e.g. 510 for RGB at 512-channel universes). Always at least one light's worth of channels — if **Universe size** is set smaller than the channels per light, one full light is still included per universe.
116
116
***#Outputs per IP**: Number of physical outputs per controller. When all outputs for one IP are filled, sending continues on the next IP.
117
117
***Universes per output**: How many universes each output handles, determining the maximum lights per output.
118
118
***Total universes***(read-only)*: Universes required to transmit all lights.
Copy file name to clipboardExpand all lines: docs/moonlight/layouts.md
+44-9Lines changed: 44 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,49 @@
1
1
# Layouts
2
2
3
-
A layout (🚥) defines the positions of lights connected to a MoonLight device.
4
-
5
-
* The **coordinates** of each light are defined in a 3D coordinate space
6
-
* Coordinates needs to be specified in the order the lights are wired so MoonLight knows which light is first, which is second etc.
7
-
* For lights in a straight line (1D, e.g. LED strips or a LED bar), specify coordinates as [x,0,0]
8
-
* For lights in a flat area (2D, e.g. LED matrix), specify coordinates as [x,y,0]
9
-
***Multiple layout nodes** can be defined which will be mapped in the order of the layouts
10
-
* MoonLight will use the layout definition to generate a **mapping** of the effects to a real world light layout. Most simple example is a panel which has a snake layout. The mapping will create a layer for effects where the snake layout is hidden.
11
-
* Layouts also assign groups of LEDs to esp32 GPIO pins.
3
+
A layout (🚥) tells MoonLight **where your lights physically are** and **how they are wired**. Get this right and every effect — from a simple rainbow to a 3D plasma — automatically fits your fixture perfectly.
4
+
5
+
## How layouts work
6
+
7
+
### The coordinate grid
8
+
9
+
When you define a layout, each light gets a position in a 3D coordinate space (X, Y, Z). MoonLight takes all those positions and figures out the bounding box — the smallest grid that contains every light. Effects are then computed across that whole grid and automatically mapped to your physical lights.
10
+
11
+
This means:
12
+
13
+
-**Effects are fixture-aware.** A plasma effect on a 16×16 panel looks like a full-screen plasma. The same effect on a 3D cube wraps correctly around all three axes. You don't write a different effect for each shape.
14
+
-**Wiring order doesn't matter to effects.** Your LED strip might snake left-to-right on odd rows and right-to-left on even rows (serpentine wiring). The layout describes that wiring pattern; effects just see a clean grid.
15
+
-**Resolution scales automatically.** A 10×10 panel and a 32×32 panel both run the same effects — the effect adapts to however many lights you have.
16
+
17
+
### 1D, 2D and 3D fixtures
18
+
19
+
| Fixture type | Typical examples | Grid shape |
20
+
|---|---|---|
21
+
|**1D** — a line | LED strip, LED bar, single tube | Y axis only — X and Z are 0. The Y axis runs vertically so 1D effects like bouncing balls, drip and rain move in the natural downward direction |
22
+
|**2D** — a flat surface | LED matrix, panel, ring, wheel | X and Y axes — Z is 0 |
23
+
|**3D** — a volume | Cube, Christmas tree, spiral tower, Human Sized Cube | X, Y and Z axes all used |
24
+
25
+
MoonLight automatically detects the dimensionality from the coordinates you define, so 1D effects run on strips and 3D effects light up cubes without any extra configuration.
26
+
27
+
### How effects fill the grid
28
+
29
+
The effect runs across every point in the bounding grid, but your fixture only has lights at specific positions inside it. MoonLight builds a **mapping** that links each grid point to the nearest physical light — so even a 500-LED Christmas tree mounted inside a 25×25×100 bounding box gets a smooth, full-volume effect. Sparse fixtures (few lights in a large space) work fine as long as the pixel density is reasonable. Very sparse grids — for example, a handful of moving heads spread across a large stage — are a future use case.
30
+
31
+
### Multiple layout nodes
32
+
33
+
You can add more than one layout node — for example three separate panels or a ring combined with a bar. MoonLight merges all their positions into a single shared grid and maps effects across all of them together. Lights are assigned to the grid in the order the layouts appear in the node list.
34
+
35
+
### GPIO pin assignment
36
+
37
+
Layouts also assign groups of LEDs to the ESP32 GPIO pins that drive them. Each layout node controls which pin(s) its lights are connected to. Complex fixtures like a cube or a multi-panel wall often use one pin per face or one pin per panel so each segment can be driven in parallel, improving performance.
38
+
39
+
!!! tip "Start simple"
40
+
Not sure which layout to use? Start with **Single Row** for a strip, **Panel** for a matrix, or **Rings** for circular fixtures. These cover the most common setups and are easy to combine into larger builds.
41
+
42
+
!!! tip "Custom shapes"
43
+
Any shape that isn't covered by the built-in layouts can be created as a **Live Script** — a small `.sc` file with an `onLayout()` function that places lights exactly where you need them. See [Live Scripts](livescripts.md).
44
+
45
+
!!! note "Future: room-scale mapping"
46
+
It is possible in principle to treat an entire room or stage as the coordinate space and map all fixtures — panels, moving heads, tubes — into that shared grid. This would let effects flow seamlessly from one fixture to another across physical space. MoonLight's architecture supports it, but algorithms optimised for very sparse, large-scale grids are not yet implemented.
0 commit comments