Combined light entities

Introduction

Many complex objects in game are build from more than one entity. Others consist of only one entity, but represent different things at the same time.

For instance, a candle consists of two entity: the candle stub, and an attached flame object.

The flame object itself consists of only one entity, but this entity both emits light, sound and particles as well as reacts to stimuli like fire and water.

This article deals with the complex entities consisting of more than one entity.

Two ways

There are two ways to attach two entities together:

• the entityDef (inside a .def file) can specify to spawn and attach a new entity when the first entity is spawned. This typical happens at map loading time, but can also happen later in game when a new base entity is spawned. This is from here one called "def_attached" due to the spawnarg being responsible: def_attach.
• the mapper can manually add both entities in the map, and then arrange them in the editor so they look bound together. We refer to this from here on as "the manual way".

The second way has several disadvantages but also advantages:

Disadvantages:

1. manually arranging the entities is error prone, f.i. often candle flames would hover over the candle, or be slightly offset
2. Moving the entities in the map must always move both in sync, or 1. happens.
3. when creating a moveable entity, the mapper must also take care that the second entity moves with the first by binding them together manually
4. Changing the color of all attached flames is cumbersome, as you need to modify each of them. With the def_attached method, you can simple edit the entityDef file or overwrite this entity with your own definition.

Advantages:

1. Both entities are present in the editor, and can thus be seen. (For combined entities, DR will hopefully later automatically show a dashed outline for any automatically attached entities, making this point moot).
2. Since the attached entity is already in the editor, its name is known, so it can be easily targeted by scripts and have spawnargs set on it. This is the main disadvantage of def_attaching entities and we see later how we can overcome it.

This article, however, deals primarily with the first way.

Example entities

Candle and Flame

Here is an example how a flame is attached to a candle:

    // attach the light, so the candle can be re-lit by fire stims
    "def_attach"            "light_candleflame_unlit"
    "pos_attach"            "flame"         // At the attach point called "flame"...
    "attach_pos_name_1"     "flame"         // ... which is defined here.
    "name_attach"           "flame"         // Set a name to pass along spawnargs
    "attach_pos_origin_1"   "0 0 15"        // Offset the flame X units in the Z direction

The name_attach is the name of the attachment, which will be important for later when setting spawnargs.

Holder and Candle (and Flame)

Here is an example entity attaching a candle (which itself has an attached flame) to a candle holder:

/* skinny tall */

entityDef atdm:moveable_candle_holder_plus_skinny_tall_candle
{
    "inherit"               "atdm:moveable_candle_holder_base"
    "mass"                  "1.5"

    "editor_usage"          "A candle holder with an unlit tall & skinny candle."

    // attach the candle
    "def_attach"            "atdm:moveable_candle_skinny_tall"
    "pos_attach"            "candle"        // At the attach point called "candle"...
    "attach_pos_name_1"     "candle"        // ... which is defined here.
    "name_attach"           "candle"        // Set a name to pass along spawnargs
    "attach_pos_origin_1"   "0 0 17.5"      // Offset the candle X units in the Z direction
}

Modifying the attached entity/entities

When you place a combined entity (f.i. candle+flame) in your map, you only see the base entity, in this case the candle. However, to switch the candle off or on, you would need to link some entity (like a switch or trigger) to the candle flame entity. Likewise, if you want to change the color of the flame, you would need to set the "_color" spawnarg on the flame.

But since the candle flame does not exist yet, you can't. Here is how you can overcome this:

Targeting the (invisible) entity

Simple target the base entity, like the holder or the candle. When triggered, these know how to extingusish or light all attached flames (even tho they don't exist at map load).

Note: sombody please test that that actually works!

Using a script to turn lights off/on

There are three special global script functions that you can use to manipulate attached light entities when you only know the base entity:

  frob_light_holder_light( holder );         # turn the light on
  frob_light_holder_ext( holder );           # turn the light off
  frob_light_holder_toggle_light( holder );  # toggle light (if on => off, if off => on)

Note: These functions are called without an object and take as first argument the base entity.

Example:

void light_on( entity zone )
  {
  entity holder = sys.getEntity( "stone_room_light" );
  if (holder)
    {
    // We need to tell the holder to turn off the bound light (as we do
    // not know what the bound light entity is named)
    frob_light_holder_light( holder );
    }
  }

Note: Don't call these functions this way:

  holder.frob_light_holder_light(); # WRONG!

Setting spawnargs

Setting a spawnarg on the attached entity is simply done by setting the spawnarg set SPAWNARGNAME on ATTACHMENTNAME on the base entity. SPAWNARGNAME is the name of the spawnarg, while the attachment name can be looked up in the entityDef for the base entity, e.g. in DR by checking the "Show inherited" in the entity inspector.

Here is an example, changing the color of the attached flame:

 "set _color on flame" "0.2 0.2 0.9"

In DR, enter the spawnarg name and value without the quotes. The above setting will set the spawnarg '_color' on any entity attached that has the attachement name 'light' to "0.2 0.2 09", thus coloring the light blue.

The ATTACHMENTNAME is defined as name_attach spawnarg on either the base entity or one of its attached entities.