Text
A Text is an object with a text and optional background frame attached.
It may be used in two different display modes by setting its Text.Type field,
- as a TextType.World, it will behave exactly like any other object in the scene, great for creating postsigns;
- as a TextType.Screen, it will be displayed from its position in the scene always facing the camera, like an UI element - great for text bubbles.
By default, a Text is set to TextType.World.
If you were using the deprecated Object:TextBubble and Object:ClearTextBubble functions prior to 0.0.48, you may use the "textbubble.lua" module. It contains the following functions which use Text objects instead,
- import the module with tb = require("textbubble.lua")
- tb.set(object, text, duration, offset, color, backgroundColor, tail)
- tb.clear(object)
Constructors
Creates a Text with default properties.
local t = Text() -- change text properties t.Text = "Hello world!" t.Type = TextType.Screen t.IsUnlit = true t.Tail = true -- use it as a normal object in the scene t:SetParent(Player) t.LocalPosition = { 0, 34, 0 }
Functions
Inherited from Object
HideAdds given Object as a child. Object extensions like Shape or MutableShape are naturally accepted too.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
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.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
o:RemoveChild(someChildObject)
Unsets parent/child relationship with all children. Individual children end up being deleted if they have no other references.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
o:RemoveChildren()
Get child Object at index.
if o.ChildrenCount > 0 then print(o:GetChild(1)) -- prints first child end
Sets parent/child relationship with parent parameter. nil can be used to remove the Object from its parent.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new parent.
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 Text from its parent. Doesn't do anything if the Text has no parent.
The keepWorld optional parameter, false by default, dictates whether to maintain the child's world or local position and rotation. Keeping world will ensure the object doesn't move in the scene, adjusting its local position/rotation accordingly; keeping local will have the object move in the scene in order to maintain an equivalent local position/rotation relative to its new 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)
Rotates the Text in its own coordinates system.
o = Object() -- rotate with provided Euler angle o:RotateLocal({0, 0, math.pi / 2.0}) -- rotate along specified axis o:RotateLocal(o.Forward, math.pi / 2.0)
Converts a local rotation to world coordinate system.
Converts a world rotation to local coordinate system.
Returns true if the two Objects may collide with each other.
Properties
Anchor of the text, text.Anchor = { 0.5, 0.5 } by default, which corresponds to the middle of the text.
Color of the background frame, white by default. Set alpha to zero to disable.
Font size in points, 22.0 by default. Expressed in world units if the text type is TextType.World.
Height of the Text in points. Expressed in world units if the text type is TextType.World.
This accounts for the total size including background frame, padding, and tail.
Integer or table of integers between 1 and 8. Cameras only render objects corresponding to their layers.
Maximum distance in world units beyond which the text will disappear, 350.0 by default.
Maximum width in points beyond which the text will automatically break line, 0 by default (disabled). Expressed in world units if the text type is TextType.World.
Text padding over background in points, 8 by default. Expressed in world units if the text type is TextType.World.
Whether to display a tail under the background frame, like a text bubble, false by default.
The text type can be set to TextType.World (default) or TextType.Screen.
As a TextType.World, the text will be translated, rotated, and scaled like any other object in the scene, eg. a signpost.
As a TextType.Screen, the text will be displayed in front of everything else, facing the camera from its position in the scene, eg. a text bubble above a player's head.
Note that it can be changed at any time. Some Text fields are automatically expressed in world units or points based on the text type.
Width of the Text in points. Expressed in world units if the text type is TextType.World.
This accounts for the total size including background frame, padding, and tail.
Inherited from Object
HideText's constant acceleration in world coordinates per second squared.
⚠️ Acceleration will only affect Text's position while Text.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 Text belongs to.
⚠️ It doesn't mean the Text will collide with other Objects in these groups.
If the Text 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 Text collides with.
By default:
- Objects collide with the Map and other Objects
- Players collide with the Map and the Objects
That can all be configured differently depending on your needs.
local object = Object() -- It's not mandatory to change Physics value. -- (default value is PhysicsMode.Static) -- An object with Physics set to PhysicsMode.Static contributes -- to the physics simulation as a static item (can't be moved) object.Physics = PhysicsMode.Dynamic -- 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}
Sets the simulation mode for this object, it can be one of the following:
- PhysicsMode.Disabled: excluded from all physics features.
- PhysicsMode.Trigger: Text's collision box is available for casts and collision callbacks, and is passed through by other dynamic objects.
- PhysicsMode.TriggerPerBlock: if Text is a Shape, its model blocks are available for casts and collision callbacks, and is passed through by other dynamic objects.
- PhysicsMode.Static: Text's collision box is available for casts, collision callbacks, and acts as an obstacle for other dynamic objects.
- PhysicsMode.StaticPerBlock: if Text is a Shape, its model blocks are available for casts, collision callbacks, and act as obstacles for other dynamic objects.
- PhysicsMode.Dynamic: Text's world-aligned collision box is available for casts, collision callbacks, may act as obstacles for other dynamic objects, and is itself fully simulated.
By default, objects are set to PhysicsMode.Static.
You may use Dev.DisplayColliders to visualize each object's collision settings.
⚠️ When set to PhysicsMode.Disabled, Text.Velocity & Text.Motion are set to {0,0,0}.
nil by default. Can be set to a function that will be triggered when this object begins a collision with another object.
The function is called with 3 parameters:
- the object the callback was set for,
- the other actor in the collision,
- the world normal of the hit surface.
Note: it's not necessary to use all 3 parameters.
object.OnCollisionBegin = function(self, other, normal) print("collision began between", self, " and ", other, " with world normal ", normal) end
nil by default. Can be set to a function that will be triggered every frame where this object remains in contact with another object.
Like OnCollisionBegin, this function has 3 arguments: self, other, normal.
nil by default. Can be set to a function that will be triggered when the Text 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(self, other) print("collision ended between", self, "and", other) 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 Text in the world.
local o = Object() -- places the object where the local player is o.Position = Player.Position
Local position of the Text relative to its parent.
All of Text's ancestors local transformations are combined to obtain the Text "world position" (Object.Position), the Object's final position.
Rotation of the Text 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 Text.Up, Text.Right or Text.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
Local rotation of the Text relative to its parent.
All of Text's ancestors local transformations are combined to obtain the "world rotation" (Object.Rotation), the Object's final 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 Text every frame, without changing Text.Velocity directly.
Motion is expressed in world coordinates per second.
⚠️ Motion will only affect Text's position while Text.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
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 slide, no friction) and 1 (full stop on contact), values lower than 0 or higher than 1 are allowed and will create an increasing or inverted 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).
Returns number of child Objects.