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 {
    enable_multipass_for_primary_context: true,
});
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());

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 (there are also Vpeol3dRotation and Vpeol3dScale, but they don’t currently get editing support from vpeol_3d). To enable dragging across the third axis, add Vpeol3dThirdAxisWithKnob as well.

   app.add_yoleck_entity_type({
       YoleckEntityType::new("Example")
           .with::<Vpeol3dPosition>() // vpeol_3d dragging
           .with::<Example>() // entity's specific data and systems
           // Optional:
           .insert_on_init_during_editor(|| Vpeol3dThirdAxisWithKnob {
               knob_distance: 2.0,
               knob_scale: 0.5,
           })
   });

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")));
       });
   }

   When using this option, Vpeol3dThirdAxisWithKnob can still be used to add the third axis knob.

Structs

Vpeol3dCameraControl

Move and rotate a camera entity with the mouse while inisde 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 populated (but not edited) by vpeol_3d.

Vpeol3dScale

A scale component that’s populated (but not edited) by vpeol_3d.

Vpeol3dThirdAxisWithKnob

Add a knob for dragging the entity perpendicular to the VpeolDragPlane.