Crate all_is_cubes
source ·Expand description
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 aUniverse
.- A
Space
is a 3D array ofBlock
s forming the physical space/scene which player characters can move through and interact with.Space
s currently have fixed boundaries (no infinite procedural generation), can have dimensions in the range of ani32
, 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,Space
s have global physical properties such as gravity and illumination. They also can haveBehavior
s 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 assistsBlock
s.
- A
Block
is a cubical object which can be placed in aSpace
or carried in aCharacter
’s inventory.- Blocks’ shape and appearance (their
Primitive
) is either a cube of a single color, or recursively defined by aSpace
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
Space
s 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
Space
s, such as for the purposes of animation or deriving variations from a single template or formula.
- The player will be able to enter these
- Blocks can have
Modifier
s 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.
- Blocks’ shape and appearance (their
- A
Character
can move around aSpace
, acting as the player’s viewpoint, and carryTool
s (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
andBlock
use 3-dimensional integer coordinates with no assumptions about axes. However, the defaultSpacePhysics
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
andBody
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.
§Package features
This package, all-is-cubes
, defines the following feature flags:
"save"
: Enableserde
serialization ofUniverse
s and some other types."auto-threads"
: Enable use of threads for parallel and background processing, including viarayon
’s global thread pool. This feature does not affect the public API (except via enabling other features), only performance and dependencies."arbitrary"
: Adds implementations of thearbitrary::Arbitrary
trait for fuzzing / property testing on types defined by this crate."std"
(enabled by default): If disabled, the library becomesno_std
compatible, at this cost:- Many types are no longer
Send
orSync
. Listener
callbacks are no longer required to beSend + Sync
, which makes this feature non-additive. Proceed with care.- Certain data calculations are not memoized.
- Error types do not implement
std::error::Error
.
- Many types are no longer
§Platform compatibility
- Compatible with web
wasm32-unknown-unknown
, whether or not thestd
feature is active. That is, the parts ofstd
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 (asall_is_cubes::euclid
).ordered_float
(asall_is_cubes::math::NotNan
).embedded_graphics
(asall_is_cubes::drawing::embedded_graphics
).
Re-exports§
Modules§
- Dynamic add-ons to game objects; we might also have called them “components”.
- Player-character stuff.
- Algorithms for grouping cubes into cubical batches (chunks).
- Draw 2D graphics and text into
Space
s, using a general adapter forembedded_graphics
’s drawing algorithms. - Momentary decorative and informative effects produced by the game world, such as sound and particles.
- Storing and accessing definitions of standard blocks in a
Universe
. - Broadcasting of notifications of state changes, and other messages.
- Mathematical utilities and decisions.
Operation
s that modify the world due to player or world actions.- Continuously moving objects and collision.
- Algorithm for raycasting through voxel grids.
- Serialization/persistence/saved games.
- That which contains many blocks.
- Data types for simulated and real time.
- The
Transaction
trait, for modifying game objects. Universe
, the top-level game-world container.- Tools that we could imagine being in the Rust standard library, but aren’t.
Macros§
- Construct a
Block
with the given reflectance color, and default attributes.