Step 2: Create Groups

This is the core innovation that makes shows portable between venues. If you understand nothing else about Luma, understand this section.

What Are Groups?

Groups are logical collections of fixtures organized by their role and position in the venue, NOT by their DMX address. When you create a group, you give it a descriptive snake_case name:

• front_wash -- the wash lights pointing at the audience from the front
• back_truss -- the moving heads on the rear truss
• floor_ring -- uplights arranged in a circle on the floor
• dj_booth -- lights illuminating the DJ

Groups are a venue-level concept. They exist inside a specific venue. The same physical lights in two different venues will have different group names but might serve the same role.

Group Naming

Group names are automatically normalized to snake_case: lowercase, spaces and hyphens become underscores, non-alphanumeric characters are stripped. Names must match [a-z][a-z0-9_]* and cannot be all (which is reserved to mean "every fixture").

Spatial Axes

Each group has three spatial axis values, which describe where the group sits in the room on a normalized scale:

These values are auto-calculated from the average positions of the fixtures in the group, but you can manually adjust them. They are used by patterns that want to treat groups differently based on their spatial role.

Why Groups Are the Magic

When you build a pattern (Step 4), you do not say "animate fixtures 1 through 8." You say "animate floor_ring" or "animate front_wash & back_truss."

Now your pattern works on ANY venue:

• Small club with 8 par cans in a ring? Put them in a group called floor_ring and patterns that reference floor_ring pick them up.
• Stadium with 200 moving heads on a circular truss? Same pattern, same group name. It animates all 200 lights in their circular arrangement, with zero changes to your pattern.
• Dive bar with 4 random LED pars on the ceiling? No floor_ring group exists, so the pattern gracefully finds the best available alternative via the fallback operator.

This is the sheet-music analogy in action. Your pattern says "play a C major chord" and the venue provides whatever instruments it has.

Selection Expressions

Selection expressions let you write boolean logic over group names to precisely target fixtures. They support the following operators:

Parentheses work for grouping: (left_truss | right_truss) & front_wash means "left or right truss fixtures, but only if they are also in the front wash group."

The > (fallback) operator is unique to Luma. It evaluates the left side first, and only includes the right side's results if the left side matched zero fixtures. This enables graceful degradation across venues with different fixture inventories.

The all token is the default if you leave the expression empty. It matches every fixture in the venue.

Designing Groups for Portability

The key to portability is using consistent, descriptive group names across your venues. If every venue has a front_wash group (even if the actual fixtures are completely different), then patterns referencing front_wash will work everywhere.

Think about naming groups by their role (what they do) and position (where they are):

When you move a show between venues, an LLM can automatically remap group names (e.g., front_wash in venue A maps to house_pars in venue B) based on the fixture positions and roles.

Next Steps

With groups defined, you are ready to import tracks and start building your show.