Classes:DynamicLight

From ZDoom Wiki
Jump to navigation Jump to search
Note: Wait! Stop! You do not need to copy this actor's code into your project! Here's why:
  1. This actor is already defined in GZDoom, there's no reason to define it again.
  2. In fact, trying to define an actor with the same name will cause an error (because it already exists).
  3. If you want to make your own version of this actor, use inheritance.
  4. Definitions for existing actors are put on the wiki for reference purpose only.
Dynamic light
Actor type Internal Game MiniOpenGLLogoIcon.png (OpenGL)
DoomEd Number None Class Name DynamicLight


Classes: DynamicLight
 →PointLight
  →PointLightAdditive
  →PointLightFlicker
  →PointLightFlickerRandom
  →PointLightPulse
  →PointLightSubtractive
  →SectorPointLight
 →SpotLight
  →SpotLightAdditive
  →SpotLightSubtractive
  →SpotLightAttenuated
  →SpotLightPulse
   →SpotLightPulseAdditive
   →SpotLightPulseSubtractive
   →SpotLightPulseAttenuated
  →SpotLightFlicker
   →SpotLightFlickerAdditive
   →SpotLightFlickerSubtractive
   →SpotLightFlickerAttenuated
  →SectorSpotLight
   →SectorSpotLightAdditive
   →SectorSpotLightSubtractive
   →SectorSpotLightAttenuated
  →SpotLightFlickerRandom
   →SpotLightFlickerRandomAdditive
   →SpotLightFlickerRandomSubtractive
   →SpotLightFlickerRandomAttenuated
 →VavoomLight
  →VavoomLightColor
  →VavoomLightWhite

The base class for all dynamic lights. Lights can be toggled on and off with Thing_Activate and Thing_Deactivate.

New lights can be created in ZScript to modify their behavior and properties dynamically.

Note, it's not possible to define or modify the actor considered the source of the light in ZScript. As such, some of the features listed below are not dynamically accessible or modifiable.

Types

GZDoom supports 3 base light types:

  • Pointlight — based on the PointLight class. These lights emit a simple spherical light.
  • Spotlight — based on the SpotLight class. These lights have a cone shape, with SpotInnerLight and SpotOuterLight fields determining the area of the cone and the sharpness of its edges.
  • Vavoom light — based on the VavoomLight class, these lights are simple versions of pointlights, with the only difference being that their Z position is used as an absolute value instead of relative to the sector's floor height. These are styled after lights in Vavoom. Normally these lights will not be useful in custom projects, and instead pointlights or spotlights can be safely used.

These lights come with various subclasses that can slightly modify their behavior and lighting.

Pointlights and spotlights can have the following behaviors:

  • standard (no special behavior)
  • pulsing (pulses smoothly between two values)
  • flickering (flickers between two values)
  • randomly flickering (flickers between two values at random intervals)
  • sector (brightness depends on the brightness of the sector)

and the following lighting modes:

  • normal
  • additive (brightness increase is additive instead of flat)
  • attenuated (appears dimmer but can interact with materials)
  • subtractive (reduces brightness instead of increasing it)

When placing lights from a map editor or attaching them to actors via GLDEFS, the corresponding light class will need to be used. However, when spawning them directly in ZScript, authors can spawn a base class (i.e. PointLight, SpotLight or VavoomLight) and then dynamically modify its fields

DynamicLight properties

  • DynamicLight.SpotInnerAngle value
The inner angle of the light. Used only for spotlights.
  • DynamicLight.SpotOuterAngle value
The outer angle of the light. Used only for spotlights.
  • DynamicLight.Type "value"
The type of the dynamic light as a string. Possible values:
  • "Point" — PointLight
  • "Pulse" — PulseLight
  • "Flicker" — FlickerLight
  • "Sector" — SectorLight
  • "RandomFlicker" — RandomFlighterLight

DynamicLight flags

  • DynamicLight.SUBTRACTIVE
Makes the light subtractive. Subtractive lights are "inverted", thus darkening the surrounding area instead of illuminating it.
Related GLDEFS keyword: subtractive 1
  • DynamicLight.ADDITIVE
Makes the light additive.
Related GLDEFS keyword: (Need more info)
  • DynamicLight.DONTLIGHTSELF
Prevents the light from illuminating the actor it's attached to.
Related GLDEFS keyword: dontlightself 1
  • DynamicLight.ATTENUATE
Makes the light attenuated. Attenuated lights can interact with materials.
Related GLDEFS keyword: attenuate 1
  • DynamicLight.NOSHADOWMAP
The dynamic light will not emit any shadowmaps on the level, which are shadows that are emitted by lights when they hit void surfaces.
Related GLDEFS keyword: noshadowmap 1
  • DynamicLight.DONTLIGHTACTORS
Stops the light from illuminating actors.
  • DynamicLight.SPOT
Related GLDEFS keyword: dontlightactors 1
  • DynamicLight.DONTLIGHTOTHERS
The light will only illuminate the actor it's attached to (effectively, the inverse of DONTLIGHTSELF).
Related GLDEFS keyword: dontlightothers 1
  • DynamicLight.DONTLIGHTMAP
The light will only illuminate actors, not geometry.
Related GLDEFS keyword: dontlightmap 1

Fields

Public

  • int args[5]
In DynamicLight-based actors the args field determines the light's color values and intensity:
  • arg[0] — red in a 0-255 range
  • arg[1] — green in a 0-255 range
  • arg[2] — blue in a 0-255 range
  • arg[3] — intensity/radius/spotlight length (depends on the type of the light)
  • arg[4] — secondary radius (used by flickering and pulsing lights only)
  • double SpotInnerAngle
The inner angle of the light. Used only for spotlights.
  • double SpotOuterAngle
The outer angle of the light. Used only for spotlights.

Private

  • private int lighttype
The type of the light. Not modifiable directly, can only be set through the DynamicLight.Type property in the Default block.
  • private int lightflags
The flags used by the light. Not modifiable directly, can only be set through flags in the Default block.

Methods

Public

  • native void SetOffset(Vector3 offset)
Sets the light's offset from its source. (Note, the source itself cannot be set from ZScript, only via GLDEFS (Verification needed))

Private

These methods cannot be called from ZScript directly.

  • private native void AttachLight()
Attaches the light to its source.
  • private native void ActivateLight()
Activates the light. This can be called indirectly by calling Activate on the light.
  • private native void DeactivateLight()
Deactivates the light. This can be called indirectly by calling Deactivate on the light.

ZScript definition

Note: The ZScript definition below is for reference and may be different in the current version of GZDoom.The most up-to-date version of this code can be found on GZDoom GitHub. 
class DynamicLight : Actor
{
	double SpotInnerAngle;
	double SpotOuterAngle;
	private int lighttype;
	private int lightflags;

	property SpotInnerAngle: SpotInnerAngle;
	property SpotOuterAngle: SpotOuterAngle;
	
	flagdef subtractive: lightflags, 0;
	flagdef additive: lightflags, 1;
	flagdef dontlightself: lightflags, 2;
	flagdef attenuate: lightflags, 3;
	flagdef noshadowmap: lightflags, 4;
	flagdef dontlightactors: lightflags, 5;
	flagdef spot: lightflags, 6;
	flagdef dontlightothers: lightflags, 7;
	flagdef dontlightmap: lightflags, 8;

	enum EArgs
	{
	   LIGHT_RED = 0,
	   LIGHT_GREEN = 1,
	   LIGHT_BLUE = 2,
	   LIGHT_INTENSITY = 3,
	   LIGHT_SECONDARY_INTENSITY = 4,
	   LIGHT_SCALE = 3,
	};

	// These are for use in A_AttachLight calls.
	enum LightFlag
	{
		LF_SUBTRACTIVE = 1,
		LF_ADDITIVE = 2,
		LF_DONTLIGHTSELF = 4,
		LF_ATTENUATE = 8,
		LF_NOSHADOWMAP = 16,
		LF_DONTLIGHTACTORS = 32,
		LF_SPOT = 64,
		LF_DONTLIGHTOTHERS = 128,
		LF_DONTLIGHTMAP = 256,
	};

	enum ELightType
	{
		PointLight,
		PulseLight,
		FlickerLight,
		RandomFlickerLight,
		SectorLight,
		DummyLight,
		ColorPulseLight,
		ColorFlickerLight, 
		RandomColorFlickerLight
	};

	native void SetOffset(Vector3 offset);
	private native void AttachLight();
	private native void ActivateLight();
	private native void DeactivateLight();

	Default
	{
		Height 0;
		Radius 0.1;
		FloatBobPhase 0;
		RenderRadius -1;
		DynamicLight.SpotInnerAngle 10;
		DynamicLight.SpotOuterAngle 25;
		+NOBLOCKMAP
		+NOGRAVITY
		+FIXMAPTHINGPOS
		+INVISIBLE
		+NOTONAUTOMAP
	}

	override void Tick()
	{
		// Lights do not call the super method.
	}
	
	override void BeginPlay()
	{
		ChangeStatNum(STAT_DLIGHT);
	}

	override void PostBeginPlay()
	{
		Super.PostBeginPlay();
		AttachLight();
		
		if (!(SpawnFlags & MTF_DORMANT))
		{
			Activate(self);
		}
	}

	override void Activate(Actor activator)
	{
		bDormant = false;
		ActivateLight();
	}

	override void Deactivate(Actor activator)
	{
		bDormant = true;
		DeactivateLight();
	}
	
}
Retrieved from "https://zdoom.org/w/index.php?title=Classes:DynamicLight&oldid=54820"