Skip to content

Your first mapping

Go from an empty install to a projector landing media on a surface, in about ten minutes.

This walkthrough uses one projector and a flat rectangular surface, because that is the shortest path through every part of the interface you will use daily. Everything here scales to more projectors and to real geometry; the deep pages linked at each step cover that.

Before you start: Moonshine is running on the show computer, you are signed in, and the connection dot at the bottom-left reads WS: Connected. See Install and activate and First launch if not.

1. Create a project

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

  1. Click New Project.
  2. Project Name — anything; the field starts empty with My Show as a hint.
  3. Initial Projectors — leave it at 1 for this walkthrough. You can add more later.
  4. Resolution — pick the native resolution of your projector: 1920 x 1080, 1920 x 1200, 3840 x 2160, or Custom for anything else (choosing Custom reveals width and height fields).
  5. Click Create.

The window closes and you land in the project. In the top bar you now have a 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 inherit the resolution of the first one, and any projector's resolution can be changed afterwards — see Projectors.

2. Add a surface

A surface is the geometry the projector is aimed at. A real show usually loads a model of the set; for now, a built-in plane stands in for a flat screen.

  1. Press G to open the scene graph panel along the bottom (or click the Scene Graph pill in the status bar).
  2. Right-click empty space in the panel.
  3. Choose Add Mesh → Plane.

A mesh node appears in the graph, with Material and Texture nodes hanging off it. Switch to the Scene tab and you will see the plane in the 3D view.

Add Mesh also offers Box and Empty. To use your own model instead, upload it in step 4 and drag it from the Asset Browser into the scene graph — it becomes a surface of its own. See Surfaces and models.

3. Aim the projector

Go to the Scene tab. This is the 3D view of the room: your surface, and a projector with a visible frustum showing where its light falls.

  1. Make sure Object mode is active — the leftmost button in the mode strip at the top-left of the view, or press V.
  2. Select the projector from the projector selector in the top bar (or press 1). A transform gizmo attaches to it.

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

    Key Gizmo
    T Translate — drag the arrows to move it
    R Rotate — drag the rings to turn it
    S Scale
    L Switch between world and local axes

    Hold Shift while dragging for fine control.

  4. Useful while you work: F frames the selection (keep the pointer over the 3D view — that is what tells Moonshine you mean the viewport and not the scene graph), P looks through the projector so you can see exactly what it covers, and Esc detaches the gizmo (or leaves the projector view).

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

Get it roughly right here

Physical placement in the Scene tab is about the projector's real position and angle. Fine alignment onto the surface happens in the Warp tab in step 6 — do not try to fix an aim problem with warping.

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

4. Load media

Switch to the Assets tab.

  • Click Upload in the header and pick your files, or
  • drop files onto the drop zone in the lower half of the sidebar — it reads Drop files here with or click to browse underneath.

Accepted formats are listed under the drop zone: OBJ, GLTF, GLB, FBX, PNG, JPG, WEBP, MP4, MOV, WEBM. Upload one image or video for now.

Where the drop zone went

That lower half of the sidebar shows the drop zone only while nothing is selected. Click an asset and it is replaced by that asset's details. Press Esc to deselect and the drop zone comes back — or just use the Upload button, which always works.

Uploads run in the background and you can drop more while they are in flight. The New Folder button and the folder tree in the sidebar keep a real show's media organized — see Uploading media and Organizing media.

5. Put the media on the surface

Media reaches a surface through the scene graph. The quickest route:

  1. Press G to open the scene graph if it is closed.
  2. In the sidebar's folder tree, find the image or video you just uploaded.
  3. Drag it onto the surface's Texture node in the graph. The node highlights as a valid drop target.

The texture is set immediately, and a node for the media appears beside the Texture node, wired to it — that wire is what "this media plays on this surface" looks like.

Two other ways to do the same thing:

  • Right-click the Texture node → Set Asset, then pick from the list of uploaded media. A bullet marks the current one.
  • Drag the media into empty graph space to drop a loose node, then drag a wire from it to the Texture node.

Right-click → Clear Texture takes it off again.

Now switch to the Scene tab and look at the plane. The display mode buttons at the top-left of the view control what you are looking at:

Mode Shows
UV The media mapped straight onto the surface by its own coordinates
Projection What the projector actually throws onto the surface — the honest preview
Lux An illuminance heatmap
Solid Flat color, for judging geometry without media

Switch to Projection to see the result the room will see. More on all four: View modes.

6. Align it

Switch to the Warp tab. The bar across the top confirms what you are editing — Editing warp for Projector 1 with its resolution beside the name. This is why the projector selector in the top bar matters: the Warp tab always works on the selected projector.

In the sidebar, the mode switch 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 Move to the next corner (Shift+Tab goes back)
Esc Deselect
Scroll Zoom the editor
Middle-drag Pan the editor

Arrow Key Sensitivity in the sidebar controls how far one arrow press moves a corner — turn it down for the final pass. Reset All Corners puts everything back, after a confirmation.

Pull each corner until the projected image sits on the real surface. If the surface is curved or the projector is off-axis enough that four corners cannot do it, switch to Bezier Mesh: you get a grid of control points with curve handles, and Rows / Cols to add more of them where the surface needs it.

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

7. Play something

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

  1. Switch to the Playback tab. The sidebar has the Asset Browser on top and Playlists underneath. A project with no playlists gets one called Default Playlist automatically; the + beside the Playlists heading makes more.
  2. Click a playlist to make it the current one. The main pane lists its items — No items in playlist when it is empty.
  3. Drag media from the Asset Browser into the main pane to add it to that playlist. The drop area confirms with Drop to add, and dragging a whole folder adds everything in it.
  4. Wire the playlist to the surface the same way you wired the single asset: drag the playlist onto the mesh's Texture node in the scene graph, or right-click the Texture node and choose Set Playlist.
  5. Use the transport — ▶ to play, ⏮ / ⏭ to step between items, and the loop button to cycle No loop → Loop all → Loop one. The current mode is named beside the button.

A playlist that is not wired will not play

If you press play on a playlist that no surface is using, Moonshine refuses and tells you why: "Default Playlist" isn't connected to a texture in the node graph — it won't play back. Wire it to a Texture node first. Do step 4 and try again.

The transport also lives in the floating Playback card, so you can run the show from any tab — see Tour of the interface. Everything else about sequencing is in Playback: transport controls, transitions and image adjustments.

8. Leave it in a good state

There is nothing to save. Watch the dot in the top bar instead: amber while changes are travelling, green once the show computer has them. Hover it for Saved just now and friends.

If the dot is amber with Warp edits not baked — click Bake Warp to commit, your warp work is still provisional — read Baking and reverting before you walk away.

Where to go next