# Beams¶

Beams are springs of varying properties that transmit forces between nodes. A flexible physical structure is created when many beams are used to interconnect nodes in a mesh or lattice like network. The primary properties of beam are their spring and damp values which will determine, along with the geometry of the beam network, how the structure will respond to applied forces.

In any given structure of nodes and beams there is a stability limit, where too much spring or damp in the beams will cause the structure to vibrate unnaturally or explode. The amount of spring and damp thata beam can have is depending primarily on the mass of the nodes on each and, and how many other beams are connecting to those same nodes. Too stiff of a beam, or too many beams connecting to one node can cause instability.

Beams can be visualized using the vehicle debug options menu (make sure to enable advanced functions in the options/user interface menu) or by pressing CTRL+B to cycle visualization modes.

Terminology todo: Free length Length ratio Expansion Compression

## Normal Beams¶

Normal beams have a constant spring and damping rate. They are the simplest and most efficient beam type, and they should be used for the majority of the vehicle structure.

### Arguments¶

Name Type Required/Default Range Description
beamSpring Float 4300000 >=0 The spring constant in N/m
beamDamp Float 580 >=0 The damping constant in N/m/s
beamDeform Float 220000 >=0 The force in N over which the beams free length will permanently deform
beamStrength Float FLT_MAX >=0 The force * strain at which the beam completely breaks
deformLimit Float FLT_MAX 0-1 Limits the deformation to a certain length ratio
deformLimitExpansion Float FLT_MAX >=1 Limits the deformation to a certain length ratio in expansion only
precompression Float 1 >=0 Modifies the free length of the beam after spawning (as a length ratio)
precompressionTime Float 0 >=0 The time taken for the beam to reach the precompressed free length
precompressionRange Float 0 R Modifies the free length of the beam after spawning (m) (overwrites Precompression!)
breakGroup String nil na Creates groups of beams where if one breaks, all in the group will be forced to break
breakGroupType Int 0 0 or 1 Type 1 means a beam will be broken by the group, but will not trigger the breakage
deformGroup String nil na Creates groups of beams where deformation triggers material switching or other damage
deformationTriggerRatio Float nil >0 Changes the deformation ratio at which a deformGroup is triggered
dampCutoffHz Float nil >0 Enables frequency limited damping
optional Bool FALSE na If true, disables warnings for missing, duplicate, zero length beams

## Bounded Beams¶

Bounded beams have an upper and lower bound length which can be used to ramp the spring and damp values in a piecewise linear fashion. Useful for limiting both the compression and expansion of a beam or for simulating materials with non linear properties, ie a suspension bump stop. They also have velocity sensitive damping properties useful for replicating a car’s suspension dampers.

### Arguments¶

Bounded beams can use all the parameters of normal beams plus the following:

Name Type Required/Default Range Description
beamDampRebound Float beamDamp >=0 Damping (N/m/s) in expansion direction
beamDampVelocitySplit Float FLT_MAX >=0 Velocity (m/s) where damping transitions to fast values
beamDampFast Float beamDamp >=0 Damping (N/m/s) beyond velocitySplit
beamDampReboundFast Float beamDampRebound >=0 Damping (N/m/s) beyond velocitySplit in expansion direction
longBound Float 1 >=0 Expansion ratio where the spring and damping begins transition to limit values
shortBound Float 1 >=0 Compression ratio where the spring and damping begins transition to limit values
beamLimitSpring Float 1 >=0 Final spring value that the beam approaches beyond the bound
beamLimitDamp Float 1 >=0 Final damping value that the beam approaches beyond the bound
beamLimitDampRebound Float beamLimitDamp >=0 Final damping value that the beam approaches beyond the bound in expansion direction
boundZone Float 1 >=0 Distance (m) over which values transition to limit values
longBoundRange Float nil >=0 Expansion distance (m) where the spring and damping begins transition to limit values
shortBoundRange Float nil >=0 Compression distance (m) where the spring and damping begins transition to limit values

## Anisotropic Beams¶

Anisotropic beams have non-linearity in extension only. They are typically used to limit expansion of the structure.

### Arguments¶

Anisotropic beams can use all the parameters of normal beams plus the following:

Name Type Required/Default Range Description
springExpansion Float beamSpring >=0 Final spring value in expansion
dampExpansion Float beamDamp >=0 Final damping value in expansion
transitionZone Float 0 >=0 Distance (m) over which the values transition to expansion values
longBound Float FLT_MAX >=0 Expansion ratio where the beam automatically breaks
longBoundExtent Float nil >=0 Expansion distance (m) where the beam automatically breaks

## Support Beams¶

Support beams have resistance in compression only, and break after expanding beyond a specified length.

### Arguments¶

Support beams can use all the parameters of normal beams plus the following:

Name Type Required/Default Range Description
longBound Float FLT_MAX >=0 Expansion ratio where the beam automatically breaks
longBoundExtent Float FLT_MAX >=0 Expansion distance (m) where the beam automatically breaks

## Pressured Beams¶

Pressured beams replicate an air spring with its non-linear spring rate.

### Arguments¶

Pressured beams can use all the parameters of normal beams plus the following:

Name Type Required/Default Range Description
pressure Float 308167.71 (30psi + 1 atm) The starting pressure of the beam in Pa (abs)
pressurePSI Float 30psi + 1atm The starting pressure of the beam (psi) (overrides pressure)
surface Float 1 The acting surface area of the cylinder piston
volumeCoef Float 1 The linearity of the force curve
maxPressure Float FLT_MAX The maximum pressure limit (Pa)
maxPressurePSI Float FLT_MAX The maximum pressure limit (psi)

Note: Pressured beams do not have dampCutoffHz functionality!

## L Beams¶

L beams replicate a simplistic angular spring by measuring the angle at a 3rd node. An L-beam must be defined with a 3rd node like so:

"beams": [
["id1:", "id2:"],
["node1","node3"],
["node2","node3"],
["node1","node2",{"beamType":"|LBEAM","id3:":"node3"}],
],


There must already be beams going from the 1st and 2nd node to the 3rd node for the L-beam to be created.

The 1st and 2nd nodes are the ends of the “L”. The 3rd node defines the “knee” in the L shape. The L beam only applies a force between node 1 and 2 if the angle at 3 changes.

### Arguments¶

L beams have a limited set of parameters:

Name Type Required/Default Range Description
id3 String required Name of the 3rd node
beamSpring Float 4300000 Spring constant (N/m)
springExpansion Float beamSpring Spring constant (N/m) in expansion
beamDamp Float 580 Damping rate (N/m/s)
dampExpansion Float beamDamp Damping rate (N/m/s) in expansion direction
precompression Float 1 Modifies the free length of the beam after spawning (as a length ratio)
dampCutoffHz Float nil Enables frequency limited damping
optional Float FALSE If true, disables warnings for missing, duplicate, zero length beams