Struct all_is_cubes::space::Space

pub struct Space { /* fields omitted */ }

Container for Blocks arranged in three-dimensional space. The main “game world” data structure.

Implementations

impl Space

Methods on Space that specifically implement the lighting algorithm.

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).

TODO: Revisit whether this is a good public API.

impl Space

pub fn for_block(resolution: Resolution) -> SpaceBuilder

Returns a SpaceBuilder configured for a block, which may be used to construct a new Space.

This means that its bounds are as per Grid::for_block(), and its physics is SpacePhysics::DEFAULT_FOR_BLOCK.

pub fn builder(grid: Grid) -> SpaceBuilder

Returns a SpaceBuilder with the given grid and all default values, which may be used to construct a new Space.

pub fn empty(grid: Grid) -> Space

Constructs a Space that is entirely filled with AIR.

Equivalent to Space::builder(grid).build_empty()

pub fn empty_positive(
    wx: GridCoordinate,
    wy: GridCoordinate,
    wz: GridCoordinate
) -> Space

Constructs a Space that is entirely empty and whose coordinate system is in the +X+Y+Z octant. This is a shorthand intended mainly for tests.

pub fn listen(
    &self,
    listener: impl Listener<SpaceChange> + Send + Sync + 'static
)

Registers a listener for mutations of this space.

pub fn grid(&self) -> Grid

Returns the Grid describing the bounds of this space; no blocks may exist outside it.

pub fn get_block_index(
    &self,
    position: impl Into<GridPoint>
) -> Option<BlockIndex>

Returns the internal unstable numeric ID for the block at the given position, which may be mapped to a Block by Space::block_data. If you are looking for simple access, use space[position] (the std::ops::Index trait) instead.

These IDs may be used to perform efficient processing of many blocks, but they may be renumbered after any mutation.

pub fn extract<V>(
    &self,
    subgrid: Grid,
    extractor: impl FnMut(Option<BlockIndex>, &SpaceBlockData, PackedLight) -> V
) -> GridArray<V>

Copy data out of a portion of the space in a caller-chosen format.

If the provided Grid contains portions outside of this space’s grid, those positions in the output will be treated as if they are filled with AIR and lit by SpacePhysics::sky_color.

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

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

pub fn get_lighting(&self, position: impl Into<GridPoint>) -> PackedLight

Returns the light occupying the given cube.

This value may be considered as representing the average of the light reflecting off of all surfaces within, or immediately adjacent to and facing toward, this cube. If there are no such surfaces, or if the given position is out of bounds, the result is arbitrary. If the position is within an opaque block, the result is black.

Lighting is updated asynchronously after modifications, so all above claims about the meaning of this value are actually “will eventually be, if no more changes are made”.

pub fn set<'a>(
    &mut self,
    position: impl Into<GridPoint>,
    block: impl Into<Cow<'a, 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.

use all_is_cubes::block::*;
use all_is_cubes::math::Rgba;
use all_is_cubes::space::Space;
let mut space = Space::empty_positive(1, 1, 1);
let a_block = Block::builder().color(Rgba::new(1.0, 0.0, 0.0, 1.0)).build();
space.set((0, 0, 0), &a_block);
assert_eq!(space[(0, 0, 0)], a_block);

pub fn fill<F, B>(
    &mut self,
    region: Grid,
    function: F
) -> Result<(), SetCubeError> where
    F: FnMut(GridPoint) -> 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 grid extends outside of self.grid(), that will always be rejected before any changes are made.)

use all_is_cubes::block::{AIR, Block};
use all_is_cubes::math::Rgba;
use all_is_cubes::space::{Grid, Space};

let mut space = Space::empty_positive(10, 10, 10);
let a_block: Block = Rgba::new(1.0, 0.0, 0.0, 1.0).into();

space.fill(Grid::new((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)], AIR);

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

See also Space::fill_uniform for filling a region with one block.

pub fn fill_uniform<'b>(
    &mut self,
    region: Grid,
    block: impl Into<Cow<'b, Block>>
) -> Result<(), SetCubeError>

Replace blocks in region with the given block.

TODO: Document error behavior

use all_is_cubes::block::{AIR, Block};
use all_is_cubes::math::Rgba;
use all_is_cubes::space::{Grid, Space};

let mut space = Space::empty_positive(10, 10, 10);
let a_block: Block = Rgba::new(1.0, 0.0, 0.0, 1.0).into();

space.fill_uniform(Grid::new((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)], &AIR);

See also Space::fill for non-uniform fill and bulk copies.

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

Provides an DrawTarget adapter for 2.5D drawing.

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

pub fn distinct_blocks(&self) -> Vec<Block>

Returns all distinct block types found in the space.

TODO: This was invented for testing the indexing of blocks and should be replaced with something else if it only gets used for testing.

pub fn block_data(&self) -> &[SpaceBlockData]

Returns data about all the blocks assigned internal IDs (indices) in the space, as well as placeholder data for any deallocated indices.

The indices of this slice correspond to the results of Space::get_block_index.

pub fn step(
    &mut self,
    self_ref: Option<&URef<Space>>,
    tick: Tick
) -> (SpaceStepInfo, UniverseTransaction)

Advance time in the space.

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 physics(&self) -> &SpacePhysics

Returns the current SpacePhysics data, which determines global characteristics such as the behavior of light and gravity.

pub fn set_physics(&mut self, physics: SpacePhysics)

Sets the physics parameters, as per physics.

This may cause recomputation of lighting.

pub fn spawn(&self) -> &Spawn

pub fn spawn_mut(&mut self) -> &mut Spawn

pub fn add_behavior<B>(&mut self, behavior: B) where
    B: Behavior<Self> + 'static, 

Trait Implementations

impl Debug for Space

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

Formats the value using the given formatter.

impl<T: Into<GridPoint>> Index<T> for Space

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

Gets a reference to the block in this space at the given position.

If the position is out of bounds, returns AIR.

Note that Space does not implement IndexMut; use Space::set or Space::fill to modify blocks.

type Output = Block

The returned type after indexing.

impl Transaction<Space> for SpaceTransaction

type CommitCheck = <BehaviorSetTransaction<Space> as Transaction<BehaviorSet<Space>>>::CommitCheck

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 = ()

The result of a Transaction::commit() or Transaction::execute().

fn check(&self, space: &Space) -> 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,
    space: &mut Space,
    check: Self::CommitCheck
) -> Result<(), Box<dyn Error>>

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) -> Result<Self::Output, Box<dyn Error>>

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

fn bind(self, target: URef<T>) -> UniverseTransaction where
    Self: Sized,
    T: UTransactional<Transaction = Self>, 

Specify the target of this transaction as a URef, and erase its type, so that it can be combined with other transactions in the same universe.

impl Transactional for Space

type Transaction = SpaceTransaction

impl UTransactional for Space

fn bind(
    target: URef<Self>,
    transaction: Self::Transaction
) -> UniverseTransaction

Specify the target of the transaction as a URef, and erase its type, so that it can be combined with other transactions in the same universe.

impl UniverseIndex<Space> for Universe

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

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

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

Inserts a new object with a specific name.

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

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