User Tools

Site Tools


xg:map_object_reference

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
xg:map_object_reference [2019-11-26 09:11] – [Line → property] skyjakexg:map_object_reference [2021-01-22 15:09] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +====== XG map object cross-referencing ======
 +
 +===== 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_type|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_special]]s this is typically done with [[tag]]s, 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, [[plane]]s (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.
 +
 +
 +
 +===== Reference classification =====
 +
 +
 +Complete listing of all available XG references. The type of reference you use depends on the object types which are to interact.
 +
 +
 +
 +==== Line → lightlevel ====
 +
 +
 +//Light level references// or //lightrefs// are used when [[xg_line]]s need to refer to the [[light_level]]s of [[sector]]s. When using lightrefs a set of sectors or [[plane]]s has usually already been targeted.
 +
 +Lightrefs do not use the [[data component]].
 +
 +^ Name^ Summary |
 +| [[.refs:lightref_none|none]]| Refers to nothing. Has a special meaning depending on the context. |
 +| [[.refs:lightref_my|my]]| The referring line's front sector's light level. |
 +| [[.refs:lightref_back|back]]| The referring line's back sector's light level. |
 +| [[.refs:lightref_original|original]]| The original light level set when the map is loaded. |
 +| [[.refs:lightref_current|current]]| The current light level. |
 +| [[.refs:lightref_highest|highest]]| The highest light level among the adjoining sectors. |
 +| [[.refs:lightref_lowest|lowest]]| The lowest light level among the adjoining sectors. |
 +| [[.refs:lightref_next_highest|next_highest]]| The next highest light level among the adjoining sectors. |
 +| [[.refs:lightref_next_lowest|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 |
 +| [[.refs:lref_none|none]]| Refers to nothing. Has a special meaning depending on the context. |
 +| [[.refs:lref_self|self]]| The referenced line itself. |
 +| [[.refs:lref_tagged|tagged]]| All lines whose tag matches the [[data component]]. |
 +| [[.refs:lref_line_tagged|line_tagged]]| All lines whose tag number matches that of the referring line. |
 +| [[.refs:lref_act_tagged|act_tagged]]| All lines whose [[activation_tag|act tag]] matches the [[data component]]. |
 +| [[.refs:lref_index|index]]| The one specific line whose index number matches the [[data component]]. |
 +| [[.refs:lref_all|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 |
 +| [[.refs:lpref_none|none]]| Refers to nothing. Has a special meaning depending on the context. |
 +| [[.refs:lpref_special|special]]| Meaning depends on the context (documented by line type). |
 +| ||
 +^ Floor plane ||
 +| [[.refs:lpref_my_floor|my_floor]]| The referring line's front sector's floor plane. |
 +| [[.refs:lpref_back_floor|back_floor]]| The referring line's back sector's floor plane. |
 +| [[.refs:lpref_tagged_floors|tagged_floors]]| All floor planes in all sectors whose tag matches the [[data component]]. |
 +| [[.refs:lpref_line_tagged_floors|line_tagged_floors]]| All floor planes in all sectors whose tag matches that of the referring line. |
 +| [[.refs:lpref_act_tagged_floors|act_tagged_floors]]| All floor planes in all sectors whose [[activation_tag|act tag]] matches the [[data component]]. |
 +| [[.refs:lpref_index_floor|index_floor]]| Floor plane of the one sector whose index matches the [[data component]]. |
 +| [[.refs:lpref_all_floors|all_floors]]| All floor planes in the map. |
 +| [[.refs:lpref_thing_exist_floors|thing_exist_floors]]| All floor planes of all sectors which currently have at least one of a mobj type within them. |
 +| [[.refs:lpref_thing_noexist_floors|thing_noexist_floors]]| All floor planes of all sectors which currently do not have any of a mobj type within them. |
 +| ||
 +^ Ceiling plane ||
 +| [[.refs:lpref_my_ceiling|my_ceiling]]| The referring line's front sector's ceiling plane. |
 +| [[.refs:lpref_back_ceiling|back_ceiling]]| The referring line's back sector's ceiling plane. |
 +| [[.refs:lpref_tagged_ceilings|tagged_ceilings]]| All ceiling planes in all sectors whose tag matches the [[data component]]. |
 +| [[.refs:lpref_line_tagged_ceilings|line_tagged_ceilings]]| All ceiling planes in all sectors whose tag matches that of the referring line. |
 +| [[.refs:lpref_act_tagged_ceilings|act_tagged_ceilings]]| All ceiling planes in all sectors whose [[activation_tag|act tag]] matches the [[data component]]. |
 +| [[.refs:lpref_index_ceiling|index_ceiling]]| Ceiling plane of the one sector whose index matches the [[data component]]. |
 +| [[.refs:lpref_all_ceilings|all_ceilings]]| All ceiling planes in the map. |
 +| [[.refs:lpref_thing_exist_ceilings|thing_exist_ceilings]]| All ceiling planes of all sectors which currently have at least one of a mobj type within them. |
 +| [[.refs:lpref_thing_noexist_ceilings|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 |
 +| [[.refs:lsref_none|none]]| Refers to nothing. Has a special meaning depending on the context. |
 +| [[.refs:lsref_my|my]]| The referring line's front sector. |
 +| [[.refs:lsref_tagged|tagged]]| All sectors whose tag matches the [[data component]]. |
 +| [[.refs:lsref_line_tagged|line_tagged]]| All sectors whose tag matches the referring line's tag. |
 +| [[.refs:lsref_act_tagged|act_tagged]]| All sectors whose [[activation_tag|act tag]] matches the [[data component]]. |
 +| [[.refs:lsref_index|index]]| The one sector whose index matches the [[data component]]. |
 +| [[.refs:lsref_all|all]]| All sectors in the map. |
 +| [[.refs:lsref_back|back]]| The referring line's back sector. |
 +| [[.refs:lsref_thing_exist|thing_exist]]| All sectors which currently have at least one of a mobj type within them. |
 +| [[.refs:lsref_thing_noexist|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_type]]s need to reference one or more [[plane]]s 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 |
 +| [[.refs:spref_none|none]]| Reference to nothing. With some line classes this type of reference has a special meaning. |
 +| [[.refs:spref_special|special]]| Has a special meaning that depends on the context. |
 +| ||
 +^ Floor plane ||
 +| [[.refs:spref_my_floor|my_floor]]| The referring line's front sector's floor plane. |
 +| [[.refs:spref_back_floor|back_floor]]| The referring line's back sector's floor plane. |
 +| [[.refs:spref_original_floor|original_floor]]| The original floor height of the referring sector. |
 +| [[.refs:spref_current_floor|current_floor]]| The current floor height of the referring sector. |
 +| [[.refs:spref_highest_floor|highest_floor]]| The highest floor plane of the adjoining sectors. |
 +| [[.refs:spref_lowest_floor|lowest_floor]]| The lowest floor plane of the adjoining sectors. |
 +| [[.refs:spref_next_highest_floor|next_highest_floor]]| The next highest floor plane of the adjoining sectors. |
 +| [[.refs:spref_next_lowest_floor|next_lowest_floor]]| The next lowest floor plane of the adjoining sectors. |
 +| [[.refs:spref_sector_tagged_floor|sector_tagged_floor]]| All floor planes of all sectors whose [[sector_tag|tag]] matches that of the referring sector. |
 +| [[.refs:spref_line_tagged_floor|line_tagged_floor]]| All floor planes of all sectors whose [[sector_tag|tag]] matches that of the referring line. |
 +| [[.refs:spref_tagged_floor|tagged_floor]]| All floor planes of all sectors whose [[sector_tag|tag]] matches the [[data component]]. |
 +| [[.refs:spref_line_act_tagged_floor|line_act_tagged_floor]]| All floor planes of all sectors whose [[activation_tag|act tag]] matches the referring line's [[line_tag|tag]]. |
 +| [[.refs:spref_act_tagged_floor|act_tagged_floor]]| All floor planes of all sectors whose [[activation_tag|act tag]] matches the [[data component]]. |
 +| [[.refs:spref_index_floor|index_floor]]| The floor plane of the one specific sector whose index matches the [[data component]]. |
 +| ||
 +^ Ceiling plane ||
 +| [[.refs:spref_my_ceiling|my_ceiling]]| The referring line's front sector's ceiling plane. |
 +| [[.refs:spref_back_ceiling|back_ceiling]]| The referring line's back sector's ceiling plane. |
 +| [[.refs:spref_original_ceiling|original_ceiling]]| The original ceiling height of the referring sector. |
 +| [[.refs:spref_current_ceiling|current_ceiling]]| The current ceiling height of the referring sector. |
 +| [[.refs:spref_highest_ceiling|highest_ceiling]]| The highest ceiling plane of the adjoining sectors. |
 +| [[.refs:spref_lowest_ceiling|lowest_ceiling]]| The lowest ceiling plane of the adjoining sectors. |
 +| [[.refs:spref_next_highest_ceiling|next_highest_ceiling]]| The next highest ceiling plane of the adjoining sectors. |
 +| [[.refs:spref_next_lowest_ceiling|next_lowest_ceiling]]| The next lowest ceiling plane of the adjoining sectors. |
 +| [[.refs:spref_sector_tagged_ceiling|sector_tagged_ceiling]]| All ceiling planes of all sectors whose [[sector_tag|tag]] matches that of the referring sector. |
 +| [[.refs:spref_line_tagged_ceiling|line_tagged_ceiling]]| All ceiling planes of all sectors whose [[sector_tag|tag]] number matches the referring line's [[line_tag|tag]]. |
 +| [[.refs:spref_tagged_ceiling|tagged_ceiling]]| All ceiling planes of all sectors whose [[sector_tag|tag]] matches the [[data component]]. |
 +| [[.refs:spref_line_act_tagged_ceiling|line_act_tagged_ceiling]]| All ceiling planes of all sectors whose [[activation_tag|act tag]] matches the referring line's [[line_tag|tag]]. |
 +| [[.refs:spref_act_tagged_ceiling|act_tagged_ceiling]]| All ceiling planes of all sectors whose [[activation_tag|act tag]] matches the [[data component]]. |
 +| [[.refs:spref_index_ceiling|index_ceiling]]| The ceiling plane of the one specific sector whose index matches the [[data component]]. |
 +| ||
 +^ Property evaluation ||
 +| [[.refs:spref_min_bottom_texture|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). |
 +| [[.refs:spref_min_mid_texture|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). |
 +| [[.refs:spref_min_top_texture|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). |
 +| [[.refs:spref_max_bottom_texture|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). |
 +| [[.refs:spref_max_mid_texture|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). |
 +| [[.refs:spref_max_top_texture|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). |
 +
 +
 +
 +==== Line → property ====
 +
 +
 +//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 [[xg:class|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 [[xg:line type]] definition.
 +
 +One potential usage of this functionality would be a line type which upon [[xg:activation_requirement|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.
 +
 +^ Name^ Summary |
 +| [[.refs:ldref_none|none]]| Refers to nothing. Has a special meaning depending on the context. |
 +| [[.refs:ldref_id|id]]| Unique index number. |
 +| [[.refs:ldref_special|special]]| [[line_special|special]]. |
 +| [[.refs:ldref_tag|tag]]| [[line_tag|tag]]. |
 +| [[.refs:ldref_acttag|acttag]]| [[activation_tag|act tag]]. |
 +| [[.refs:ldref_count|count]]| Internal count. |
 +| [[.refs:ldref_angle|angle]]| Physical angle in the [[map]] coordinate space. |
 +| [[.refs:ldref_length|length]]| Physical length in the [[map]] coordinate space. |
 +| [[.refs:ldref_top_offsetx|top_offsetx]]| [[material]] X offset of the front [[side]]'s top section. |
 +| [[.refs:ldref_top_offsety|top_offsety]]| [[material]] Y offset of the front [[side]]'s top section. |
 +| [[.refs:ldref_middle_offsetx|middle_offsetx]]| [[material]] X offset of the front [[side]]'s middle section. |
 +| [[.refs:ldref_middle_offsety|middle_offsety]]| [[material]] Y offset of the front [[side]]'s middle section. |
 +| [[.refs:ldref_bottom_offsetx|bottom_offsetx]]| [[material]] X offset of the front [[side]]'s bottom section. |
 +| [[.refs:ldref_bottom_offsety|bottom_offsety]]| [[material]] Y offset of the front [[side]]'s bottom section. |
 +
 +