Player

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

Player is a shortcut to Client.Player.
Represents the local Player.

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 from player's position, returns an Impact if it hits something, nil otherwise.

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

local impact = Player:CastRay()
if impact ~= nil then
  print(impact)
end
nil EquipBackpack ( Item item ) coming soon

Equips an Item, Shape or MutableShape on the back of the Player.
You can remove what's been equiped using nil argument

nil EquipHat ( Item Item ) coming soon
nil EquipHat ( Shape shape )

Equips an Item, Shape or MutableShape on Player's head.
You can remove what's been equiped using nil argument

Puts an Item, Shape or MutableShape in Player's left hand.
You can remove what's been equiped using nil argument

Puts an Item, Shape or MutableShape in Player's right hand.
You can remove what's been equiped using nil argument

Config = {
  Items = { "aduermael.rainbow_sword" }
}

Client.OnStart = function()
  Player:EquipRightHand(Items.aduermael.rainbow_sword)
  -- or
  local s = Shape(Items.aduermael.rainbow_sword)
  Player:EquipRightHand(s)

  Player:EquipRightHand(nil) -- unequips the sword
end

Swaps Player's hand held items.
If one hand holds nothing, the Item switches hands.

Make Player's left hand swing.

Make Player's right hand swing.

Inherited from Object

Hide

Adds given Object as a child.

Object extensions like Shape or MutableShape are naturally accepted too.

By default, when using AddChild, the child maintains it's LocalPosition. But since the local position remains the same in the new parent, it means the child's world position may change.

The keepWorld optional parameter, false by default, can be used to maintain the child's Position (world position) instead.

It's also a good practice to set child/parent relationships before setting positions.

local o = Object()
local myShape = Shape(Items.someuser.someitem)
o:AddChild(myShape)

Unsets parent/child relationship with child parameter. The child ends up being deleted if it has no other references.

o:RemoveChild(someChildObject)

Unsets parent/child relationship with all children. Individual children end up being deleted if they have no other references.

o:RemoveChildren()
nil GetChild ( integer index )

Get child Object at index.

if o.ChildrenCount > 0 then
  print(o:GetChild(1)) -- prints first child
end

Get Player's parent.

print(myObject:GetParent())

Sets parent/child relationship with parent parameter. nil can be used to remove the Object from its parent.

By default, when using SetParent, the child maintains it's LocalPosition. But since the local position remains the same in the new parent, it means the child's world position may change.

The keepWorld optional parameter, false by default, can be used to maintain the child's Position (world position) instead.

It's also a good practice to set child/parent relationships before setting positions.

local o = Object()
o:SetParent(Map) -- o is now a child of the map
-- (Map is an extension of Object)

Removes the Player from its parent. Doesn't do anything if the Player has no parent.

o:RemoveFromParent()

Converts a local position to world coordinate system.

local p = Number3(1, 2, 3)
local pInWorldCoords = myObject:PositionLocalToWorld(p)

Converts a world position to local coordinate system.

local p = Number3(1, 2, 3)
local pInLocalCoords = myObject:PositionWorldToLocal(p)

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

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

Converts a local rotation to world coordinate system.

Converts a world rotation to local coordinate system.

Adds a text bubble at Object's position. For a Shape or Player, the text bubble will appear above its bounding box.

You may use a duration of -1 to set a permanent text bubble.

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.

Instantaneously remove any ongoing text bubble.

Properties

Returns the block on which the Player is standing on.

Returns an array of Blocks the player is standing on

local blocks = Player.BlocksUnderneath
for index, value in ipairs(blocks) do 
    -- greenColorIndex is a block previously defined
    local newBlock = Block(10) -- 10: BlockerProperties index
    value:Replace(newBlock)
end

The Shape of the Player's body.

The Shape of the Player's head.

Unique player ID for played game. A different ID can be attributed after reconnection.

Indicates whether the Player object is the local Player.
This is only valid on the Client, not on the Server.

The Shape of the Player's left arm.

The Shape of the Player's left leg.

Absolute world position of the Player.

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

The Shape of the Player's right arm.

The Shape of the Player's right leg.

Player's rotation. (Y value is not considered)

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

Player's account identifier (ID). Identifiers are unique.

Player's account username. Usernames are unique.

Player's velocity (speed + direction).

-- makes myObject jump:
myObject.Velocity.Y = 100

Inherited from Object

Hide

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

⚠️ Acceleration will only affect Player's position while Player.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 Player belongs to.

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

If the Player 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 Player 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}

Turns physic simulation on/off when set.

⚠️ When turned off, Player.Velocity & Player.Motion are set to {0,0,0}.

nil by default. Can be set to a function that will be triggered when the Player 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 Player 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
boolean IsOnGround read-only

true when the Player is not falling.

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

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

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

Tick is a function executed ~30 times per second when set (nil by default). Provides the Player 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 Player in its parent.

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

Be aware, this Motion property is a hack regarding laws of physics. (sorry Isaac)

But it's very practical to move objects without worrying about forces at play.

This is what's being used by default when you're moving around with your avatar (see Client.DirectionalPad). It's the reason why you can stop moving horizontally while in the air.

Basically, Motion is an instantaneous displacement that contributes to moving Player every frame, without changing Player.Velocity directly.

Motion is expressed in world coordinates per second.

⚠️ Motion will only affect Player's position while Player.Physics is true. Whenever it is set to false, Motion is set to {0,0,0}.

local speed = 10
myObject.Motion = Camera.Forward * speed
-- myObject will move in the same direction the camera is currently facing.
-- If the Camera rotates after this, it won't change where myObject is heading.

Scale of the Object, in its parent.

Nested Object local scales are combined to obtain the "world scale" (Object.LossyScale), the Object's final scale.

myObject.LocalScale = 2 -- the Object is now 2 times bigger
topLevelObject.LocalScale = 2
local o = Object()
o.LocalScale = 0.5
topLevelObject:AddChild(o) -- o becomes a child of topLevelObject
-- o ends up being displayed with a scale of 1
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.

Returns number of child Objects.

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

Setting it is a way to rotate the Player.

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

Setting it is a way to rotate the Player.

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

Setting it is a way to rotate the Player.

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

Setting it is a way to rotate the Player.

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

Setting it is a way to rotate the Player.

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

Setting it is a way to rotate the Player.