Insert Lighting¶

The definitive guide to insert implementation in VPX, consolidating techniques scattered across 30+ table builds. Covers construction, lighting systems, text handling, color management, and the evolution from Skitso-style flashers through Flupper 3D inserts to modern VLM toolkit inserts.

Quick Start

Building a toolkit table (VPX 10.8+)? Skip the history and start here:

Each insert needs two lights in Blender (bottom glow + top spread) but only one light in VPX -- see Blender Two-Light Method
Set the insert collection's lightmapper property to "Split" for individually addressable inserts
Bake inserts into shallow cups/trays, not flat surfaces -- flat inserts look wrong in VR
Position the layer separator between the playfield and UnderPF inserts, not below them
Insert bloom lights should be 1/3 the size that feels natural on first placement
Never use pure black (#000000) on playfields -- use #111111 minimum or insert lightmaps get pruned
Test raw insert output by blacking out environment/GI with the UpdateMaterial snippet

Working with a pre-toolkit table? See Flupper 3D Insert System for the three-layer ON/OFF/BULB approach.

Insert Types and Construction¶

Standard Shapes¶

Real pinball inserts are manufactured plastic pieces pressed into holes drilled through the playfield. They come in standard catalog shapes -- round, triangle, rectangular, star, diamond, and bullet shapes. Williams tables from similar eras share insert types: Bad Cats (1989) and Whirlwind (1990) share many insert designs, so Flupper's insert meshes from Whirlwind can be directly reused with some copy-paste-tweak workflow.

Many inserts are standard catalog parts (e.g., "bullet inserts" from Pinball Life). When building a new table, check if existing VPW tables already have the same insert shapes modeled before creating new ones (learned from Austin Powers).

Multi-Color Inserts¶

Some inserts display multiple colors depending on which lamp is active. Judge Dredd documented the most complex case: crime scene inserts that show green, yellow, red, or white require 9 stacked primitives per insert -- 4 ON states (one per color), 4 BULB primitives, and 1 OFF state. The insert primitives are semi-transparent, bulbs are sunk deep underneath (good for VR depth), and ON primitives are somewhat transparent so bulb light shines through.

Clear Inserts with Visible Bulbs¶

Some older machines (like Skateball, Bally 1980) have transparent amber inserts where the bulb is directly visible through the insert. Reference photos from real machines confirm the bulb filament is clearly visible in these designs.

The Three Eras of VPW Insert Technique¶

Skitso-Style Flasher Inserts (Pre-10.8)¶

The earliest VPW technique creates a see-through effect using VPX flasher objects shaped to match the insert hole. The flasher sits at the insert position and is driven by the lamp state, creating an illuminated insert that appears to glow from beneath the playfield. First documented on Black Rose and refined on Tales from the Crypt.

Requirement: Skitso-style inserts require playfield reflections to be enabled in VPX settings, or they will not display correctly. This is a VPX limitation noted by o0skitso0o on T2.

Flupper 3D Insert System (Pre-Toolkit)¶

The three-layer insert system, invented by flupper1 and documented during the Tales from the Crypt build, became the standard VPW insert technique and was used across dozens of tables:

OFF layer: Depth bias 1000, DisableLighting=1, Z=0, ZSize=6. Visible when insert is off. Responds to GI via DisableLighting=0 when GI is active.
ON layer: Depth bias 1100, DisableLighting=0, Z=0, ZSize=6. Text/graphic visible when lit, controlled via BlendDisableLighting from script.
BULB layer: Depth bias 1200, DisableLighting=1, DisableLightingFromBelow=1, Z=-3, ZSize=30. VPX light for ball reflection only.

The VPX light on the BULB layer is purely for ball reflection; the ON layer's BlendDisableLighting controls visible illumination. Depth bias stacking ensures correct render order.

Each insert requires 5 elements total: ON primitive, OFF primitive, insert lens primitive, VPX light (for ball illumination/shadow), and a flasher (for bloom/glow). The ON/OFF system uses two pre-baked primitives swapped via opacity (detailed on Indiana Jones).

VLM Toolkit Inserts (10.8+)¶

The toolkit approach bakes insert lighting into lightmaps driven by VPX light objects. Each insert in Blender requires two lights but only one light in VPX (from Haunted House and Godzilla).

A newer two-layer technique on Space Station creates more depth: (1) Bottom layer (underPF collection) is opaque with insert color/pattern baked in, (2) Top layer (layer0 collection) is non-opaque glass-like surface that captures reflections and creates depth. The top layer uses depth bias -1000 and a layer separator linked behind it.

Blender Two-Light Method¶

Insert lighting in the Blender toolkit uses two lights per insert (documented on Godzilla by tomate80):

Bottom light: Circular or rectangular plane light inside the insert cavity -- provides the main glow from below the playfield surface
Top light (spread light): Spherical light above the insert -- creates the spread/bloom effect on the playfield surface around the insert

Without the top spread light, inserts look too dark and lack playfield diffusion. Niwak noted that the deep insert light alone has too narrow a shadow cone to create realistic surface spread.

The top light only needs to look correct from the bake camera POV (not from all angles). Adjust color temperature and edge sharpness per insert. The toolkit generates lightmaps controlled by a single VPX light, so no duplicate lights are needed in VPX -- the Blender lights are invisible in the final table.

Insert Light Positioning¶

Toolkit inserts contain an invisible mesh component (only visible in X-ray/mesh view) that disperses light from the point source below (from Johnny Mnemonic). The main light sits below this invisible mesh, and a secondary light below the upper visible mesh. Placing the light too far into the insert (above the invisible mesh) creates a harsh point-light hotspot instead of a diffused glow.

Insert Brightness in Toolkit Tables¶

Toolkit-baked insert lightmaps can appear too dim in VPX despite looking correct in Blender renders (from No Fear). Baking with a high environment light level causes the ambient light to overwhelm smaller insert light contributions. Fix: double the upper light strength in Blender for inserts, or apply a standard "50% more" insert light intensity as compensation.

To test raw insert output, add to Table1_Init:

UpdateMaterial "VLM.Bake.Active", 0, 0, 0, 0, 0, 0, 1, RGB(0,0,0), RGB(0,0,0), RGB(0,0,0), False, True, 0, 0, 0, 0
UpdateMaterial "VLM.Bake.Solid", 0, 0, 0, 0, 0, 0, 1, RGB(0,0,0), RGB(0,0,0), RGB(0,0,0), False, False, 0, 0, 0, 0

This blacks out environment and GI to reveal raw insert output.

Insert Cups and Trays¶

Tray Geometry for Depth¶

Inserts should be baked into shallow "cups" (tray shapes) rather than flat surfaces (from Haunted House). Without cups, inserts appear very deep/flat, especially noticeable in VR. Copy insert setup from existing toolkit tables (Special Force, Rollercoaster Tycoon) as starting templates.

The Flupper insert tray system uses a double-tray approach for on/off meshes (from Spider-Man). The tray Z position should be 0 (origin at top of tray). Insert opacity in the 0.995-0.999 range makes a dramatic visual difference in tray visibility -- tiny adjustments matter enormously.

Tray Material Tuning¶

Insert material tuning for the 3-prim system (from iaakki on Batman DE):

Start with VPX light intensity at 0
Adjust the three material opacities and colors first
Off-prim: set quite dark, opacity 0.8-0.95
Bulb-prim: opacity high, color tuned for hot spot appearance
On-prim: script intensity and opacity balance how visible the insert spokes are when lit
After prim materials look good, add VPX light at height -3, transmit 0, falloff ~3, intensity ~5 -- just for ball reflection
Use Alt+arrows to rotate the table view during tuning, as appearance changes significantly with viewing angle

Each insert color needs its own material; different-shaped inserts may need cloned materials with different settings.

Insert Text and Flashers¶

Dedicated Flasher per Text Label¶

Insert text labels should be maintained as a separate image layer from the playfield base, allowing independent positioning and resolution (from Bride of Pinbot). Higher resolution text images significantly improve sharpness.

The duplicated flasher approach (from Earthshaker): use one flasher for the insert glow, a second flasher layered on top for the text. The text flasher uses a separate image with text on a transparent background.

For insert text with overlapping insert graphics, the text must be set to "Image mode: World" not "Wrap" to avoid offset issues (from Hook). Two overlapping insert text flashers may be needed to prevent light bleed-through, but they must be positioned exactly on top of each other.

Insert Text Gray Edge Artifacts¶

Insert text overlays need per-insert shadows to look realistic (from Ripley's Believe It or Not). The shadow should NOT be based on a global light source -- instead each insert's shadow should be parallel to the text baseline of that specific insert. This creates an ambient-occlusion effect making the text look embedded.

Insert text overlays need 5px transparent borders on all edges of the image to prevent hard aliasing when the image meets the primitive edge (from Transporter). Additionally, the insert image should overlap the playfield hole by 2px on each side -- this prevents a visible gap between the insert and the playfield surface.

Render fill and stroke to the same image before applying the shadow to avoid anti-aliasing holes in opacity (from Ripley's Believe It or Not).

Insert Text Recreation vs Preservation¶

Two approaches debated across builds (from Earthshaker):

Cut around existing text with lasso tool, preserving scan fidelity
Recreate text from scratch using matched fonts (e.g., "Arial Black" with -50 tracking for Earthshaker)

Benji084 considers recreated text ideal because scan text edges are never sharp enough. Tomate80 prefers keeping scan imperfections for realism. Consensus: recreated text is acceptable if matched to the original.

Bloom Inserts via VPX Control Lights¶

Insert "bloom" lights (the halo effect around illuminated inserts) should be approximately 1/3 the size that feels natural when first placing them (from sixtoe on Dr. Who). Oversized blooms create a blown-out appearance, especially visible on cabinet/VR setups.

The dual-light setup for insert bloom (from Goldeneye):

Under-playfield light (white): Provides the core illumination through the insert
Over-playfield light (colored): Creates the bloom/halo effect on the playfield surface

Key technique: use a very dark full-on color (lots of black in the color value) for the over-playfield bloom light. This prevents the bloom from looking "cloudy" or washed out.

Naming convention for efficient bulk creation: name lights LL001, LLb001 -- VPX auto-increments on copy-paste (LL002, LLb002), saving hours of manual renaming across 50+ inserts.

VPX light objects with falloff power set to 1 will not emit visible light onto nearby objects including the ball. Use falloff power of 3-4 for insert lights (from Spider-Man).

DisableLighting and BlendDisableLighting for Inserts¶

Core Concepts¶

The DisableLighting (DL) parameter on VPX primitives controls how much the object ignores dynamic lighting -- effectively a brightness override. DL=0 means fully lit by scene lights (darkest), DL=1 means ignore lighting entirely (fullbright). Values above 1.0 can be set via script for even brighter objects (from Diner).

BlendDisableLighting (BDL) controls self-illumination on additive/transparent primitives. Higher values make the primitive glow independent of table lighting (from Blood Machines). In the VPX editor, both are clamped 0-1, but in script, BDL can be set above 1.0 for enhanced overbright glow effects (from Simpsons Pinball Party).

Never set blenddisablelighting to negative values -- it causes colors to break with inverted or washed-out rendering (from Metallica).

FadeDisableLighting Technique¶

The FadeDisableLighting sub adjusts a primitive's UserValue (0-1 range) on fade-in/fade-out, then applies it: a.BlendDisableLighting = alvl * a.UserValue (from Monster Bash). Fade-down decrements by 0.25 per step, fade-up by 0.5 -- asymmetric to match incandescent physics (fast on, slow off).

For the complete Hook/Metallica flasher-insert fading pattern:

FlashLevel = FlashLevel * 0.93 - 0.01
flashx3 = FlashLevel * FlashLevel * FlashLevel
Flasher.opacity = 110 * flashx3
Light.IntensityScale = 3 * flashx3

The cubic function creates a fast initial decay that slows near zero, matching incandescent cooling (from Congo).

Frosted Insert Effect¶

For a frosted insert look where internals are not visible (from iaakki on Ghostbusters): use a frosted texture over the insert, keep flasher opacity at 99%. Put something behind the frosted surface (like the original "on" image at approximately 10% visibility or a round smooth 4 bulb scaled up) to get subtle texture showing through. Make edges slightly darker than center. The "frosted" look comes from a discernible shape behind the frosting with slightly uneven glow.

Triangle Insert Hotspot Fix¶

Triangle inserts are difficult to light evenly -- they get too bright at center (from iaakki on Ghostbusters). Solution: use a DisableLighting setup combined with a mix of DL at bulb height -0.5. This gives visible tray plus haze and ball reflections without the center hotspot. Some inserts of the same color may need completely different material settings to prevent GI bleed-through.

Insert Color Management¶

Avoid Pure RGB Values¶

For insert-on textures, never use pure RGB values (e.g., 255,0,0 for red). Use slightly offset values like RGB(255,32,0) so that when DisableLighting increases, the texture gains warm orange highlights instead of staying flat (from flupper1 on Tales from the Crypt). Similarly, lamp colors should include small amounts of other channels (e.g., FF0505 instead of FF0000).

Red intensity should be lower than other colors because red bleeds through more; blue needs higher intensity.

Red inserts are much harder to get visible hotspots on compared to blue or white (from niwak on Space Station). Two critical tips: use AgX tonemapper (not Reinhard, Filmic, or Neutral) as AgX bleeds overbright colors to create hotspots. In Blender materials, never set color channels to exactly 0 or 1 -- even for a red insert, green and blue should be at least 0.1.

Insert Color Accuracy Research¶

The large center crosshair insert on F-14 Tomcat is white plastic, not green -- a common error across virtual recreations dating back to VP9. The insert appears green when GI is on because green rubber bulb covers are on the GI sockets underneath. However, when the three white flasher bulbs fire, they obliterate the green GI and the insert appears bright white. Always verify insert colors against IPDB photos of blank playfields.

Insert Brightening When GI Off¶

When GI is turned off for dramatic effect (e.g., during modes), insert primitives need their intensity multiplied to compensate for the darker environment (from Goonies and F-14 Tomcat). Without compensation, inserts appear dim and washed out against the dark playfield.

Flupper's insert lighting script for F-14 Tomcat includes a multiplier that increases insert IntensityScale when GI is off. This simulates eye adaptation -- when the overall table is darker (GI off), lit inserts appear relatively brighter to the human eye.

GI Bleed-Through on Inserts¶

Inserts of the same color may need completely different material settings to prevent GI bleed-through (from Ghostbusters). When GI lights are positioned near inserts, the GI light can bleed through the insert primitive, making it appear partially lit even when the ROM has the lamp off.

Playfield material shininess set too high (e.g., 1.0) causes dark outlines around insert cutouts when GI is on (from Goldeneye). Fix: reduce shininess to 0.1. The high shininess causes the playfield to reflect environment lighting differently than the insert overlay, creating visible contrast at the edges.

Insert Overlays Under Ramps¶

Wire ramps that visually bleed through inserts below them are typically a material problem rather than depth bias (from Rollercoaster Tycoon). A Blender-exported ramp material with transparency causes the bleed. Fix: switch to an opaque metal material or use a custom opaque wire ramp material. Setting disable lighting from below = 1 on wire ramp primitives also helps, especially in VR where insert lights transmit straight through wire ramp meshes (from F-14 Tomcat).

Insert Split Mode in Toolkit¶

The insert collection's lightmapper property must be set to "Split" (not "Merge") for individually addressable insert lightmaps (from Spectrum). If all inserts render as a single combined lightmap, check this setting in Blender's outliner. Changing it requires re-running the group and render steps.

Insert Mask Workflow¶

Playfield Alpha Cutouts¶

Cutting alpha holes in playfield images for 3D inserts is hours-long process. Using alpha masks instead of direct pixel deletion makes the process more forgiving (from Dr. Who). The mask-based approach preserves the original playfield image intact and applies transparency via a separate layer.

VPX 10.8 eliminated the need for the alpha mask hack previously required for playfield insert holes (from Earthshaker). In 10.8, the visual playfield can be set to non-static, which means alpha transparency works correctly without the workaround. Previously, the alpha mask required a value of 132 to avoid edge jaggies from Photoshop's color space handling. GIMP exported alpha correctly without this hack.

When cutting insert holes in playfield images, the edges must NOT have anti-aliasing enabled. Anti-aliased edges cause visible jaggies in VPX when used with the flasher insert method (from Road Show).

Flupper Insert Cutout Workflow¶

The Flupper insert cutout workflow in GIMP (from Diner): select the insert area, create a layer mask from the selection, cut/delete the insert from the playfield layer, place pre-rendered flupper insert graphics on a layer below. The mask ensures clean edges and preserves the original scan data for later adjustment.

When reworking a playfield from scan, cut out all inserts from the playfield texture and replace with flupper inserts for consistency -- even inserts that look good on the scan should be replaced (from Creature from the Black Lagoon).

Toolkit Insert Masks¶

Toolkit insert workflow requires two mask layers per insert (from No Fear): a text mask (black/white image of insert text/graphics) and an insert shape mask (the geometric shape of the insert cutout). These combine in the toolkit pipeline to produce correct insert rendering with text that appears when lit.

Layer Separator Positioning¶

The toolkit layer separator (mask) must be positioned between the playfield and the UnderPF inserts -- not below the inserts (from Beat the Clock). If the mask is below the insert geometry, bits of insert can bleed into the playfield render. Incorrect separator positioning can also reduce light influence calculations for under-playfield elements.

Insert Z-Fighting and Depth Bias¶

Set insert primitive z-position to -0.1 (not 0) to prevent z-fighting with the playfield surface (from Goldeneye). When inserts sit at exactly z=0, the GPU cannot reliably determine draw order, causing visual flickering.

Ball shadow primitives placed at exactly Z=0 also cause Z-fighting flicker. Fix: set ball shadow Z height to 1.01 VP units (from Earthshaker).

The playfield bakemap can be set slightly lower in Z (e.g., -0.2) to prevent insert intersecting/z-fighting in the Blender bake (from Bad Cats). However, setting it too low (e.g., -4.7) is problematic -- it should be at or very near 0.

An alternative to depth bias for resolving Z-fighting between ON/OFF primitive pairs: scale the opaque (bottom) primitive to 99.99% of its original size. This creates a sub-pixel depth offset that eliminates Z-fighting without visible geometry change. This is simpler than depth bias values, which can have inconsistent behavior across rendering backends (from niwak on Iron Man).

Depth Bias Values Reset After Crashes¶

VPX can reset depth bias values to defaults after crashes, version upgrades, or certain editor operations. This silently breaks the visual stack -- inserts disappear, z-fighting appears, or wrong layers show through (from Indiana Jones). After any disruption, verify depth bias on ALL layered primitives.

Insert Normal Maps¶

Normal map reflections on insert primitives look good in VR (showing spoke reflections naturally) but can produce distracting single bright pixels in desktop mode at certain POV angles (from Batman DE). Solution: add a script option to toggle normal maps, disabled by default and only enabled when VR mode is active.

Critical VR limitation: Normal maps on ON primitives break UpdateMaterial in VR -- the material update silently fails. Fix: remove normal maps from ON primitives entirely. OFF primitives can keep normal maps since they use standard VPX lighting (discovered on Indiana Jones).

Normal maps must use tangent space, not object space. Object space normal maps break in VR because the coordinate system differs between desktop and VR rendering (from flupper1 on Tales from the Crypt).

Playfield Alpha Blend Breaking Inserts¶

Insert primitives can disappear at certain viewing angles because the playfield image has incorrect alpha blending around insert holes (from Austin Powers). The holes in the PF texture have approximately 2 pixels of margin -- incorrect alpha in this zone breaks insert edge blending. When compositing PF layers, ensure clean alpha cutouts around all insert holes with no leftover semi-transparent pixels.

Setting DT (Desktop) and FSS (Full Single Screen) images on insert primitives can also break insert rendering. Setting these to "none" fixed insert display issues on Austin Powers.

VPX Additive Primitive Settings for Inserts¶

Correct settings for additive insert primitives in VPX 10.7.1+ (from niwak on Game of Thrones):

Off primitive: Static rendering, material without "active" checked
On primitive: NOT static rendering, "active" material, material color = mid gray (127,127,127), disable lighting = 1 from top and below
Why mid gray? When lighting is disabled in VPX, environment lighting is still applied and color is multiplied by 2. Mid gray (127) compensates for this.

Apply color changes via the primitive's .color property, not the material color.

Insert Lightmap Property (VPX 10.8+)¶

VPX primitives have a "Lightmap" property that connects them to a VPX light object. When connected, the primitive's opacity is automatically controlled by the light's state -- no script code needed (from Police Force). This replaces the old approach of writing custom fader subs for every insert.

Setup: 1. Create a VPX light object with correct timer interval matching the lamp number 2. Set the light's render mode to "Hidden" and fader model to "Incandescent" 3. In each lightmap primitive's properties, set the "Lightmap" field to point to that light

For fine opacity control on non-lightmap primitives, use the _Animate sub:

Sub L61_Animate
    Dim f
    f = L61.GetInPlayIntensity / L61.Intensity
    Flasher61.opacity = 1000 * f
End Sub

Toolkit Insert Depth vs Flupper 3D Inserts¶

Toolkit-baked inserts look flat in VR -- no depth/concavity is visible (from Medieval Madness). Flupper's 3D inserts have proper depth but use a different workflow. Niwak explained the toolkit can achieve fake depth by rendering the insert sides and bottom separately, with a transparent top overlay, but noted it may be tedious to set up.

For tables where VR insert depth is critical, a hybrid approach works: use Flupper-style inserts for prominent inserts and toolkit inserts for the rest (used on Spider-Man and Earthshaker).

Lightmap Pruning on Dark Playfields¶

The VPX Lightmapper toolkit prunes lightmap meshes when the calculated influence falls below a threshold of 0.01 (from Beat the Clock). On tables with very dark (near-black) playfield areas, insert lightmaps can be pruned because insufficient light bounces back through the dark surface.

Fixes: 1. Never use pure black (#000000) on playfields -- use at minimum #111111. Pure black is effectively a divide-by-zero for light bouncing (from Judge Dredd). 2. Add a gamma node to the playfield material to lift black levels slightly. 3. Add a noise or Gaussian blur layer to dark areas.

Insert Rendering in VR¶

VR-Specific Considerations¶

In VR, insert ON and OFF primitives can flicker/shimmer due to z-fighting at shallow viewing angles. Desktop mode's camera angle masks this (from Indiana Jones). Ensure adequate depth bias separation (ON=0, OFF=30 minimum).

Insert bloom lights can bleed through OFF primitives in VR. Fix: reduce bloom strength (try 0.01 in VPX lighting tab). Halo height of -0.5 (instead of default -0.01) can also help (from Judge Dredd).

Through transparent insert areas, VR players can see the underside of the cabinet model. Fix: texture the cabinet bottom with black/dark material, or add an opaque blocker primitive below the playfield (from Indiana Jones).

Light Swimming on Static Objects¶

Lights "swim" (shift position when moving head in VR) on objects that are both transparent/semi-opaque AND set to static rendering (from Monster Bash and No Fear). Fix: set affected objects to "active" (untick passive/static), but this costs performance. Static rendering "happens before the script runs" and cannot be changed via script.