Getting started§

ncollide relies on the official Rust package manager Cargo for dependency resolution and compilation. Therefore, making ncollide ready to be used by your project is simply a matter of adding a new dependency to your Cargo.toml file. Note that you will probably need nalgebra version 0.13.0 as well because it defines algebraic entities (vectors, points, transformation matrices) used by most types of ncollide.

[dependencies]
nalgebra = "0.13.0"
ncollide = "0.13.0"

Until ncollide reaches 1.0, it is strongly recommended to always use its latest version, though you might encounter breaking changes from time to time. Once your Cargo.toml file is set up, the corresponding crate must be imported by your project with the usual extern crate directive:

extern crate ncollide;

Cargo example§

You may use this Cargo.toml file to compile the downloadable examples of this guide. Simply replace example.rs by the actual example’s file name.

[package]
name    = "example-using-ncollide"
version = "0.0.0"
authors = [ "You" ]

[dependencies]
approx   = "0.1.0"
alga     = "0.5.0"
nalgebra = "0.13.0"
ncollide = "0.13.0"

[[bin]]
name = "example"
path = "./example.rs"

Project structure§

The ncollide crate is only an interface for several, smaller crates part of the ncollide project. Thus if only a subset of the features is of interest to you, you may directly depend any of them individually:

Crate name Description
ncollide_math Traits that must be satisfied by algebraic entities used by the whole project.
ncollide_utils Miscellaneous data structures and basic geometrical operations needed by all the other crates.
ncollide_geometry The geometric kernel of ncollide. It defines shapes, bounding volumes, structures for spacial partitioning, and geometric queries operating on all of them.
ncollide_procedural Procedural mesh generation from parameters provided by the user.
ncollide_transformation Operators that create an alternative geometrical representation of a shape or mesh given in input. This includes convex hull, convex decomposition, and shapes discretization.
ncollide_pipeline Persistent structures for recurrent geometric queries. This exploits time coherence and implements explicitly the concepts of broad phase and narrow phase. This also includes the collision world which is the main interface between the user ncollide.

To use any of those crates, simply add a corresponding dependency entry to your Cargo.toml. Note that you should not expect the version numbers of those crates to be identical. For example, ncollide being in version 0.13.0 does not implies that ncollide_geometry (say) is at its version 0.13.0 as well.


Geometric representations