source: code/branches/mergeFS18/doc/api/groups/Portals.dox @ 12196

/**
    @addtogroup Portals Portals
    @ingroup Modules

    This module allows you to place @ref orxonox::PortalEndPoint "PortalEndPoints" in space and connect pairs of them with a @ref orxonox::PortalLink "PortalLink" in order to allow fast travelling from A to B.

    @section FastHowTo Fast HowTo: Including portals in a level
    The simplest way to use portals is show by the following piece of xml-code
    @code
    <Template name=PortalDefault>
        <PortalEndPoint>
            <attached>
                <Billboard material="Portals/Default" />
            </attached>
        </PortalEndPoint>
    </Template>

    <PortalEndPoint position="0,0,0" id="1" design="PortalDefault"/>
    <PortalEndPoint position="-100,0,0" id="2" design="PortalDefault"/>
    <PortalLink fromID="1" toID="2" />
    @endcode
    This
     - creates two @ref orxonox::PortalEndPoint "PortalEndPoints", one at 0,0,0 and the other at -100,0,0
     - makes them visible by attaching a Billboard made of the "Portals/Default" material to each of them and
     - connects them, meaning that any @ref orxonox::Pawn "Pawn" which gets near 0,0,0 is immediately "warped" to -100,0,0 (but not the other way round)

    @section IncludePortals Detailed HowTo: Including portals in a level
    In the example above some default values are used. The full possibilities are shown below
    @code
    <Template name=PortalDefault>
        <PortalEndPoint>
            <attached>
                <Billboard material="Portals/Default" />
            </attached>
        </PortalEndPoint>
    </Template>

    <Template name=PortalBig>
        <PortalEndPoint>
            <attached>
                <Billboard material="Portals/Big" />
            </attached>
        </PortalEndPoint>
    </Template>

    <PortalEndPoint position="0,0,0" id="1" distance="40" target="MobileEntity" design="PortalDefault"/>
    <PortalEndPoint position="-100,0,0" id="2" distance="40" target="MobileEntity" design="PortalBig"/>
    <PortalLink fromID="1" toID="2" />
    <PortalLink fromID="2" toID="1" />
    @endcode

    step by step
    @subsection Templates "Templates"
    In order to make @ref orxonox::PortalEndPoint "PortalEndPoints" visible in the game there must be something visible.
    The idea (as shown above) is to define or include arbitrary Templates which make a PortalEndPoint visible and use them later by setting the design attribute of a @ref orxonox::PortalEndPoint "PortalEndPoint" to the template name
    @subsection Parameters "Parameters"
     - position: 3d-coordinate in space
     - distance (default: 50): distance at which a valid entity gets pulled in (if the end point is an entrance).
     - target (default: "Pawn"): the class which is able to enter this end point (if it is an entrance)
     - design: the name of the @ref orxonox::Template "design template"
*/