ViewportStencil renders a model inside a surface in Roblox: ground cracks, holes, craters, portals or openings in walls. No geometry is cut or destroyed. A ViewportFrame drawn on the surface displays the model with a perspective projection that matches the player's camera, so the surface appears to open into the model from any viewing angle.

• How it works
• Installation
• Quick start
• API reference
• Making a model
• Lighting
• Performance
• Limitations
• Example
• Development
• Credits
• License

ViewportStencil combines two existing techniques:

• Off-axis projection, from rbx-viewport-window by EgoMoose. An invisible part carries a SurfaceGui with a ViewportFrame. Every frame, the ViewportFrame's camera is placed at the player's camera position and given an off-axis projection, so the image lines up with the surface and behaves like a window rather than a flat picture.
• ViewportFrame masking, described in this DevForum post. Inside a ViewportFrame, faces whose vertex alpha has been erased are not drawn, but they still occlude the geometry behind them. Each model includes a flat mask plane with erased alpha around its opening. Where the mask is, the ViewportFrame is transparent and the real surface shows through; the rest of the model is only visible through the opening.

Because the mask is part of the mesh, every model defines its own shape. See Making a model.

You don't need a GitHub account to download ViewportStencil. Choose one of the options below.

1. Open the latest release.
2. Under Assets, click ViewportStencil.rbxm to download it.
3. In Roblox Studio, open the Explorer window, right-click ReplicatedStorage and choose Insert from File.... Select the downloaded ViewportStencil.rbxm.
4. Check that ReplicatedStorage now contains a ModuleScript named ViewportStencil, with the child modules Projection, Renderer, RigPool, Stencil, Types and Utils.

The module has to be somewhere LocalScripts can reach. ReplicatedStorage is the standard location.

If your project uses Rojo and Wally, add the dependency to your wally.toml:

[dependencies]
ViewportStencil = "sebasvcx/viewport-stencil@1.0.1"

Then run wally install.

To try it without setting anything up, download ViewportStencil-Demo.rbxl from the latest release, open it in Studio and press Play. See Example.

The version is written at the top of the ViewportStencil ModuleScript. To update, delete the old module and insert the new ViewportStencil.rbxm from the latest release, or change the version in your wally.toml. Check the release notes for changes that may affect your code.

ViewportStencil runs on the client only, so it must be required from a LocalScript (for example, one in StarterPlayerScripts).

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ViewportStencil = require(ReplicatedStorage.ViewportStencil)

local crack = ReplicatedStorage.Crack -- a Model prepared as described in "Making a model"

-- A CFrame on the surface under the mouse, rotated randomly around the surface normal
local cframe = ViewportStencil.Utils.fromMouse(nil, nil, math.random() * 2 * math.pi)
if cframe then
	ViewportStencil.new(crack:Clone(), cframe, { lifetime = 10 })
end

Two things to keep in mind:

• The stencil takes ownership of the model: it is parented into the stencil's ViewportFrame and destroyed along with the stencil. Always pass a clone.
• The stencil's CFrame is a point on the surface whose UpVector is the surface normal. The Utils functions build this CFrame from a raycast, so floors, walls, ceilings and slopes are all handled the same way.

Creates a stencil that renders model inside the surface at cframe.

Throws an error if called on the server, if model is not a Model or has no parts, or if cframe is not a CFrame.

StencilOptions

All fields are optional.

Returns every stencil that has not been destroyed. The returned table is a copy, so stencils can be destroyed while iterating over it.

Destroys every active stencil. Equivalent to calling destroy() on each stencil returned by getActive().

The module exports its types for use in typed code:

local ViewportStencil = require(ReplicatedStorage.ViewportStencil)

type Stencil = ViewportStencil.Stencil
type StencilOptions = ViewportStencil.StencilOptions

The object returned by ViewportStencil.new.

Calling setCFrame, setSize or setTransparency on a destroyed stencil has no effect and prints a warning.

Helpers that return a CFrame ready to pass to ViewportStencil.new: a point on a surface, with its UpVector along the surface normal. The functions that raycast return nil if nothing is hit.

Common parameters:

• angle: number?: rotation around the surface normal, in radians. Pass math.random() * 2 * math.pi for a random rotation. Defaults to no rotation.
• params: RaycastParams?: raycast parameters. Defaults to excluding the local player's character.

A stencil model is a mesh made of two parts:

• The mask: a flat plane on top, with the opening cut out of it. Its vertex alpha is erased, so it is not drawn, but it hides the rest of the model everywhere except through the opening.
• The visible part: the geometry seen through the opening, such as the walls and bottom of a crack.

The steps below build a ground crack in Blender. The finished file is example/crack.blend. The DevForum post on ViewportFrame masking covers the masking technique and erased-alpha vertex painting in more detail.

1. Model the mesh: a flat plane with the opening cut out, and the geometry below it.

2. Separate the mesh into two objects: the mask (the plane) and the visible part (everything below it). Vertex colors are stored per vertex, so if both parts shared vertices along the edge of the opening, erasing the mask's alpha would also fade the edges of the visible part.

To preview the erased alpha while painting, give the mesh a material with a Color Attribute node, connect its Alpha output to the Base Color input of the Principled BSDF, and set the viewport shading to Material Preview.

3. Switch to Vertex Paint mode.

4. Set the brush's blending mode to Erase Alpha.

5. Paint over the entire mask plane. Any area left unpainted will be visible in game.

6. With the preview material from step 2, the finished mask appears black and the visible part stays unchanged.

7. Export both objects together as a single FBX file. They don't need to be joined in Blender. Import the FBX into Studio as a single mesh, so both parts end up in one MeshPart.

Place the imported MeshPart inside a Model and set it as the model's PrimaryPart:

Crack (Model, PrimaryPart = Crack)
└── Crack (MeshPart)

The stencil positions the model as follows:

• Height: the top face of the PrimaryPart is placed flush with the surface, so the mask plane must be the highest point of the mesh. If the model has no PrimaryPart, the top of its bounding box is used.
• Orientation: the PrimaryPart's UpVector is aligned with the surface normal. Without a PrimaryPart, world up is used.
• Centering: the surface is centered on the stencil's CFrame, so the opening should be centered on the mesh.

Guidelines for the surface size:

• By default the surface is 90% of the model's footprint. Keeping the mask's outer edges outside the surface prevents a thin line of light from appearing along them. If you set size yourself, keep it slightly smaller than the mask.
• Keep the mask tight around the opening. The ViewportFrame's resolution is spread over the whole surface, so a large mask around a small opening makes the result blurrier.

Additional parts or effects can be added to the model, as long as they stay below the mask.

A stencil is lit in two independent layers, and both affect its final appearance:

1. ViewportFrame lighting. Objects inside a ViewportFrame are not affected by the Lighting service or by lights in the world. They are lit only by the ViewportFrame's Ambient color and a single directional light (LightColor, LightDirection). This layer determines the model's shading.
2. World lighting on the SurfaceGui. The image produced by the ViewportFrame is displayed on a SurfaceGui, which is lit by the world like any other surface, scaled by LightInfluence. With lightInfluence = 1, colored lights near the stencil tint it. With lightInfluence = 0, world lighting is ignored.

brightness (SurfaceGui.Brightness) multiplies the final result, which is useful for glowing effects.

The defaults (white ambient, lightInfluence = 1) light the model evenly and let it pick up nearby lights. This suits glowing, stylized effects, but a plain grey mesh will look flat and will take on the color of any light near it.

Example configurations:

-- Realistic hole: dark interior, lit from above, unaffected by world lights
ViewportStencil.new(model, cframe, {
	ambient = Color3.fromRGB(60, 60, 60),
	lightColor = Color3.fromRGB(200, 200, 200),
	lightDirection = Vector3.new(0, -1, 0),
	lightInfluence = 0,
})

-- Glowing crack: evenly lit and brighter than its surroundings
ViewportStencil.new(model, cframe, {
	ambient = Color3.new(1, 1, 1),
	lightInfluence = 0,
	brightness = 2,
})

-- Blended with the scene: shaded by the ViewportFrame and tinted by nearby lights
ViewportStencil.new(model, cframe, {
	ambient = Color3.fromRGB(120, 120, 120),
	lightInfluence = 1,
})

lightDirection is the direction the light travels, in world space. (0, -1, 0) points straight down and lights upward-facing surfaces; the default (-1, -1, -1) comes diagonally from above.

The model's colors, materials and textures are rendered inside the ViewportFrame, with the ViewportFrame's usual restrictions: no shadows, no post-processing, and Neon and Glass rendered at the lowest quality. Neon appears as a flat, bright color; it does not glow or illuminate its surroundings.

• Each stencil is tested every frame against the camera's view frustum, against maxDistance, and for whether the camera is in front of its surface. Stencils that fail any test have their SurfaceGui disabled, which also stops their ViewportFrame from rendering, and skip their per-frame update.
• When neither the camera nor a stencil has changed since the previous frame, that stencil is not updated.
• The per-frame update runs only while at least one stencil exists.
• The dominant cost is GPU rendering of each visible ViewportFrame. Keep the number of stencils visible at the same time reasonable, and keep the meshes simple.

• Client only.
• ViewportFrames are not anti-aliased, so edges can look slightly jagged.
• The stencil surface is a rectangle; the model's mask defines the visible shape.
• Overlapping stencils do not merge: the one on top covers the other.

The latest release includes a demo place, ViewportStencil-Demo.rbxl. Press Play and click the floor or the wall to spawn a crack, which is removed after 10 seconds.

The demo place contains:

The repository is a Rojo project:

To work on the module, run rojo serve dev.project.json and connect from the Rojo plugin in Studio. To build the model file, run rojo build default.project.json -o ViewportStencil.rbxm.

• EgoMoose, for rbx-viewport-window.
• The ViewportFrame masking technique from the Roblox DevForum.

ViewportStencil is released under the MIT License.