viewClear.package
README.md
viewClear
Keeps the player in view of a third-person camera. Crates, barrels, sacks, lanterns, posts and rails that stand between the camera and the player, or that the camera has backed into, are hidden on that player's own machine while they are in the way, and come back a moment after they are clear. Other people pressed right up against the lens can be hidden the same way. Nothing is despawned and nothing is synced, so every player keeps their own clear view and the world stays exactly as built.
It also puts those props on an orbital_follow camera's ignore list, so the camera stops pulling in tight behind every barrel.
Version 1.0.1. Made for the Dockhands level (disguiseKit's showcase) and usable in any third-person world.
Quick start
Put the props that may be hidden under one or more group entities (each child of a group, with everything under it, is one piece), then add the component anywhere in the scene:
entity.spawn("ViewClear").component.add("viewClear.ViewClear", { groups = { "Market", "Docks" } })
Press play and walk behind a stall: the crates between the camera and you vanish while they are in the way, and reappear 0.3 s after you step clear.
What gets hidden
Only pieces in the named groups, and of those only small ones:
- at most
maxHeight(2.1 m) tall andmaxWidth(2.4 m) across, or - at most
thin(0.45 m) across both ways, whatever the height (a post, a lamp pole).
A piece is hidden while the line from the lens to the player's head or chest passes through it, or while the lens is within lensMargin (0.6 m) of it. Walls, floors, the landscape and anything bigger are never touched. With no group named nothing is hidden.
Fields (viewClear.ViewClear)
| field | default | what it does |
|---|---|---|
groups | {} | entity names whose children are the props that may be hidden |
maxHeight, maxWidth, thin | 2.1, 2.4, 0.45 | what counts as small (metres) |
lensMargin | 0.6 | a piece this close to the lens is hidden even when it is not in the way |
reach | 10 | only pieces this near the player are checked |
rescan | 4 | seconds between looking for props spawned later |
linger | 0.3 | seconds a piece stays hidden after it is clear, so it never flickers |
bodies | {} | entity names of character bodies to hide while pressed against the lens (never the player's own) |
bodyNear | 1.5 | how close to the lens such a body is hidden |
cameraIgnore | true | put the pieces on the main camera's orbital_follow ignore list |
active | true | off: everything hidden is shown and nothing more is hidden |
From code
The component is a thin wrapper over viewClear.view, which a level can drive itself:
local V = require("viewClear.view")
local st = V.new()
function update(dt) if engine.mode == "play" then V.step(st, { groups = { "Market" } }, dt) end end
function onDestroy() V.showAll(st) end
V.segmentHitsBox and V.isSmall are the two tests it uses, there for a level with its own idea of what is in the way.
Multiplayer
Everything is local to each machine: every player hides what is in front of their own camera, and nobody else sees it hidden.
Tests
viewClearTests checks the segment test and the size rule, and that a crate between the camera and a stand-in player is hidden and comes back once it is clear.
Version history
- 1.0.1: search tags (camera, third-person, occlusion, hide props) so the package is found on ZeroMind. No behaviour change.
- 1.0.0: first release, lifted out of the Dockhands level's camera.