Troubleshooting HCP VBS
HEAT Capture never receives anything, but VBS4 logs “HCPVBS loaded” and “HCPVBS Connecting”
Cause. Almost always communication.type is still "namedpipe" - the value shipped in
HCPVBSConfig.json. HEAT Capture has no named-pipe listener, so HCP VBS creates the pipe,
nothing ever connects to it, and every publish attempt silently fails and retries. Both log
lines above appear regardless: they confirm the component loaded and attempted to connect, not
that HEAT Capture received anything.
Fix. Set communication.type to "websocket" and correct websocket.port/address to
match HEAT Capture’s actual configured port (5005 as shipped, not the file’s 50001). See
Configure. Confirm with onopen in the console log after restarting
VBS4.
The console repeatedly logs “Write failed, attempting reconnection”
Cause. Confirms the plugin is on the named-pipe transport with no client ever attached - see above. This is not a transient network issue; it will repeat forever at the plugin’s collection cadence (about 10 times a second) until the transport is switched.
Fix. Same as above: switch to "websocket".
A session never starts, or HCPVBSManager::Start() fails
Cause. The session-start HTTP POST (/api/session/start-session) requires a signed-in user
in HEAT Capture. If nobody is signed in, or hostname/port in HCPVBSConfig.json don’t match
the workstation HEAT Capture is actually listening on, the POST fails.
Fix. Sign in to HEAT Capture before starting the VBS4 mission, and confirm hostname and
port match HEAT Capture’s configured WebSettings:Host / WebSettings:Port.
Data arrives, but an entity’s DIS type is 0.0.0.0.0.0.0
Cause. Neither DISConfigNameMappings.json (by config class name) nor DISMappings.json
(by VBS object type) has an entry for that entity. This is the documented fallback, not a fault.
Fix. Add an entry to DISConfigNameMappings.json for the entity’s config class name - the
build/vs2022/scraper/ tool can generate entries from the VBS Gateway DIS mappings table - or a
type-level fallback entry to DISMappings.json.
An entity I expected to see is missing entirely
Cause. It matches a rule in EntityDenyList.json. A rule matches when both its type and
configClassName fields match (an empty field matches anything), and an entity denied by any
rule is never tracked at all - no creation event, no frames, no tracking events.
Fix. Review EntityDenyList.json for a rule matching that entity’s type or config class
name.
An entity gets a DESTROYED event with no preceding hit or damage
Cause. Expected after a mission load or reset. VBS can reassign an object’s id without firing a deletion callback for the old one; HCP VBS detects the stale handle on its next tick and reports it destroyed before dropping it. See Data produced.
Fix. Not a fault. If this is disruptive to a downstream consumer, filter DESTROYED events
that arrive within the first tick or two after a mission load.
A weapon hit doesn’t produce an AMMO_HIT or DETONATION event
Cause. By design in this version: those events only fire when VBS reports the projectile’s
own shot_exploded flag as true. Most kinetic (non-exploding) hits produce no tracking event at
all beyond whatever DAMAGED event follows from the resulting damage change.
Fix. Not a setting; this is a source limitation. Rely on DAMAGED events for non-exploding
hits.
Collection rate doesn’t respond to collection.intervalSeconds
Cause. This setting has no effect in this version - the code path that would apply it is never called. Collection runs at a fixed 10 Hz regardless of the file’s value.
Fix. None available from configuration. See Configure.