Vehicle Optics

Vehicle Optics

Vehicles, aircraft and mechas support configurable driver and passenger gunsights.

Controls

Default	Action
Middle mouse	Toggle Vehicle Scope
B	Cycle Vehicle Gunsight / Thermal
Y	Measure Optics Range
H	Reset Optics Range
F8	Edit Optics HUD, when the definition enables editing

These bindings appear under All Driveables and can be rebound. Minecraft preserves bindings already saved in options.txt: an existing Toggle Driver Zoom binding becomes Toggle Vehicle Scope and retains its saved key. Reset that binding in Controls to use the new middle-mouse default.

Scopes force first person while viewed and restore the previous camera when closed, on dismount, death, seat change, or when opening a screen. Scope magnification scales mouse movement without changing the saved sensitivity setting. Pilot optics temporarily suspend mouse flight input so the mouse aims the optics; the selected flight-control mode remains intact.

Explicitly configured sights work without /teams vehiclesCanZoom true, matching the reference. That command still controls the optional 7x driver zoom on ground vehicles without configured optics. Turning it off closes that fallback zoom.

Driver gunsights

HasScope true
Gunsight tank_day tank_thermal
GunsightZoom 3 8
ThermalGuis 2
HasGunsightPos true
GunsightPos 16 32 0

Texture names refer to GUI textures in the content pack, using the same resolution and collision handling as gun scope textures. Vehicle overlays use the reference's centered 4:1 quad, scaled to the screen height. Names are normalized through the modern resource loader; NONE means no overlay.

Parameter	Meaning
HasScope / hasScope <bool>	Enable a driver scope; default false.
Gunsight <texture...>	Ordered sight overlays. Driver sight cycling follows this list. Overlay supplies the fallback when this list is absent.
GunsightZoom / gunsightZoom <float...>	Magnification for each sight; default 1. If shorter than the overlay list, later sights reuse the last zoom.
ThermalGuis / ThermalGUIs <index...>	One-based thermal sight indices.
thermalSight <bool>	Allow the cycle key to toggle thermal mode for a single driver sight.
ThermalVisionColor <white|green|red>	Labjac Edition palette of every thermal sight on the driveable. Default white-hot.
ThermalVisionGeneration / thermalVisionGen <n>	Labjac Edition image generation of every thermal sight on the driveable: 1 is the roughest, with jittering rows and heavy scanlines; 2 is in between; 3 is the clearest, with light grain and slight motion. Values of 1 or less select 1, values of 3 or more select 3. Without the key, sights keep the clean original image.
NightSight / nightScope <bool>	Optical night vision while scoped. Applies to passenger optics too.
ShowCrosshair <bool>	Retain the vanilla crosshair while viewing the driver scope.
HasGunsightPos <bool>	Enable the custom driver camera anchor.
GunsightPos <x y z>	Driver camera position in model pixels (divided by 16), following the turret.

Repeated definitions and aliases apply in source order, with later assignments replacing earlier ones. As elsewhere in this port, keyword casing is accepted case-insensitively. Invalid seat references and non-finite numbers are reported without aborting later definitions. Magnification is at least 1.

Passenger and pilot optics

Seat 0 is the pilot/driver; passengers start at 1. Define the seat using the normal Driver, Pilot, or Passenger line.

Passenger 1 0 24 0 turret -180 180 -20 60
OpticsModeSeat 1 true
SeatGunsight 1 gunner_tv gunner_flir
SeatGunsightZoom 1 4 12
SeatThermalGuis 1 2
SeatOpticsCamera 1 16 32 0

Parameter and aliases	Arguments and behavior
OpticsModeSeat / SeatOpticsMode	<seat> <bool>: enables a toggled optics mode and scope support.
PilotOptics / DriverOptics / GunnerOptic	<bool>: same mode for seat 0, including aircraft.
SeatOpticsCamera / OpticsCameraSeat	<seat> <x y z>: enable a camera anchor in model pixels.
PilotOpticsCamera / DriverOpticsCamera / GunnerOpticCamera	<x y z>: camera anchor for seat 0.
PassengerZoom / passengerZoom	<seat> <float>: fallback magnification.
SeatHasScope / PassengerHasScope	<seat> <bool>: scope availability.
SeatAutoScope / PassengerAutoScope	<seat> <bool>: always use the scope while occupied; the occupant cannot lower it.
SeatNightSight / PassengerNightSight	<seat> <bool>: optical night vision.
SeatGunsight / PassengerGunsights	<seat> <texture...>: overlays; also enables scope support. The occupant starts unscoped.
SeatGunsightZoom / SeatGunsightZooms / PassengerGunsightZoom	<seat> <float...>: per-sight magnification.
SeatThermalGuis / SeatThermalGUIs / PassengerThermalGuis	<seat> <index...>: one-based thermal channels; enables scope support.
heliGUI / HeliGUI / PassengerGunsight	<texture>: shared fallback passenger overlay (singular PassengerGunsight is distinct from plural PassengerGunsights).
heliGuiSeat / SeatOverlay	<seat> <bool>: enables the passenger overlay; the occupant opens it with Toggle Vehicle Scope.

Passenger sight count follows the longest overlay/zoom list or highest thermal index. Missing overlay or zoom entries reuse the last configured entry. A single thermal channel can be toggled between thermal and TV with the cycle key. Passenger seats start unscoped, and the gunner can raise or lower the sight with Toggle Vehicle Scope. SeatAutoScope true starts scoped and keeps the scope up until the occupant leaves the seat.

The modern camera uses the project's common attachment transforms, so camera anchors follow model orientation, aircraft banking, and turret-mounted parts. Night vision is local to the optics and never adds or removes the player's potion effects. Thermal mode draws visible living entities, vehicles, flying rounds and grenades hot against a darker scene; scene depth occludes heat behind terrain. Explosions, fire, muzzle flashes, sparks, tracers, exhaust and Flan's blast and debris smoke are hot as well, as in the Labjac Edition; ordinary smoke, including smoke grenades, stays cold so it still screens. Other mods' particle types can be added with the additionalThermalHotParticles client setting. During a Teams round, team-mates and the vehicles they crew blink hot twice a second (Labjac Edition IFF strobe), so they stand out from enemies, which stay steadily hot. It uses its own post-processing chain and releases its buffers when no longer needed or when resources reload.

Optics HUD

SeatOpticsHUD 1 true
SeatOpticsHUDRequireRangeKey 1 true
SeatOpticsHUDMaxRange 1 5000
SeatOpticsHUDColor 1 85 255 85
SeatOpticsHUDScale 1 1
SeatOpticsElevationIndicator 1 true
SeatOpticsRangePos 1 -120 70
SeatOpticsRangePosSight 1 2 -100 65
SeatOpticsHUDEdit 1 true

The HUD shows range in metres (one block per metre), horizontal speed in km/h, traverse, compass bearing and optional elevation. Range measurement stops at unloaded terrain and selects the nearest visible block or pickable entity, excluding the occupied vehicle and its occupants. With Distant Horizons installed, a measurement that finds nothing before unloaded terrain carries on over Distant Horizons' simplified terrain up to HUDMaxRange; such a range is approximate and shown with a leading ~. With HUDRequireRangeKey true, Y stores a measurement; otherwise range updates live. H clears the stored measurement.

All following keys start with SeatOptics and take the seat id first:

Suffix	Remaining arguments
HUD, HUDEdit, HUDRequireRangeKey, ElevationIndicator	<bool>
HUDMaxRange	<distance> (at least 1; default 5000)
HUDInherit	<sourceSeat> or NONE
HUDScale, HUDScaleSight	<scale> or <sight> <scale>
HUDColor, HUDColorSight	<r g b> or packed color; insert <sight> before the color for Sight.
RangePos, SpeedPos, TraversePos, CompassPos, ElevationPos	<x y> offsets from screen center. Append Sight and insert a one-based sight index for an override.
RangeScale, SpeedScale, TraverseScale, CompassScale, ElevationScale	<scale>; Sight variants also supported.
RangeTexture, SpeedTexture, TraverseTexture, CompassTexture, ElevationTexture	<texture> or NONE; Sight variants also supported.
The five element names followed by TextureSize	<width height>
CompassMarker, CompassMarkerSight	<texture> or <sight> <texture>
CompassMarkerSize, CompassMarkerOffset	<width height> or <x y>

PilotOpticsHUD, PilotOpticsHUDEdit, PilotOpticsHUDMaxRange, and PilotOpticsHUDRequireRangeKey accept the same values without a seat index. The reference's inheritance behavior is retained: seat 0 uses seat 1's HUD when present unless an explicit SeatOptics... setting overrides those pilot defaults. Use SeatOpticsHUDInherit 0 NONE to select the pilot's own HUD explicitly.

With editing enabled, F8 opens the HUD editor: Tab selects an element, arrows move it, Shift increases the movement step, +/- changes scale, C copies PosSight and ScaleSight definition lines, and Escape closes the editor. Changes are session-local; paste the exported lines into the pack definition to keep them.

Multiplayer and compatibility

The client sends toggle/cycle intent through the normal driveable input packet. The server verifies the occupied seat and input sequence, applies cooldowns, and synchronizes active scope, sight index and thermal state. Leaving a seat resets its optics state. One occupant's scope does not change another occupant's view.

The networking protocol is version 12 because seat synchronization gained optics fields. Clients and servers must use matching builds. Existing vehicle definitions require no changes unless adding these optics settings; bundled pack data is not automatically given scopes.