What is toObjectSpace and what does it do?

CFrames describe positions and orientations.

You can view them as either absolute, where they tell you your position/orientation relative to the origin (the middle of the world at 0,0,0), or as relative where they dictate position/orientation relative to some reference CFrame.

a.CFrame:toObjectSpace(b.CFrame) describes the CFrame of b relative to the CFrame of a a.

For example, if a and b are 2x1x4 bricks with b sitting on top of a, then

print( a.CFrame:toObjectSpace(b.CFrame) )
--> same as CFrame.new(0, 1, 0)

This output means that b is 1 stud above a and they share the same orientation.

The reverse operation is :toWorldSpace. If rel is a CFrame measured relative to a.CFrame, then a.CFrame:toWorldSpace(rel) is a CFrame relative to the origin, and usable for example as a .CFrame of a part:

b.CFrame = a.CFrame:toWorldSpace(CFrame.new(0, 2, 0))

Now b would be floating two studs above a.

:pointToWorldSpace does the same operation, but is used when you don't care about the orientation, only the position. It's equivalent to the following:

alpha:pointToObjectSpace(beta)

-- equivalent to
alpha:toObjectSpace(CFrame.new(beta)).p

:vectorToObjectSpace does a similar operation, but is used when you have a direction and don't care about absolute positions:

alpha:vectorToObjectSpace(beta)

-- equivalent to
(alpha - alpha.p):toObjectSpace(CFrame.new(beta)).p

Right so to understand what a lot of the CFrame methods do you have to understand a bit of linear algebra, specifically what the inverse of a CFrame is.

The inverse of a CFrame allows you to either pre or post multiple the original CFrame and get CFrame.new() (the identity CFrame) back. This property is extremely unique in CFrame (matrix) multiplication as for the most part a * b ~= b * a.

Using that knowledge we can start to look at what "object space is".

Say we have some cframe A and want to get to cframe B by traveling the offset between the two. We can use inverses and algebra to solve what that offset would be.

A * offset = B
A:inverse() * A * offset = A:inverse() * B
CFrame.new() * offset = A:inverse() * B
offset = A:inverse() * B

If you check the method for the toObjectSpace method we see it's exactly equivalent to the above process we just calculated:

offset = A:toObjectSpace(B)

Thus the toObjectSpace method can be thought of as a way to calculate the offset between two cframes.

Another way to think about object space is to think the returned item as being directions from your exact location/orientation. Say I tell you to walk ten steps forward then 5 steps right. Those directions are relative to you. If I followed those exact same directions I would end up in a completely different position (on earth) and maybe since I'm facing east right now I may end up facing a different direction to you. Those directions are object space!

World space directions on the other hand are not relative to the object that's following them. Say for example I gave you GPS coordinates. If we both followed them we would end up in the same place.

If you want more intuition and examples on these check out these articles:

• Check the object and world space section on this article
• CFrame methods
• A good guide for inverses