Light Entities

Area Lights are still WIP as of CRYENGINE 3.7.0. Please see related parameters below to see what is currently supported. Improved support is on-going as they're rebuilt for PBR and Tiled shading.

To use Area Lights, ensure r_DeferredShadingAreaLights is set to '1'.

Overview

The light entity is a dynamic real-time light that can be used to light a scene. For indoor areas it is essential to place proper lighting as the sun light does not light the interiors well. The light intensity of a light entity falls off linearly to the border of its radius.

Due to the increased calculation time for dynamic lights, you need to carefully place them in a scene. Deferred lights (as per default setting) are much more performance friendly but you should still use an amount within reason.

The Light entity can be found in Rollup Bar -> Entity -> Lights.

Light Properties

Property

Description

Active

Turns the light on/off.

AttenuationBulbSize

See Attentuation and Falloff for more information. When using AmbientLights, setting this value to '0' reverts to the older, non-physical attenuation model.

Radius

Specifies how far from the source the light affects the surrounding area.

Color

Diffuse

Specify the RGB diffuse color of the light.

DiffuseMultiplier

Control the strength of the diffuse color.

SpecularMultiplier

Control the strength of the specular brightness.

Options

AffectThisAreaOnly

Set this parameter to false to make light cast in multiple visareas.

AmbientLight

Makes the light behave like an ambient light source, with no point of origin.

AttenuationFalloffMax

DEPRECATED (use BulbSize)
Controls the light fall-off. This can only be used for Ambient lights. Valid range between 0.0 and 1.0. See below for examples.

deferred_clip_geom

DEPRECATED (arbitrary light clip volumes not supported on Tiled shading, Light Boxes can still be used)
This is automatically filled in when using Light Shapes to specify the boundary of the light.

DeferredClipBounds

Specifies that the light is linked to a light box or light shape and to use the volume of the target area for clipping. See Light Boxes and Light Shapes.

FakeLight

Disables light projection, useful for lights which you only want to have Flare effects from.

ForceDisableCheapLight

Forces the engine to de-classify the light as a "CheapLight", which is a memory optimization done on export for Pure Game mode.
Lights are automatically de-classified as needed, based on whether they're used in a FG, trackview, etc, so this option should never need to be used, but provided as a fail-safe.

IgnoresVisAreas

Controls whether the light should respond to visareas.

Projector

ProjectorFov

Specifies the Angle on which the light texture is projected.

ProjectorNearPlane

Set the near plane for the projector, any surfaces closer to the light source than this value will not be projected on.

Texture

Here a texture can be specified that will be projected in the direction of the Y axis of the light entity.

A light projector texture must use the LightProjector CryTif preset, be 512*512px resolution, and contain no alpha channel.

Shadows

CastShadows

Makes the light cast a shadow based on the minimum selected config spec. "High" won't work on Low/Medium, for example. To ensure shadows are always cast, set the this to 'Low Spec'.

This setting is often confused as a 'Quality' setting for the shadows, it is not a quality setting. It's a method to control what system spec the shadows should be cast on.

With tiled shading, the amount of shadow-casting lights on screen is limited by default to '12'. This is because each 4 lights requires an additional 8MB of video memory for shadow texture mapping.

The limit can be controlled with the r_ShadowCastingLightsMaxCount CVar.

ShadowBias

Moves the shadow cascade toward or away from the shadow-casting object.

ShadowMinResPercent

Specify, per-light, the percentage of the shadow pool the light should use for its shadows. Unless otherwise needed, "default" should be used for best performance vs quality.

ShadowResolutionScale

ShadowSlopeBias

Allows you to adjust the gradient (slope-based) bias used to compute the shadow bias.

ShadowUpdateMinRadius

Define the minimum radius from the light source to the player camera that the ShadowUpdateRatio setting will be ignored.

i.e; If set to 10 and the camera is less than 10m from the light source, the shadow will update normally. If further than 10m, the shadow will update as per ShadowUpdateRatio setting.

This will not work in Very High spec as Shadow Caching is disabled.

ShadowUpdateRatio

Define the update ratio for shadow maps cast from this light. The lower the value (example 0.01), the less frequent the updates will be and the more "stuttering" the shadow will appear.

This setting is enabled or disabled, depending on the ShadowUpdateMinRadius value and how far the player camera is from the light source.

This will not work in Very High spec as Shadow Caching is disabled.

Shape

PlanarLight

Used to turn the selected light entity into an Area Light. Was previously called "AreaLight".

To use Area/Planar Lights, ensure r_DeferredShadingAreaLights is set to '1'.

DiffuseSoftness

DEPRECATED (3.7.0)
Control the softness of the projected texture (must use an alpha channel). Valid range between 0.0 and 1.0. See below for examples.

LightFov

DEPRECATED (3.7.0) - Use ProjectorFov instead
Control the size/shape of the cone or "Field of View" of the light projection.

PlaneHeight

Set the height of the Area Light shape.

PlaneWidth

Set the width of the Area Light shape.

Texture

DEPRECATED (3.7.0)
Specify a texture to be projected from the light. Texture must use an alpha channel if wanting to use diffuse softness.

TextureReflection

DEPRECATED (3.7.0)
Renders the texture in the reflection, as well as in the projection (see below for example).

Style

AnimationPhase

This will start the light animation, specified with the light style property, at a different point along the sequence.
This is typically used when you have multiply lights using the same animation in the same scene, using this property will make the animations play asynchronously.

AnimationSpeed

Specifies the speed at which the light animation should play.

AttachToSun

When enabled, sets the Sun to use the Flare properties for this light.

Flare

Specify the path to the Flare Library item.

FlareEnable

Used by the Flare Editor system.

FlareFOV

Control the FOV for the flare. This control needs to be enabled in the properties for the flare itself.

LightAnimation

Trackview sequence used to animate the light.

LightStyle

Specifies the a preset animation for the light to play. Styles are defined through Light.cfx shader. Valid values are 0-48. 40-48 are Testing/Debug styles.

TimeScrubbingInTrackview

Rotation

X,Y,Z

DEPRECATED
These values can be used to apply animated rotation to the light. Values range between 0-1.

Negative Lights and Darkening Areas

In earlier revisions of CRYENGINE, lights had an option called "Negative Light". This system was removed in later revisions because a more solid implementation was introduced into the lighting system.

The idea here is to add darker/lower luminance light to the scene rather that "sucking out" the color and luminance by using negative lighting.

You can achieve better results now by using the Ambient Light option for your light. By using this option in conjunction with a dark Diffuse color, you can apply a "negative" light to your scene with much more precision and control.

3 Easy Steps:

  1. Add a Light entity.
  2. Select Ambient in the Options properties.
  3. Apply a Diffuse color of 2,2,2. Important note: If you use 0,0,0, you won't get the desired effect.

You can also apply color to this negative light, not just pure black. This also mixes well with other lights placed on top in a positive light fashion, and negative lights also stack on top of each other for the blackest of blacks!

Ambient Light OffAmbient Light OnAdditional Light Off

Attenuation and Fall Off

Since CRYENGINE 3.6, we have changed our light entities so that the falloff curve is based on a physically correct model (inverse square falloff), meaning the light value falls off exponentially.

Light in the real world never completely falls off to 0. This poses a problem in our engine, since we don’t want to have lights with an infinite radius (performance, light leaking issues, etc), and we don’t want the light to cut off at the end of the radius since there will be a noticeable cull of the light (ugly).

To combat this, light begins to falloff linearly from 80% to 100% of the radius value, which ensures that the light value reaches 0 before being culled.

AttenuationBulbSize is a value which combats the problem of lights in a 3d engine being infinitely small. This means that the light begins to fall off exponentially from the origin coordinates. AttenuationBulbSize fakes the size of the "light bulb", and thus acts as a radius for when the falloff should begin.

  • A value of 1 means that the light is at full intensity within a 1 meter ball before it begins to falloff.
  • This value is very useful for ensuring that the DiffuseMultiplier can remain at sane levels.

It becomes more important when there are objects that will be very close to the light entity. With a small AttenuationBulbSize, a nearby entity might look blown out because so much light energy is focused in such a small area before falling off rapidly.

When the AttenuationBulbSize parameter is larger, the artist can use a lower DiffuseMultiplier value, and thus have a much more natural level of light on nearby objects.

100 Bulb Size / No Falloff / Old System0.2 Bulb Size , Inverse Square Falloff, New System

Similar to EnvironmentProbes, it is recommended that you do not change the SpecularMultiplier value from 1 on Light Entities because this will affect the diffuse/specular ratio of any object in the light’s radius and will then technically not be rendered in a physically correct way.

It’s worth noting that all the Cubemap related parameters here (AttenuationFalloffMax, SortPriority) are disabled and do not function, as only EnvironmentProbes should be used for cubemap management.

It’s also worth noting that the Area Light parameters do not function properly with our current physically based shading model.

Ambient Lights

The Ambient flag behaves very differently from pre-3.6 versions of the engine. In the new workflow, ambient lights are simply multipliers for cubemap values.

For example, an ambient light with a DiffuseMultiplier of between 0 and 1 will remove ambient light from the local cubemaps.

An ambient light with a DiffuseMultiplier value above 1 will multiply the local cubemap lighting.

  • Note that Ambient lights cannot remove light provided by direct sources (ie, Sunlight, or non-ambient light entities)
  • Note that Ambient lights MUST have an AttenuationBulbSize value of 0, which ensures that the falloff model is Linear and more visually appealing.
Non-AmbientAmbient

Example Images

AttenuationFalloffMax 0AttenuationFalloffMax 0.5AttenuationFalloffMax 1
TextureReflection OffTextureReflection On
DiffuseSoftness 0DiffuseSoftness 0.5DiffuseSoftness 1
SortPriority 0SortPriority 1

DestroyableLight

The DestroyableLight entity is a special light with many additional properties enabling the setup of destroyable light settings including damage, explosion, sounds, and physics.

Two different models are specified for the base model and broken model.

To use the entity, simply place it in a level via RollupBar -> Entities -> Lights -> DestroyableLight.

The light entity before it is destroyed

Destroyed, disabled and broken into pieces

Property

Description

TurnedOn

Turns the entity on/off.

LightProperties_Base

Radius

Specifies how far from the source the light affects the surrounding.

UseThisLight

Turns the Base_Light on/off.

Color

Diffuse

The diffuse color of the light can be specified here.

DiffuseMultiplier

To make the light brighter this diffuse multiplier can be used.

HDRDynamic

Specifies how much brighter than the default 255,255,255 white the light is. Sun light set in the Time of Day tool is 3 times brighter, for example.

SpecularMultiplier

Multiplies the specular color brighter, use to adjust brightness.

Options

AffectThisAreaOnly

Set this parameter to false to make lights other visarea.

CastShadows

Makes the light cast a shadow based on the config spec.

DeferredLight

Enables/disables the light as a deferred light.

FakeLight

Only applies corona effects but does not dynamically light the surroundings.

GlowSubmatId

GlowSubmatId is used to control the glow intensity of the destructible lights (for instance, destructible street light).

IgnoreGeomCaster

Used in conjunction with the Cast Shadows option. When Cast Shadows is set to true, setting this tick box will prevent the model attached to the light from obstructing the light.

ViewDistRatio

Value used to set the draw distance of the light.

Projector

ProjectInAllDirs

Makes the light shine omni-directionally.

ProjectorFov

Specifies the Angle on which the light texture is projected.

ProjectorNearPlane

ProjectNearPlane is used to clip the light projector from the light source, so the light doesn't affect certain objects near the light source.

Texture

Here a texture can be specified that will be projected in the direction of the y axis of the light entity.

Style

AnimationPhase

This will start the light animation, specified with the light style property, at a different point along the sequence.

This is typically used when you have multiply lights using the same animation in the same scene, using this property will make the animations play asynchronously.

AnimationSpeed

Specifies the speed at which the light animation should play.

CoronaDistIntensityFactor

Specifies how bright the corona effect is in the distance.

CoronaDistFactor

Specifies how big the corona effect is in the distance.

CoronaScale

Specifies how big the corona effect is. NOTE: To apply a corona to a light entity you need to assign the light a suitable material and the material should use the Light.Flare shader.

LightStyle

Specifies the a preset animation for the light to play.

Rotation

X,Y,Z

DEPRECATED - These values can be used to apply animated rotation to the light. Values range between 0-1.

Test

FillLight

Obsolete.

vDirection

X,Y,Z

Change the direction of the entity light. Used with projector lights this defines which direction the light will be projected. Valid values are -1,0,1.

vOffset

X,Y,Z

Offset of the light from the pivot of the entity. This defines where the light entity will be spawned.

LightProperties_Destroyed

Radius

Specifies how far from the source the light affects the surrounding.

UseThisLight

Turns the Destroyed_Light on/off.

Color

Diffuse

The diffuse color of the light can be specified here.

DiffuseMultiplier

To make the light brighter this diffuse multiplier can be used.

HDRDynamic

Specifies how much brighter than the default 256,256,256 white the light is. (sunlight set in the time of day window is for example 3 times brighter).

SpecularMultiplier

Multiplies the specular color brighter, use to adjust brightness.

Options

AffectThisAreaOnly

Set this parameter to false to make lights other visarea.

CastShadows

Makes the light cast a shadow based on the config spec.

DeferredLight

Enables/disables the light as a deferred light.

FakeLight

Only applies corona effects but does not dynamically light the surroundings.

IgnoreGeomCaster

Used in conjunction with the Cast Shadows option. When Cast Shadows is set to true, setting this tick box will prevent the model attached to the light from obstructing the light.

GlowSubmatId

Set which sub-material in the model material should be used as the glow material.

UsedInRealTime

Specifies if the light is a real-time light or not.

ViewDistRatio

Value used to set the draw distance of the light.

Projector

ProjectInAllDirs

Makes the light shine omni-directionally.

ProjectorFov

Specifies the Angle on which the light texture is projected.

ProjectorNearPlane

ProjectNearPlane is used to clip the light projector from the light source, so the light doesn't affect certain objects near the light source.

Texture

Here a texture can be specified that will be projected in the direction of the y axis of the light entity.

Style

AnimationPhase

This will start the light animation, specified with the light style property, at a different point along the sequence.

This is typically used when you have multiply lights using the same animation in the same scene, using this property will make the animations play asynchronously.

AnimationSpeed

Specifies the speed at which the light animation should play.

CoronaDistIntensityFactor

Specifies how bright the corona effect is in the distance.

CoronaDistFactor

Specifies how big the corona effect is in the distance.

CoronaScale

Specifies how big the corona effect is.

LightStyle

Specifies the frequency at which the light is blinking.

Rotation

X,Y,Z

DEPRECATED - These values can be used to apply animated rotation to the light. Values range between 0-1.

Test

FillLight

Obsolete.

NegativeLight

This will make the light object actually remove light from an area. Can be used to darken specific areas.

vDirection

X,Y,Z

Change the direction of the entity. This defines which direction the entity will be faced.

vOffset

X,Y,Z

Offset of the pivot of the entity. This defines where the entity will be spawned.

Entity Properties

Faction

Select which AI faction the entity belongs to.

Pickable

When set, the object can be picked up.

Usable

When set, the object will activate when actioned by the player.

UseMessage

When an object is marked as usable this text will appear on the screen to indicate the player what to do with it, or what happens when you interact with it.

Breakage

ExplodeImpulse

Sets the impulse with which the destruction particles will be spawned.

LifeTime

Sets the lifetime of the destruction particles.

SurfaceEffects

When disabled no destruction particles will be spawned.

Damage

DamageThreshhold

Damage below the threshold set here will be ignored.

Explode

Determines whether or not the entity should explode. True/False.

Health

Health of the entity, how much damage can it take before exploding/breaking.

PlayerOnly

If true the light can only be damaged by players.

DamageMultipliers

Bullet

Multiplies the damage inflicted by bullets.

Collision

Multiplies the damage inflicted by collisions.

Explosion

Damage

Damage dealt to nearby objects.

Decal

Decal being projected to the ground, on explosion.

Delay

Time to wait until the effect is played.

Effect

Name of the effect to be played if the object is destroyed.

EffectScale

Size of the effect.

HoleSize

Size of the hole being cut into objects around the explosion.

MinPhysRadius

Lower boundary of the explosion falloff effects for physical objects that are not players/AI.

MinRadius

Lower boundary of the explosion falloff effects for players/AI.

PhysRadius

Upper boundary of the explosion falloff effects for physical objects that are not players/AI.

Pressure

Used for physical simulation of the explosion.

Radius

Upper boundary of the explosion falloff effects for players/AI.

TerrainHoleSize

Obsolete.

DelayEffect

Effect

A particle effect.

HasDelayEffect

If selected the effect will be played with delay.

Params

AttachForm

If AttachType is non-blank, this property determines where particles emit from the attached geometry. Set it to Vertices, Edges, Surface, or Volume.

AttachType

If this entity is attached to a parent entity, as described above, this field can be used to cause particles to emit from the entity's geometry.
Set it to one of these string values (heeding case):

  • blank: Emit from the effect origin, as normal.
  • BoundingBox: Emit from the parent effect's bounding box.
  • Physics: Emit from the parent effect's physics geometry.
  • Render: Emit from the parent effect's render geometry.

CountPerUnit

(flag) If AttachType is non-blank, this multiples the particle count by the "extent" of the attached geometry.
Depending on AttachForm, the extent is either total vertex count, edge length, surface area, or volume.

CountScale

Multiples the particle counts of the entire effect.

Prime

(flag) If true, and the assigned ParticleEffect is immortal, causes the emitter to start "primed" to its equilibrium state, rather than starting up from scratch.
Very useful for placed effects such as fires or waterfalls, which are supposed to be already running when the level starts. Applies only to immortal, not mortal effects. Defaults to true.

Scale

Multiplies the overall size and velocity of the entire effect.

SizePerUnit

(flag) Currently ignored

SpawnPeriod

(or PulsePeriod): If not 0, restarts the effect continually at this interval. This property should be used to create effects that pulse on and off at somewhat large intervals, a second or so.
Do not set a low value such as 0.1 to try to make an instant effect into a continuous one. That method is inefficient, framerate-dependent, and won't look as good as it should.
Instead, make sure the actual library effect is set Continuous and has an appropriate Count.

vOffset

Offset from light entity in local space.

vRotation

Rotation from light entity, as angles in local space.

Direction

Direction of the explosion.

vOffset

Offset of the explosion from the light entity in local space.

Health

Invulnerable

If true the light cannot be damaged.

MaxHealth

Maximum (and initial) health value.

OnlyEnemyFire

If true the light cannot be damaged by friendly fire.

Model

Model

The CGF model to use for the primary, non-destroyed model.

ModelDestroyed

The CGF model for the broken pieces.

SubObject_Name

If the model has sub-models, specifies the unbroken piece name.

SubObject_NameDestroyed

If the model has sub-models, specifies the broken piece name.

Physics

ActivateOnDamage

Activates a rigid body with RigidBodyActive=0, when it receives damage.

CanBreakOthers

True if the entity can break jointed objects by colliding with them (provided they overcome the strength limit). BasicEntities have this flag off unconditionally.

Density

(= Volume/Mass) Affects the way the objects interact with other objects and float in the water (they sink if their density is more than that of the water).

Mass

(= Density*Volume) The weight of the object (the density of the object multiplied by its volume).

PushableByPlayers

When set, the object can be moved by the player.

RigidBody

Determines whether the original "Main" object is physicalized; if not, it's static.

RigidBodyActive

Indicates that the object is a RigidBody, but initially it is immovable; instead, it can be later activated by an event.

RigidBodyAfterDeath

Determines whether the remaining "Remain" object is physicalized; if not, it's static.

Simulation

damping

(0..3) This sets the strength of 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 over-damping. Note that when several objects are in contact, the highest damping is used for the entire group.

max_time_step

(0.005..0.1) This sets the maximum time step the entity is allowed to make (defaults to 0.01).
Smaller time steps increase stability (can be required for long and thin objects, for instance), but are more expensive.
Each time the physical world is requested to make a step, the objects that have their maxsteps smaller than the requested one, slice the big step into smaller chunks and perform several sub-steps.
If several objects are in contact, the smallest max_time_step is used.

sleep_speed

(0.01..0.3) If the object's kinetic energy falls below some limit over several frames, the object is considered to be sleeping. This limit is proportional to the square of the sleep speed value.
A sleep speed of 0.01 loosely corresponds to the object's center moving at a velocity of the order of 1 cm/s.

Sounds

AISoundRadius

Units to which distance the sounds can be heard.

Alive

Sound event to be played as long as the object is in the "Alive" state.

Dead

Sound event to be played as long as the object is in the "Dead" state.

Dying

Sound event to be played if the object is changed from the "Alive" state to the "Dead" state.

StopSoundsOnDestroyed

Stops playing sounds once the object has been broken/destroyed. Used, for instance, for a radio.

Vulnerability

Bullet

When set, the object will take damage from bullets.

Collision

When set, the object will take damage from impact with other objects.

Explosion

When set, the object will take damage from explosions.

Melee

When set, the object will take damage from melee hits.

Other

When set, the object will take damage from other damage sources.