References are one of the fundamental building blocks of the xg system, in fact, just about every time you create a new line or sector_type you will need to use at least one of them.

Every time a line needs to perform an action on either itself, a sector, another line or something else, a reference is needed. For example a switch that opens a door needs some way of knowing which door it should open when triggered. This is when a reference is used.

With doom's built in line_specials this is typically done with tags, so that the lines and sectors sharing the same tag will participate in the execution of some special action.

In order to provide extended functionality, lines, planes (floors and ceilings) and sectors need to refer to each other in some way. In XG, this concept is abstracted using references.

All references are composed of two parts: a type and a data component. However, most types of reference have no use for the data component.

Complete listing of all available XG references. The type of reference you use depends on the object types which are to interact.

Light level references or lightrefs are used when xg_lines need to refer to the light_levels of sectors. When using lightrefs a set of sectors or planes has usually already been targeted.

Lightrefs do not use the data component.

Line references or lrefs are line to line references. They are used when a line needs to refer to a line or a group of lines.

Line-plane references or lprefs are line to plane references. They are used when a line needs to refer to a plane or a group of planes.

Line-sector references or lsrefs are line to sector references. They are used when a line needs to refer to a sector or a group of sectors.

Sector-plane references or sprefs are sector to plane references. They are used when line_types need to reference one or more planes in special and/or comparative ways.

Sprefs are most often used to refer to the height (Z coordinate) of a material among the referenced surfaces. When using sprefs a set of sectors or planes have usually already been targeted via another reference.

Property references are a little different to object references. Rather than referencing another object they are used to obtain a value from a specific property of an already referenced object. If a parameter of a line class can be logically resolved by interpreting a using a property value reference, it can be determined dynamically for the reference object(s) instead of specifying it statically in a line type definition.

One potential usage of this functionality would be a line type which upon activation, ends the current map and sets the next map in the current progression according to a value specified with a line's top material offset (interpreting it as a logical map index).

Property references are commonly used in Boom in a method it calls “property overloading”.

Line data references or ldrefs are line property references. They are typically used in combination with an lref as the target reference to refer to a property of the line.