Map object reference (XG)

From Doomsday Wiki
Jump to: navigation, search

What is a reference?

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.

Reference anatomy

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.

Type

Data component

Reference classification

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

Object references

Line → lightlevel

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.

Name Summary
none Refers to nothing. Has a special meaning depending on the context.
my The referring line's front sector's light level.
back The referring line's back sector's light level.
original The original light level set when the map is loaded.
current The current light level.
highest The highest light level among the adjoining sectors.
lowest The lowest light level among the adjoining sectors.
next_highest The next highest light level among the adjoining sectors.
next_lowest The next lowest light level among the adjoining sectors.

Line → line

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.

Name Summary
none Refers to nothing. Has a special meaning depending on the context.
self The referenced line itself.
tagged All lines whose tag matches the data component.
line_tagged All lines whose tag number matches that of the referring line.
act_tagged All lines whose act tag matches the data component.
index The one specific line whose index number matches the data component.
all All lines in the map.

Line → plane

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.

Name Summary
none Refers to nothing. Has a special meaning depending on the context.
special Meaning depends on the context (documented by line type).

Floor plane

my_floor The referring line's front sector's floor plane.
back_floor The referring line's back sector's floor plane.
tagged_floors All floor planes in all sectors whose tag matches the data component.
line_tagged_floors All floor planes in all sectors whose tag matches that of the referring line.
act_tagged_floors All floor planes in all sectors whose act tag matches the data component.
index_floor Floor plane of the one sector whose index matches the data component.
all_floors All floor planes in the map.
thing_exist_floors All floor planes of all sectors which currently have at least one of a mobj type within them.
thing_noexist_floors All floor planes of all sectors which currently do not have any of a mobj type within them.

Ceiling plane

my_ceiling The referring line's front sector's ceiling plane.
back_ceiling The referring line's back sector's ceiling plane.
tagged_ceilings All ceiling planes in all sectors whose tag matches the data component.
line_tagged_ceilings All ceiling planes in all sectors whose tag matches that of the referring line.
act_tagged_ceilings All ceiling planes in all sectors whose act tag matches the data component.
index_ceiling Ceiling plane of the one sector whose index matches the data component.
all_ceilings All ceiling planes in the map.
thing_exist_ceilings All ceiling planes of all sectors which currently have at least one of a mobj type within them.
thing_noexist_ceilings All ceiling planes of all sectors which currently do not have any of a mobj type within them.

Line → sector

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.

Name Summary
none Refers to nothing. Has a special meaning depending on the context.
my The referring line's front sector.
tagged All sectors whose tag matches the data component.
line_tagged All sectors whose tag matches the referring line's tag.
act_tagged All sectors whose act tag matches the data component.
index The one sector whose index matches the data component.
all All sectors in the map.
back The referring line's back sector.
thing_exist All sectors which currently have at least one of a mobj type within them.
thing_noexist All sectors which currently do not have any of a mobj type within them.

Sector → plane

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.

Name Summary
none Reference to nothing. With some line classes this type of reference has a special meaning.
special Has a special meaning that depends on the context.

Floor plane

my_floor The referring line's front sector's floor plane.
back_floor The referring line's back sector's floor plane.
original_floor The original floor height of the referring sector.
current_floor The current floor height of the referring sector.
highest_floor The highest floor plane of the adjoining sectors.
lowest_floor The lowest floor plane of the adjoining sectors.
next_highest_floor The next highest floor plane of the adjoining sectors.
next_lowest_floor The next lowest floor plane of the adjoining sectors.
sector_tagged_floor All floor planes of all sectors whose tag matches that of the referring sector.
line_tagged_floor All floor planes of all sectors whose tag matches that of the referring line.
tagged_floor All floor planes of all sectors whose tag matches the data component.
line_act_tagged_floor All floor planes of all sectors whose act tag matches the referring line's tag.
act_tagged_floor All floor planes of all sectors whose act tag matches the data component.
index_floor The floor plane of the one specific sector whose index matches the data component.

Ceiling plane

my_ceiling The referring line's front sector's ceiling plane.
back_ceiling The referring line's back sector's ceiling plane.
original_ceiling The original ceiling height of the referring sector.
current_ceiling The current ceiling height of the referring sector.
highest_ceiling The highest ceiling plane of the adjoining sectors.
lowest_ceiling The lowest ceiling plane of the adjoining sectors.
next_highest_ceiling The next highest ceiling plane of the adjoining sectors.
next_lowest_ceiling The next lowest ceiling plane of the adjoining sectors.
sector_tagged_ceiling All ceiling planes of all sectors whose tag matches that of the referring sector.
line_tagged_ceiling All ceiling planes of all sectors whose tag number matches the referring line's tag.
tagged_ceiling All ceiling planes of all sectors whose tag matches the data component.
line_act_tagged_ceiling All ceiling planes of all sectors whose act tag matches the referring line's tag.
act_tagged_ceiling All ceiling planes of all sectors whose act tag matches the data component.
index_ceiling The ceiling plane of the one specific sector whose index matches the data component.

Property evaluation

min_bottom_texture Refers to the specific Z coordinate of the height that is calculated by finding the lower texture with the smallest height (Y) of a sector's all lines and then adding this texture height to the lowest contacted floor height (Z coordinate).
min_mid_texture Refers to the specific Z coordinate of the height that is calculated by finding the middle texture with the smallest height (Y) of a sector's all lines and then adding this texture height to the highest contacted floor height (Z coordinate).
min_top_texture Refers to the specific Z coordinate of the height that is calculated by finding the upper texture with the smallest height (Y) of a sector's all lines and then subtracting this texture height from the highest contacted ceiling height (Z coordinate).
max_bottom_texture Refers to the specific Z coordinate of the height that is calculated by finding the lower texture with the largest height (Y) of a sector's all lines and then adding this texture height to the lowest contacted floor height (Z coordinate).
max_mid_texture Refers to the specific Z coordinate of the height that is calculated by finding the middle texture with the largest height (Y) of a sector's all lines and then adding this texture height to the highest contacted floor height (Z coordinate).
max_top_texture Refers to the specific Z coordinate of the height that is calculated by finding the upper texture with the largest height (Y) of a sector's all lines and then subtracting this texture height from the highest contacted ceiling height (Z coordinate).

Property references

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 :: property

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.

Name Summary
none Refers to nothing. Has a special meaning depending on the context.
id Unique index number.
special special.
tag tag.
acttag act tag.
count Internal count.
angle Physical angle in the map coordinate space.
length Physical length in the map coordinate space.
top_offsetx Material X offset of the front side's top section.
top_offsety Material Y offset of the front side's top section.
middle_offsetx Material X offset of the front side's middle section.
middle_offsety Material Y offset of the front side's middle section.
bottom_offsetx Material X offset of the front side's bottom section.
bottom_offsety Material Y offset of the front side's bottom section.

This is an exemplary article. It is considered to follow the DEW documentation guidelines in such a way that it serves as an example of good practices.