Struct amethyst::ApplicationBuilder

pub struct ApplicationBuilder<S, T, E, R> {
    pub world: World,
    // some fields omitted
}

ApplicationBuilder is an interface that allows for creation of an Application using a custom set of configuration. This is the normal way an Application object is created.

Fields

world: World

Used by bundles to access the world directly

Methods

impl<S, T, E, X> ApplicationBuilder<S, T, E, X> where
    T: DataDispose + 'static, 

pub fn new<P: AsRef<Path>>(path: P, initial_state: S) -> Result<Self, Error>

Creates a new ApplicationBuilder instance that wraps the initial_state. This is the more verbose way of initializing your application if you require specific configuration details to be changed away from the default.

Parameters

• initial_state: The initial State handler of your game. See State for more information on what this is.

Returns

Returns a Result type wrapping the Application type. See errors for a full list of possible errors that can happen in the creation of a Application object.

Type parameters

• S: A type that implements the State trait. e.g. Your initial game logic.

Lifetimes

• a: The lifetime of the State objects.
• b: This lifetime is inherited from specs and shred, it is the minimum lifetime of the systems used by Application

Errors

Application will return an error if the internal threadpool fails to initialize correctly because of systems resource limitations

Examples

use amethyst::prelude::*;
use amethyst::core::transform::{Parent, Transform};
use amethyst::ecs::prelude::System;

struct NullState;
impl EmptyState for NullState {}

// initialize the builder, the `ApplicationBuilder` object
// follows the use pattern of most builder objects found
// in the rust ecosystem. Each function modifies the object
// returning a new object with the modified configuration.
let assets_dir = "assets/";
let mut game = Application::build(assets_dir, NullState)?

// components can be registered at this stage
    .register::<Parent>()
    .register::<Transform>()

// lastly we can build the Application object
// the `build` function takes the user defined game data initializer as input
    .build(())?;

// the game instance can now be run, this exits only when the game is done
game.run();

pub fn register<C>(self) -> Self where
    C: Component,
    C::Storage: Default, 

Registers a component into the entity-component-system. This method takes no options other than the component type which is defined using a 'turbofish'. See the example for what this looks like.

You must register a component type before it can be used. If code accesses a component that has not previously been registered it will panic.

Type Parameters

• C: The Component type that you are registering. This must implement the Component trait to be registered.

Returns

This function returns ApplicationBuilder after it has modified it

Examples

use amethyst::prelude::*;
use amethyst::ecs::prelude::Component;
use amethyst::ecs::storage::HashMapStorage;

struct NullState;
impl EmptyState for NullState {}

// define your custom type for the ECS
struct Velocity([f32; 3]);

// the compiler must be told how to store every component, `Velocity`
// in this case. This is done via The `amethyst::ecs::Component` trait.
impl Component for Velocity {
    // To do this the `Component` trait has an associated type
    // which is used to associate the type back to the container type.
    // There are a few common containers, VecStorage and HashMapStorage
    // are the most common used.
    //
    // See the documentation on the ecs::Storage trait for more information.
    // https://docs.rs/specs/0.9.5/specs/struct.Storage.html
    type Storage = HashMapStorage<Velocity>;
}

// After creating a builder, we can add any number of components
// using the register method.
let assets_dir = "assets/";
let mut game = Application::build(assets_dir, NullState)?
    .register::<Velocity>();

pub fn with_resource<R>(self, resource: R) -> Self where
    R: Resource, 

Adds the supplied ECS resource which can be accessed from game systems.

Resources are common data that is shared with one or more game system.

If a resource is added with the identical type as an existing resource, the new resource will replace the old one and the old resource will be dropped.

Parameters

• resource: The initialized resource you wish to register

Type Parameters

• R: resource must implement the Resource trait. This trait will be automatically implemented if Any + Send + Sync traits exist for type R.

Returns

This function returns ApplicationBuilder after it has modified it.

Examples

use amethyst::prelude::*;

struct NullState;
impl EmptyState for NullState {}

// your resource can be anything that can be safely stored in a `Arc`
// in this example, it is a vector of scores with a user name
struct HighScores(Vec<Score>);

struct Score {
    score: u32,
    user: String
}

let score_board = HighScores(Vec::new());
let assets_dir = "assets/";
let mut game = Application::build(assets_dir, NullState)?
    .with_resource(score_board);

pub fn with_source<I, O>(self, name: I, store: O) -> Self where
    I: Into<String>,
    O: Source, 

Register an asset store with the loader logic of the Application.

If the asset store exists, that shares a name with the new store the net effect will be a replacement of the older store with the new one. No warning or panic will result from this action.

Parameters

• name: A unique name or key to identify the asset storage location. name is used later to specify where the asset should be loaded from.
• store: The asset store being registered.

Type Parameters

• I: A String, or a type that can be converted into aString.
• S: A Store asset loader. Typically this is a Directory.

Returns

This function returns ApplicationBuilder after it has modified it.

Examples

use amethyst::prelude::*;
use amethyst::assets::{Directory, Loader, Handle};
use amethyst::renderer::{Mesh, formats::mesh::ObjFormat};
use amethyst::ecs::prelude::World;

let assets_dir = "assets/";
let mut game = Application::build(assets_dir, LoadingState)?
    // Register the directory "custom_directory" under the name "resources".
    .with_source("custom_store", Directory::new("custom_directory"))
    .build(GameDataBuilder::default())?
    .run();

struct LoadingState;
impl SimpleState for LoadingState {
    fn on_start(&mut self, data: StateData<'_, GameData<'_, '_>>) {
        let storage = data.world.read_resource();

        let loader = data.world.read_resource::<Loader>();
        // Load a teapot mesh from the directory that registered above.
        let mesh: Handle<Mesh> =
            loader.load_from("teapot", ObjFormat, "custom_directory", (), &storage);
    }
}

pub fn with_default_source<O>(self, store: O) -> Self where
    O: Source, 

Registers the default asset store with the loader logic of the Application.

Parameters

• store: The asset store being registered.

Type Parameters

• S: A Store asset loader. Typically this is a Directory.

Returns

This function returns ApplicationBuilder after it has modified it.

Examples

use amethyst::prelude::*;
use amethyst::assets::{Directory, Loader, Handle};
use amethyst::renderer::{Mesh, formats::mesh::ObjFormat};
use amethyst::ecs::prelude::World;

let assets_dir = "assets/";
let mut game = Application::build(assets_dir, LoadingState)?
    // Register the directory "custom_directory" as default source for the loader.
    .with_default_source(Directory::new("custom_directory"))
    .build(GameDataBuilder::default())?
    .run();

struct LoadingState;
impl SimpleState for LoadingState {
    fn on_start(&mut self, data: StateData<'_, GameData<'_, '_>>) {
        let storage = data.world.read_resource();

        let loader = data.world.read_resource::<Loader>();
        // Load a teapot mesh from the directory that registered above.
        let mesh: Handle<Mesh> = loader.load("teapot", ObjFormat, (), &storage);
    }
}

pub fn with_frame_limit(
    self,
    strategy: FrameRateLimitStrategy,
    max_fps: u32
) -> Self

Sets the maximum frames per second of this game.

Parameters

strategy: the frame limit strategy to use max_fps: the maximum frames per second this game will run at.

Returns

This function returns the ApplicationBuilder after modifying it.

pub fn with_frame_limit_config(self, config: FrameRateLimitConfig) -> Self

Sets the maximum frames per second of this game, based on the given config.

Parameters

config: the frame limiter config

Returns

This function returns the ApplicationBuilder after modifying it.

pub fn with_fixed_step_length(self, duration: Duration) -> Self

Sets the duration between fixed updates, defaults to one sixtieth of a second.

Parameters

duration: The duration between fixed updates.

Returns

This function returns the ApplicationBuilder after modifying it.

pub fn ignore_window_close(self, ignore: bool) -> Self

Tells the resulting application window to ignore close events if ignore is true. This will make your game window unresponsive to operating system close commands. Use with caution.

Parameters

ignore: Whether or not the window should ignore these events. False by default.

Returns

This function returns the ApplicationBuilder after modifying it.

pub fn build<'a, I>(
    self,
    init: I
) -> Result<CoreApplication<'a, T, E, X>, Error> where
    S: State<T, E> + 'a,
    I: DataInit<T>,
    E: Clone + Send + Sync + 'static,
    X: Default,
    X: EventReader<'b, Event = E>, 

Build an Application object using the ApplicationBuilder as configured.

Returns

This function returns an Application object wrapped in the Result type.

Errors

This function currently will not produce an error, returning a result type was strictly for future possibilities.

Notes

If the "profiler" feature is used, this function will register the thread that executed this function as the "Main" thread.

Examples

See the example show for ApplicationBuilder::new() for an example on how this method is used.