BeamNG levels use two main local light object classes:

• PointLight
• SpotLight

Both inherit common behavior from LightBase, but they emit light differently and use different default physical units.

PointLight emits light in all directions, while SpotLight emits light in a cone.

Overview

Use PointLight for omnidirectional sources such as bulbs, lamps, small glow sources, or area-like fill lights.

Use SpotLight for directional sources such as headlights, flashlights, street lamps, spot lamps, and projected beam patterns.

PointLight example

{
  "class": "PointLight",
  "name": "garage_bulb",
  "position": [10, 20, 3],
  "rotationMatrix": [1,0,0,0,1,0,0,0,1],
  "color": [1, 0.86, 0.65, 1],
  "intensity": 800,
  "intensityUnit": "lm",
  "radius": 12,
  "castShadows": false,
  "isEnabled": true
}

SpotLight example

{
  "class": "SpotLight",
  "name": "street_lamp",
  "position": [10, 20, 6],
  "rotationMatrix": [1,0,0,0,1,0,0,0,1],
  "color": [1, 0.86, 0.65, 1],
  "intensity": 25000,
  "intensityUnit": "cd",
  "range": 35,
  "innerAngle": 35,
  "outerAngle": 65,
  "castShadows": true,
  "isEnabled": true
}

Common LightBase fields

These fields are shared by both PointLight and SpotLight.

Some renderer/light-manager-specific fields may be injected at runtime or exposed by editor tools depending on the active renderer.

Physical intensity

Modern lighting should use intensity with a physical unit.

PointLight

PointLight uses lumens by default.

"intensity": 800,
"intensityUnit": "lm"

Lumens describe total emitted luminous flux in all directions.

This is useful for sources like:

• Light bulbs
• Lamps
• Small omnidirectional lights
• Interior lights

SpotLight

SpotLight uses candelas by default.

"intensity": 25000,
"intensityUnit": "cd"

Candelas describe directional luminous intensity.

This is useful for:

• Headlights
• Street lamps
• Flashlights
• Spotlights
• Projectors

Legacy brightness

The brightness field exists for compatibility with older content.

Modern content should use:

"intensity": 1000,
"intensityUnit": "lm"

or:

"intensity": 1000,
"intensityUnit": "cd"

instead of relying on brightness.

Color

Light color is stored as linear RGBA:

"color": [1, 0.86, 0.65, 1]

For realistic lights, use color temperature/Kelvin controls in the editor when possible.

Typical examples:

PointLight

PointLight emits light in all directions from a point.

It is best for lights that should illuminate evenly around the source.

PointLight fields

Example:

{
  "class": "PointLight",
  "name": "interior_light",
  "position": [0, 0, 2],
  "intensity": 400,
  "intensityUnit": "lm",
  "radius": 8,
  "color": [1, 0.82, 0.6, 1]
}

radius

radius defines how far the light is allowed to contribute.

"radius": 8

The light still uses inverse squared falloff. The radius only limits/clamps the light’s effective range.

Large radius values can increase cost because the light affects more objects and pixels.

When to use PointLight

Use PointLight for:

• Small bulbs
• Interior lamps
• Decorative lights
• Omnidirectional light sources
• Local fill lights
• Small glowing props that need actual illumination

Avoid using point lights for directional beams such as headlights or street lamps. Use SpotLight instead.

SpotLight

SpotLight emits light in a cone.

It is best for lights that have a clear direction and beam shape.

SpotLight fields

Example:

{
  "class": "SpotLight",
  "name": "headlight_left",
  "position": [0.9, 2.4, 0.6],
  "intensity": 45000,
  "intensityUnit": "cd",
  "range": 120,
  "innerAngle": 12,
  "outerAngle": 45,
  "color": [1, 0.92, 0.78, 1]
}

range

range defines how far the spotlight cone extends.

"range": 35

Like PointLight.radius, this clamps contribution range. It does not create non-physical falloff.

innerAngle and outerAngle

The spotlight cone is controlled by two angles:

"innerAngle": 35,
"outerAngle": 65

• Inside innerAngle, the light is at full cone intensity.
• Between innerAngle and outerAngle, the light fades out.
• Outside outerAngle, the light does not contribute.

innerAngle is clamped so it cannot be greater than outerAngle.

Cone angle and intensity

When using candelas, the intensity represents directional brightness and is not reduced by changing cone angle.

When using lumens, the emitted luminous flux is distributed across the cone. A wider cone spreads the same light over a larger area.

When to use SpotLight

Use SpotLight for:

• Vehicle headlights
• Street lamps
• Flashlights
• Spot lamps
• Lamps with reflectors
• Directional area illumination
• Lights using cookies or IES-derived beam patterns

Shadows

Both PointLight and SpotLight can cast shadows:

"castShadows": true

Shadows improve realism but are expensive.

Use shadow-casting lights carefully, especially if there are many lights in the scene.

Good candidates for shadows:

• Street lamps
• Headlights
• interior lights
• Large gameplay-relevant lights

Poor candidates:

• Tiny decorative bulbs
• Distant lights
• Lights that barely affect visible geometry

Priority

priority helps the light manager decide which lights are more important.

"priority": 1

Higher-priority lights are preferred when the renderer needs to sort or limit light influence.

Use higher priority for important gameplay or visual lights, and lower priority for decorative lights.

Light cookies

Spotlights can use cookie textures to shape their beam.

A cookie masks the light spatially:

• White = full light
• 50% gray = about 50% light
• Black = no light

Cookies are useful for:

• Headlight patterns
• Street lamp optics
• Window/gobo projections
• IES-derived beam shapes

Example:

"cookie": "/levels/example/art/lights/streetlamp_cookie.color.png"

IES profiles

IES files can be converted into cookie textures using the IES Cookie Importer.

The generated cookie texture represents the measured light distribution pattern, while the light intensity remains controlled by lumens or candelas.

Useful for:

• Street lights
• Architectural lights
• Industrial lights
• Real-world lamp fixtures

See Physically Based Lighting for more information about IES profiles and cookies.

Light animation

Lights can reference LightAnimData through animationType.

Example:

{
  "animate": true,
  "animationType": "FlickerLightAnim",
  "animationPeriod": 5,
  "animationPhase": 0.25
}

Light animation can affect properties such as:

• Brightness
• Position offset
• Rotation

Common uses:

• Flickering bulbs
• Fire light
• Warning lights
• Pulsing lights
• Rotating beacons

animationPhase is useful to offset multiple lights so they do not all animate identically.

Light flares

Lights can reference LightFlareData through flareType.

Example:

{
  "flareType": "LightFlareExample0",
  "flareScale": 1
}

Flares are visual screen-space/lens-style effects. They do not add real illumination.

Use flares for:

• Bright lamps
• Sun glare
• Headlights
• Signals
• Distant bright lights

Avoid relying on flares to fake lighting. Use actual light intensity for illumination.

Editor visualization

When a light is selected, the editor can display its shape:

• PointLight shows a sphere using radius
• SpotLight shows a cone using range and outerAngle

The visualization helps understand what area the light affects.

Scale behavior

PointLight and SpotLight remove normal object scale from the inspector because their size is controlled by light-specific fields:

Internally, editor scaling may modify these fields, but serialized content should use the explicit light fields.

Performance notes

Local lights can be expensive depending on:

• Number of lights
• Light range/radius
• Shadow casting
• Screen coverage
• Overlapping lights
• Cookies/flares
• Reflection passes
• Lighting quality settings

General rules:

• Keep radius/range as small as reasonable.
• Disable shadows unless needed.
• Avoid many overlapping large lights.
• Use cookies for shape, not for brute-force brightness.
• Prefer physically correct intensity and exposure instead of overbright hacks.

Best practices

• Use PointLight for omnidirectional lights.
• Use SpotLight for directional beams.
• Use lumens for point lights.
• Use candelas for spotlights.
• Keep range/radius realistic and limited.
• Use Kelvin/color temperature for natural colors.
• Use cookies for beam shape.
• Use IES-derived cookies for real fixture patterns.
• Avoid many shadow-casting local lights.
• Use priority for important lights.
• Test lighting with auto exposure and different times of day.
• Prefer physical values over legacy brightness.

Common issues

Light does not appear

Possible causes:

• isEnabled is false
• intensity is too low
• Wrong intensityUnit
• Radius/range too small
• Exposure makes it appear dim
• Light is outside visible area
• Graphics settings limit lighting

Light is too dim

Check:

• Physical intensity value
• Exposure / auto exposure
• Range/radius
• Cone angle
• Cookie texture
• Surface distance

Spotlight points in the wrong direction

Check the object rotation. SpotLight uses its transform direction to aim the cone.

Shadows are missing

Possible causes:

• castShadows is false
• Shadow quality settings are low
• Light type/settings do not support shadows in current mode
• Object does not cast/receive shadows
• Light is too far or too low priority

Cookie does not work

Possible causes:

• Invalid cookie path
• Texture is not grayscale/appropriate
• Cookie assigned to unsupported light usage
• Light is not a spotlight
• Cookie is too dark

Flares appear but scene is not lit

Flares are visual effects only. Increase the actual light intensity or add a real light source.

Too much performance cost

Reduce:

• Number of active lights
• Radius/range
• Shadow-casting lights
• Large overlapping lights
• Cookie/flare use where unnecessary

Summary

PointLight and SpotLight are the main local light classes used in levels.

• PointLight emits in all directions and uses lumens by default.
• SpotLight emits in a cone and uses candelas by default.
• Both support color, physical intensity, shadows, priority, animation, and flares.
• Spotlights can use cookies/IES-derived textures for realistic beam shapes.

Use physically based values, realistic ranges, and limited shadow casting for the best balance between quality and performance.

For a level-wide nighttime workflow, see Night Lighting .