Crate bevy_basic_portals

Bevy Basic Portals is a Bevy game engine plugin aimed to create portals.

Those portals are (for now) purely visual and can be used to make mirrors, indoor renderings, crystal balls, and more!

Basic Usage

//! This example illustrates how to create a simple portal,
//! it uses a single sphere that will be displayed two times on screen thanks to the portal

use bevy::prelude::*;
use bevy_basic_portals::*;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, PortalsPlugin::MINIMAL))
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands, mut meshes: ResMut<Assets<Mesh>>) {
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(-20.0, 0., 20.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));

    let portal_mesh = meshes.add(Mesh::from(Rectangle::new(10., 10.)));
    commands.spawn((
        // This component will be deleted and things that are needed to create the portal will be created
        CreatePortal {
            destination: PortalDestinationSource::Create(CreatePortalDestination {
                transform: Transform::from_xyz(20., 0., 0.),
                ..default()
            }),
            // Uncomment this to see the portal
            /*debug: Some(DebugPortal {
                show_window: false,
                ..default()
            }),*/
            ..default()
        },
        Mesh3d(portal_mesh),
    ));

    let sphere_mesh = meshes.add(Mesh::from(Sphere::new(2.).mesh().uv(32, 18)));
    commands.spawn((
        Mesh3d(sphere_mesh),
        MeshMaterial3d::<StandardMaterial>::default(),
        Transform::from_xyz(20., 0., -5.),
    ));
}

More complex examples are available in the git project.

Vocabulary

• A Portal is an entity used to visualise the effect
• A Main Camera is a camera used to visualize the effect
• A (portal) Destination is an entity representing the point in space where a portal is “looking”
• A Portal Camera is a camera being used to render the effect, its position to the destination is the same as the main camera’s position to the portal
• All of those are Portal Parts, their references are stored in a separate entity

Known limitations

(may be fixed in the future)

• portals created by this crate are uni-directionnal, you can only look from one space to the other, if you want a bidirectional portal you can crate two portals manually
• this crate doesn’t handle “portal recursion”, as in viewing a portal through another portal
• portals created by this crate have no visible borders (not counting aliasing artifacts), you can “see” them with DebugPortal
• this crate doesn’t handle moving stuff through the portal, it is only visual, more like a crystal ball
• this crate doesn’t handle raycasting through the portal, it has to be done manually
• this crate doesn’t handle resizing window/viewport of the main camera
• this crate doesn’t handle changing the portal’s or the destination’s scale
• this crate doesn’t handle changing camera settings after creation

Re-exports

pub use portals::*;

Modules

picking

Module to pick entities through portals. This requires the feature picking_backend.

portals

Components, systems and others to create portals

Structs

CreatePortal

Component to create a Portal and everything needed to make it work.

PortalsPlugin

Plugin to add support for portals to a bevy App.