Your first mapping

Go from an empty install to media playing on a surface in about ten minutes.

This walkthrough uses one projector and a flat surface, which is the shortest path through the parts of the interface you'll use every day. The same steps work with more projectors and real geometry, and each step links to the page with the details.

Before you start: Moonshine is running on the show computer, you're signed in, and the connection dot at the bottom left is green and reads Connected to and the show computer's name. If not, see Install and activate and First launch.

---

1. Create a project

If no project is open, the Projects window is already showing. Otherwise, click the project name in the top bar to open it.

1. Click New Project.
2. Project Name: type any name. The empty field shows My Show as a hint.
3. Initial Projectors: set this to 1 for this walkthrough. The default, 2, creates two blended projectors side by side (see Creating a project). You can add more later.
4. Resolution: choose your projector's native resolution: 1920 x 1080, 1920 x 1200, 3840 x 2160, or Custom, which shows width and height fields.
5. Click Create.

The window closes and the project opens on the Scene tab, with a flat screen, your projector aimed at it, and the moon test card on the screen. The top bar shows the project name and a projector called Projector 1.

Resolution is per projector

This sets the resolution of the projectors created with the project. Projectors you add later take the first projector's resolution, and you can change any projector's resolution afterwards (see Projectors).

2. Find the surface

A surface is the geometry a projector is aimed at. The new project already has one: a flat screen called Screen, the same size as the projector's picture.

1. Press G to open the scene graph along the bottom, or click the Scene Graph pill in the status bar.
2. Find the Screen node. Its Material node, called Main, is attached to it, with the moon test card wired into the material.

In a real show, you'll usually project onto a model of the set rather than a flat screen. See Surfaces and models when you're ready.

3. Aim the projector

Go to the Scene tab. This is a 3D view of the room, showing your surface and a projector whose frustum shows where its light falls. The new project has already aimed the projector at the screen. In a real room, this is where you place it to match the physical projector.

1. Make sure Object mode is on: click the leftmost button in the toolbar at the top of the view, or press V.
2. Select the projector from the projector selector in the top bar, or press 1. A transform gizmo appears on it.

3. Move and rotate it until the frustum covers your surface:

   Key	Gizmo
   M	Move: drag the arrows
   R	Rotate: drag the rings
   O	Switch between world and local axes

   Hold Shift while dragging for finer control.

   S does nothing useful on a projector

   It shows the scale handles, but a projector has no scale, so a scale drag is discarded when you let go. To make the image bigger, move the projector back or change its throw ratio.

4. While you work: F frames the selection (keep the pointer over the 3D view), P looks through the projector so you can see exactly what it covers, and Esc deselects the projector or leaves the projector view.

Camera controls in this view: left-drag orbits, right-drag pans, and scrolling zooms.

Get it roughly right here

In the Scene tab, you match the projector's real position and angle. Fine alignment onto the surface happens in the Warp tab, in step 6. If the aim is wrong, fix it here before you warp.

More on this: Projectors, and Outputs for sending a projector's image to a physical output.

4. Load media

Go to the Assets tab.

• Click Upload under the Asset Browser title on the left and choose your files, or
• drag files from your desktop and drop them anywhere on the tab.

The accepted formats are listed under the drop zone in the right-hand column: OBJ, GLTF, GLB, FBX, PNG, JPG, WEBP, MP4, MOV and WEBM, plus TOX for administrators. Upload one image or video for now.

Where the drop zone went

The right-hand column shows the drop zone (Drop files here, with or click to browse underneath) only while nothing is selected. When you click an asset, its details replace the drop zone. You can still drop files anywhere on the tab, and the Upload button always works.

Uploads run in the background, and you can add more files while they're in progress. Use New Folder and the folder tree in the sidebar to organize a show's media (see Uploading media and Organizing media).

5. Put the media on the surface

You put media on a surface in the scene graph. The quickest way:

1. Press G to open the scene graph if it's closed.
2. In the sidebar's folder tree, find the image or video you uploaded.
3. Drag it onto the surface's Material node in the graph. The node turns indigo while it's the drop target.

The media appears on the surface right away and starts playing. A wire now runs from the Material node to the media's node in the Assets column on the right of the graph. That wire shows that this media plays on this surface. Every file you upload has a node there, in its folder.

There are two other ways to do the same thing:

• Right-click the Material node → Set Asset, then choose from your uploaded media. A bullet marks the current one.
• Drag a wire from the media's node, in the Assets column, to the Material node.

To take the media off the surface, right-click → Unlink. The media's node stays where it is, unwired, for later.

Now go to the Scene tab and look at the screen. The display mode buttons in the toolbar at the top of the view change what you see:

Mode	Shows
Mesh	The model's geometry (its vertices, edges and a flat fill), so you can judge it without media
UV	The media mapped onto the surface by the surface's own coordinates
Lux	A heatmap of illuminance
Beams	What the projector throws onto the surface: the most accurate preview of the room

Switch to Beams to see what the audience will see. More on all four: View modes.

6. Align it

Go to the Warp tab. The toolbar at the top of the canvas shows what you're editing: Editing warp for Projector 1. The Warp tab always works on the projector selected in the top bar.

The mode switch in the sidebar offers 4-Corner and Bezier Mesh. Start with 4-Corner.

Action	Result
Click a corner	Select it. The sidebar names it and shows its X / Y offset
Drag a corner	Move it
Arrow keys	Nudge the selected corner
Tab	Select the next corner (Shift+Tab goes back). After the last corner, Tab moves to the next control
Esc	Deselect
Scroll, or the buttons at the top right	Zoom the editor
Middle-drag	Pan the editor

Arrow Key Sensitivity in the sidebar sets how far each arrow press moves a corner. Lower it for the final pass. Reset All Corners puts every corner back, after you confirm.

Drag each corner until the projected image sits on the real surface. If the surface is curved, or the projector is too far off-axis for four corners to fix, switch to Bezier Mesh. It gives you a grid of control points with curve handles, and Rows and Cols settings to add points where the surface needs them.

More detail: 4-corner keystone, Bezier mesh, and 3D surface warping for when the geometry itself needs adjusting rather than the image.

7. Play something

One image on a surface is a mapping. A show needs a sequence, which is what cuelists are for.

1. Go to the Cue tab. The sidebar has Cuelists at the top and the Asset Browser below. A project with no cuelists gets one called Default Cuelist. Click + beside the Cuelists heading to add more.
2. Click a cuelist to select it. The main pane lists its cues on the left (No cues yet when it's empty) and shows a 3D view of your surface on the right, so you can see what the cuelist puts on it.
3. Drag media from the Asset Browser into the list to add it to the cuelist. The list reads Drop to add while you drag. Drag a folder to add everything in it.
4. Wire the cuelist to the surface the same way you wired the single asset: drag the cuelist onto the surface's Material node in the scene graph, or right-click the Material node and choose Set Cuelist. The cuelist starts playing as soon as it's wired.
5. Use the transport: ▶ plays or pauses, ⏮ / ⏭ step between cues, and the loop button cycles through No loop → Loop all → Loop one. The current mode is shown beside the button.

The Timeline drawer along the bottom (T) also draws the cuelist to scale, showing where each cue starts and how long the whole cuelist runs. You don't need it for this walkthrough; see The timeline when you do.

A cuelist that is not wired will not play

If you press play on a cuelist that isn't wired to a surface, Moonshine doesn't play it and shows this message: "Default Cuelist" isn't linked to a material in the scene graph — it won't play back. Link it to a Material node first. Do step 4, then try again.

The transport is also in the floating Playback card, so you can run the show from any tab (see Tour of the interface). For more on sequencing, see Playback: transport controls, transitions and image adjustments.

8. Leave it in a good state

There's nothing to save. An amber dot appears in the top bar while changes are on their way to the show computer, and disappears once they arrive. No dot means everything is saved.

If you hover over the amber dot and it reads Warp edits not baked yet. On the Scene tab, choose the Warp tool (W) and press Bake Warp to keep them., you've sculpted a surface since its last bake. After a restart, the show machine would restore the older shape, so read Baking and reverting before you leave.

Where to go next

• Add the rest of your projectors and give each one an output: Projectors, Outputs.
• Replace the flat screen with your real geometry: Surfaces and models.
• Paint masks for spill and edges: Masking.
• Have a second person align at the same time: Working Together.
• Align from a phone in front of the surface: Join from another device.