# Goggles (module)
A player's own sensor goggles: put them on, cycle through sensor modes (night vision, thermal, x-ray, sonar, any sensorBlocks look or block), take them off. It runs on each machine and changes only what that machine's player sees, while heat and sonar pings stay shared by everyone. GogglesRig drives it from the player's controls; a game can also call it directly (a pickup that gives goggles, a cutscene that forces them off).
```luau
local Goggles = require("~sensorGoggles.Goggles")
Goggles.setModes({ "gen3NightVision", "militaryThermal" })
Goggles.setPowerStyle("tube") -- instant | tube | crt | digital
Goggles.setHud("military") -- military | scifi | crt | minimal | none
Goggles.on() -- or Goggles.on("militaryThermal"), Goggles.on(2)
Goggles.next() -- Goggles.previous(), Goggles.next(2)
Goggles.ping() -- a ping from this player, every player sees it
Goggles.off()
Goggles.toggle()
Goggles.onChange(function(event, mode) -- "on", "off", "mode", "empty"
if event == "empty" then print("battery flat") end
end)
print(Goggles.state()) -- { on, mode, index, power, battery, powerStyle, hud }
```
## What it does
- **Power on**: instant, a tube warm-up (a soft bloom that settles), an old monitor (a line that opens to the picture) or a digital boot (blocks that resolve). Switching modes plays a short re-boot, never a flash.
- **Readout**: mode name, compass heading, range and the temperature under the reticle (from `Heat.at`), and the battery, in a military, sci-fi, old CRT or minimal style, or none.
- **Battery**: drains slowly while on and recharges while off; at zero the goggles switch off and `"empty"` fires.
- **Pings**: in a sonar or echolocation mode the goggles ping by themselves every few seconds (echolocation faster and shorter).
- **Default modes**: gen3NightVision, militaryThermal, sciFiScanner, submarineSonar, horrorInfrared, infraredLandscape, blacklightParty, airportScanner.
`Goggles.tick(dt)` runs one frame; GogglesRig calls it, so call it yourself only when you drive the goggles without a rig.
## Known limits
- One pair of goggles per machine (the local player's).
- Battery and mode are not saved between sessions.
# sensorGoggles
Night vision goggles, thermal goggles or any sensor view a player puts on, cycles through and takes off with keyboard, gamepad or touch, each player's own.
Add one GogglesRig to a scene and every player has goggles: night vision, thermal, x-ray, sonar or any sensorBlocks look or block, with a power-on effect, a readout of mode, heading, range and the temperature under the reticle, and a battery. One player in night vision never changes what another sees, while heat and sonar pings stay the same for everyone. Made for stealth games, horror games, military shooters and sci-fi scanners.
## Five minutes to a sensor look on your own scene
1. **Install.** Search ZeroMind for `sensorGoggles` (or "night vision goggles") and install it. It brings sensorBlocks, heatSignatures and styleKit.
2. **Add the rig.** Put a GogglesRig on any entity, in the scene's build or from a script:
```luau
entity.spawn("Goggles").component.add("sensorGoggles.GogglesRig", {
modes = { "gen3NightVision", "militaryThermal", "submarineSonar" },
powerStyle = "tube", -- instant | tube | crt | digital
hud = "military", -- military | scifi | crt | minimal | none
})
```
3. **Pick the weather heat sits in** (optional): `require("~heatSignatures.Heat").setClimate("temperateNight")`.
4. **Play.** Press N to put the goggles on, B and V to cycle modes, G to send a ping.
| Control | Keyboard | Gamepad | Touch |
|---|---|---|---|
| Goggles on / off | N | d-pad up | Goggles |
| Next mode | B | d-pad right | Mode |
| Previous mode | V | d-pad left | Mode back |
| Ping | G | d-pad down | Ping |
5. **Drive them from your game** when you want (a pickup that unlocks thermal, a cutscene):
```luau
local Goggles = require("~sensorGoggles.Goggles")
Goggles.on("militaryThermal")
Goggles.onChange(function(event) if event == "empty" then print("battery flat") end end)
```
## What is inside
| Asset | What it is |
|---|---|
| `GogglesRig` component | One per scene: every player's goggles, read from their own controls. Fields `modes`, `powerStyle`, `hud`, `startOn`, `controls`. |
| `Goggles` module | `on`, `off`, `toggle`, `next`, `previous`, `ping`, `setModes`, `setPowerStyle`, `setHud`, `state`, `onChange`, `tick`. |
| `goggles.inputMap` | The four controls on keyboard, gamepad and touch (`toggle`, `next`, `previous`, `ping`). |
| `guides/how-to-add-night-vision-goggles.guide` | How to add night vision and thermal goggles a player can put on. |
What the goggles do:
- **Power on** in one of four styles: instant, tube (a soft bloom that settles), crt (a line that opens to the picture), digital (blocks that resolve). Changing mode plays a short re-boot, never a flash.
- **Readout** with the mode name, compass heading, range and the temperature under the reticle, and the battery, in military, sci-fi, old CRT or minimal style, or none.
- **Battery** drains while on and recharges while off; at zero the goggles switch off.
- **Automatic pings** every few seconds in sonar and echolocation modes.
- **Flash blinding**: night vision washes out when a flash (`Sensors.flash`) goes off in view, never more than three full-screen washes a second.
## Stacking with Style Cookbook blocks
The goggles lay their sensor look over the scene's own style stack on this player's machine only. A Cookbook ink line, film grain or paper the scene already has stays under the sensor look, and taking the goggles off gives the scene's own look back exactly as it was.
## Multiplayer
- **Per player**: goggles on or off, the mode, power, battery, the readout and blinding. Each machine reads only its own player's controls.
- **Shared**: heat (climate, heat sources, warm hand prints), pings (yours reach every player) and flashes.
## Players, enemies and pickups read apart
Under every mode, sensorBlocks' role cues mark what things are: you and allies a steady outline with a slow friend-or-foe blink, enemies a bright outline with hatching, pickups a slow shimmer, hazards a dashed outline. Give roles with `StyleRoles.give(e, "enemy")` or name things so the defaults find them (Guard, Pickup, Mine...).
## What it costs
The goggles themselves cost a few table writes a frame, plus a readout refreshed ten times a second (its text changes, never the screen's brightness). The real cost is the sensor look they put on, which the sensorBlocks README measures per look with the engine's own profiler, on desktop and in the browser. Power-on effects and flash blinding never wash the whole screen more than three times a second.
## Known limits
- One pair of goggles per machine; battery and mode are not saved between sessions.
- Everything in sensorBlocks' Known limits applies: 64 nearest heat shapes, 32 contacts and 8 pings drawn; data textures fall back to rgba16f; transparent things are not in the depth; offscreen captures, mirrors and render-to-texture cameras do not show the goggles' view; x-ray counts surfaces, not real density; reflectance in IR and UV is guessed from base colour.
- Players who join late miss pings and warm prints sent before they joined.
- The touch buttons share the right lower zone with a game's other buttons.
## Version history
- **1.0.9**: built against sensorBlocks 1.0.9 and heatSignatures 1.0.8.
- **1.0.8**: built against sensorBlocks 1.0.8.
- **1.0.7**: built against sensorBlocks and heatSignatures 1.0.7; version history without dates.
- **1.0.6**: auto-gated night vision joins the default goggle modes (after gen 3; gen 2 and any other look can be added to `modes`); depends on heatSignatures (heatKit's new name) and sensorBlocks 1.0.6.
- **1.0.5**: heat drawn on the GPU (heatSignatures's HeatPass: one geometry pass into a heat buffer, each object's heat in a shader-data lane; thermal blocks read `input:heatObj`); scripts keep only soft shapes for prints, radiant warmth and mesh-less sources; heat tick every fourth frame on heatSignatures's own clock; scans, new sources and clean-up spread over frames; climate cached; heatSignatures's render feature restarts itself if the engine stops it; styleKit 1.8.1; SensorBench checks that heat was live in every thermal window.
- **1.0.4**: lighter per-frame work: name scans use the engine's own name search and remember each name stem; moving heat sources and contacts are read from the engine every fourth frame and dead-reckoned in between; the heat tick keeps separate moving and still lists and runs once a second when no look needs heat; 40 heat shapes and 16 contacts drawn (smaller data textures); the climate component no longer runs every frame; SensorBench measures in alternating look-on and look-off windows and reports the median; What it costs updated with desktop and browser numbers.
- **1.0.2**: fixes the gen-3 night vision look, whose look file was damaged in 1.0.1 so styleKit could not read it; heat and contact data are uploaded every other frame; x-ray thickness passes draw at half resolution (the airport scanner went from 4.5 to 0.24 ms of GPU with 2,500 objects); the name scans run every ten seconds; each runtime keeps asking for styleKit until it answers; SensorBench (measure a look's engine CPU and GPU cost on this device); What it costs measured as the engine's own per-system CPU and per-pass GPU time.
- **1.0.1**: a shared clock every machine agrees on for heat prints and pings (ages never step back); per-frame work trimmed (reused arrays, static heat sources updated a slice at a time, only heat shapes in view and worth drawing are packed, lighter night vision shader); `Heat.of` reads player bodies; `Sensors.use(look, { shared = true })` makes the scene's style stack when there is none; What it costs section.
- **1.0.0**: first release. GogglesRig, the Goggles module with four power styles, four readouts, battery and automatic pings, and keyboard, gamepad and touch controls.