Module vpeol_3d 

Viewport Editing Overlay for 3D games.

Use this module to implement simple 3D editing for 3D games.

To use add the egui and Yoleck plugins to the Bevy app, as well as the plugin of this module:

app.add_plugins(EguiPlugin::default());
app.add_plugins(YoleckPluginForEditor);
// - Use `Vpeol3dPluginForGame` instead when setting up for game.
// - Use topdown is for games that utilize the XZ plane. There is also
//   `Vpeol3dPluginForEditor::sidescroller` for games that mainly need the XY plane.
app.add_plugins(Vpeol3dPluginForEditor::topdown());

Add the following components to the camera entity:

• VpeolCameraState in order to select and drag entities.
• Vpeol3dCameraControl in order to control the camera with the mouse. This one can be skipped if there are other means to control the camera inside the editor, or if no camera control inside the editor is desired.

commands
    .spawn(Camera3d::default())
    .insert(VpeolCameraState::default())
    // Use a variant of the camera controls that fit the choice of editor plugin.
    .insert(Vpeol3dCameraControl::topdown());

Custom Camera Modes

You can customize available camera modes using YoleckCameraChoices:

app.insert_resource(
    YoleckCameraChoices::default()
        .choice_with_transform(
            "Custom Camera",
            {
                let mut control = Vpeol3dCameraControl::fps();
                control.mode = Vpeol3dCameraMode::Custom(0);
                control
            },
            Vec3::new(10.0, 10.0, 10.0),
            Vec3::ZERO,
            Vec3::Y,
        )
);

// Implement custom camera movement
app.add_systems(PostUpdate, custom_camera_movement);

fn custom_camera_movement(
    mut cameras: Query<(&mut Transform, &Vpeol3dCameraControl)>,
) {
    for (mut transform, control) in cameras.iter_mut() {
        if control.mode == Vpeol3dCameraMode::Custom(0) {
            // Your custom camera logic here
        }
    }
}

Entity selection by clicking on it is supported by just adding the plugin. To implement dragging, there are two options:

1. Add the Vpeol3dPosition Yoleck component and use it as the source of position. Gizmo with axis knobs (X, Y, Z) are automatically added to all entities with Vpeol3dPosition. Configure them using the Vpeol3dTranslationGizmoConfig resource. Optionally add Vpeol3dRotation (edited with Euler angles) and Vpeol3dScale (edited with X, Y, Z values) for rotation and scale support.

   app.add_yoleck_entity_type({
       YoleckEntityType::new("Example")
           .with::<Vpeol3dPosition>() // vpeol_3d dragging with axis knobs
           .with::<Vpeol3dRotation>() // optional: rotation with egui (Euler angles)
           .with::<Vpeol3dScale>() // optional: scale with egui
           .with::<Example>() // entity's specific data and systems
   });

2. Use data passing. vpeol_3d will pass a Vec3 to the entity being dragged:

   fn edit_example(mut edit: YoleckEdit<(Entity, &mut Example)>, passed_data: Res<YoleckPassedData>) {
       let Ok((entity, mut example)) = edit.single_mut() else { return };
       if let Some(pos) = passed_data.get::<Vec3>(entity) {
           example.position = *pos;
       }
   }
   
   fn populate_example(
       mut populate: YoleckPopulate<&Example>,
       asset_server: Res<AssetServer>
   ) {
       populate.populate(|_ctx, mut cmd, example| {
           cmd.insert(Transform::from_translation(example.position));
           cmd.insert(SceneRoot(asset_server.load("scene.glb#Scene0")));
       });
   }

Structs

Vpeol3dCameraControl

Move and rotate a camera entity with the mouse while inside the editor.

Vpeol3dPluginForEditor

Add the systems required for 3D editing.

Vpeol3dPluginForGame

Add the systems required for loading levels that use vpeol_3d components

Vpeol3dPosition

A position component that’s edited and populated by vpeol_3d.

Vpeol3dRotation

A rotation component that’s edited and populated by vpeol_3d.

Vpeol3dScale

A scale component that’s edited and populated by vpeol_3d.

Vpeol3dSnapToPlane

Add this to an entity with Vpeol3dPosition to force it to be on a specific plane while editing.

Vpeol3dTranslationGizmoConfig

YoleckCameraChoice

A single camera mode choice with its control settings and optional initial transform.

YoleckCameraChoices

Resource that defines available camera modes in the editor.

Enums

Vpeol3dCameraMode

Camera mode identifier for type-safe camera mode comparisons.

Vpeol3dTranslationGizmoMode

Functions

vpeol_3d_camera_mode_selector

vpeol_3d_translation_gizmo_mode_selector