PortalComponent

A Component that enables entity surfaces to act as portals to a target world (the targetEntity EC tree) and should be used in conjunction with PortalMaterial.

Terminologies:

• PortalEntity: An entity that the PortalComponent is added to.

• PortalWorldEntity: An entity that the PortalWorldComponent is added to.

• PortalCrossableEntity: An entity that the PortalCrossableComponent is added to.

To achieve the desired portal effect, you should adhere to the following design principles:

• PortalEntity should have a PortalMaterial linked to its ModelComponent.

• PortalEntity must be either a sibling or parent node to PortalWorldEntity, not a child.

• PortalCrossableEntity must be a child node within a PortalWorldEntity and cannot be isolated outside of it.

• The system can display up to 8 pairs of Portal-World relationships simultaneously. This supports up to 8 such pairs.

Background Settings

The portal background can be configured with panelColor and backgroundMode:

• PortalBackgroundMode.SOLID_COLOR: Displays a solid color background (default). The color is controlled by panelColor.

• PortalBackgroundMode.PASSTHROUGH: Shows the real world (passthrough) behind the portal.

These properties are experimental and require ExperimentalSpatialApi to be enabled.

Usage Example

// Create world entity and crossing entity
val worldEntity = Entity()
worldEntity.components.set(PortalWorldComponent())
val willCrossingEntity = Entity()
willCrossingEntity.components.set(PortalCrossableComponent())
worldEntity.addChild(willCrossingEntity)

// Create portal entity
val portalEntity = Entity()
portalEntity.components.set(
    PortalComponent(
        targetEntity = worldEntity,
        allowClipping = true,
        doubleSide = false,
        allowEntityCrossing = true
    )
)

// Attach required visual components
portalEntity.components.set(ModelComponent(mesh, PortalMaterial()))

See also