Transform System Guide - Revision history

174.85.0.134: /* TransformModel */ rework transform model/frame descriptions

2025-02-04T15:30:02Z

TransformModel: rework transform model/frame descriptions

← Older revision		Revision as of 17:30, 4 February 2025
Line 8:		Line 8:
	=== Major classes / structs ===		=== Major classes / structs ===

	==== ~~TransformFrame~~ ====		==== TransformModel ====
	~~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~~.		TransformModel is the primary class in the transform system, representing a particular position/rotation inside of a reference frame. It is similar to Unity's Transform class, but does not have a scale.

			Instantiating a TransformModel object implies instantiating a number of other interconnected support objects. If wanting to use the service of those other support objects, it may be best to instantiate a TransformModel and use the indirectly created support objects, instead of trying to instantiate those classes directly.

	~~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. There is a galactic frame (GameInstance.UniverseModel.GalacticOrigin) that serves as~~ the ~~root 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. Calculations with no common parent frame~~ may ~~fail or be invalid~~.		SimulationObjectModel always has a TransformModel representing the sim object's position. However, many parts of the game will create independent TransformModel that may be a child of a sim object, or may have sim objects as children.

	==== ~~TransformModel~~ ====		==== TransformFrame ====
	~~TransformModel~~ represents ~~a particular object inside of~~ a reference frame. It is ~~similar to Unity's Transform class~~.		TransformFrame represents a reference frame (Cartesian coordinate system) that can contain points or other spatial objects. They are usually created automatically when creating a TransformModel, and are "owned" by the model. But a TransformModel is considered a child of a TransformFrame, forming a mutually-recursive parent/child hierarchy.

	TransformModel ~~has~~ a ~~1:1 relationship with the simulation SimulationObjectModel~~.		To put it more simply: a TransformModel owns a TransformFrame, which can have TransfromModels as children, which in turns owns its own frames, which in turn can have other models as children, et cetera.

	~~A model can have other models as children~~, ~~or directly~~ "~~float~~" in the reference 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. There is a galactic frame (GameInstance.UniverseModel.GalacticOrigin) that serves as the root 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. Calculations with no common parent frame may fail or be invalid.

	==== Primitive types ====		==== Primitive types ====

Foonix: /* Frame tracked types */ Describe angular velocity vector

2025-02-04T15:10:57Z

Frame tracked types: Describe angular velocity vector

← Older revision		Revision as of 17:10, 4 February 2025
Line 91:		Line 91:
	\|Vector		\|Vector
	\| -		\| -
	\|		\|A vector representing the axis of rotation,
			with magnitude representing speed of rotation.
	\|}		\|}

Foonix at 10:18, 3 January 2025

2025-01-03T10:18:24Z

← Older revision		Revision as of 12:18, 3 January 2025
Line 11:		Line 11:
	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.		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~~. There is a galactic frame (GameInstance.UniverseModel.GalacticOrigin) 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.		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. There is a galactic frame (GameInstance.UniverseModel.GalacticOrigin) that serves as the root 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. Calculations with no common parent frame may fail or be invalid.

	==== TransformModel ====		==== TransformModel ====

Foonix: /* TransformFrame */ Note galactic frame. Thanks StellatedCUBE for the correction.

2025-01-03T10:07:32Z

TransformFrame: Note galactic frame. Thanks StellatedCUBE for the correction.

← Older revision		Revision as of 12:07, 3 January 2025
Line 11:		Line 11:
	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.		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.		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. There is a galactic frame (GameInstance.UniverseModel.GalacticOrigin) 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 ====

Foonix: Hand of Kraken

2025-01-03T08:03:00Z

Hand of Kraken

← Older revision		Revision as of 10:03, 3 January 2025
Line 105:		Line 105:
	!Implemented by		!Implemented by
	!Use		!Use
	!
	\|-		\|-
	\|ITransformFrameInternal		\|ITransformFrameInternal
	\|TransformFrame		\|TransformFrame
	\|Calls between different kinds of TransformFrame subclasses		\|Calls between different kinds of TransformFrame subclasses
	\|
	\|-		\|-
	\|ITransformFrame		\|ITransformFrame
	\|TransformFrame		\|TransformFrame
	\|Consumers of TransformFrame		\|Consumers of TransformFrame
	\|
	\|-		\|-
	\|ITransformModelInternal		\|ITransformModelInternal
	\|TransformModel		\|TransformModel
	\|Calls between different TransformModel objectss		\|Calls between different TransformModel objectss
	\|
	\|-		\|-
	\|ITransformModel		\|ITransformModel
	\|TransformModel		\|TransformModel
	\|Consumers of TransformModel		\|Consumers of TransformModel
	\|
	\|-		\|-
	\|ICoordinateSystem		\|ICoordinateSystem
Line 131:		Line 126:
	TransformModel		TransformModel
	\|Translate a position, rotation, vector, or transform matrix that exists in some other ICoordinateSystem into the implementing coordinate system.		\|Translate a position, rotation, vector, or transform matrix that exists in some other ICoordinateSystem into the implementing coordinate system.
	\|
	\|-		\|-
	\|IPositionDriver		\|IPositionDriver
	\|(various)		\|(various)
	\|Change or listen for changes to an object's position.		\|Change or listen for changes to an object's position.
	\|
	\|-		\|-
	\|IRotationDriver		\|IRotationDriver
	\|(various)		\|(various)
	\|Change or listen for changes to an object's rotation.		\|Change or listen for changes to an object's rotation.
	\|
	\|-		\|-
	\|ILinearMotionDriver		\|ILinearMotionDriver
	\|		\|
	\|Change or listen for changes to an object's velocity.		\|Change or listen for changes to an object's velocity.
	\|
	\|-		\|-
	\|IAngularMotionDriver		\|IAngularMotionDriver
	\|		\|
	\|Change or listen for changes to an object's angular velocity.		\|Change or listen for changes to an object's angular velocity.
	\|
	\|-		\|-
	\|IMotionFrame		\|IMotionFrame
	\|		\|
	\|Translate a velocity or angular velocity between moving reference frames.		\|Translate a velocity or angular velocity between moving reference frames.
	\|
	\|-		\|-
	\|IMotion		\|IMotion
	\|		\|
	\|The velocity and angular velocity between two objects (or reference frames).		\|The velocity and angular velocity between two objects (or reference frames).
	\|
	\|-		\|-
	\|IMotionRelative		\|IMotionRelative
	\|
	\|		\|
	\|		\|
Line 171:		Line 158:
	\|PhysicsSpaceProvider		\|PhysicsSpaceProvider
	\|Translate between simulation space and Unity object space		\|Translate between simulation space and Unity object space
	\|
	\|}		\|}

Line 181:		Line 167:
	When a vessel gets close enough to the player to be visible in game, the relationship between the parts and the vessel changes.The parts are individually loaded into Unity, the simulation positions are copied to unity GameObjects, and then PhysX eventually becomes the "source of truth" as to where exactly the part is. The vessel position is then calculated as an average of the of all of the part positions.		When a vessel gets close enough to the player to be visible in game, the relationship between the parts and the vessel changes.The parts are individually loaded into Unity, the simulation positions are copied to unity GameObjects, and then PhysX eventually becomes the "source of truth" as to where exactly the part is. The vessel position is then calculated as an average of the of all of the part positions.

	The coordinate system in Unity is referred to as "physics space" by the simulation code. Physics space is a moving reference frame used for showing sim objects to the player, and leveraging PhysX for physics simulation. Typically, physics space follows a vessel's orbit around (or location on) a planet. This means that ~~although~~ a vessel/part may be moving very fast and traveling long distances in sim terms, it may be moving very slowly and traveling short distances in PhysX terms.		The coordinate system in Unity is referred to as "physics space" by the simulation code. Physics space is a moving reference frame used for showing sim objects to the player, and leveraging PhysX for physics simulation. Typically, physics space follows a vessel's orbit around (or location on) a planet. This means that while a vessel/part may be moving very fast and traveling long distances in sim terms, it may be moving very slowly and traveling short distances in PhysX terms. This makes better use of PhysX's 32-bit precision by allowing calculations to be performed more precisely.

	The game will periodically "reset" physics space according to what the vessel does; It will move and change velocity of the physics space frame, and subtract that movement/position change to keep them from moving too far away from the origin or too high a speed. This is how the "floating origin" concept often mentioned in KSP context is actually implemented.		The game will periodically "reset" physics space according to what the vessel does; It will move and change velocity of the physics space frame, and subtract that movement/position change to keep them from moving too far away from the origin or too high a speed. This is how the "floating origin" concept often mentioned in KSP context is actually implemented.
Line 193:		Line 179:

	When a vessel is unloaded from physics space, it will save the last known sim positions and destroy all of the associated Unity GameObjects. The simulation objects' positions return to being controlled by the simulation engine.		When a vessel is unloaded from physics space, it will save the last known sim positions and destroy all of the associated Unity GameObjects. The simulation objects' positions return to being controlled by the simulation engine.

			==== Hand of Kraken ====
			HandOfKraken is a special class for dealing with what players call the "orbital decay" problem. It intermediates and adjusts things between the simulation and physics space frames, so warrants some explanation here. It is only used for active vessels that are being simulated in physics space.

			===== What the problem is =====
			There are two main ways to calculate orbits and object motion:

			* Parametric.A relatively simple equation is used to figure out an object's position at a given (possibly future) time. KSP players call this "on rails" orbit calculation.
			* Iterative step solving. Based on the current position and forces, calculate the motion a small step at a time into the future.

			Both approaches have their respective strengths and weaknesses. The main difference here is that iterative step solvers can suffer from "cumulative drift error." Small rounding errors each iteration can add up to large, unpredictable differences in motion outcome.

			Drift error is an inherent problem in iterative step solvers, and PhysX is no exception. In most PhysX use cases, there is some kind of unmoving "ground" that objects sit on, which would prevent them from floating away due to minor velocity calculation errors. Any velocity calculation error would be pulled toward zero as the object encounters friction with the ground. This is actually true for landed vessels, so HandOfKraken is only needed in orbit.

			But we don't have a "ground" when vessels are in orbit. PhysX objects are allowed to float freely inside physics space. So errors can accumulate for various difficult to fix reasons. Because the physic space frame is periodically reset to track the motion of the vessel, the errors trickle up into the simulation, eventually resulting in changes to the orbit the player can notice but can't account for. If the changes can't be explained by noticeable things like drag or thrust, it becomes a gameplay bug.

			(Aside: There are orbital mechanics, such as tidal forces, that could cause an orbit or motion to change over time without forces like friction or thrust, but the game doesn't intend to simulate these, so in a sense they could be considered bugs even if that is what is causing the error.)

			So, the purpose of HandOfKraken is to correct drift errors in situations the player would typically notice and break players' expectations. The player's expectation of a vessel in orbit under no thrust, drag, or other force is that it should follow a Parametric ("rails") style orbital path.

			HandOfKraken guarantees that a vessel will follow a "rails" obit despite issues with iterative step solving, if and when it can.

			===== How it works =====
			HandOfKraken monitors the movement of the vessel and the forces it is under, and makes periodic correction.

			* When the forces applied to the vessel are go some certain small threshold (close to zero),it will record the current rails orbit and go into "correcting" mode.
			* While in correcting mode, it hides the actual orbit from the player, and presents the recorded rails orbit. Any discrepancy between the expected rails orbit and iterative physics orbit is calculated every frame.
			* If the discrepancy gets too high, it quietly drags the entire vessel back the position and velocity it should have had as predicted by the recorded rails orbit. (This might be where it gets its name from.)
			* If any significant force becomes active on the vessel, it goes out of correcting mode. The orbit shown to the player is then again (as normal) the one derived from the current vessel physics situation. (Normally, a vessel's position and velocity is calculated by averaging all of the individual parts.)

Foonix: write some stuff about physics space

2025-01-03T06:46:22Z

write some stuff about physics space

@@ Line 166: / Line 166: @@
+|
+|
+|
 |}

Foonix: Document some of the interfaces

2025-01-03T05:49:40Z

Document some of the interfaces

@@ Line 6: / Line 6: @@
 This guide will assume some knowledge of how Unity transforms works, and 3d programming concepts such as points, vectors, quaternions, etc.
-=== Major classes ===
+=== Major classes / structs ===
 ==== TransformFrame ====
@@ Line 91: / Line 91: @@
 |Vector
 | -
+|
 |}

Foonix: Put my notes into a guide

2025-01-02T17:55:10Z

Put my notes into a guide

New page

== 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 ===

==== 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).
{| class="wikitable"
|+Primitive types
!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.
{| class="wikitable"
|+Frame tracked types
!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
| -
|
|}