Camera

Camera extends Object, adding functions and properties to it.
Camera is not creatable, there's only one instance of it. It can only be accessed through its globally exposed variable.

Camera is a shortcut to Client.Camera.

Controls camera movement and position.

All camera modes listed on this page are implemented in Lua, it's totally possible to implement custom ones.

Functions

Impact CastRay ( Shape filterIn )
Impact CastRay ( nil filterIn, Object filterOut )
Impact CastRay ( CollisionGroups filterIn, Object filterOut )
Impact CastRay ( Shape filterIn, Object filterOut )

Casts a ray and returns an Impact (can be nil).

The Impact contains information about the kind of thing that's been hit.

💡 Calls Ray.Cast under the hood. See Ray.Cast definition for more details about possible filters.

local impact = Camera:CastRay()
if impact.Block ~= nil then
  print("block hit:", impact.Block)
end
nil FitToScreen ( Shape target, number screenRatio, boolean spherize )

Fits the target to the screen.

screenRatio indicates the percentage of the screen that should be covered by the target.

When spherize is true, a sphere that contains the target is used to place the camera.

local myShape = Shape(R.usename.myShape)
Map:AddChild(myShape)
Camera:FitToScreen(myShape, 0.6, false)
-- the shape now covers 60% of the screen
nil Hide ( Object o )

Hides an object for the local camera only. Other players will still be able to see it if object.IsHidden remains false.

It's usefull when implementing a first person camera for example, to hide local player's body parts.

Puts Camera in "first person" mode. Looking at the world from target's perspective.

When calling SetModeFirstPerson without parameters, the target defaults to Player (local player).

When offset is set to an number, the offset is set on the vertical axis only, (Number3(0, offset, 0))

Camera:SetModeFirstPerson(Player, 3.0)

When in that mode, the camera rotates around its target, maintaining its distance from it.

When calling SetModeSatellite without parameters, the target defaults the current position of the camera.

SetModeSatellite can be called several time to update the distance.

Once the "satellite mode" is set, Camera.LocalRotation can be used to rotate around the target.

Camera:SetModeSatellite(Player, 10.0)
nil SetModeThirdPerson ( Object target, number minDist, number maxDist, number offset )
nil SetModeThirdPerson ( Object target, number minDist, number maxDist, Number3 offset )

Puts Camera in "third person" mode. (looking at Camera's target, from a behind-the-shoulder perspective)

When calling SetModeThirdPerson without parameters, the target defaults to Player (local player).

By default, the Camera is placed beind its target. But it's then possible to change its LocalRotation to look at the target from a different angle.

minDist, maxDist and offset settings are optional but can be provided to tweak positioning.

Camera:SetModeThirdPerson()

Camera:SetModeThirdPerson(someShape)
nil Show ( Object o )

Shows an object that's been hidden to the local camera with Camera:Hide

Inherited from Object

Hide

Get Camera's parent.

print(myObject:GetParent())

Object:RotateLocal(number3) -- euler angles
Object:RotateLocal(number3, number) -- axis angle

Object:RotateWorld(number3) -- euler angles
Object:RotateWorld(number3, number) -- axis angle

Returns true if the two Objects may collide with each other.

nil ApplyForce ( Object self, Number3 value )

Apply a force to Object, taking into account its Mass.

Properties

Can be set to change Camera's vertical field of view.

The default value is 60 degrees.

Camera.FieldOfView = 40.0

Inherited from Object

Hide

Camera's constant acceleration in world coordinates per second squared.

⚠️ Acceleration will only affect Camera's position while Camera.Physics is true.

-- Acceleration can be used to compensate gravity: 
myObject.Acceleration = -Config.ConstantAcceleration
-- myObject's acceleration is now the invert of 
-- Config.ConstantAcceleration, cancelling it.

Collision groups the Camera belongs to.

⚠️ It doesn't mean the Camera will collide with other Objects in these groups.

If the Camera belongs to group number 3 for example, it means all Objects that have group number 3 in their Object.CollidesWithGroups property will collide with it.

By default:
- Objects collide with the Map and other Objects
- Players collide with the Map only

That can all be configured differently depening on your needs.

local object1 = Object()
local object2 = Object()
-- It's not mandatory to set Physics to true
-- An object with Physics set to false contributes to the
-- physics simulation as a static item (can't be moved)
object1.Physics = true
object2.Physics = true

-- making sure 2 objects collide with each other
-- NOTE: by default:
-- Map.CollisionGroups == {1},
-- Player.CollisionGroups == {2},
-- Object.CollisionGroups == {3}
object1.CollisionGroups = {5}
object2.CollisionGroups = {5}
object1.CollidesWithGroups = {1, 5} -- collides with Map + objects in group 5
object2.CollidesWithGroups = {1, 5} -- collides with Map + objects in group 5

-- would also work this way if you don't 
-- remember Map's group (which can be changed too by the way)
object1.CollidesWithGroups = Map.CollisionGroups + {5}

-- making an object collides with the Map and Players
local object = Object()
object.CollidesWithGroups = Map.CollisionGroups + Player.CollisionGroups

-- for Player (local player) to collide with other players and the Map
Player.CollidesWithGroups = Map.CollisionGroups + Player.CollisionGroups

Collision groups the Camera collides with.

By default:
- Objects collide with the Map and other Objects
- Players collide with the Map only

That can all be configured differently depening on your needs.

local object = Object()
-- It's not mandatory to set Physics to true
-- An object with Physics set to false contributes to the
-- physics simulation as a static item (can't be moved)
object.Physics = true

-- making an object collide with the Map and Players
object.CollidesWithGroups = Map.CollisionGroups + Player.CollisionGroups

-- for an Object to collide with other objects only
-- (won't collide with the map)
object.CollidesWithGroups = object.CollisionGroups

-- for Player (local player) to collide with other players and the Map
Player.CollidesWithGroups = Map.CollisionGroups + Player.CollisionGroups

-- making sure 2 objects collide with each others
-- NOTE: by default:
-- Map.CollisionGroups == {1},
-- Player.CollisionGroups == {2},
-- Object.CollisionGroups == {3}
local object1 = Object()
local object2 = Object()
object1.CollisionGroups = {5}
object2.CollisionGroups = {5}
object1.CollidesWithGroups = {1, 5} -- collides with Map + objects in group 5
object2.CollidesWithGroups = {1, 5} -- collides with Map + objects in group 5

-- would also work this way if you don't 
-- remember Map's group (which can be changed too by the way)
object1.CollidesWithGroups = Map.CollisionGroups + {5}

nil by default. Can be set to a function that will be triggered when the Camera collides with another Object.

The function is called with 3 parameters: the object the callback was set for, the other actor in the collision and the Face of the first actor that's in contact.

Note: it's not necessary to do use all 3 parameters.

object.OnCollision = function(o1, o2)
  -- `o1` is `object` here
  print("collision detected between", o1, "and", o2)
end

object.OnCollision = function(o1, o2, face)
  -- `o1` is `object` here
  print("collision detected between", o1, "'s", face, "and", o2)
end

nil by default. Can be set to a function that will be triggered when the Camera ends colliding with another Object.

The function is called with 2 parameters: the object the callback was set for and the other actor in the collision.

object.OnCollisionEnd = function(o1, o2)
  -- `o1` is `object` here
  print("collision ended between", o1, "and", o2)
end

Executed when the Pointer is dragged (moved while down). Receives a PointerEvent parameter, just like Pointer.Drag.

(nil by default)

myObject.OnPointerDrag = function(pointerEvent)
  print("dx:", pointerEvent.DX, "dy:", pointerEvent.DY)
end

Position of the Camera in the world.

local o = Object()
-- places the object where the local player is
o.Position = Player.Position
boolean IsOnGround read-only

true when the Camera is not falling.

⚠️ IsOnGround only makes sense when Camera.Physics is true.

Can be set to true for the Camera to be hidden.
Nothing else changes, the Camera remains in the scene and it keeps being affected by the simulation (collisions, etc.).

Position of the Camera in its parent.
In other words, LocalPosition refers to the position of the Camera relative to the {0,0,0} position of its parent.

Rotation of the Camera in the world (as seen on screen).

While it usually works for simple operations (like Rotation.X = Rotation.X + someAngle), we advise you to use Number3.Rotate to rotate an object around X, Y & Z axis.

You can also set unit vectors like Camera.Up, Camera.Right or Camera.Forward to orient your object.

local o = Object()
o.Rotation = {0, math.pi, 0}
-- o revolved half a turn on Y axis

-- another way to rotate the object:
o.Forward:Rotate({0, 0, math.pi / 2})
o.Forward = Camera.Forward

Tick is a function executed ~30 times per second when set (nil by default). Provides the Camera and elapsed time in seconds as parameters.

-- executed ~30 times per second on each user device
myObject.Tick = function(object, dt)
  print("elapsed:", dt, "seconds")
end

Rotation of the Camera in its parent.

Nested Object local rotations are combined to obtain the "world rotation" (Object.Rotation), the Object's final on-screen rotation.

number LossyScale read-only

Convenience property that attempts to match the actual world scale as much as it can. Note that Objects that have multiple levels of nested rotations and scales will return a skewed lossy scale.

The mass of the Object determines how much a given force can move it and whether or not another object can be pushed by it. It cannot be zero, a neutral mass is a mass of 1.

The combined friction of 2 Objects in contact represents how much the moving Object will be able to slide along the colliding Object. It is a rate between 0 (full stop on contact) and 1 (full slide, no friction), values higher than 1 are allowed and will create an increasing momentum, like sliding on ice.

The combined bounciness of 2 Objects in contact represents how much of the moving Object's velocity is produced after being in contact with colliding Object, it is a rate between 0 (no bounce) and 1 (100% of the velocity bounced). Values higher than 1 are allowed and will create an increasing momentum at each bounce (try at your own risk).

All Objects have a collision box that represents the space occupied in the scene with regards to collisions. For Shapes and Players, the collision box is updated with their bounding box. For Objects, it is a 1-cube by default after physics was enabled for the first time.

Up is a unit vector (vector with a length of 1). It determines which direction is "up" for the Camera.

Setting it is a way to rotate the Camera.

Right is a unit vector (vector with a length of 1). It determines which direction is "right" for the Camera.

Setting it is a way to rotate the Camera.

Forward is a unit vector (vector with a length of 1). It determines which direction is "forward" for the Camera.

Setting it is a way to rotate the Camera.

Left is a unit vector (vector with a length of 1). It determines which direction is "left" for the Camera.

Setting it is a way to rotate the Camera.

Down is a unit vector (vector with a length of 1). It determines which direction is "down" for the Camera.

Setting it is a way to rotate the Camera.

Backward is a unit vector (vector with a length of 1). It determines which direction is "backward" for the Camera.

Setting it is a way to rotate the Camera.