Struct all_is_cubes::block::Block

pub struct Block(/* private fields */);

A Block is something that can exist in the grid of a Space; it occupies one unit cube of simulated physical space, and has a specified appearance and behavior.

A Block is made up of a Primitive and zero or more Modifiers.

In general, when a block appears multiple times from an in-game perspective, that may or may not be the the same copy; Blocks are “by value” and any block Eq to another will behave identically and should be treated identically. However, some blocks are defined by reference to shared mutable data, and Block containers such as Space must follow those changes.

To determine the concrete appearance and behavior of a block, use Block::evaluate() or Block::evaluate_and_listen(), which will return an EvaluatedBlock value.

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.

Implementations

impl Block

pub const fn builder() -> BlockBuilder<NeedsPrimitive, ()>

Returns a new BlockBuilder which may be used to construct a Block value from various inputs with convenient syntax.

pub fn from_primitive(p: Primitive) -> Self

Construct a Block from a Primitive value.

pub fn primitive(&self) -> &Primitive

Returns the Primitive which defines this block before any Modifiers are applied.

pub fn primitive_mut(&mut self) -> &mut Primitive

Returns a mutable reference to the Primitive which defines this block before any Modifiers are applied.

This may cause part or all of the block’s data to stop sharing storage with other blocks.

pub fn modifiers(&self) -> &[Modifier]

Returns all the modifiers of this block.

Modifiers are arranged in order of their application to the primitive, or “innermost” to “outermost”.

Note that this does not necessarily return all modifiers involved in its definition; modifiers on the far end of a Primitive::Indirect are not reported here, even though they take effect when evaluated.

pub fn modifiers_mut(&mut self) -> &mut Vec<Modifier>

Returns a mutable reference to the vector of Modifiers on this block.

This may cause part or all of the block’s data to stop sharing storage with other blocks.

pub fn with_modifier(self, modifier: impl Into<Modifier>) -> Self

Add the given modifier to this block.

This is a convenience operation which is exactly equivalent to doing block.modifiers_mut().push(modifier.into()). It does not do any of the special case logic that, for example, Block::rotate() does.

pub fn rotate(self, rotation: GridRotation) -> Self

Rotates this block by the specified rotation.

Compared to direct use of Modifier::Rotate, this will:

• Avoid constructing chains of redundant modifiers.
• Not rotate blocks that should never appear rotated (including atom blocks).

(TODO: This should be replaced with with_modifier() or similar having a general rule set for combining modifiers.)

use all_is_cubes::block::{AIR, Block, Modifier};
use all_is_cubes::color_block;
use all_is_cubes::content::make_some_voxel_blocks;
use all_is_cubes::math::{GridRotation, Rgba};
use all_is_cubes::universe::Universe;

let mut universe = Universe::new();
let [block] = make_some_voxel_blocks(&mut universe);
let clockwise = GridRotation::CLOCKWISE;

// Basic rotation
let rotated = block.clone().rotate(clockwise);
assert_eq!(rotated.modifiers(), &[Modifier::Rotate(clockwise)]);

// Multiple rotations are combined
let double = rotated.clone().rotate(clockwise);
assert_eq!(double.modifiers(), &[Modifier::Rotate(clockwise * clockwise)]);

// Atoms and AIR are never rotated
let atom = color_block!(Rgba::WHITE);
assert_eq!(atom.clone().rotate(clockwise), atom);
assert_eq!(AIR.rotate(clockwise), AIR);

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

Standardizes any characteristics of this block which may be presumed to be specific to its usage in its current location, so that it can be used elsewhere or compared with others. Specifically, it has the following effects:

• Removes Modifier::Rotate.

In future versions there may be additional changes or ones customizable per block.

Examples

Removing rotation:

use all_is_cubes::block::Block;
use all_is_cubes::math::GridRotation;
use all_is_cubes::universe::Universe;

let mut universe = Universe::new();
let [block] = make_some_voxel_blocks(&mut universe);
let rotated = block.clone().rotate(GridRotation::CLOCKWISE);

assert_ne!(&block, &rotated);
assert_eq!(vec![block], rotated.clone().unspecialize());

pub fn evaluate(&self) -> Result<EvaluatedBlock, EvalBlockError>

Converts this Block into a “flattened” and snapshotted form which contains all information needed for rendering and physics, and does not require Handle access to other objects.

pub fn evaluate_and_listen( &self, listener: impl Listener<BlockChange> + 'static, ) -> Result<EvaluatedBlock, EvalBlockError>

As Block::evaluate(), but also installs a listener which will be notified of changes in all data sources that might affect the evaluation result.

Note that this does not listen for mutations of the Block value itself, in the sense that none of the methods on Block will cause this listener to fire. Rather, it listens for changes in by-reference-to-interior-mutable-data sources such as the Space referred to by a Primitive::Recur or the BlockDef referred to by a Primitive::Indirect.

Errors

If an evaluation error is reported, the Listener may have been installed incompletely or not at all. It should not be relied on.

pub fn color(&self) -> Rgba

Returns the single Rgba color of this block’s Primitive::Atom or Primitive::Air, or panics if it has a different kind of primitive. Intended for use in tests only.

Trait Implementations

impl<'a> Arbitrary<'a> for Block

fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

impl AsRef<Block> for BlockDef

fn as_ref(&self) -> &Block

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Block

fn clone(&self) -> Block

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Block

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Block

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

Deserialize this value from the given Serde deserializer.

impl<'a> From<&'a Block> for Cow<'a, Block>

fn from(block: &'a Block) -> Self

Converts to this type from the input type.

impl From<&'static Primitive> for Block

fn from(r: &'static Primitive) -> Self

Constructs a Block which references the given static Primitive.

This performs no allocation.

impl From<Atom> for Block

fn from(value: Atom) -> Self

Converts to this type from the input type.

impl From<Block> for Cow<'_, Block>

fn from(block: Block) -> Self

Converts to this type from the input type.

impl<C: BuildPrimitive> From<BlockBuilder<C, ()>> for Block

Allows implicitly converting BlockBuilder to the block it would build.

fn from(builder: BlockBuilder<C, ()>) -> Self

Converts to this type from the input type.

impl From<Handle<BlockDef>> for Block

fn from(block_def_handle: Handle<BlockDef>) -> Self

Convert a Handle<BlockDef> into a block with Primitive::Indirect that refers to it.

The returned block will evaluate to the same EvaluatedBlock as the block contained within the given BlockDef (except in case of errors).

impl From<Primitive> for Block

fn from(primitive: Primitive) -> Self

Constructs a Block that owns the given Primitive.

This operation creates a heap allocation for the Primitive.

impl From<Rgb> for Block

fn from(color: Rgb) -> Self

Constructs a Block with the given reflectance color, and default attributes.

This operation allocates a new Primitive value on the heap. If the color is a constant, you may use color_block! instead to avoid allocation.

impl From<Rgba> for Block

fn from(color: Rgba) -> Self

Construct a Block with the given reflectance color, and default attributes.

This operation allocates a new Primitive value on the heap. If the color is a constant, you may use color_block! instead to avoid allocation.

impl Hash for Block

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Block

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PixelColor for &'a Block

type Raw = ()

Raw data type.

impl Serialize for Block

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

Serialize this value into the given Serde serializer.

impl VisitHandles for Block

fn visit_handles(&self, visitor: &mut dyn HandleVisitor)

For each Handle contained within self that is reachable without traversing another Handle, call visitor with a reference to it.

impl<'a> VoxelColor<'a> for &'a Block

fn into_blocks(self) -> VoxelBrush<'a>

Returns a corresponding VoxelBrush, the most general form of blocky drawing.

impl Eq for Block