Struct amethyst::ApplicationBuilder

pub struct ApplicationBuilder<'a, 'b, T> {
    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<'a, 'b, T> ApplicationBuilder<'a, 'b, T>

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

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, LocalTransform, TransformSystem};

struct NullState;
impl State 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 mut game = Application::build("assets/", NullState)
    .expect("Failed to initialize")

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

// systems can be added before the game is run
    .with::<TransformSystem>(TransformSystem::new(), "transform_system", &[])

// lastly we can build the Application object
    .build()
    .expect("Failed to create Application");

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

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

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::{Component, HashMapStorage};

struct NullState;
impl State 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 specs::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.
Application::build("assets/", NullState)
    .expect("Failed to initialize")
    .register::<Velocity>();

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 State 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());
Application::build("assets/", NullState)
    .expect("Failed to initialize")
    .with_resource(score_board);

fn with_barrier(self) -> Self

Inserts a barrier which assures that all systems added before the barrier are executed before the ones after this barrier.

Does nothing if there were no systems added since the last call to with_barrier(). Thread-local systems are not affected by barriers; they're always executed at the end.

Returns

This function returns ApplicationBuilder after it has modified it.

Examples

use amethyst::prelude::*;
use amethyst::ecs::System;

struct NullState;
impl State for NullState {}

struct NopSystem;
impl<'a> System<'a> for NopSystem {
    type SystemData = ();
    fn run(&mut self, (): Self::SystemData) {}
}

// Three systems are added in this example. The "tabby cat" & "tom cat"
// systems will both run in parallel. Only after both cat systems have
// run is the "doggo" system permitted to run them.
Application::build("assets/", NullState)
    .expect("Failed to initialize")
    .with(NopSystem, "tabby cat", &[])
    .with(NopSystem, "tom cat", &[])
    .with_barrier()
    .with(NopSystem, "doggo", &[]);

fn with<S>(self, system: S, name: &str, dependencies: &[&str]) -> Self where
    S: System<'c> + Send + 'a, 

Adds a given system to the game loop.

Note: all dependencies must be added before you add the system.

Parameters

• system: The system that is to be added to the game loop.
• name: A unique string to identify the system by. This is used for dependency tracking. This name may be empty "" string in which case it cannot be referenced as a dependency.
• dependencies: A list of named system that must have completed running before this system is permitted to run. This may be an empty list if there is no dependencies.

Returns

This function returns ApplicationBuilder after it has modified it.

Type Parameters

• S: A type that implements the System trait.

Panics

If two system are added that share an identical name, this function will panic. Empty names are permitted, and this function will not panic if more then two are added.

If a dependency is referenced (by name), but has not previously been added this function will panic.

Examples

use amethyst::prelude::*;
use amethyst::ecs::System;

struct NullState;
impl State for NullState {}

struct NopSystem;
impl<'a> System<'a> for NopSystem {
    type SystemData = ();
    fn run(&mut self, _: Self::SystemData) {}
}

Application::build("assets/", NullState)
    .expect("Failed to initialize")
    // This will add the "foo" system to the game loop, in this case
    // the "foo" system will not depend on any systems.
    .with(NopSystem, "foo", &[])
    // The "bar" system will only run after the "foo" system has completed
    .with(NopSystem, "bar", &["foo"])
    // It is legal to register a system with an empty name
    .with(NopSystem, "", &[]);

fn with_thread_local<S>(self, system: S) -> Self where
    S: System<'c> + 'b, 

Add a given thread-local system to the game loop.

A thread-local system is one that must run on the main thread of the game. A thread-local system would be necessary typically to work around vendor APIs that have thread dependent designs; an example being OpenGL which uses a thread-local state machine to function.

All thread-local systems are executed sequentially after all non-thread-local systems.

Parameters

• system: The system that is to be added to the game loop.

Returns

This function returns ApplicationBuilder after it has modified it.

Type Parameters

• S: A type that implements the System trait.

Examples

use amethyst::prelude::*;
use amethyst::ecs::System;

struct NullState;
impl State for NullState {}

struct NopSystem;
impl<'a> System<'a> for NopSystem {
    type SystemData = ();
    fn run(&mut self, _: Self::SystemData) {}
}

Application::build("assets/", NullState)
    .expect("Failed to initialize")
    // the Nop system is registered here
    .with_thread_local(NopSystem);

fn with_local<S>(self, system: S) -> Self where
    S: RunNow<'c> + 'b, 

Add a local RunNow system.

The added system will be dispatched after all normal and thread local systems. This is special because it does accept types implementing only RunNow, but not System, which is needed for e.g. the RenderSystem.

Examples

use amethyst::core::transform::Transform;
use amethyst::prelude::*;
use amethyst::renderer::*;

let pipe = Pipeline::build().with_stage(
    Stage::with_backbuffer()
        .clear_target([0.0, 0.0, 0.0, 1.0], 1.0)
        .with_pass(DrawShaded::<PosNormTex>::new()),
);

let config = DisplayConfig::load("config_path.ron");

let mut game = Application::build("resources/", Example)?
.with_bundle(RenderBundle::new())?
.with_local(RenderSystem::build(pipe, Some(config))?)
.build()?;

fn with_bundle<B>(self, bundle: B) -> Result<Self> where
    B: ECSBundle<'a, 'b>, 

Add a given ECS bundle to the game loop.

A bundle is a container for registering a bunch of ECS systems and their dependent resources and components.

Parameters

• bundle: The bundle to add

Returns

This function returns ApplicationBuilder after it has modified it, this is wrapped in a Result.

Errors

This function creates systems and resources, which use any number of dependent crates or APIs, which could result in any number of errors. See each individual bundle for a description of the errors it could produce.

fn with_source<I, S>(self, name: I, store: S) -> Self where
    I: Into<String>,
    S: 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};
use amethyst::renderer::ObjFormat;
use amethyst::ecs::World;

let mut game = Application::build("assets/", LoadingState)
    .expect("Failed to initialize")
    // Register the directory "custom_directory" under the name "resources".
    .with_source("custom_store", Directory::new("custom_directory"))
    .build()
    .expect("Failed to build game")
    .run();

struct LoadingState;
impl State for LoadingState {
    fn on_start(&mut self, world: &mut World) {
        let storage = world.read_resource();

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

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.

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.

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.

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.

fn register_asset<A>(self) -> Self where
    A: Asset, 

Register a new asset type with the Application. All required components related to the storage of this asset type will be registered. Since Amethyst uses AssetFutures to allow for async content loading, Amethyst needs to have a system that translates AssetFutures into Components as they resolve. Amethyst registers a system to accomplish this.

Parameters

make_context: A closure that returns an initialized Asset::Context object. This is given the a reference to the world object to allow it to find any resources previously registered.

Type Parameters

• A: The asset type, an Asset in reference to Amethyst is a component that implements the Asset trait.
• F: A function that returns the Asset::Context context object.

Returns

This function returns ApplicationBuilder after it has modified it.

fn build(self) -> Result<Application<'a, 'b>> where
    T: State + 'a, 

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.