Core Concepts

Value Types

These classes represent values, they are usually temporaries or properties of other classes. They form the foundation upon which the rest of the engine is built. Most of the Value Types are contained in the physics/math and physics/geometry folders.

Basic building blocks

• Vec2, Vec3, Vec4, Vec2f, Vec3f, Vec4f, Vector: vectors
• Mat2, Mat3, Mat4, Mat2f, Mat3f, Mat4f, Matrix: matrices
• Quat4, Quat4f, Quaternion: quaternions
• Rotation: implemented as a rotation matrix (though we do have a quaternion implementation as well)
• CFrame: 'Coordinate Frames' represent a position and rotation in space. Used for transforming from one coordinate system to another. For example: Location and orientation of pistons and motors, or relative positions of attached parts.
• BoundingBox: an axis-aligned box, defined by a minimum xyz Vec3, and a maximum xyz Vec3

Fixed-point representation and Positions:

• Fix<32>: Fixed-point decimal number, 32 bits representing the integer part, 32 bits representing the fractional part.
• Position: World-space Vec3; this is so we don't lose precision further from the origin (implemented using Fix<32>)
• GlobalCFrame: World-space CFrame; represents the position and orientation of an object in the world.
• Bounds: World-space BoundingBox; defines an axis-aligned box in the world, is defined by a minimum xyz Position, and a maximum xyz Position

Motion and Taylor types:

• Taylor: represents derivatives, used in Motion. eg velocity -> acceleration -> jerk
• FullTaylor: represents a value and it's derivatives, eg position -> velocity -> acceleration -> jerk
• Motion and it's components TranslationalMotion and RotationalMotion: Represent velocity, angular velocity, acceleration, angular acceleration. Contains a Taylor.
• RelativeMotion: Describes a relative motion at an offset. Contains a CFrame describing the current offset, and a Motion describing the change of that offset. For example, the current state of a piston can be represented as a RelativeMotion. The CFrame is the relative offset, the Motion is the current velocity and acceleration of the piston.

Geometry

• Polyhedron: A closed collection of vertices and triangles connecting them, many interesting quantities can be computed from this, such as volume, and inertial properties.
• TriangleMesh: contains a list of vertices and a list of triangles connecting them, but unline the polyhedron, the shape needs not be closed.
• ShapeClass: Represents a 'normalized' shape. This means a shape that has a boundingbox of exactly -1..1 on all axes. Caches physical properties of shapes such as volume and inertial mass. Builtin ShapeClasses are:
  • CubeClass: Singleton, represents builtin box shape
  • SphereClass: Singleton, represents builtin cylinder shape (restricts scale dimentions y and z to be the same)
  • CylinderClass: Singleton, represents builtin sphere shape (restricts all scale dimentions to be the same)
  • PolyhedronShapeClass: Constructed from a normalized Polyhedron
• Shape: Contains a pointer to it's ShapeClass, as well as a scaling factor. Due to the fact that ShapeClasses represent normalized shapes, these scaling factors translate directly to the shape's BoundingBox.

Data Structures

Data structures differ from value types in that they are not copyable, and are usually fairly persistent. They are found in physics/datastructures

• BoundsTree: A tree Built from TreeNode nodes, leaf nodes represent objects that can have bounds, trunk nodes contain the union of all subNode bounds. Allows for efficiently iterating and trimming collision candidates in the world.
• MonotonicTree: A fixed-size tree structure contained within a single block. Used for reducing allocations and reusing tree memory.

Object Types

These types are meant to be persistent, usually allocated on the heap, and often polymorphic. They represent the current state of the world.

World Structure

Found in physics

• Part: A part in the world, a single block which can move around and interact with others. A Part has a Shape, a GlobalCFrame representing it's location, and various properties such as density, friction, and bouncyness. This is also the primary point of extention for users of the physics library.
• RigidBody: Represents a collection of parts connected together through unmoving attachments, basically a group of parts that are glued together.
• MotorizedPhysical: Represents a group of RigidBodies that are connected together using Hard Constraints
• World: Contains everything. Parts are split up into Layers, between which various update and colission rules can be specified. Can also be extended by the user in conjunction with their extention to Part.
• WorldLayer: A single layer in the world. Contains a BoundsTree to store the parts in that layer. Usually there will be one object layer for all moving objects, which is updated every tick, and one terrain layer, which is optimized once, but does not change during world updates.

Constraints

Found in physics/constraints

• Rigid Constraints: pseudo-class of constraints, does not actually exist. This term is used to refer to two parts being glued together in a RigidBody. In a rigid constraint, the two connected parts do not move relative to each other
• HardConstraint: Interface for creating constraints in which all degrees of freedom are taken away for one part. In other words, one part's CFrame is essentially defined in terms of another's
  • MotorConstraint: A motor along the z-axis. Turns at a constant rate
  • SinusoidalPistonConstraint: A piston along the z-axis. Extends and retracts along a sine wave
  • FixedConstraint: Fixed to be the identity CFrame. HardConstraint version of Rigid Constraints, only used in testing, use Rigid Constraints instead
• Soft Constraint: Class of constraints that do leave at least one degree of freedom. For example a hinge
  • BallConstraint: Contains an offset on either object, the global positions of these points must remain equal at all times, as if connected by a ball joint.