Rendy: Migration Guide

Audio

AudioFormat no longer exists, you have to use the lower level types -- Mp3Format, WavFormat, OggFormat, FlacFormat.

Assets

SimpleFormat trait has merged into Format.
Format::Options associated type has been removed; options are now stored in the format instance.
NAME associated constant is now a method call.
Format<A> type parameter now takes in Format<D>, where D is A::Data.
Implement import_simple instead of import.
Loader::load no longer takes in the Options parameter.

Input

Bindings<String, String> is now Bindings<StringBindings>.

Bindings<AX, AC> is now Bindings<T>, where T is a new type you must implement:

pub struct ControlBindings;

impl BindingTypes for ControlBindings {
    type Axis = PlayerAxisControl;
    type Action = PlayerActionControl;
}

Diff:

-Bindings<PlayerAxisControl, PlayerActionControl>
+Bindings<ControlBindings>

InputBundle type parameters:

-InputBundle::<String, String>::new()
+InputBundle::<StringBindings>::new()

UiBundle type parameters:

+use amethyst::renderer::types::DefaultBackend;

-UiBundle::<String, String>::new()
+UiBundle::<DefaultBackend, StringBindings>::new()

Window

DisplayConfig's fullscreen field is now an Option<MonitorIdent>. MonitorIdent is MonitorIdent(u16, String), indicating the native monitor display ID, and its name.
WindowBundle is now separate from amethyst_renderer.
```
use amethyst::window::WindowBundle;

game_data.with_bundle(WindowBundle::from_config_file(display_config_path))?;
```
This system is loaded automatically by the RenderToWindow render plugin.

Renderer

amethyst::renderer::VirtualKeyCode is now amethyst::input::VirtualKeyCode
amethyst::renderer::DisplayConfig is now amethyst::window::DisplayConfig
amethyst::renderer::WindowEvent is now amethyst::winit::WindowEvent
amethyst::renderer::Event is no longer re-exported. Use amethyst::winit::Event
amethyst::renderer::Transparent is now under amethyst::renderer::transparent::Transparent.
amethyst::renderer::Visibility is now under amethyst::renderer::visibility::Visibility.
TextureHandle type alias no longer exists, use Handle<Texture>.
Flipped component is removed. You can specify flipped during sprite loading, or mutating Transform at run time.

To load a texture in memory, you can't use [0.; 4].into() as the TextureData anymore. Use:

use amethyst::{
    assets::{AssetStorage, Handle, Loader, Prefab, PrefabLoader},
    ecs::World,
    renderer::{
        loaders::load_from_srgba,
        palette::Srgba,
        types::TextureData,
        Texture,
    },
};

let loader = world.read_resource::<Loader>();
let texture_assets = world.read_resource::<AssetStorage<Texture>>();
let texture_builder = load_from_srgba(Srgba::new(0., 0., 0., 0.));
let texture_handle: Handle<Texture> =
    loader.load_from_data(TextureData::from(texture_builder), (), &texture_assets);

RenderBundle and Pipeline are gone, now you need to use the RenderingBundle, for example:

In main.rs:

use amethyst::renderer::{types::DefaultBackend, RenderingSystem};

let game_data = GameDataBuilder::default()
    .with_bundle(
        RenderingBundle::<DefaultBackend>::new()
            .with_plugin(
                RenderToWindow::from_config_path(display_config)
                    .with_clear([0.34, 0.36, 0.52, 1.0]),
            )
            .with_plugin(RenderShaded3D::default())
            .with_plugin(RenderDebugLines::default())
            .with_plugin(RenderSkybox::with_colors(
                Srgb::new(0.82, 0.51, 0.50),
                Srgb::new(0.18, 0.11, 0.85),
            )),
    )?;

Render passes can be integrated into amethyst by using the newly introduced RenderPlugin trait, for example:

pub struct RenderCustom {
    target: Target,
}

impl RenderTerrain {
    /// Set target to which 2d sprites will be rendered.
    pub fn with_target(mut self, target: Target) -> Self {
        self.target = target;
        self
    }
}


impl<B: Backend> RenderPlugin<B> for RenderCustom {
    fn on_build<'a, 'b>(
        &mut self,
        builder: &mut DispatcherBuilder<'a, 'b>,
    ) -> Result<(), Error> {
        // You can add systems that are needed by your renderpass here
        Ok(())
    }

    fn on_plan(
        &mut self,
        plan: &mut RenderPlan<B>,
        _factory: &mut Factory<B>,
        _res: &Resources,
    ) -> Result<(), Error> {
        plan.extend_target(self.target, |ctx| {
            ctx.add(RenderOrder::Opaque, DrawCustomDesc::new().builder())?;
            Ok(())
        });
        Ok(())
    }
}

RenderBundle::with_sprite_sheet_processor() is replaced by:
```
game_data.with(
    Processor::<SpriteSheet>::new(),
    "sprite_sheet_processor",
    &[],
);
```
This system is added automatically by each of the 3D render plugins (RenderPbr3D, RenderShaded3D, RenderFlat3D).

RenderBundle::with_sprite_visibility_sorting() is replaced by:

use amethyst::rendy::sprite_visibility::SpriteVisibilitySortingSystem;

game_data.with(
    SpriteVisibilitySortingSystem::new(),
    "sprite_visibility_system",
    &["transform_system"],
);

This system is added automatically by the RenderFlat2D render plugin.

Sprite transparency is no longer a separate flag. Instead of with_transparency, you add a second render pass using DrawFlat2DTransparent. See the sprites_ordered example.

Camera changes:

CameraPrefab is no longer nested:

-camera: Perspective((aspect: 1.3, fovy: 1.0471975512, znear: 0.1, zfar: 2000.0))
+camera: Perspective(aspect: 1.3, fovy: 1.0471975512, znear: 0.1, zfar: 2000.0)

nalgebra's Perspective3/Orthographic3 are no longer compatible, as they use OpenGL coordinates instead of Vulkan.

Amethyst now has amethyst::rendy::camera::Orthographic and Perspective, respectively. These types are mostly feature-parity with nalgebra, but correct for vulkan. You can use as_matrix to get the inner Matrix4 value.
Camera now stores Projection, which means it is type-safe.
You can no longer serialize raw camera matrices, only camera parameter types.

Z-axis direction clarifications:

In Vulkan, Z+ is away.
in OpenGL, Z- is away.
In amethyst_renderer, Z- is away (world coordinates).
In amethyst_rendy, Z- is away (world coordinates).

Amethyst Test

The render_base function has been changed:

-let visibility = false;
-AmethystApplication::render_base("test_name", visibility);
+use amethyst::renderer::{types::DefaultBackend, RenderEmptyBundle};
+AmethystApplication::blank()
+    .with_bundle(RenderEmptyBundle::<DefaultBackend>::new());

The mark_render() and .run() chained call is replaced by a single run_isolated() call.

Amethyst Documentation