Struct all_is_cubes::universe::Universe

pub struct Universe {
    pub whence: Arc<dyn WhenceUniverse>,
    /* private fields */
}

A collection of named objects which can refer to each other via URef, and which are simulated at the same time steps.

Thread-safety caveat: See the documentation on avoiding deadlock.

A Universe consists of:

• members of various types, which may be identified using Names or URefs.
• Behaviors that modify the Universe itself.
• A time::Clock defining how time is considered to pass in it.
• A WhenceUniverse defining where its data is persisted, if anywhere.
• A UniverseId unique within this process.

Serialization stability warning

This type implements serde::Serialize and serde::Deserialize, but serialization support is still experimental (as is the game data model in general). We do not guarantee that future versions of all-is-cubes will be able to deserialize data which is serialized by this version.

Additionally, the serialization schema is designed with serde_json in mind. It is not guaranteed that using a different data format crate, which may use a different subset of the information exposed via serde::Serialize, will produce stable results.

Fields

whence: Arc<dyn WhenceUniverse>

Where the contents of `self came from, and where they might be able to be written back to.

For universes created by Universe::new(), this is equal to Arc::new(()).

Implementations

impl Universe

pub fn new() -> Self

Constructs an empty Universe.

pub fn get_any(&self, name: &Name) -> Option<Box<dyn URefErased>>

Returns a URef for the object in this universe with the given name, regardless of its type, or None if there is none.

This is a dynamically-typed version of Universe::get().

pub fn get_default_character(&self) -> Option<URef<Character>>

Returns the character named "character". This is currently assumed to be the “player character” for this universe.

TODO: this is a temporary shortcut to be replaced with something with more nuance (e.g. we might have temporary characters for editing purposes, which are ‘current’ but not ‘primary’).

pub fn universe_id(&self) -> UniverseId

Returns a unique identifier for this particular Universe (within this memory space).

It may be used to determine whether a given URef belongs to this universe or not.

pub fn step<I: Instant>( &mut self, paused: bool, deadline: Deadline<I> ) -> UniverseStepInfo

Advance time for all members.

• deadline is when to stop computing flexible things such as light transport.

pub fn clock(&self) -> Clock

Returns the time::Clock that is used to advance time when step() is called.

pub fn insert_anonymous<T>(&mut self, value: T) -> URef<T>

where Self: UniverseOps<T>, T: UniverseMember,

Inserts a new object without giving it a specific name, and returns a reference to it.

pub fn get<T>(&self, name: &Name) -> Option<URef<T>>

where Self: UniverseOps<T>, T: UniverseMember,

Translates a name for an object of type T into a URef for it, which allows borrowing the actual object.

Returns None if no object exists for the name.

pub fn insert<T>( &mut self, name: Name, value: T ) -> Result<URef<T>, InsertError>

where Self: UniverseOps<T>, T: UniverseMember,

Inserts a new object with a specific name.

Returns an error if the name is already in use.

pub fn iter_by_type<T>(&self) -> UniverseIter<'_, T>

where Self: UniverseOps<T>, T: UniverseMember,

Iterate over all of the objects of type T. Note that this includes anonymous objects.

use all_is_cubes::block::{Block, BlockDef};
use all_is_cubes::content::make_some_blocks;
use all_is_cubes::universe::{Name, Universe, URef};

let mut universe = Universe::new();
let [block_1, block_2] = make_some_blocks();
universe.insert(Name::from("b1"), BlockDef::new(block_1.clone()));
universe.insert(Name::from("b2"), BlockDef::new(block_2.clone()));

let mut found_blocks = universe.iter_by_type()
    .map(|(name, value): (Name, URef<BlockDef>)| {
        (name, value.read().unwrap().block().clone())
    })
    .collect::<Vec<_>>();
found_blocks.sort_by_key(|(name, _)| name.to_string());
assert_eq!(
    found_blocks,
    vec![Name::from("b1"), Name::from("b2")].into_iter()
        .zip(vec![block_1, block_2])
        .collect::<Vec<_>>(),
);

pub fn gc(&mut self)

Delete all anonymous members which have no references to them.

This may happen at any time during operations of the universe; calling this method merely ensures that it happens now and not earlier.

Trait Implementations

impl BehaviorHost for Universe

type Attachment = ()

Additional data about “where” the behavior is attached to the host; what part of the host should be affected by the behavior.

impl Debug for Universe

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Universe

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Universe

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Serialize for Universe

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl Transaction<Universe> for UniverseTransaction

type CommitCheck = UniverseCommitCheck

Type of a value passed from Transaction::check to Transaction::commit. This may be used to pass precalculated values to speed up the commit phase, or even lock guards or similar, but also makes it slightly harder to accidentally call commit without check.

type Output = Infallible

The results of a Transaction::commit() or Transaction::execute(). Each commit may produce any number of these messages.

fn check( &self, target: &Universe ) -> Result<Self::CommitCheck, PreconditionFailed>

Checks whether the target’s current state meets the preconditions and returns Err if it does not. (TODO: Informative error return type.)

fn commit( &self, target: &mut Universe, checks: Self::CommitCheck, outputs: &mut dyn FnMut(Self::Output) ) -> Result<(), CommitError>

Perform the mutations specified by this transaction. The check value should have been created by a prior call to Transaction::commit.

fn execute( &self, target: &mut T, outputs: &mut dyn FnMut(Self::Output) ) -> Result<(), ExecuteError>

Convenience method to execute a transaction in one step. Implementations should not need to override this. Equivalent to:

impl Transactional for Universe

type Transaction = UniverseTransaction

The type of transaction which should be used with Self.