PassthroughKey – User Manual
What PassthroughKey does
PassthroughKey puts your VaM characters into your real room, using Virtual Desktop's passthrough on a Quest 3 headset.
Virtual Desktop shows your room wherever the picture has one exact background colour (the "key"). PassthroughKey takes care of that for you:
- Clean background. The background is always the exact colour Virtual Desktop removes, even with lighting, bloom or other effects in the scene.
- No holes in the character. Dark hair, shadows and clothes stay solid, even with a black key.
- Solid VaM menu. The menu and its text stay visible instead of being cut out.
- Room hidden automatically. Floors, walls and props are hidden, people stay. Works in normal scenes.
- Light matching. Look at your real lights and the scene lighting matches your room.
- Profiles. Save your setup and load it again, or have it load when VaM starts.
You need: VaM, a Quest 3 headset (other HMD's not tested), and Virtual Desktop.
Quest Link and Air Link are not supported. They have no chroma-key passthrough.
Installing and first start
- Download the plugin.
- Go to Session Plugins and add PassthroughKey. A session plugin stays loaded when you change scenes.
- Optional, recommended: in Session Plugin Presets, choose Change User Defaults, so PassthroughKey loads every time VaM starts.
- Open the plugin's window. The status box on the main page should say active | shader OK.
Your settings are not saved with scenes. Save them in a profile (see Profiles & advanced) so they come back next time.
Setting up Virtual Desktop
In the headset, open the Virtual Desktop menu and go to
Settings > Streaming > VR Passthrough. Turn passthrough on and set:
| Setting | Value |
|---|
| Key colour (R G B) | The three numbers shown in the plugin's Virtual Desktop box |
| Similarity | The same value as the plugin's VD Similarity % (default 5) |
| Smoothness | 0 |
| Sharpening | 0 |
| Snapdragon Game Super Resolution | Off |
Important: type the numbers from the plugin's Virtual Desktop box, not the colour values from the colour picker. Virtual Desktop sees colours slightly differently, and the plugin already works out the numbers it needs. For black, white and pure colours both are the same.
Main page
The main page shows how everything is running, the numbers for Virtual Desktop, and the way into each settings page.
Status box (left).
- PassthroughKey v1.0: the version you have.
- active / off and shader OK: whether the plugin is working ("off (desktop mode)" means it is paused because VaM is not in VR). If it says "bundle not found" or "shader missing", see Troubleshooting.
- Key: the key colour preset in use.
- Environment: how many scene objects are hidden.
- Post effects: how many effects (bloom, grain and so on) are paused.
- Lights: whether light matching is set up and applied.
Virtual Desktop box (right). The R G B and Similarity to type into Virtual Desktop, plus the other VD settings to use. The grey "Plugin key" line shows the colour the plugin itself uses, for reference only.
Category buttons. Each opens a full settings page: Key & Virtual Desktop, Scene handling, Light matching & floor, Profiles & advanced. Every page has a
Back button at the top right.
Key pass active. Turns the plugin on or off. Off puts the scene back exactly as it was.
Disabled in desktop mode. On by default. The plugin only works while VaM is in VR; on the monitor you see the normal scene. It switches by itself when you go between VR and desktop mode, as long as Key pass active is ticked.
Quick start. A short checklist of the setup steps.
Reset all settings to default. Click once, then click again within 3 seconds to confirm. All settings go back to default; captured light positions are kept.
Key & Virtual Desktop
This page sets the background colour that Virtual Desktop removes, and how safely the character is protected from being cut.
Key colour (left).
- Key preset: Black (default and recommended), Dark grey, Mid grey, Blue, Green, Magenta, or Custom.
- Colour picker: pick any colour. Changing it switches the preset to Custom. When you type a number, press Enter or just wait 2 seconds and it is applied.
- Pick a colour that isn't in your character's hair or clothes. Black works well for most scenes, because the plugin protects dark areas.
Virtual Desktop keyer (right).
- Virtual Desktop box: the R G B and Similarity to enter in Virtual Desktop. It updates as you change the colour.
- VD Similarity %: how much Virtual Desktop cuts around the key colour. Set the same value here and in Virtual Desktop. 5 is a good start.
- VD colour curve: how Virtual Desktop reads colours. It was measured at 0.89; leave it there.
- Extra safety margin: how far the character's colours are kept from the key colour. The default is 0.1. Lower keeps dark colours truer but can let holes appear in dark areas and in the VaM menu. Raise it if you see holes.
Scene handling
This page decides what of the VaM scene stays visible, and what happens to visual effects.
Environment (left).
- Hide environment (keep people): while the plugin is on, everything that isn't a person is hidden: rooms, floors, furniture, props. Items a person holds or wears stay. New items are picked up every 2 seconds. Turning the plugin off shows everything again.
- Hide skybox: hides the scene's sky so it can't cover your room.
Post effects (right). Effects like bloom, grain or colour grading (for example PostMagic) change the background colour, which stops Virtual Desktop from removing it.
- Suspend (exact key): pauses those effects while the plugin is on. Recommended.
- Keep, snap background: keeps the effects and pulls the background back to the key colour.
- Snap tolerance (Keep mode): how far off the background may drift and still be pulled back. Raise it if the background flickers; lower it if dark edges of the character disappear.
Light matching & floor
This page lights the character like your real room, so it looks like it belongs there. The lights stay fixed to your real room, even when you move around in VaM.
Top.
- Status box: whether your lights are captured and applied, and what just happened.
- PT lights replace scene lights: turns off the scene's lights while yours are in use, so only your room's lighting shows.
- Remove PT lights, restore scene lights: removes the plugin's lights and turns the scene's lights back on.
Main light (left).
- Capture MAIN light: a 5-second countdown appears in front of you with a white + in the middle. Point the + at your brightest real light (a window or a lamp) and hold still. "Captured" shows in green when done, and the light is created straight away.
- Main light preset: Window – sunny, Window – overcast, Ceiling light, Warm lamp, Cool LED, TV/monitor, Candle. Picking one sets the three sliders below.
- Brightness: how strong the light is.
- Colour (K): the light's colour. Lower numbers are warm and orange (candle, lamp), higher numbers are cool and blue (daylight, LED). The step buttons move it by 1, 10, 100 or 1000.
- Shadows: how strong the shadows are. 0 turns them off.
Second light (right). Optional, for a second light source. Tick the box in its header to use it, then capture it and set it like the main light. Its shadows start off, to save performance.
Room.
- Room fill brightness: soft overall light, so the shaded side isn't too dark.
- Apply / update lights: creates or updates the lights in the scene. Use it after changing presets or captures.
Floor match. Use it when the character floats above or sinks into your real floor.
- Keep real floor at scene floor: keeps your real floor level with the scene's floor.
- Scene floor height (m): fine-tunes where the scene's floor sits.
Profiles & advanced
This page saves and loads your settings, and holds a few advanced options most people never need.
Profiles (left). VaM doesn't save session plugin settings with scenes, so save them here.
- Status box: whether the chosen profile has anything saved, and the result of your last save or load (shown in bold for 2 seconds).
- Profile: choose one of 4 slots. A profile holds everything, including your captured lights, so you can keep one per room.
- Save settings to this profile and Load this profile: what they say.
- Load this profile when VaM starts: loads the chosen profile automatically each time.
Profiles are stored in
VaM/Saves/PluginData/PassthroughKey.
Pass tuning (right). The defaults are right for almost everyone.
- Clear to black (cleaner edges): gives cleaner character edges. Leave on.
- Use depth: tells the character apart from the background. Off removes everything; only for testing.
- Edge erode (px): trims the outline of the character by a few pixels.
- Despill: removes colour fringes on the edges. Only matters with pure blue or green keys.
- Keep key pass last on camera: keeps the plugin working after other plugins add camera effects.
Diagnostics. For checking problems or reporting bugs.
- Debug view (white = kept): shows what is kept (white) and what is removed (black).
- Test pattern (colour chart): shows a colour chart floating in front of you, to check which colours Virtual Desktop cuts out. Turn it off when done.
- Report UI layers to log and Log cameras: write technical details to VaM's log, useful in a bug report.
Troubleshooting and tips
| Problem | What to do |
|---|
| The background doesn't disappear | Check the R G B in Virtual Desktop matches the plugin's Virtual Desktop box (not the colour picker). Similarly - the same in both. Smoothness 0. Status should say active and shader OK. |
| Status says "bundle not found" or "shader missing" | Reinstall the package and restart VaM. |
| Holes in the character or in the VaM menu | Raise Extra safety margin in steps of 0.05, or lower Similarity in both places. |
| Dark colours look washed out | Lower Extra safety margin a little and check nothing gets holes. |
| Part of the scene is still visible | It may count as attached to a person. Turn Hide environment off and on again. |
| The background flickers with effects on | Set Post effects to Suspend. |
| Settings gone after a restart | Save a profile and tick Load this profile when VaM starts. |
| The character floats or sinks | Turn on Floor match and adjust Scene floor height. |
Credits
PassthroughKey v1.0 by CraSh.it.
Thanks to Sally Whitemane, whose Camera Background Color plugin inspired the creation of PassthroughKey.
