Attached Effects

Attached Effects

Attaching an Effect

Most effects can now be attached to most objects with geometry – vehicles, soldiers, and items, for instance, in addition to props. This is done in the odf using the following standard tags:

AttachDynamic = “1”

AttachOdf = “<odf_name>”

AttachToHardpoint = “<hardpoint_name>”

AttachEffect = “<fx_name>”

AttachToHardpoint = “<hardpoint> [respawn_delay_min] [_max]”

Each AttachToHardpoint tag will create one instance of the last effect declared with AttachOdf or AttachEffect, attached to the specified hardpoint.

Effects may also include additional parameters controlling respawning – if no parameters follow, it will only spawn once; if one parameter follows, the effect will respawn after it dies after the given delay in seconds; if two, the effect will respawn after it dies after a random delay in the given range.

If an attached effect must remain attached to a moving or animated object, you must include the tag AttachDynamic = “1”.

Effect types

• EntityLight
  • Type: ODF (use AttachODF to attach) or FX (AttachEffect)
  • ODF parameters match FX parameters:
    • Color = “<red> <green> <blue> [alpha]”
    • Color(<red>, <green>, <blue>[, <alpha>]);
      • Colors channels are specified in the range 0 – 255
      • Ex. “255 128 0” is bright orange.
      • Alpha simply multiplies all channels, allowing you to modulate the brightness without distorting the hue.
      • Ex. “255 128 0 128” is orange, but has one half the brightness.
    • OmniRadius = “<radius>”
    • OmniRadius(<radius>);
      • Sets the range of the lighting system point light associated with this EntityLight.
      • Radius 0.0 will turn off the point light, but leave the light beam and flare part of the EntityLight active.
    • Static = “1”
    • Static(1);
      • If specified, the lighting system will assume this light has already been burned into the terrain and any vertex lit objects in the area. It will only affect non-vertex lit objects like vehicles and soldiers.
    • ConeLength = “<length>”
    • ConeLength(<length>);
      • Sets the light beam effect for this EntityLight to be cone shaped with the specified length in meters before the final fade out.
    • ConeWidth = “<width_x> [width_z]”
    • ConeWidth(<width_X>[, <width_z>]);
      • Sets the light beam effect to be cone shaped with the specified width in meters at the far end.
      • If width_z is not specified, the beam will be round. If width_z is included and is different from width_x, the beam will be elliptical and will appear narrower or wider depending on which side it is viewed from.
    • ConeInitialWidth = “<width_x> [width_z]”
    • ConeInitialWidth(<width_X>[, <width_z>]);
      • Sets the light beam effect to be cone shaped with the specified with in meters at the light source end.
      • If width_z is not specified, the beam will be round. If width_z is included and is different from width_x, the beam will be elliptical and will appear narrower or wider depending on which side it is viewed from.
    • ConeFadeLength = “<factor>”
    • ConeFadeLength(<factor>);
      • Sets the light beam effect to be cone shaped with the given percentage of the length used for fading out, between 0.0 and 1.0.
      • Defaults to 0.2. Larger values will create a rounder end; smaller values will create a squarer end.
    • ConeFadeFactor = “<factor>”
    • ConeFadeFactor(<factor>);
      • Sets the light beam effect to be cone shaped with the given intensity fade factor at ConeFadeLength from the light source end, between 0.0 and 1.0.
      • Defaults to 0.2. Larger values will create a sharper or looking end on the beam.
    • HaloRadius = “<radius>”
    • HaloRadius(<radius>);
      • Sets the light beam effect to be halo shaped – i.e. round regardless of the view direction – with the given radius in meters before the final fade out.
    • HaloFadeLength = “<factor>”
    • HaloFadeLength(<factor>);
      • Sets the light beam effect to be halo shaped with the given percentage of the length used for fading out, between 0.0 and 1.0.
      • Defaults to 0.5. Larger values will enlarge the bright center with a correspondingly smaller fade out band.
    • HaloFadeFactor = “<factor>”
    • HaloFadeFactor(<factor>);
      • Sets the light beam effect to be cone shaped with the given intensity fade factor at HaloFadeLength from the center, between 0.0 and 1.0.
      • Defaults to 0.2. Larger values will brighten the halo in the ring between the center and the outside edge.
    • BeamIntensity = “<factor>” (XBOX/PC only)
    • BeamIntensity(<factor>);
      • Sets the brightness of the light beam effect, independently of the point light or light flare effect, from 0.0 to 1.0.
    • FlareIntensity = “<factor>”
    • FlareIntensity(<factor>);
      • Sets the brightness of the light flare effect, independently of the light beam effect and point light, from 0.0 to 1.0.
    • FlickerType = “<type>”
    • FlickerType(“<type>”);
      • Sets this light to animate its brightness over time using a number of stock animations:
        • Strobe – toggle on/off every period seconds
        • StrobeRandom – toggle on/off after a random number of seconds from 0.0 to period.
        • StrobeFade – turn on and fade out (in 2 seconds) every period seconds.
        • Pulse – fade in and out every period seconds.
        • Flicker – flicker in a torch-like pattern. Longer periods will result in a slower flicker.
        • None – disable animation
    • FlickerPeriod = “<time>”
    • FlickerPeriod(<time>);
      • Sets the period of the flicker effect specified by FlickerType. In general, a smaller period results in faster animation.
    • DrawDistance = “<distance>”
    • DrawDistance(<distance>);
      • Sets the distance at which this light beam will fade out. EntityLights always fade out by the end of the near scene, but may fade out sooner if needed.
  • Example: worlds/hot/odf/hothlight2.odf – an elliptical light beam

[GameObjectClass]                           

ClassLabel   = "Light"

[Properties]

Color    = "65 65 30"

ConeLength   = 8

ConeWidth    = "4.0 6.0"

ConeInitialWidth    = "0.8 3.0"

ConeFadeFactor    = 0.3

ConeFadeLength     = 0.1

FlareIntensity    = 0

FlickerType     = 0

FlickerPeriod    = 1.0

OmniRadius     = 0

• Example: the same converted to fx format:

EntityLight(“hothlight2”)

{

Color(65, 65, 30);

ConeLength(8);

ConeWidth(4.0, 6.0);

ConeInitialWidth(0.8, 3.0);

ConeFadeFactor(0.3);

ConeFadeLength(0.1);

FlareIntensity(0);

FlickerType(0);

FlickerPeriod(1.0);

OmniRadius(0);

      }

• LightBeam
  • Type: FX (AttachEffect)
  • Config parameters:
    • Position(<x>, <y>, <z>);
      • Sets the head (light source end) position of the light beam in meters.
      • Default is (0.0, 0.0, 0.0), the attachment point.
    • Length(<length>);
      • Sets this light beam to be cone shaped with the given length.
    • Direction(<x>, <y>, <z>);
      • Sets this light beam to be cone shaped, aligned along the given axis.
      • Defaults to (0.0, 1.0, 0.0) – the Y axis
    • TailPosition(<x>, <y>, <z>);
      • Sets this light beam to be cone shaped and sets the tail (far end) position of the light beam in meters.
      • Use as an alternative to Direction, Length to attach a beam to a target.
    • Color(<r>, <g>, <b> [, <a>]);
      • Sets the color of this light beam. Color channels are specified from 0 to 255.
      • Alpha modulates the brightness.
    • DrawDistance(<distance>);
      • Sets the distance at which this light beam will fade out.
      • Light beams always fade out by the end of the near scene, but may be faded sooner with this parameter.
    • InitialWidth(<x> [, <z>]);
      • Sets the width of this light beam at the light source end in meters. If z is not specified, the light beam will be elliptical – it’s width will be narrower when viewed from some angles.
      • For halo shaped light beams, this only sets the size of the associated light flare, and z is ignored.
    • FinalWidth(<x> [, <z>]);
      • Sets the width of this light beam at the far end in meters. If z is not specified, the light beam will be elliptical – it’s width will be narrower when viewed from some angles.
      • For halo shaped light beams, this sets the size of the halo. Z is ignored, as all halos are always round.
    • FadeLength(<length>);
      • Sets the length of the fade out of this light beam in meters. The total length (or radius) of a light beam is Length + FadeLength.
      • Defaults to 1.0 meter.
    • FadeFactor(<factor>);
      • Sets the relative intensity of the light beam at the start of the fade out, from 0.0 to 1.0.
      • Defaults to 0.2.
    • FlareIntensity(<factor>);
      • Sets the relative intensity of the light flare associated with the light beam, from 0.0 to 1.0.
    • BeamIntensity(<factor>); (XBOX/PC only)
      • Sets the relative intensity of the light beam, from 0.0 to 1.0, without affecting the light flare intensity.

• FlareAngle(<angle>); (XBOX/PC only)
  • Sets the angle in degrees from the axis within which the flare associated with a cone shaped beam is visible.
• Example file: (could be in my_light_beam.fx, or part of a world .fx file – if not in a world .fx file, the name of the file must match the name of the effect in order for req files to be generated properly)

LightBeam(“my_light_beam”)

{

              Color(255, 128, 0);

              Length(8.0);

              InitialWidth(1.0, 0.5);              // elliptical start

              FinalWidth(4.0, 2.0);              // elliptical end             

}

• LensFlare
  • Type: FX (AttachEffect)
  • Config parameters:
    • Size(<size>);
      • Sets the size of this lens flare.
      • Defaults to 1.0.
    • Color(<r>, <g>, <b> [, <a>]);
      • Sets the color of this lens flare. Color channels are specified from 0 to 255.
      • Alpha modulates the brightness.
    • DrawDistance(<distance>);
      • Sets the distance at which this lens flare will fade out.
      • Lens flares always fade out by the end of the near scene, but may be faded sooner with this parameter.
  • Example file: (could be in my_lens_flare.fx or part of a world .fx file – if not in a world .fx file, the name of the file must match the name of the effect in order for req files to be generated properly)

LensFlare(“my_lens_flare”)

{

              Color(255, 128, 0);

              Size(1.0);

}