Audio: in-game TRIGGERING works -- real StateIndicator attrs + audio-watcher databinding (task #50)

Enabling audio unlocked L4AudioRenderer::CreateEntityAudioObjects, which binds
AudioStateWatchers to entity/subsystem state attrs BY NAME (attribute-pointer
databinding) and calls AddAudioWatcher on them.  The reconstruction pointed the
Mech's state attrs at the scalar read-pad `attrPad` (fine for gauges that READ a
value, fatal for a state watcher that calls a METHOD) -> AV in SChainOf::Add on
0xCDCDCDCD.  Root-caused via cdb + a BT_ATTRBIND_LOG trace in AttributeWatcher.

Mech-level state audio now REAL + driven (verified: walking fires SetupPatch +
PlayNote/alSourcePlay, patches 78/80/116):
- AnimationState (0x1f) / ReplicantAnimationState (0x20): real StateIndicators
  (0x21 states covering MechAnimationState 0..0x20), driven from SetBodyAnimation
  so footstep/gait/transition sounds fire on animation change.
- CollisionState (0x16): real 4-state StateIndicator driven from ProcessCollision
  via collisionTemporaryState (the deferred @4aa741 per-frame zero + the
  part_012.c:15406-15413 contact tail, InitialHit accumulation; the 1-vs-2 Slide
  split awaits the 0x240/0x244 floats still stubbed by fieldAt()).
- @0x44c CORRECTED: "ammoState (0/1 leaking/2 dry)" was a mislabel -> it is
  collisionTemporaryState (never read as ammo).

Bring-up guards [T3, temporary, self-clearing] so audio-on is STABLE while the
subsystem state models are still stubs (Generators/Condensers/Myomers/Torso/
Avionics/Reservoir/ControlsMapper -- ~15 subsystems, ~40 attrs: GeneratorState,
CondenserState, ReportLeak, ...): a NULL subsystem attr redirects to an inert pad
(was a fatal Fail); an AudioStateWatcher on an unconstructed StateIndicator (null/
0xCDCDCDCD) skips instead of AV.  Both pass automatically once the subsystem is
reconstructed.  Those subsystem sounds stay silent until then (their audio wave).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

engine/MUNGA/AUDWTHR.cpp

@@ -1,3 +1,4 @@
+#include <cstdlib>
 #include "munga.h"
 #pragma hdrstop
 
@@ -873,6 +874,26 @@ AudioStateWatcher::AudioStateWatcher(
 	AudioWatcherOf<StateIndicator>(stream, entity)
 {
 	Check_Pointer(attributePointer);
+	// BRING-UP GUARD [T3, temporary]: an AudioStateWatcher binds to a StateIndicator
+	// attribute BY NAME.  The Mech's own state indicators (SimulationState, Animation/
+	// ReplicantAnimationState, CollisionState) are real; but audio also binds state
+	// attrs on subsystems that are not fully reconstructed yet (GeneratorState,
+	// CondenserState, Torso MotionState, ...).  Those resolve to an unconstructed
+	// object -- a null/garbage vtable at +0 or a debug-fill (0xCDCDCDCD) watcher chain
+	// at +0x18 -- and AddAudioWatcher would AV in SChainOf::Add.  Skip the register
+	// (that subsystem's state audio stays silent) until the subsystem is built; this
+	// is SELF-CLEARING (a real StateIndicator passes).  See docs: audio subsystem wave.
+	{
+		unsigned vt    = *(unsigned*)attributePointer;
+		unsigned chain = *(unsigned*)((char*)attributePointer + 0x18);
+		if (vt == 0 || vt == 0xCDCDCDCD || chain == 0xCDCDCDCD)
+		{
+			if (getenv("BT_AUDIO_LOG"))
+				DEBUG_STREAM << "[audiostate] skip watcher on unbuilt StateIndicator "
+					<< attributePointer << " (vt=" << (void*)vt << ")\n" << std::flush;
+			return;
+		}
+	}
    Cast_Object(StateIndicator*, attributePointer)->AddAudioWatcher(this);
 }
 

engine/MUNGA/WATCHER.cpp

@@ -1,3 +1,4 @@
+#include <cstdlib>
 #include "munga.h"
 #pragma hdrstop
 
@@ -95,21 +96,31 @@ AttributeWatcher::AttributeWatcher(
 
 	attributePointer = simulation->GetAttributePointer(attribute_name);
 
-	#if DEBUG_LEVEL>0
+	if (getenv("BT_ATTRBIND_LOG"))
-		if (attributePointer == NULL)
+	{
-		{
+		DEBUG_STREAM << "[attrbind] subsys=[" << subsystem_name
-			Dump(attribute_name);
+			<< "] attr=[" << attribute_name << "] -> ptr=" << attributePointer
-		}
+			<< " vtbl=" << (attributePointer ? *(void**)attributePointer : (void*)0)
-	#else
+			<< "\n" << std::flush;
-		if (attributePointer == NULL)
+	}
-		{
+
-			DEBUG_STREAM <<
+	// BRING-UP GUARD [T3, temporary]: audio references attributes on subsystems that
-				"AttributeWatcher::AttributeWatcher - attribute " <<
+	// are not fully reconstructed yet (GeneratorState/On, CondenserState, ReportLeak,
-				attribute_name <<
+	// Torso SpeedOfTorsoHorizontal/MotionState, Reservoir/Avionics/ControlsMapper ...).
-				"\n";
+	// GetAttributePointer returns NULL for those, and the original engine Fail()s
-			Fail("AttributeWatcher::AttributeWatcher - attribute not found\n");
+	// (fatal) -- which would abort every audio-enabled run.  Redirect NULL to a shared
-		}
+	// inert zero pad so scalar/vector watchers read 0 (that sound stays silent) instead
-	#endif
+	// of crashing; state watchers on it are skipped by the AudioStateWatcher guard.
+	// Self-clearing: a registered attribute resolves to its real member.  Remove once
+	// the subsystem attribute tables are reconstructed (the audio subsystem wave).
+	if (attributePointer == NULL)
+	{
+		static char s_missingAttrPad[64] = {0};
+		if (getenv("BT_AUDIO_LOG"))
+			DEBUG_STREAM << "[attrnull] " << subsystem_name << "." << attribute_name
+				<< " not reconstructed -> inert pad\n" << std::flush;
+		attributePointer = s_missingAttrPad;
+	}
 
 	Check_Pointer(attributePointer);
 #endif

game/reconstructed/mech.cpp

@@ -703,7 +703,7 @@ const Mech::IndexEntry
 	Mech::AttributePointers[]=
 {
 	ATTRIBUTE_ENTRY(Mech, MaxAcceleration,         attrPad),				// 0x15
-	ATTRIBUTE_ENTRY(Mech, CollisionState,          attrPad),				// 0x16
+	ATTRIBUTE_ENTRY(Mech, CollisionState,          collisionState),			// 0x16 real StateIndicator (audio impact/scrape watcher)
 	ATTRIBUTE_ENTRY(Mech, CollisionNormal,         attrPad),				// 0x17
 	ATTRIBUTE_ENTRY(Mech, CollisionSpeed,          attrPad),				// 0x18
 	ATTRIBUTE_ENTRY(Mech, CollisionMaterialType,   attrPad),				// 0x19
@@ -712,8 +712,8 @@ const Mech::IndexEntry
 	ATTRIBUTE_ENTRY(Mech, EyepointRotation,        eyepointRotation),		// 0x1c (real member -- the eye reads it per frame)
 	ATTRIBUTE_ENTRY(Mech, TargetReticle,           targetReticle),		// 0x1d (real Reticle struct -- task #36)
 	ATTRIBUTE_ENTRY(Mech, FootStep,                attrPad),				// 0x1e
-	ATTRIBUTE_ENTRY(Mech, AnimationState,          attrPad),				// 0x1f
+	ATTRIBUTE_ENTRY(Mech, AnimationState,          animationState),			// 0x1f real StateIndicator (audio state-watcher binds + AddAudioWatcher)
-	ATTRIBUTE_ENTRY(Mech, ReplicantAnimationState, attrPad),				// 0x20
+	ATTRIBUTE_ENTRY(Mech, ReplicantAnimationState, replicantAnimationState),	// 0x20 real StateIndicator
 	ATTRIBUTE_ENTRY(Mech, LinearSpeed,             linearSpeed),			// 0x21 (live forward speed)
 	ATTRIBUTE_ENTRY(Mech, ClimbRate,               attrPad),				// 0x22
 	ATTRIBUTE_ENTRY(Mech, AccelerationLastFrame,   attrPad),				// 0x23
@@ -910,6 +910,19 @@ Mech::Mech(
 								// emission so the window was never hit.)  Standing = 0.
 	attrPad             = 0.0f;	// shared read pad for un-populated gauge attributes
 	linearSpeed         = 0.0f;	// live forward ground speed (LinearSpeed gauge); set per frame
+	// Size the animation StateIndicators to cover clips 0..0x20 (MechAnimationState,
+	// death variants past AnimationCount=0x1d included) so SetState(state) never trips
+	// Verify(state<stateCount).  operator= copies only the counts (keeps the ctor-built
+	// watcher sockets); then seat the initial standing state.  [T2]
+	animationState          = StateIndicator(0x21);
+	animationState.SetState(0);						// StandingAnimation
+	replicantAnimationState = StateIndicator(0x21);
+	replicantAnimationState.SetState(0);
+	// CollisionState: 4 states (NoCollision/InitialHit/Slide/Rest) driven per frame
+	// from the collision walk (ProcessCollision) so impact audio fires on contact.
+	collisionState          = StateIndicator(4);	// CollisionStateCount
+	collisionState.SetState(0);						// NoCollisionState
+	collisionTemporaryState = 0;
 	radarRange          = 1000.0f;						// radar display scale (SetTargetRange is stubbed;
 														// 1km default zoom so contacts within ~500m show on
 														// the radar, vs the config maximum_range=4000 edge)

game/reconstructed/mech.hpp

@@ -829,6 +829,18 @@ protected:
 		// forward ground speed the speed readout / arc / radar consume (binary @0x81c).
 		Scalar		attrPad;
 		Scalar		linearSpeed;
+		// Real StateIndicators for the animation-state attributes (0x1f/0x20).
+		// The audio subsystem binds AudioStateWatchers to these BY NAME and calls
+		// AddAudioWatcher() on them -- so unlike the scalar gauge attrs they CANNOT
+		// share the read-only attrPad (a Scalar has no watcher chain -> the watcher
+		// register AV'd on 0xCDCDCDCD).  Driven from SetBodyAnimation so footstep/
+		// gait sounds fire on animation transitions.  [T2]
+		StateIndicator	animationState;			// 0x1f AnimationState
+		StateIndicator	replicantAnimationState;	// 0x20 ReplicantAnimationState
+		// 0x16 CollisionState -- audio binds an AudioStateWatcher here too (impact/
+		// scrape sounds).  Driven from ProcessCollision via collisionTemporaryState:
+		// NoCollision(0)/InitialHit(1)/Slide(2)/Rest(3) (RP VTV CollisionStateCount).
+		StateIndicator	collisionState;
 		// Radar/map gauge attributes (binary @0x404/0x408/0x40c/0x3f8).  The map
 		// widget reads position/angle as POINTERS into the mech's live origin, so
 		// radarLinearPosition/radarAngularPosition point at localOrigin.{linear,
@@ -1047,7 +1059,11 @@ protected:
 		int				flags;					// entity flags word (this+0x28 region)
 		Scalar			lastInflictingDamage;	// task #60: killing-blow magnitude (port-only; reuses
 												// the retired phantom `stance` slot -- feeds the kill score)
-		int				ammoState;				// @0x44c  0 none / 1 leaking / 2 dry
+		int				collisionTemporaryState;	// @0x44c  per-frame collision accumulator
+													// (0 none / 1 InitialHit / 2 Slide) -- CORRECTED from
+													// the "ammoState 0/1 leaking/2 dry" mislabel; the decomp
+													// (part_012.c:15406-15413) sets it per resolved contact,
+													// pushed into collisionState each frame.  Never read as ammo.
 		AlarmIndicator	graphicAlarm;			// body graphic-state alarm
 		EntityID		lastInflictingID;		// @0x43c  last attacker (read by DamageZone routing)
 		Logical			IsAirborne();

game/reconstructed/mech2.cpp

@@ -239,6 +239,16 @@ void
 		// binary's DAT_0050d700/704).
 		(void *)&Mech::BodyClipFinished, 0, 0);
 	bodyStateAlarm.SetLevel(state);					// FUN_0041bbd8(this+0x714, state)
+
+	// Drive the AnimationState indicators so the audio subsystem's state-watchers
+	// (footstep/gait/transition sounds) fire on every animation change.  Guarded to
+	// the constructed range (stateCount 0x21) so an out-of-range clip can't trip
+	// StateIndicator::SetState's Verify(state<stateCount).  [T2]
+	if (state >= 0 && state < 0x21)
+	{
+		animationState.SetState(state);
+		replicantAnimationState.SetState(state);
+	}
 }
 
 //

game/reconstructed/mech4.cpp

@@ -5309,7 +5309,9 @@ void
 	const int  freshBlock = isPlayer ? (gBlockCooldown <= 0.0f ? 1 : 0) : 1;
 	if (isPlayer && gBlockCooldown > 0.0f)
 		gBlockCooldown -= dt;							// decay the out-of-contact window
-	// BINARY-TAIL-DEFERRED: collisionTemporaryState = 0 here (@4aa741).
+	// Per-frame collision-state reset (@4aa741): the walk below re-accumulates it
+	// per resolved contact, then it's pushed into the collisionState StateIndicator.
+	collisionTemporaryState = 0;
 	// COLLISION-DAMAGE ECONOMY GUARD: snapshot the TRUE frame motion for the
 	// per-contact velocity restore in Mech::ProcessCollision (see mech.hpp) --
 	// the list walk below reflects worldLinearVelocity at every StaticBounce,
@@ -5328,6 +5330,12 @@ void
 	if (cols != 0)
 		ProcessCollisionList(cols, dt, old_position, &dmg);
 
+	// Push the frame's accumulated contact state into the audio-bound
+	// collisionState indicator: 0->1 on a fresh contact fires the impact sound,
+	// 1->0 when contact breaks; SetState only fires on change so a pressed-against
+	// contact plays once, not every frame.  (@4aa741 sibling of the reset above.)
+	collisionState.SetState((unsigned)collisionTemporaryState);
+
 	// 6. response policy (@4aa76c-4aab5f)
 	if (dmg.damageAmount == 0.00123f)					// crushable icon: move STANDS
 	{
@@ -5669,9 +5677,14 @@ void
 			damage->damageAmount = 0.00123f;	// walk-through sentinel 0x3aa137f4 (:15402-15404)
 	}
 
-	// BINARY-TAIL-DEFERRED: collisionTemporaryState tail (:15406-15413) --
+	// Contact-state accumulator tail (decomp part_012.c:15406-15413).  The
-	// implement together with the per-frame zero (@4aa741) and the named
+	// authentic split is InitialHit(1) vs Slide(2), keyed on the two collision
-	// StateIndicator members.
+	// floats @0x240/0x244 -- both are still fieldAt() stubs (return 0), so the
+	// Slide branch can't be computed faithfully yet.  A resolved contact IS an
+	// impact, so accumulate InitialHit(1) -- the decomp's dominant `else` branch;
+	// upgrade to the full 1-vs-2 split once 0x240/0x244 are reconstructed.  [T3]
+	if (collisionTemporaryState == 0)
+		collisionTemporaryState = 1;
 }