# 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 |