Skip to content
Untitled Sandbox - Developer Documentation
docs/types/Instance

Instance

An object in your place, such as a part, group, model, spawn, light or NPC, which your scripts find, change and spawn.

Fields

idstring
kindstring
namestring?
parentInstance?
positionvector
rotationvector
sizevector
colorColor
transparencynumber
visibleboolean
can_collideboolean
anchoredboolean
velocityvector
physics{ density: number, friction: number, bounciness: number }
seatSeat?
spawnSpawn?
prefabstring?
angular_velocityvector
massnumber
collision_groupstring
center_of_massvector
gravity_scalenumber
linear_dampingnumber
angular_dampingnumber
sleepingboolean
display_namestring
clickableClickable?
billboardBillboard?
audience{ Player }?

Events

touch_endedEvent<(Instance, Player?, Instance?)>
touchingEvent<(Instance, Player?, Instance?)>
interactedEvent<(Instance, Player)>
occupiedEvent<(Instance, Player)>
vacatedEvent<(Instance, Player)>

You listen to these with :connect, which the Event page covers.

Instance:children

method

Gives the instances that sit directly inside this one, but not the ones deeper down.

Instance:children() -> { Instance }
example
for _, child in door:children() do print(child.display_name) end

Use it forgoing through every light in a group, or every part of a door.

Instance:has_tag

method

Says whether the instance has the tag you ask about.

Instance:has_tag(tag: string) -> boolean
example
if part:has_tag("Lava") then print("hot") end

Use it forchecking if a touched part is lava or a checkpoint before reacting to it.

tagThe tag.

Instance:add_tag

method

Puts a tag on the instance while the game runs.

Instance:add_tag(tag: string) -> ()
example
part:add_tag("Coin")

Use it forturning a part into a token or a kill brick during play, without placing a new one.

tagThe tag, at most 64 characters. An instance has at most 64 tags.

Instance:remove_tag

method

Takes one tag off the instance and leaves its other tags alone.

Instance:remove_tag(tag: string) -> ()
example
part:remove_tag("Coin")

Use it formaking a trap safe once it has been switched off.

tagThe tag.

Instance:tags

method

Gives a list of every tag the instance has.

Instance:tags() -> { string }
example
for _, tag in part:tags() do print(tag) end

Use it forlisting every tag on a part, for example to print them while debugging.

Instance:tween

method

Smoothly changes a part's position, rotation, color, size or transparency over a set time.

Instance:tween(options: TweenOptions) -> Tween
example
local tween = door:tween({ position = door.position + math3d.vector3.new(0, 10, 0), duration = 2 })

Use it forsliding doors, moving platforms, or walls that fade away.

optionsThe target values, how long it takes and the easing.
Build a tween callduration · position · rotation · color · size · transparency · 1 more
  • durationrequired

    How many seconds the tween takes to reach its target values.

  • position

    The position the instance moves to by the end of the tween.

  • rotation

    The rotation in degrees that the instance turns to by the end of the tween.

  • color

    The color the instance changes to by the end of the tween.

  • size

    The size the part grows or shrinks to, which only works on parts.

  • transparency

    How see-through the instance becomes, from 0 for fully solid up to 1.

  • easing

    How the change speeds up and slows down: linear, or quad, sine, cubic, quart, expo, back, bounce or elastic followed by _in, _out or _in_out.

    for example

Instance:clone

method

Makes a copy of the instance and returns it, placed where you choose.

Instance:clone(options: CloneOptions?) -> Instance
example
local copy = door:clone({ position = math3d.vector3.new(10, 0, 0) })

Use it forcopying a token, enemy or obstacle to put more of them around the map.

optionsoptionalWhere the copy goes, its group, its Script Name and its audience. The group cannot be inside the instance.
Build a clone callposition · rotation · parent · name · audience
  • position

    Where the copy is placed in the world.

  • rotation

    How the copy is turned, in degrees on each axis.

  • parent

    The group to put the copy in when it is made.

  • name

    The Script Name to give the new copy.

  • audience

    The only players who see the copy, as one Player or a list of them, and without it the copy has the same audience as the original.

Instance:destroy

method

Removes the instance, and everything inside it, from the world for good.

Instance:destroy() -> ()
example
part:destroy()

Use it forremoving collected tokens, broken walls or spent projectiles.

Instance:exists

method

Says whether the instance is still in the world or has been destroyed.

Instance:exists() -> boolean
example
if part:exists() then part:destroy() end

Use it forchecking a part was not already destroyed before your script uses it.

Instance:apply_impulse

method

Gives a physics part a sudden push, like a kick or a blast.

Instance:apply_impulse(impulse: vector, at: vector?) -> ()
example
part:apply_impulse(math3d.vector3.new(0, 500, 0))

Use it forkicking a ball, launch pads, or blasting crates across the room.

impulseThe push: mass times studs per second, within 1e6 on each axis.
atoptionalWhere to push, in world space. Nil pushes the centre of mass.

Instance:apply_force

method

Keeps pushing a physics part, and does not stop until clear_forces is called.

Instance:apply_force(force: vector, at: vector?) -> ()
example
part:apply_force(math3d.vector3.new(0, 100, 0))

Use it forrockets, hover cars, or wind that keeps pushing objects along.

forceThe force. It stays until clear_forces.
atoptionalWhere to push, in world space. Nil pushes the centre of mass.

Instance:clear_forces

method

Removes the forces and torques that scripts added to the part.

Instance:clear_forces() -> ()
example
part:clear_forces()

Use it forturning off a rocket's thrust, or making the wind stop.

Instance:apply_torque

method

Keeps turning a physics part, and does not stop until clear_forces is called.

Instance:apply_torque(torque: vector) -> ()
example
part:apply_torque(math3d.vector3.new(0, 50, 0))

Use it forspinning wheels, fans, or platforms that keep turning.

torqueThe turning force. It stays until clear_forces.

Instance:apply_angular_impulse

method

Gives a physics part a sudden spin, like a flick.

Instance:apply_angular_impulse(impulse: vector) -> ()
example
part:apply_angular_impulse(math3d.vector3.new(0, 200, 0))

Use it forspinning a thrown object, or knocking a crate into a tumble.

impulseThe spin to add.

Instance:descendants

method

Gives every instance inside this one, at every level, not only the first.

Instance:descendants() -> { Instance }
example
for _, child in door:descendants() do child.transparency = 0.5 end

Use it forfading or recoloring a whole model at once.

Instance:find_child

method

Finds a child directly inside by its Explorer name or its Script Name.

Instance:find_child(name: string) -> Instance?
example
local handle = door:find_child("Handle")

Use it forgrabbing the handle of a door, or the light inside a lamp.

nameThe name in the Explorer, or the Script Name, of a child.

Instance:find_descendant

method

Finds anything inside, however deep, by its Explorer name or Script Name.

Instance:find_descendant(name: string) -> Instance?
example
local knob = door:find_descendant("Knob")

Use it forfinding a part buried deep inside a big model without going through every level.

nameThe name in the Explorer, or the Script Name, of anything under it.

Instance:bounds

method

Gives the center and size of the box around the instance and everything inside it.

Instance:bounds() -> Bounds
example
local box = door:bounds()

Use it forplacing things on top of a model or measuring its size.

Instance:scale_by

method

Grows or shrinks the instance, and the spacing of what is inside it along with it.

Instance:scale_by(factor: number) -> ()
example
door:scale_by(2)

Use it forpower-ups that make things grow, shrinking puzzles, or giant bosses.

factor2 doubles the size, 0.5 halves it.

Instance:set_text

method

Puts text on one face of a part or model, in the color and font you choose.

Instance:set_text(face: Face, text: string?, options: SurfaceTextOptions?) -> ()
example
door:set_text("front", "Exit", { color = math3d.color.rgb(255, 255, 255) })

Use it forsigns, scoreboards on walls, or labels on buttons.

face"front", "back", "left", "right", "top" or "bottom".
textoptionalThe text, cut to 200 characters. Nil or empty removes it.
optionsoptionalIts color, font, size and alignment.
Build a set_text callcolor · font · size · align
  • color

    The color of the text, which is black when you leave it out.

  • font

    The font the text is drawn in, which is bold when you leave it out.

  • sizedefault 0

    The height of each line of text in studs, where 0 makes the text fit the face.

  • align

    How the lines of text line up across the face of the part.

Instance:get_text

method

Gives the text on one face of the part, or nil if there is none.

Instance:get_text(face: Face) -> SurfaceText?
example
local sign = door:get_text("front")

Use it forreading a sign's current text, such as a counter you add one to.

face"front", "back", "left", "right", "top" or "bottom".
↑ ↓ moveEnter openEsc close