Struct Mutation 

pub struct Mutation<'m, 'space> { /* private fields */ }

Access to a Space’s contents to perform several modifications.

Obtain this using Space::mutate().

Implementations

impl<'space> Mutation<'_, 'space>

pub fn bounds(&self) -> GridAab

Same as Space::bounds().

pub fn get_evaluated(&self, position: impl Into<Cube>) -> &EvaluatedBlock

Returns the EvaluatedBlock of the block in this space at the given position.

If out of bounds, returns the evaluation of AIR.

pub fn set<'block>( &mut self, position: impl Into<Cube>, block: impl Into<Cow<'block, Block>>, ) -> Result<bool, SetCubeError>

Replace the block in this space at the given position.

If the position is out of bounds, there is no effect.

Returns

Returns Ok(true) if the change was made, Ok(false) if the same block was already present, and Err(_) if the replacement could not be made; see SetCubeError for possible errors.

use all_is_cubes::block;
use all_is_cubes::math::Rgba;
use all_is_cubes::space::Space;
use all_is_cubes::universe::ReadTicket;

let mut space = Space::empty_positive(1, 1, 1);
let a_block = block::from_color!(1.0, 0.0, 0.0, 1.0);

space.mutate(ReadTicket::stub(), |m| {
    m.set([0, 0, 0], &a_block)
}).unwrap();

assert_eq!(space[[0, 0, 0]], a_block);

pub fn fill<F, B>( &mut self, region: GridAab, function: F, ) -> Result<(), SetCubeError>

where F: FnMut(Cube) -> Option<B>, B: Borrow<Block>,

Replace blocks in region with a block computed by the function.

The function may return a reference to a block or a block. If it returns None, the existing block is left unchanged.

The operation will stop on the first error, potentially leaving some blocks replaced. (Exception: If the region extends outside of self.bounds(), that will always be rejected before any changes are made.)

use all_is_cubes::block;
use all_is_cubes::math::{GridAab, Rgba};
use all_is_cubes::space::Space;
use all_is_cubes::universe::ReadTicket;

let mut space = Space::empty_positive(10, 10, 10);
let a_block: block::Block = block::from_color!(1.0, 0.0, 0.0, 1.0);

space.mutate(ReadTicket::stub(), |m| {
    m.fill(GridAab::from_lower_size([0, 0, 0], [2, 1, 1]), |_point| Some(&a_block))
}).unwrap();

assert_eq!(space[[0, 0, 0]], a_block);
assert_eq!(space[[1, 0, 0]], a_block);
assert_eq!(space[[0, 1, 0]], block::AIR);

TODO: Support providing the previous block as a parameter (take cues from extract).

See also Mutation::fill_uniform() for filling a region with one block.

pub fn fill_all<F, B>(&mut self, function: F) -> Result<(), SetCubeError>

where F: FnMut(Cube) -> Option<B>, B: Borrow<Block>,

As Mutation::fill(), but fills the entire space instead of a specified region.

pub fn fill_uniform( &mut self, region: GridAab, block: &Block, ) -> Result<(), SetCubeError>

Replace blocks in region with the given block.

TODO: Document error behavior

use all_is_cubes::block;
use all_is_cubes::math::{GridAab, Rgba};
use all_is_cubes::space::Space;
use all_is_cubes::universe::ReadTicket;

let mut space = Space::empty_positive(10, 10, 10);
let a_block: block::Block = block::from_color!(1.0, 0.0, 0.0, 1.0);

space.mutate(ReadTicket::stub(), |m| {
    m.fill_uniform(GridAab::from_lower_size([0, 0, 0], [2, 1, 1]), &a_block)
}).unwrap();

assert_eq!(&space[[0, 0, 0]], &a_block);
assert_eq!(&space[[1, 0, 0]], &a_block);
assert_eq!(&space[[0, 1, 0]], &block::AIR);

See also Mutation::fill() for non-uniform fill and bulk copies.

pub fn fill_all_uniform(&mut self, block: &Block) -> Result<(), SetCubeError>

As Mutation::fill_uniform(), but fills the entire space instead of a specified region.

pub fn draw_target<C>( &mut self, transform: Gridgid, ) -> DrawingPlane<'_, Self, C>

Provides an DrawTarget adapter for 2.5D drawing.

For more information on how to use this, see all_is_cubes::drawing.

pub fn evaluate_light( &mut self, epsilon: u8, progress_callback: impl FnMut(LightUpdatesInfo), ) -> usize

Perform lighting updates until there are none left to do. Returns the number of updates performed.

This may take a while. It is appropriate for when the goal is to render a fully lit scene non-interactively.

epsilon specifies a threshold at which to stop doing updates. Zero means to run to full completion; one is the smallest unit of light level difference; and so on.

pub fn fast_evaluate_light(&mut self)

Clear and recompute light data and update queue, in a way which gets fast approximate results suitable for flat landscapes mostly lit from above (the +Y axis).

This function is useful immeduately after filling a Space with its initial contents.

TODO: Revisit whether this is a good public API.

pub fn spawn(&self) -> &Spawn

Returns the current default Spawn, which determines where new Characters are placed in the space if no alternative applies.

pub fn set_spawn(&mut self, spawn: Spawn)

Sets the default Spawn, which determines where new Characters are placed in the space if no alternative applies.

Trait Implementations

impl<T: Into<Cube>> Index<T> for Mutation<'_, '_>

type Output = Block

The returned type after indexing.

fn index(&self, position: T) -> &Self::Output

Performs the indexing (container[index]) operation.