Portals for Bevy

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: AsPortalDestination::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 examples folder.

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

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 changing the portal's or the destination's scale
• this crate doesn't handle changing camera settings after creation

Bevy versions

Bevy version	Bevy Basic Portals recommended version
0.15.*	0.7.0
0.14.*	0.6.0
0.13.*	0.5.0
0.12.*	0.4.0
0.11.1	0.3.0
0.10.*	0.2.1

License

Bevy Basic Portals is non-violent software: you can use, redistribute, and/or modify it under the terms of the NVPLv7+ as found in the LICENSE file in the source code root directory or at the CNPL repository.

Bevy Basic Portals comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law.

See the CNPL website for more information.