Lumberyard
Legacy Reference

Physics Entities

This topic references tools and features that are legacy. If you want to use legacy tools in Lumberyard Editor, disable the CryEntity Removal gem using the Project Configurator or the command line. To learn about the latest features, see the Amazon Lumberyard User Guide.

Physics entities are used to simulate physical events such as explosions, gravity fields, or wind, or to physicalize objects such as cloth, breakable entities, or ropes. Physical entities that are related to a body instead of an event are connected to an object.

The following entities can be accessed by clicking Entity, then expanding Physics on the Objects tab of the Rollup Bar.

  • AnimObject

  • BasicEntity

  • Constraint

  • DeadBody

  • GravityBox

  • GravitySphere

  • GravityValve

  • LivingEntity

  • ParticlePhysics

  • RigidBodyEx

  • Wind

  • WindArea

AnimObject

An AnimObject extends the functionality of a BasicEntity by the ability of playing pre-baked animations and physicalizing parts of the object afterwards.

AnimObject Properties

Property Description
ActivatePhysicsDist Used for objects with pre-baked physical animations (requires Articulated to be on and ActivatePhysicsThreshold to be greater than 0). Specifies the distance from the pivot after which parts automatically detach themselves from the animation and become fully physicalized. 0 disables distance-based detachment.
ActivatePhysicsThreshold Greater than 0 values are used for objects with pre-baked physical animations (requires Articulated to be on). Specifies the amount of force (in fractions of gravity) that needs to be exerted on a part for it to become detached and fully controlled by the physics.
CanTriggerAreas

Triggers when this entity enters/exits. Only applicable to AreaTriggers; ProximityTriggers triggers regardless.

DmgFactorWhenCollidingAI

Multiplier applied when dealing damage to AI.

Faction Entity faction.
InteractLargeObject

Players can trigger large object interactions (such as grab and kick) with the entity.

MissionCritical

Entity is not be hidden by explosions.

Model Defines the CGA model to be used.
Pickable Defines whether or not the object can be picked up.
SmartObjectClass

Specifies the smart object type of the object.

Usable Defines whether or not the object can be used.
UseMessage The message displayed when the object is in the crosshairs for use.
Animation
Animation Defines the animation to be played.
Loop Defines whether the animation is looped.
PhysicalizeAfterAnimation Defines whether the object is physicalized after the animation has reached its end.
playerAnimationState If set, the animation plays immediately.
Playing If set, the animation plays immediately.
Speed Playback speed of the animation sequence.
Health
Invulnerable

Object does not receive damage, but registers "Hit" output when applicable.

MaxHealth

Health of the entity, how much damage can it take before being considered "Dead" and triggering the output.

OnlyEnemyFire

Takes damage from enemy (Faction-based) fire, only if a faction is set.

MultiplayerOptions
Networked

Physics is simulated on the server and serialized over the network; otherwise, simulated on the client.

Physics
Articulated Physicalizes the character as an articulated physical entity (i.e., with bendable joints).
Density Can be used instead of Mass (if mass is -1) to set the density of each node.
Mass The overall mass for the entire model.
Physicalize Selects whether or not the model can become physicalized.
PushableByPlayers Allows the object to be pushed by players.
RigidBody If deselected, the object is static. Pre-baked physics objects must have it selected.

BasicEntity

A BasicEntity provides the simplest way of controlling objects physically. Once a model has been set, several properties can be set, defining its physical behavior. It is possible to specify either density or mass of the object. If one is specified, the other one must be set to a negative value (-1, or -0.01). Mass and density affect the way objects interact with other objects and float in the water (they sink if their density is more than that of the water). A zero-mass rigid body (with both mass and density 0) is a special case which means an "animated" rigid body (moved from outside the physics system).

The difference from a static entity is that the physics is aware that this object is actually dynamic, although it cannot simulate it directly. Note that both values describe the same physical property. When you specify mass, density is computed automatically, and vice versa. The relationship mass = density x volume is used. These computations imply that the object is solid. If a box is used to model an empty crate, one can assume that its density is a weighted average between wood density and inside air density.

BasicEntity Properties

Property Description
CanTriggerAreas Areas trigger when this entity enters/exits them. Only applicable to AreaTriggers; ProximityTriggers trigger regardless.
DmgFactorWhenCollidingAI Multiplier applied when dealing damage to AI.
Faction Entity faction.
InteractLargeObject

Players can trigger large object interactions (such as grab and kick) with the entity.

MissionCritical Entity is not be hidden by explosions. The threshold for hiding/removal is defined via the console variable g_ec_removeThreshold which is set to 20 by default. If an explosion occurs and more than 20 entities are hit by it, it keeps 20 and hides the rest for better performance. See GameRulesClientServer.cpp for more information.
Model Defines the model to be used.
Pickable

Players can grab or pick up the object.

SmartObjectClass Can be used to define AI interaction capabilities on code-side.
Usable

Entity is usable by players.

UseMessage

If useable is true, this message is displayed when players are in range. Can be a localized string such as @use_object.

Health
Invulnerable

Object does not receive damage, but registers "Hit" output when applicable.

MaxHealth

Health of the entity, how much damage can it take before being considered "Dead" and triggering the output.

OnlyEnemyFire

Takes damage from enemy (faction-based) fire, only if a faction is set.

MultiplayerOptions
Networked

Physics is simulated on the server and serialized over the network; otherwise, simulates on the client.

Physics
Density (= Mass / Volume) Density affects the way objects interact with other objects and float in the water (they sink if their density is more than that of the water). Note that both density and mass can be overridden in the asset file.
Mass (= Density * Volume) Mass is the weight of the object (the density of the object multiplied by its volume).
Physicalize If false, the object is not taken into account by physics.
PushableByPlayers It true, the player pushes the object by walking/running into it.
RigidBody False means a static entity, true - a simulated rigid body. Note that a rigid body can still behave like a static entity if it has mass 0 (set either explicitly or by unchecking RigidBodyActive). The main difference between these rigid bodies and pure statics is that the physics system knows that they can be moved by some other means (such as a track view sequence) and expects them to do so. This means that objects that are supposed to be externally animated should be mass-0 rigid bodies in order to interact properly with pure physicalized entities.

Constraint

A constraint entity can create a physical constraint between two objects. The objects are selected automatically during the first update, by sampling the environment in a sphere around the constraint object's world position with a specified radius. The "first" object (the one that will own the constraint information internally) is the lightest among the found objects, and the second is the second lightest (static objects are assumed to have infinite mass, so a static object is always heavier than a rigid body).

Constraints operate in a special "constraint frame." It can be set to be either the frame of the first constraint object (if UseEntityFrame is checked), or the frame of the constraint entity itself. In that frame, the constraint can operate either as a hinge around the x-axis, or as a ball-in-a-socket around y- and z-axes (that is, with the x-axis as the socket's normal). If x limits are set to a valid range (max>min) and the yz limits are identical (such as both ends are 0), it is the former and, if the yz limits are set and not x limits, it's the latter. If all limits are identical (remain 0, for instance), the constraint operates in a 3 degrees of freedom mode (does not constrain any rotational axes). If all limits are set, no axes are locked initially, but there are rotational limits for them.

Constraint Properties

Property Description
damping Sets the strength of the damping on an object's movement. Most objects can work with 0 damping; if an object has trouble coming to rest, try values like 0.2-0.3. Values of 0.5 and higher appear visually as overdamping. Note that when several objects are in contact, the highest damping is used for the entire group.
max_bend_torque The maximum bending torque (Currently it's only checked against for hinge constraints that have reached one of the x limits).
max_pull_force Specifies the maximum stretching force the constraint can withstand.
NoSelfCollisions Disables collision checks between the constrained objects (To be used if the constraint is enough to prevent inter-penetrations).
radius Defines spherical area to search for attachable objects.
UseEntityFrame Defines whether to use the first found object or the constraint itself as a constraint frame.
Limits
x_max If set greater than x_min, the constraint only rotates the object along its x-axis within the defined angle.
x_min See x_max.
yz_max If set greater than yz_min, the constraint only rotates the object along its yz-axis within the defined angle.
yz_min See yz_max.

DeadBody

A DeadBody entity can ragdollize characters assigned to it. As soon as a character is intended not to act any more, but to only react passively on external impacts, as if it were dead, this physical entity provides the necessary model.

A typical usage is to create the entity as non-resting, simulate it in the editor, and then save the settled physics state. Note that the entity does not react to collisions with the player, bullets, or explosions.

DeadBody Properties

Property Description
CollidesWithPlayers Defines whether the ragdoll of the entity may collide with the player (does not override the non-interactive ragdoll legal restriction)
ExtraStiff Uses the main solver to apply stiffness instead of joint springs. It can handle a lot higher stiffness values, but the downside is that the same stiffness is applied to all joint axes, including locked and limited ones.
lying_damping (0..1..10) Defines damping in the "lying" mode (which is when the ragdoll has enough contacts with the ground). Note that this is an overall damping, and there also exist per-joint dampings, set based on the asset.
mass The mass of the object.
MaxTimeStep As with other entities, decreasing it makes the simulation more stable, but makes this entity and all entities it contacts with more expensive to simulate. Can be especially useful when higher stiffness is needed.
Model Character model to be physicalized.
NoFriendlyFire If set, the entity does not react on bullet impacts from friendly units.
PoseAnim Allows to use the first frame of the specified animation as an initial pose
PushableByPlayers If set, the entity does not react on bullet impacts from friendly units.
PushableByPlayers See BasicEntity (does not override the non-interactive ragdoll legal restriction)
Resting

If set, object do not spawn in a physically 'awake' state. Instead it waits until physically interacted with first.

SmartObjectClass

Specifies the smart object type of the object.

Stiffness Stiffness with which the ragdoll tries to maintain the original pose (set either in the model or from PoseAnim). For SDK character values around 2000 are practical. Higher values can lead to stability issues, which can be overcome by either decreasing MaxTimeStep (which makes it more expensive to simulate), or using ExtraStiff mode.
Buoyancy
water_damping

A cheaper alternative/addition to water resistance (applies uniform damping when in water).

Sets the strength of the damping on an object's movement as soon as it is situated underwater. Most objects can work with 0 damping; if an object has trouble coming to rest, try values like 0.2-0.3.

Values of 0.5 and higher appear visually as overdamping. Note that when several objects are in contact, the highest damping is used for the entire group.

water_density

Can be used to override the default water density (1000). Lower values assume that the body is floating in the water that's less dense than it actually is, and thus it sinks easier.

(100..1000) This parameter could be used to specify that the object's physical geometry can leak. For instance, ground vehicles usually have quite large geometry volumes, but they are not waterproof, thus Archimedean force acting on them is less than submerged_volume 1000 (with 1000 being the actual water density).

Decreasing per-object effective water density allows such objects to sink while still having large-volume physical geometry.

Important note: If you are changing the default value (1000), it is highly recommended that you also change water_resistance in the same way (a rule of thumb might be to always keep them equal).

water_resistance

Can be used to override the default water resistance (1000). Sets how strongly the water affects the body (this applies to both water flow and neutral state).

(0..2000) Water resistance coefficient. If non-0, precise water resistance is calculated. Otherwise only water_damping (proportional to the submerged volume) is used to uniformly damp the movement. The former is somewhat slower, but not prohibitively, so it is advised to always set the water resistance.

Although water resistance is not too visible on a general object, setting it to a suitable value prevents very light objects from jumping in the water, and water flow affects things more realistically.

Note that water damping is used regardless of whether water resistance is 0, so it is better to set damping to 0 when resistance is turned on.

GravitySphere

A GravitySphere is a spherical area, which replaces the gravitational parameters of the environment. Objects reaching this area moved along the entities' Gravity vector and their own physical impact can be damped by a certain factor.

GravitySphere Properties

Property Description
Active Defines whether the entity affects its environment.
Damping Damps physical impact of entities inside the sphere.
Radius Size of the sphere.
Gravity x,y, z vector of the gravity applied to objects within the sphere.

GravityValve

A GravityValve entity performs an additional gravity into an upwards showing direction, relative to the entity.

GravityValve Properties

Property Description
Active Defines whether the entity affects its environment.
Radius Size of the affected area.
Strength Gravitational force.

Wind

A wind entity is used to simulate wind in a local position. This should not be used to create the global wind in your level.

Wind Properties

Property Description
FadeTime The time the wind entity uses to fade between disabled and enabled states.
vVelocity x,y,z vector sets the direction and strength of the wind.

WindArea

A WindArea simulates air moving with an arbitrary speed in a specific direction. It affects the flow direction of all objects and aero-form substances within the defined area, as well as vegetation bending depending on density and resistance values. If no direction is set, the wind-source moves omni-directionally from the center of the WindArea.

WindArea Properties

Property Description
Active Defines whether wind is blowing or not.
AirDensity Causes physicalized objects moving through the air to slow down, if > 0.
AirResistance Causes very light physicalized objects to experience a buoyancy force, if > 0.
Ellipsoidal Forces an ellipsoidal falloff.
FalloffInner Distance after which the distance-based falloff begins.
Speed Wind-speed in units per second.
Dir XYZ x,y,z vector of normalized wind direction.
Size XYZ x,y,z vector of affected area.

Useful Console Variables

The following console variables are useful for debugging physics entity issues:

p_draw_helpers

Same as p_draw_helpers_num, but encoded in letters Usage [Entity_Types]_[Helper_Types] - [t|s|r|R|l|i|g|a|y|e]_[g|c|b|l|t(#)] Entity Types: t - show terrain s - show static entities r - show sleeping rigid bodies R - show active rigid bodies l - show living entities i - show independent entities g - show triggers a - show areas y - show rays in RayWorldIntersection e - show explosion occlusion maps Helper Types g - show geometry c - show contact points b - show bounding boxes l - show tetrahedra lattices for breakable objects j - show structural joints (forces translucency on the main geometry) t(#) - show bounding volume trees up to the level # f(#) - only show geometries with this bit flag set (multiple f's stack) Example: p_draw_helpers larRis_g - show geometry for static, sleeping, active, independent entities and areas

p_debug_joints

If set, breakable objects log tensions at the weakest spots.