Crate all_is_cubes

All is Cubes is a game/engine for worlds made of cubical blocks, where the blocks are themselves made of “smaller” blocks (voxels) that define their appearance and behavior.

This crate defines the world model, simulation rules, and basic non-GPU-accelerated rendering. (User interface components, platform glue, and game content are kept in other crates.) This crate is designed to be a reusable library for simulating and rendering voxel world/scenes, but is not yet mature.

Capabilities

Here is a brief summary of the concepts and capabilities (actual or planned) of All is Cubes, so that you may evaluate whether it suits your needs. Many of these details are subject to change; this is currently a one-author project with a rather chaotic vision.

Data model

Note that there is not currently any networking/multiplayer, or any save files. Both of these are planned, but may result in substantal revisions to the data model.

• Universe manages a graph of interrelated game objects. It is intended to be the run-time form of what a player might call “a save file” or “a world”. Time advances at a uniform rate throughout a Universe.
• A Space is a 3D array of Blocks forming the physical space/scene which player characters can move through and interact with.
  • Spaces currently have fixed boundaries (no infinite procedural generation), can have dimensions in the range of an i32, and are kept in memory uncompressed at 6 bytes per cube. They can contain at most 65536 distinct blocks (subject to change).
  • The light falling on surfaces within a Space is computed using a global illumination algorithm (optionally).
  • In addition to their Block contents, Spaces have global physical properties such as gravity and illumination. They also can have Behaviors attached for miscellaneous “scripting” purposes, though this feature is incomplete.
  • There can be arbitrarily many spaces per Universe. Eventually there will be ways to teleport between spaces; for now, this mainly assists Blocks.
• A Block is a cubical object which can be placed in a Space or carried in a Character’s inventory.
  • Blocks’ shape and appearance (their Primitive) is either a cube of a single color, or recursively defined by a Space of smaller blocks (at a reduced size between 1/2 to 1/255 of a full cube). Each of these voxels can be transparent.
    • The player will be able to enter these Spaces and interactively edit blocks. This is not currently implemented but that is a lack in the user interface rather than core data structures.
    • In the future, there may be ways for blocks to be fully procedurally defined rather than working through Spaces, such as for the purposes of animation or deriving variations from a single template or formula.
  • Blocks can have Modifiers applied to them which change the basic shape and behavior in a particular instance, such as being rotated into different orientations.
  • Blocks will have various forms of active behavior and responses to their environment but that has not been designed yet.
• A Character can move around a Space, acting as the player’s viewpoint, and carry Tools (items) with which to affect the space.
  • There can be multiple characters, but not yet any multiplayer, NPC AI, or even being able to see another character. Some of these this may be in the future.
  • A character’s ability to modify the Space depends entirely on the provided tools, so that there can be entirely free editing or only actions following gameplay rules.

Coordinate system

Currently, there are some assumptions of a specific coordinate system. All of these might be generalized in the future.

• Space and Block use 3-dimensional integer coordinates with no assumptions about axes. However, the default SpacePhysics configuration currently has a gravity vector in the −Y direction.
• camera assumes OpenGL-style coordinates: +X right, +Y up, +Z towards viewer — a “right-handed” coordinate system.
• Character and Body have a look direction and corresponding transformation matrix which use the same coordinate system as camera. Jumping is also hardcoded to work in the +Y direction. Future versions may support arbitrary character orientation.

Crate features

This crate, all_is_cubes, defines the following feature flags:

• save: Enable serde serialization of Universes and some other types.
• threads: Enable use of threads for parallel and background processing, including via rayon’s global thread pool. This feature does not affect the public API, only performance and dependencies.
• arbitrary: Adds implementations of the arbitrary::Arbitrary trait for fuzzing / property testing on types defined by this crate.
• std (enabled by default): If disabled, the library becomes no_std compatible, at this cost:
  • Many types are no longer Send or Sync.
  • Listener callbacks are no longer required to be Send + Sync, which makes this feature non-additive. Proceed with care.
  • Certain data calculations are not memoized.
  • Error types do not implement std::error::Error.

Platform compatibility

• Compatible with web wasm32-unknown-unknown, whether or not the std feature is active. That is, the parts of std it uses are the thread-safety and floating-point parts, not IO (and not creating threads, unless requested).
• usize must be at least 32 bits (that is, not 16).

Dependencies and global state

all_is_cubes avoids having any global state, for the most part. However, it does write log messages using the log crate and is therefore subject to that global configuration.

all_is_cubes depends on and re-exports the following crates as part of its public API:

• euclid for vector math (as all_is_cubes::euclid).
• ordered_float (as all_is_cubes::math::NotNan).
• embedded_graphics (as all_is_cubes::drawing::embedded_graphics).

Re-exports

• pub use arcstr;
• pub use euclid;

Modules

• behavior
  Dynamic add-ons to game objects; we might also have called them “components”.
• block
  Definition of blocks, which are the game objects which occupy the grid of a Space. See Block for details.
• camera
  Projection and view matrices, viewport and aspect ratio, visibility, raycasting into the scene, etc.
• character
  Player-character stuff.
• chunking
  Algorithms for grouping cubes into cubical batches (chunks).
• drawing
  Draw 2D graphics and text into Spaces, using a general adapter for embedded_graphics’s drawing algorithms.
• fluff
  Momentary decorative effects produced by the game world, such as sound and particles.
• inv
  Characters’ Inventory which contains Tools for modifying the world.
• linking
  Storing and accessing definitions of standard blocks in a Universe.
• listen
  Broadcasting of notifications of state changes, and other messages.
• math
  Mathematical utilities and decisions.
• op
  Operations that modify the world due to player or world actions.
• physics
  Continuously moving objects and collision.
• raycast
  Algorithm for raycasting through voxel grids.
• raytracer
  Raytracer for Spaces.
• save
  Serialization/persistence/saved games.
• space
  That which contains many blocks.
• time
  Data types for simulated and real time.
• transaction
  The Transaction trait, for modifying game objects.
• universe
  Universe, the top-level game-world container.
• util
  Tools that we could imagine being in the Rust standard library, but aren’t.

Macros

• rgb_const
  Allows writing a constant Rgb color value, provided that its components are float literals.
• rgba_const
  Allows writing a constant Rgba color value, provided that its components are float literals.