More actions
Guide to the KSP 2 Transform system
KSP 2 uses a 64-bt double-precision system for tracking object position and movement. This guide attempts to explain how it works and how to use it.
The system is used to keep track of all objects in game, is used for game save state, and dealing with position between objects very long distances away. It works in tandem with Unity's 32-bit space, but provides better accuracy when dealing with astronomical distances or sizes.
This guide will assume some knowledge of how Unity transforms works, and 3d programming concepts such as points, vectors, quaternions, etc.
Major classes / structs
TransformFrame
TransformFrame represents a reference frame (Cartesian coordinate system) that can contain points or other spatial objects. They can be nested, that is, a frame can be "inside" of another frame.
Moving points and vectors from one transform frame to another is similar to using Unity's Transform matricies to move between objects spaces. However, there is no "global" space frame. Kerbol can be treated as a root level frame that all bodies move inside of (its position is (0,0,0), but most calculations will try to find the closest common parent .For example, if the player is on the Mun, but the game needs to draw an icon for a vessel on Minmus, the calculation will go through Kerbin's reference frame.
TransformModel
TransformModel represents a particular object inside of a reference frame. It is similar to Unity's Transform class.
TransformModel has a 1:1 relationship with the simulation SimulationObjectModel.
A model can have other models as children, or directly "float" in the reference frame.
Primitive types
There are double-precision types comparable to common Unit types, but using double or other underlying storage. These are straight forward replacements for various unity single-precision types. They are castable too and from the corresponding Unity types.
All of these primitive types are value types (struct).
| KSP2 primative | Unity Analog | Underlying storage |
|---|---|---|
| Matrix4x4D | Matrix4x4 | Unity.Mathematics.double4x4 |
| Vector3d | Vector3 | double (3x) |
| Vector4d | Vector4 | double (4x) |
| QuaternionD | Quaternion | double (4x) |
Frame tracked types
There are certain types that are similar to primitive types, but include a reference to the coordinate system that they are created with respect to.
The transform system provides helpers to get relative position and rotations between points that are not in the same reference frame without having to explicitly pass around which frame they came from.
| KSP2 class | Underlying storage | Unity Analog | Usage notes |
|---|---|---|---|
| TransformFrame | Vector3d/QuaternionD/Matrix4x4D | (Unity coordinate system) | |
| TransformModel | Vector3d/QuaternionD | Transform | |
| Position | Vector3d | Vector3 | A vector representing a position |
| Rotation | QuaternionD | Quaternion | |
| Vector | Vector3d | - | A vector representing a direction |
| Velocity | Vector | - | Physics velocity vector |
| AngularVelocity | Vector | - |
Interfaces
A number of interfaces denote which methods should be used on a given type.
The "Internal" interfaces are generally meant to be methods that a given type uses when calling between objects of its own type.
The "Driver" interfaces provide notification callbacks for specific value changes.
| Name | Implemented by | Use | |
|---|---|---|---|
| ITransformFrameInternal | TransformFrame | Calls between different kinds of TransformFrame subclasses | |
| ITransformFrame | TransformFrame | Consumers of TransformFrame | |
| ITransformModelInternal | TransformModel | Calls between different TransformModel objectss | |
| ITransformModel | TransformModel | Consumers of TransformModel | |
| ICoordinateSystem | TransformFrame,
TransformModel |
Translate a position, rotation, vector, or transform matrix that exists in some other ICoordinateSystem into the implementing coordinate system. | |
| IPositionDriver | (various) | Change or listen for changes to an object's position. | |
| IRotationDriver | (various) | Change or listen for changes to an object's rotation. | |
| ILinearMotionDriver | Change or listen for changes to an object's velocity. | ||
| IAngularMotionDriver | Change or listen for changes to an object's angular velocity. | ||
| IMotionFrame | Translate a velocity or angular velocity between moving reference frames. | ||
| IMotion | The velocity and angular velocity between two objects (or reference frames). | ||
| IMotionRelative |