Editing Linked portal

'''Linked portals''' are a powerful feature which make it possible to connect two separate areas of a map via the floor/ceiling or linedefs, allowing the player to see, shoot, and even move seamlessly from one area into another. They are used similarly to two-way portals, apart from the fact that you can pass through them. They can be used to create 3D architecture and room-over-room effects, with very few limitations.

'''NOTE''': for [[UDMF]] portals, you use the [[Portal_Define]] and [[Line_QuickPortal]] specials.
{{backto|Portal linedef types}}

==Screenshots==
{| class="wikitable"
|-
| [[File:Linked_portals_bottom.png|320px]] || [[File:Linked_portals_top.png|320px]]
|-
| View from the bottom room || View from the top room.
|}

==Line triggers==
Linked portals are set up by using linedef types (specials). If the map format is [[UDMF]], they are also set up using UDMF sector and linedef properties.
===UDMF format===
The following specials are used in UDMF to setup portals: [[Portal_Define]] and [[Line_QuickPortal]]. Then, on each sector you can set the '''portalfloor''' and '''portalceiling''' properties, using portal ID, to apply newly defined portal on the respective surfaces. On each linedef you can set the '''portal''' property similarly.

The portal ID can be made negative as well: this spawns a portal going the opposite direction. For example, a linedef linked portal going from area A to B has a positive '''portal''' setting, and the corresponding linedef going from B to A has the negative value for '''portal'''.

===Classic Doom format===
 #     Class  Trig Description
 
 358   Ext    --   Apply linked portal to like-tagged ceilings
 
 359   Ext    --   Apply linked portal to like-tagged floors
 
 360   Ext    --   Linked portal anchor line for special 358
 
 361   Ext    --   Linked portal anchor line for special 359
 
 376   Ext    --   Apply linked portals to like-tagged lines
 
 377   Ext    --   Anchor line for special 376
 
 385   Ext    --   Apply portal to front sector

For sectors you will use the specials 358, 359, 360, 361 and 385, while for lines you'll use 376 and 377.

==Terminology==
Linked portals have their own specific sub-set of terminology used to describe certain aspects and behaviors.

===Sector portal plane===
Unlike the basic portal types, which were rendered and could cover height variances (much like the doom sky), linked portals form an actual map structure. The '''Portal Plane''' refers to an X/Y plane that bisects the sector(s) that contain the portal. The z-position of the portal is fixed, and should be the same height on both sides of the linked portal.

===Linedef portal plane===
There are also line-to-line portals, whose plane is vertical. They need to be placed on 2-sided linedefs with a buffer sector behind them. The buffer sector will never be seen in the game, but it's needed to provide a safe space behind the portal linedef for any actor to be able to pass through without being blocked by stray BSP partition lines which may appear in the void, were it not for a buffer sector.

===Beyond the Plane===
Map architecture is said to be beyond the portal plane when its vertical height is equal to or beyond the portal height--that is, at or above a ceiling portal plane or at or below a floor portal plane. When map architecture is beyond a portal plane, the portal will display at the height of the plane.

===Inside the plane===
Map architecture is said to be inside the portal plane when its vertical height is not beyond the portal plane--that is, below a ceiling portal or above a floor portal. Any architecture that is inside the portal plane will render normally and will obscure rendering of the portal.

==Usage==
Linked portals use trigger and anchor lines (much like anchored portals) to determine an X and Y offset from one part of the map to another, but there are specific requirements unique to linked portals:

*Linked portals must be two-way, meaning the upper area must reference the lower area and vice versa.
*Linked portals have specific behavior relating to z-coordinates of the portal plane.

==Setup==

There are two kinds of linked portals: plane portals and line portals. Plane portals are sector floor or ceiling surfaces that vertically connect different sector groups (layers) of the map. Line portals are linedefs that connect areas horizontally.

===Setting up sector portals===
There must be (at least) two sectors in the map, not linked together by any path (similar to how disjoint areas exist in classic Doom maps and are gameplay-connected only by teleporters).

The ceiling height of one of them must match the floor height of the other. Let's call the bottom sector A and the top sector B.

Even though the sectors need to have the same outline, they can have different detail inner sectors in them. For example, sector A can have several crate sectors whose outlines don't need to be copied into upper sector B, which has much less detail. Note that one-sided linedef walls inside sectors (e.g. columns) must have their outlines copied.

Reserve two linedefs for each sector. Make sure the two linedefs selected for sector A will have the same relative coordinates and sizes as the two corresponding linedefs from B.

Tag sector A and its inner details with a number. Tag B and its details with another number.

Give the reserved linedefs from A special 359, tag of B and special 360, tag of A respectively. Give the reserved linedefs from B special 358, tag of A and special 361, tag of B respectively. Here is how they should correspond:

* Reserved linedef 1 of sector A: special 359, tag B (Apply linked portal to floor of B)
* Reserved linedef 1 of sector B: special 361, tag B (Linked portal anchor line for special 359)
* Reserved linedef 2 of sector A: special 360, tag A (Linked portal anchor line for special 358)
* Reserved linedef 2 of sector B: special 358, tag A (Apply linked portal to ceiling of A)

Note that with this implementation, you'll have to give a tag to every sector which needs a portal. Sometimes this is not practical, because you may want to make various sectors with special effects within A or B. To bypass this problem, you can tag the special sector differently, but one of the linedefs facing it must have special 385 (Apply portal to front sector) and have the tag of the non-special sectors that surround it (A or B). This will copy the portal information into the special sector.

Here is a diagram on how to set up:

 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 -----------------x---------------------x:::::::::::::      ~-------------------x---------------------x:::::::::::::::::::
                 /                       \::::::::::::      ~ Neighbour        /                       \::::::::::::::::::
  Neighbour     /         SECTOR A        \::::::::::       ~ sector of       /         SECTOR B        \:::::::::::::::::
  sector of    /  x----x             floor \:::::::::       ~ B              /  x----x                   \::::::::::::::::
  A           /   |::::|             detail \::::::::       ~ (not tagged)  /   |    |                    \:::::::::::::::
  (untagged) /    |::::|wall         x---x   \:::::::       ~              /    |    |top of wall from A   \::::::::::::::
 -----------x     x----x             |   |    x:::::::::    ~-------------x     x----x <NOT tagged          x:::::::::::::
 ::::::::::::\                       x---x   /:::::::::::::::::::::::::::::\                               /::::::::::::::
 :::::::::::::\    x---x-----x same tag as^ /:::::::::::::::::::::::::::::::\     x-------------x         /:::::::::::::::
 ::::::::::::::\    \   \    | <  A        x:::::::::::::::::::::::::::::::::\    x-------------x        x::::::::::::::::
 :::::::::::::::\    x---x---x            /360,A::::::::::::::::::::::::::::::\ ceil. detail            /358,A::::::::::::
 ::::::::::::::::\ flr.detail    359,B   /:::::::::::::::::::::::::::::::::::::\ tag of B      361,B   /::::::::::::::::::
 :::::::::::::::::x-------------x-------x:::::::::::::::::::::::::::::::::::::::x-------------x-------x:::::::::::::::::::
 :::::::::::::::::::::::::::::::::THE PORTAL LINEDEFS:::::::::::::::::::::::::::::::::::::::::THE PORTAL LINEDEFS:::::::::

===Setting up wall portals===
Wall portals are slightly simpler to implement. The two separate sectors must have the same floor and ceiling heights and the portal linedefs need to be of the same length and angle.

The two linedefs will have the 376 and 377 specials (respectively, order not being important) and a common tag (which doesn't have to belong to any sector).

Note that on older Eternity versions, the portal lines needed to be 2-sided and passable, and you had to add a buffer sector behind the portal lines. On the latest versions, 1-sided lines are accepted. The only requirement left is to leave enough space in the void behind these 1-sided lines to prevent actors from bumping on other walls from the same layer.

Here is a diagram on how to set up:

 ----------x <---two separate layers---> x---------
           |                             x
           |                             |
           |                             |<linedef B
           x                             | type 377
 linedef A>|                             | tag n
 type 376  |                             x
 tag n     |                             |
           |                             |
 ----------x                             x---------

===Lifts between sector portals===

You can make the floor or ceiling of a sector move from a sector group (layer) to another by using the [[Attached surface linedef types]]. Here's how to do it:
* Place the two parts of the lift as two sectors, the one below the portal and the one above the portal. Make sure the sectors have the same size, floor texture, floor height and lower textures relative to floor.
* Set the floor height of both sectors to the Z position of the portal plane. Do this even if the lift's resting position is lower or higher.
* Set up a sector portal between the two sectors.
* Attach the floor movement between the two sectors. Check the link above to see how it's done.
* To adjust the floor to the bottom or top height, you can use a special at the beginning of the level (either through an OPEN ACS script, using Boom voodoo dolls / conveyors or a trigger near the player start).

===Polyobject portals===
You can even place portals on polyobjects now. Connecting the edges of a polyobject with a sector matching its "interior", you can now have moving platforms. Unlike conventional wall portals, the ones on the polyobject's exterior must be one-sided. Upper and lower textures will still work, despite this. The wall portals from the inside area to the outside will have to be conventional though (2-sided with a buffer sector behind).
====Caveats====
Though this may get fixed in future versions, make sure to connect the polyobject control sector (the one holding all prototype polyobjects) to the main area it will appear in. You can use tunnel sectors or joined sectors. To avoid glitches, the sector containing the prototypes must not be the same sector as the one where polyobjects will be spawned.
====Simple moving platform illusion====
You can put a linked portal in the ceiling of the inner sector to give the illusion that a simple platform is moving on the floor. It works if you used the [[Portal_Define]] special for the line portals and if the background room has the same ceiling height, or in very small variation, in the area where the polyobject moves. Acceptable variations are at most 8 map units. Otherwise, you get bleeding effects.

The platform sector must have the ceiling height set to the maximum ceiling of the outside area. Set the '''portalceiling''' field of the sector to the same ID you used for the walls. Make sure the z offset of [[Portal_Define]] is set correctly: if the inner sector is a raised platform compared to the outside sector, the z offset should be the ''minimum'' ceiling height from the outside area, minus the elevation of the platform against the background. If it's a "moving pit", the z offset should be the negative of the height of the lowest ceiling detail from the outside area.

It is recommended to set '''portal_ceil_nopass''' on the sector, especially if there is no height variation. This prevents unnecessary side effects.

An example is available for download: [https://www.dropbox.com/s/xi1xhv92h27ptep/polyceilport.wad?dl=0 PolyCeilPort.wad].

===Edge portals===
You can also put portals on upper and lower edges of linedefs. See [[Edge portals]].

===Attached portals===
You can attach linked portals to their floors or ceiling. By default they stay fixed, so that making elevators going through portals is possible. But if you want the linked portal to move along with the floor or ceiling over which it's drawn, you enable the [[UDMF]] '''portal_floor_attached''' or '''portal_ceil_attached''' flags, or the [[ExtraData]] '''ATTACHEDPORTAL''' portal flag. Set these flags for both parts of the portal, and combine them with the [[attached surfaces]] feature, so that all required surfaces move synchronized.

An example usage of this is a platform you can walk both under and above, which is made possible by sector portals (optionally with [[edge portals]] surrounding it). Giving the "attached portal" flag to the portals, and attaching both their surfaces and platform's surfaces to a moving floor, will allow you to setup the effect of the platform itself bobbing up and down. You can also setup other less realistic effects with this flag.

==Caveats and limitations==
* Linked areas must have aligned floor or ceiling heights. It's not currently possible to look and move into an area with different Z coordinates.
* It is possible to make "impossible" structures, both with plane and line portals, where certain tunnels can lead into otherwise occupied areas. In previous Eternity versions, you could possibly see "phantom" walls belonging to other areas, relative to your position, but this phenomenon has been reduced. If it still happens, this undesired effect can be reduced by setting up the layout of the map properly and moving the seen areas away from the vicinity of others.
* An "infinite" tunnel can be created, but it must consist of at least three sector groups in a cycle, as well as avoiding any visibility glitches mentioned in the previous point. The automap will be unable to align all areas, so one of the portals will appear as a simple teleporter. Several of the physics rules, such as collision detection, may break down at that portal, so try to minimize the action that takes place at that point.

==Tutorial==
Refer to Zarkyb's [[linked portals tutorial]] for more examples on usage.

==UDMF portals editor support==
At the moment of this writing, Doom Builder X (Windows only) by anotak highlights sectors with matching portal IDs for you. You can otherwise use any editor with full UDMF support, but may not get all the visual support.

==Examples==
===[https://s3-eu-west-1.amazonaws.com/eternity/linked_port.wad Linked Portals Demo]===
a demonstration of both plane and wall portals.
Played on '''Doom2''' / '''Map01'''.

Things to note:

* In compatibility menu the option '''actors have infinite height''' needs to be set to '''false''' in order for any actor to fall through a portal.
* The "upper part" is textured differently from the "lower part". While in game observe when textures change and where exactly the clipping occurs.
* The lower room has a different shape than the room upstairs. Only the tagged, corresponding sectors which make up a "hole" have to be shaped alike.
* Any LineDef that copies floor / ceiling requires an appropriate '''Anchor''' action on correspodning LineDef in the copied sector. E.g. should the action '''special: 360; tag: 1''' be cleared from where it is and set on any other LineDef, you'd get clipping errors, HoM effects or the renderer would simply refuse to connect portals.
* When viewing automap notice how position is updated. Player doesn't seem to "teleport" from one place of the map to another, yet his X/Y coordinates change when passing a portal boundary.
* Use console commands like '''spawn doomimp''' to test how monsters see, hear and aim through portals.
* Use console command '''fly''' to test that you can indeed cross portals from both sides of the "hole".
* When viewing through map editor note that there's no sector tagged with a '''3''' (tag used to link wall portals). Wall portals clipping is based on LineDefs, not sectors.

[[File:Linked_portals.png]]

==See also==
*[[3DMidTex]]: for lighter ways to achieve room-over-room.

[[Category:Editing]]
[[Category:Editing reference]]
[[Category:Portals]]