DPT_ProceduralMechanicalDrive

Component Reference Guide
A generic, data-driven companion component designed to mathematically translate, rotate, scale, and apply gravity-aligned pendulum physics to cosmetic secondary sub-assemblies in perfect synchronization with a weapon's core tracking state.

Quick Navigation Reference: Inspector Properties Technical Architecture Assembly Configurations Troubleshooting Support

Inspector Property Configuration Tables

Mechanical Asset Elements Array

Processes an array of MechanicalElement blocks targeting distinct cosmetic sub-mesh objects within the prefab hierarchy.

Property	Description
Element Label	A descriptive text string used to organize and name array entries within the Unity Inspector layout for easy modification.
Target Transform	The scene reference to the moving sub-mesh geometry container (e.g., a gear, crank, worm screw, bellows, or counterweight arm).
Tracking Source	Determines whether the element responds directly to the weapon's vertical pitch (`Elevation`) or horizontal yaw (`Traverse`).
Drive Mode	The mathematical behavior calculation type applied to this asset: `ContinuousRotation`: Spins infinitely matching pitch shifts times a gear ratio value. Ideal for handwheels and winding drums. `MappedRotation`: Smoothly lerps between a baseline and a maximum angle boundary. Ideal for torsion limbs or lever linkages. `MappedTranslation`: Shifts lineally down a local axis vector using spatial interpolation. Ideal for telescopic elevation screws or piston rods. `MappedScale`: Rescales geometry continuously along a selected local axis vector. Ideal for mechanical tension springs, ropes, or leather air bellows.
Local Axis	The local direction vector (directional mask) along or around which transformation modifications are processed.
Multiplier	The physical scaling factor. Serves as a gear ratio multiplier for rotations (in degrees), indicates the maximum travel displacement window for translations (in meters), or maps dimensional extension ratios for geometric scaling.

Gravity Aligned Elements (Pendulums)

Calculates dynamic physics-based sway and downward alignment for objects that must hang freely (counterweights, slings, lanterns).

Property	Description
Label	A string used to identify this specific pendulum. Critical for targeting this element via Unity Events or Animation Events using `PausePendulumByLabel`.
Target Transform	The hanging object that will be driven by the procedural gravity alignment. Should typically be an empty parent transform.
Sway Sensitivity	How aggressively the weight swings in reaction to world-space movement. Use negative values to invert the momentum direction.
Gravity Tension & Damping	Tension controls how powerfully the object is pulled back toward true downward resting alignment. Damping dictates how quickly the oscillating swing settles to a complete stop.
Swing Clamps & Locks	`Max Swing Angle X/Z` bounds the oscillation limits to prevent clipping through frames. `Disable Z Rotation` restricts movement entirely to a 2D planar pitch.
Animated Child	If the Animator drives a child object (e.g., visual ropes) while this script drives the un-animated parent pivot, assign the child here. Enables perfect positional handoffs when transitioning from pre-baked animations back to procedural physics.
Recovery Duration	The duration in seconds used to perform a smooth spherical interpolation (Slerp) from the Animator's final frame back into the procedural downward gravity state, eliminating visual popping.

Wheel Configurations

Manages automated wheel rotations for mobile platforms, integrating both straight translation metrics and rotational spot-turn deltas.

Property	Description
Left Wheels	An array of transforms representing all wheels assigned to the left track side of the chassis frame structure.
Right Wheels	An array of transforms representing all wheels assigned to the right track side of the chassis frame structure.
Wheel Diameter	The literal bounding distance of the wheel meshes in meters. This is critical for exact algebraic wheel rolling translations without visual ground slippage.
Track Width	The lateral distance measured between the left and right wheel sets. Controls the differential velocity calculations during stationary spot turns.

Locomotion Audio Dynamic Settings

Controls the integrated real-time dynamic locomotion loop channel. Audio functions independently of weapon actions to prevent audio cut-offs or clip context overwriting bugs.

Property	Description
Loop Source	Explicit inspector assignment slot for the secondary `AudioSource` dedicated to structural movement. Populating this ensures that the core weapon script does not overwrite the travel loop during firing sequence calls. If left unassigned, fallback logic hooks an existing secondary source or appends a new one dynamically.
Locomotion Loop	The seamless audio asset clip representing continuous chassis translation friction (heavy wood creaking, iron rim grinding, structural straining).
Max Audio Speed	The true travel velocity threshold (m/s) at which the looping channel reaches its maximum volume and pitch parameters. Default: 4 m/s.
Audio Volume Smoothing	The interpolation factor governing how rapidly the audio's volume and pitch values respond to abrupt velocity adjustments or sudden braking stamps. Default: 5.

Mechanical Aim Audio Setup

Manages the continuous operational tracking soundscape for turret traversal and barrel elevation adjustments, isolating aiming feedback from discrete action triggers.

Property	Description
Aim Source	Explicit inspector assignment slot for the dedicated aiming `AudioSource` component. Isolating continuous rotation audio on this channel prevents tracking modifications from disrupting or cutting off primary actions like weapon fire and reloading triggers. If unassigned, an independent instance is generated automatically on initialization.
Aim Loop	The seamless looping audio asset clip representing mechanical friction, internal gear grinding, iron crank strain, or structural pressure during active weapon adjustments.
Aim Audio Smoothing	The interpolation smoothing speed controlling how dynamically the audio loop scales its volume and pitch envelopes between active tracking and full stops. Prevents sudden audio pops or abrupt cuts. Default: 8.

Technical Architecture

Composition via Companion Scripting: Decouples purely aesthetic mechanical mesh logic from gameplay tracking engines (firing arrays, health loops, input listeners). It sits on the same object layer as a companion add-on, eliminating code modifications when creating unique visual styles.
Procedural Gravity & Animation Handoffs (The Baton Pass): Solves the notorious "Double Gravity" conflict where an Animator and script fight for transform control. Using PausePendulumByLabel instantly wipes the script's gravity calculation and resets the parent transform to its clean prefab state, allowing the Animator to execute Firing sequences completely unimpeded on the child object.
Seamless Slerp Recovery: Upon triggering ResumePendulumByLabel, the script isolates the exact world rotation of the animated child mesh on the final frame of the animation clip. It then applies a SmoothStep spherical lerp over the defined Recovery Duration, melting the pre-baked animation follow-through flawlessly back into dynamic gravity.
Drift Elimination Matrix: Securely caches structural anchors (initialLocalPosition, initialLocalRotation, and initialLocalScale) on initialization. This ensures calculations are always bound back to baseline spatial matrices, preventing compounding precision drift errors caused by delta float updates.
Differential Tracking Engine: Uses a Vector3.Dot operation against the transform's forward vector to track linear distance traveled, combined with a Mathf.DeltaAngle calculation to determine angular turning offsets. This merges track vectors into an accurate, non-slip rolling sequence.
Fixed-Angle Launcher Fallback Matrix: Features an automated operational loop when evaluating an elevation tracking target source. If the parent weapon lacks an explicit elevationPivot reference but uses variable launch speeds, the script switches calculations to map the element's rotation to a flat 360-degree sweep scaled by the active power factor calculation profile (t * 360f). This handles crank-handle rotations accurately on fixed-chassis artillery like trebuchets or mortars where winding power scales distance.
Real-Time Kinematic Audio Pipeline: Samples world space positional translations every frame to calculate accurate velocity independent of input event calls. Volume envelopes scale from 0 to 1 based on velocity relative to maxAudioSpeed, while pitch curves bend dynamically (from 0.75× up to 1.25×) to mimic weight changes before dampening to full silence when stationary.
Isolated Multi-Channel Audio Orchestration: Establishes separate, dedicated AudioSource components for translation wheels and targeting gear loops. By pulling continuous tracking sound updates completely out of the core weapon logic, this architecture guarantees that ongoing manual adjustments never prematurely clip or clobber discrete gameplay audio states like firing explosions or reloading clips.
Teleportation Clamp Safeguard: Monitors step deltas inside the tracking loops. If a coordinate movement exceeds a squared magnitude boundary of 25f (such as when a weapon system fires a ResetWeapon() execution layout), calculations temporarily suspend to freeze the wheels and mute audio, eliminating instantaneous hyper-spin visual glitches or auditory bursts.
Automatic Destruction Gate: Continuously checks the main component status state loop. Updates automatically sleep if the tracking system switches into a Destroyed state, turning off looping audio immediately so separate debris fragment rigidbodies can fall and shatter naturally.

Practical Assembly Configurations

Because the mechanical driver relies on a single generic script, you can easily replicate distinct ancient weapon physics setups natively in the Inspector without creating unique C# dependencies.

Mobile Cannon Setup Example:

Attach the script to your cannon prefab alongside the main DPT_SiegeWeapon script component.
Assign your chassis hubs to the Left Wheels and Right Wheels arrays, setting your exact asset metrics for Wheel Diameter and Track Width.
Explicitly assign secondary audio source components to both the Loop Source and Aim Source property slots.
Provide your seamless wood-creaking loop clip to the Locomotion Loop slot, and assign a gear grinding or crank tension loop to the Aim Loop property slot.
Add an element block for the Handwheel: Set Drive Mode to ContinuousRotation, Local Axis to 1, 0, 0 (Local Right), and Multiplier to 5. This spins the wheel rapidly to match subtle muzzle tracking adjustments.
Add an element block for the underlying Worm Screw Support: Set Drive Mode to MappedTranslation, Local Axis to 0, 1, 0 (Local Up), and Multiplier to 0.25. This causes the block to extend and slide upward exactly as the cannon barrel depresses downward into lower pitch angles.

Torsion Catapult Setup Example:

Add an array slot for the main Throwing Arm Tensioner Ropes: Set Drive Mode to MappedScale, Local Axis to 0, 0, 1 (Local Forward), and Multiplier to 0.3. This stretches the visual coil meshes along their axis as target range increases, indicating rope torsion.
Add an array slot for the side Winch Crank Wheel: Set Drive Mode to ContinuousRotation, Local Axis to -1, 0, 0 (Inverted Local Left), and Multiplier to 6. This handles spinning opposite mechanical fixtures smoothly.
Assign an operational wood-strain friction audio loop into the Aim Loop parameter field to output accurate acoustic creaks as the winch cranks the arm backwards into its firing position.

Trebuchet Sling (Gravity + Animator) Setup Example:

Ensure a layered hierarchy: Arm -> Sling_Pivot (Empty) -> Sling_Ropes (Animated Visuals).
In the Pendulums array, assign Sling_Pivot to the Target Transform, and Sling_Ropes to the Animated Child. Set Recovery Duration to 0.25.
In the weapon's Unity Events, link the onFireEvent to PausePendulumByLabel, passing your sling's string label.
Link the onFireCompleteEvent (or onIdle/onReload) to ResumePendulumByLabel, passing the same label.
In your Animator, ensure the Transition Duration returning to Idle from Firing is set to exactly 0 seconds.

Troubleshooting Notes

"My sling mesh points backward or has 'double rotation' applied when the script is on."

This is "Double Gravity". The script is pointing the parent downward, and your idle animation is simultaneously pointing the child downward, causing the rotations to stack. Remove rotation keyframes from the child during the Idle/Loaded animations, or set them strictly to 0,0,0. The script will handle the downward gravity on the parent.

"The pendulum violently snaps or jumps when transitioning from the Firing animation back to Idle."

Ensure you have populated the Animated Child slot so the script knows where the mesh ended its swing. Verify your Recovery Duration is greater than zero, and most importantly, check the Unity Animator to ensure the Transition Duration leaving the Firing state is set to 0 seconds. The physics script must handle the visual smoothing, not the Animator.

"Handwheels are turning in the wrong direction during pitch shifts"

Invert the sign of your Multiplier property (e.g., change 5 to -5) or flip the alignment values of your Local Axis property input fields inside the Inspector window.

"Chassis wheels are rolling backward when the platform travels forward"

By default, the script rotates wheel components along their local relative Vector3.right axis. Ensure your individual wheel meshes are modeled with their pivot forwards facing the exact same direction as the main vehicle chassis parent structure.

"Chassis wheels slip or spin too fast during tight turns"

Increase the value within your Track Width input field. If this value is too narrow relative to your physical asset layout, turn deltas overwrite linear vectors too aggressively, inducing visual slip.

"Locomotion or aiming audio cuts off or pops instantly when the weapon fires or finishes reloading"

Verify that you have explicit, separate components assigned to both the Loop Source and Aim Source slots. If left empty and the script automatically falls back to sharing a channel with the main weapon script, structural action cues will overwrite continuous mechanical looping feedback.

"Elevation screws or scale objects are jumping out of alignment or clipping through frames"

Ensure your target components have their initial pivot locations set cleanly in your modeling software. The script uses the starting layout location inside your Unity scene view as baseline coordinate anchors, meaning offsetting child groups manually can skew linear movement paths.

"A component isn't moving at all when changing power parameters on fixed artillery"

Verify that your parent weapon has its power options configured correctly. If minLaunchSpeed and maxLaunchSpeed possess identical metrics on a weapon without a physical elevation pivot, your interpolation fallback ratio cannot resolve and returns a flat value of zero.

Support, Contact & Custom Integration

For all technical assistance, bug reports, asset configuration help, and general support, please reach out via email using the Contact Form. This is the primary and most reliable way to get help with any problems you encounter with the packages.

You can also use this form to inquire about custom freelance technical art services. If your project requires external 3D models to be integrated into the DPT ecosystem—including bespoke vertex-data packing, procedural wood grain mapping, GPU wind systems, or game-ready LOD budgeting—get in touch to discuss your specific needs and availability.

Email Contact (Preferred for all Support):
For troubleshooting, bug reports, publisher licensing, and freelance inquiries, please use the Contact Form on the DPT Games Hub.

DPT Community Discord:
While the contact form is the best way to get direct help with issues, you are also welcome to join the Discord Server to share feedback and connect with other users.