# Class `Objects.Moveable`

Represents any object inside the game world.

Examples include traps, enemies, doors, pickups, and Lara herself (see also Objects.LaraObject for Lara-specific features).

## Functions

Moveable(object, name, position, rotation, roomNumber, animNumber, frameNumber, hp, OCB, AIBits) | Used to generate a new moveable dynamically at runtime.
Moveable:Explode() | Explode item.
Moveable:Shatter() | Shatter item.
Moveable:SetEffect(effect[, timeout]) | Set effect to moveable
Moveable:SetCustomEffect(Color1, Color2[, timeout]) | Set custom colored burn effect to moveable
Moveable:GetEffect() | Get current moveable effect
Moveable:GetStatus() | Get the moveable's status.
Moveable:SetStatus(status) | Set the moveable's status.
Moveable:GetObjectID() | Retrieve the object ID
Moveable:SetObjectID(ID) | Change the object's ID.
Moveable:GetState() | Retrieve the index of the current state.
Moveable:GetTargetState() | Retrieve the index of the target state.
Moveable:SetState(index) | Set the object's state to the one specified by the given index.
Moveable:GetAnim() | Retrieve the index of the current animation.
Moveable:SetAnim(index[, slot]) | Set the object's animation to the one specified by the given index.
Moveable:GetAnimSlot() | Retrieve the slot ID of the animation.
Moveable:GetFrame() | Retrieve frame number.
Moveable:SetFrame(frame) | Set frame number.
Moveable:GetEndFrame() | Get the end frame number of the moveable's active animation.
Moveable:SetVelocity(velocity) | Set the object's velocity to specified value.
Moveable:GetVelocity() | Get the object's velocity.
Moveable:GetHP() | Get current HP (hit points/health points)
Moveable:SetHP(HP) | Set current HP (hit points/health points) Clamped to [0, 32767] for "intelligent" entities (i.e.
Moveable:GetSlotHP() | Get HP definded for that object type (hit points/health points) (Read Only).
Moveable:GetOCB() | Get OCB (object code bit) of the moveable
Moveable:SetOCB(OCB) | Set OCB (object code bit) of the moveable
Moveable:GetItemFlags(index) | Get the value stored in ItemFlags[index]
Moveable:SetItemFlags(value, index) | Stores a value in ItemFlags[index]
Moveable:GetColor() | Get the moveable's color
Moveable:SetColor(color) | Set the moveable's color
Moveable:GetHitStatus() | Get the hit status of the object
Moveable:GetActive() | Determine whether the moveable is active or not
Moveable:GetJointPosition(index[, offset]) | Get the object's joint position
Moveable:GetJointRotation(index) | Get the object's joint rotation
Moveable:GetRotation() | Get the moveable's rotation
Moveable:SetRotation(rotation) | Set the moveable's rotation
Moveable:GetName() | Get the moveable's name (its unique string identifier) e.g.
Moveable:SetName(name) | Set the moveable's name (its unique string identifier) e.g.
Moveable:GetValid() | Test if the object is in a valid state (i.e.
Moveable:Destroy() | Destroy the moveable.
Moveable:AttachObjCamera(mesh, target, mesh) | Attach camera to an object.
Moveable:AnimFromObject(ObjectID, animNumber, stateID) | Borrow animation from an object
Moveable:SetOnHit(callback) | Set the name of the function to be called when the moveable is shot by Lara.
Moveable:SetOnCollidedWithObject(func) | Set the function to be called when this moveable collides with another moveable
Moveable:SetOnCollidedWithRoom(func) | Set the function called when this moveable collides with room geometry (e.g.
Moveable:SetOnKilled(callback) | Set the name of the function to be called when the moveable is destroyed/killed Note that enemy death often occurs at the end of an animation, and not at the exact moment the enemy's HP becomes zero.
Moveable:GetPosition() | Get the object's position
Moveable:SetPosition(position[, updateRoom]) | Set the moveable's position If you are moving a moveable whose behaviour involves knowledge of room geometry, (e.g.
Moveable:GetLocationAI() | Get the location value stored in the Enemy AI
Moveable:SetLocationAI(value) | Updates the location in the enemy AI with the given value.
Moveable:GetAIBits() | Get AIBits of object This will return a table with six values, each corresponding to an active behaviour.
Moveable:SetAIBits(bits) | Set AIBits of object Use this to force a moveable into a certain AI mode or modes, as if a certain nullmesh (or more than one) had suddenly spawned beneath their feet.
Moveable:GetRoom() | Get the current room of the object
Moveable:GetRoomNumber() | Get the current room number of the object
Moveable:SetRoomNumber(roomID) | Set the room ID of a moveable.
Moveable:GetMeshCount() | Get number of meshes for a particular object Returns number of meshes in an object
Moveable:GetMeshVisible(index) | Get state of specified mesh visibility of object Returns true if specified mesh is visible on an object, and false if it is not visible.
Moveable:SetMeshVisible(index, isVisible) | Makes specified mesh visible or invisible Use this to show or hide a specified mesh of an object.
Moveable:ShatterMesh(index) | Shatters specified mesh and makes it invisible Note that you can re-enable mesh later by using SetMeshVisible().
Moveable:GetMeshSwapped(index) | Get state of specified mesh swap of object Returns true if specified mesh is swapped on an object, and false if it is not swapped.
Moveable:SwapMesh(index, slotIndex[, swapIndex]) | Set state of specified mesh swap of object Use this to swap specified mesh of an object.
Moveable:UnswapMesh(index) | Set state of specified mesh swap of object Use this to bring back original unswapped mesh
Moveable:Enable(timeout) | Enable the item, as if a trigger for it had been stepped on.
Moveable:Disable() | Disable the item, as if an antitrigger for it had been stepped on (i.e.
Moveable:GetCollidable() | Get the item's collision state.
Moveable:SetCollidable(collidable) | Set the item's collision.
Moveable:MakeInvisible() | Make the item invisible.
Moveable:SetVisible(visible) | Set the item's visibility.

## Functions

Moveable(object, name, position, rotation, roomNumber, animNumber, frameNumber, hp, OCB, AIBits)
  Used to generate a new moveable dynamically at runtime.
  For more information on each parameter, see the associated getters and setters. If you do not know what to set for these, most can just be ignored (see usage).

  ### Parameters:

  - object ObjID ID
  - name string Lua name of the item
  - position Vec3 position in level
  - rotation Rotation rotation rotation about x, y, and z axes (default Rotation(0, 0, 0))
  - roomNumber int the room number the moveable is in (default: calculated automatically).
  - animNumber int animation number
  - frameNumber int frame number
  - hp int HP of item
  - OCB int ocb of item
  - AIBits table table with AI bits (default { 0, 0, 0, 0, 0, 0 })

  ### Returns:

  Moveable A new Moveable object (a wrapper around the new object)

  ### Usage:

      local item = Moveable(
      	TEN.Objects.ObjID.PISTOLS_ITEM, -- object id
      	"test", -- name
      	Vec3(18907, 0, 21201)) -- position

Moveable:Explode()
  Explode item. This also kills and disables item.
Moveable:Shatter()
  Shatter item. This also kills and disables item.
Moveable:SetEffect(effect[, timeout])
  Set effect to moveable

  ### Parameters:

  - effect EffectID Type of effect to assign.
  - timeout float time (in seconds) after which effect turns off. (optional)
Moveable:SetCustomEffect(Color1, Color2[, timeout])
  Set custom colored burn effect to moveable

  ### Parameters:

  - Color1 Color color the primary color of the effect (also used for lighting).
  - Color2 Color color the secondary color of the effect.
  - timeout float time (in seconds) after which effect turns off. (optional)
Moveable:GetEffect()
  Get current moveable effect

  ### Returns:

  EffectID effect type currently assigned to moveable.
Moveable:GetStatus()
  Get the moveable's status. ()

  ### Returns:

  MoveableStatus The moveable's status.
Moveable:SetStatus(status)
  Set the moveable's status. ()

  ### Parameters:

  - status MoveableStatus The new status of the moveable.
Moveable:GetObjectID()
  Retrieve the object ID

  ### Returns:

  int a number representing the ID of the object
Moveable:SetObjectID(ID)
  Change the object's ID. This will literally change the object.

  ### Parameters:

  - ID ObjID the new ID

  ### Usage:

      shiva = TEN.Objects.GetMoveableByName("shiva_60")
      shiva:SetObjectID(TEN.Objects.ObjID.BIGMEDI_ITEM)

Moveable:GetState()
  Retrieve the index of the current state. This corresponds to the number shown in the item's state ID field in WadTool.

  ### Returns:

  int the index of the active state
Moveable:GetTargetState()
  Retrieve the index of the target state. This corresponds to the state the object is trying to get into, which is sometimes different from the active state.

  ### Returns:

  int the index of the target state
Moveable:SetState(index)
  Set the object's state to the one specified by the given index. Performs no bounds checking. Ensure the number given is correct, else object may end up in corrupted animation state.

  ### Parameters:

  - index int the index of the desired state
Moveable:GetAnim()
  Retrieve the index of the current animation. This corresponds to the number shown in the item's animation list in WadTool.

  ### Returns:

  int the index of the active animation
Moveable:SetAnim(index[, slot])
  Set the object's animation to the one specified by the given index. Performs no bounds checking. Ensure the number given is correct, else object may end up in corrupted animation state.

  ### Parameters:

  - index int the index of the desired anim
  - slot int slot ID of the desired anim (if omitted, moveable's own slot ID is used) (optional)
Moveable:GetAnimSlot()
  Retrieve the slot ID of the animation. In certain cases, moveable may play animations from another object slot. Use this function when you need to identify such cases.

  ### Returns:

  int animation slot ID
Moveable:GetFrame()
  Retrieve frame number. This is the current frame of the object's active animation.

  ### Returns:

  int the current frame of the active animation
Moveable:SetFrame(frame)
  Set frame number. This will move the animation to the given frame. The number of frames in an animation can be seen under the heading "End frame" in the WadTool animation editor. If the animation has no frames, the only valid argument is -1.

  ### Parameters:

  - frame int the new frame number
Moveable:GetEndFrame()
  Get the end frame number of the moveable's active animation. This is the "End Frame" set in WADTool for the animation.()

  ### Returns:

  int End frame number of the active animation.
Moveable:SetVelocity(velocity)
  Set the object's velocity to specified value. In most cases, only Z and Y components are used as forward and vertical velocity. In some cases, primarily NPCs, X component is used as side velocity.

  ### Parameters:

  - velocity Vec3 velocity represented as vector
Moveable:GetVelocity()
  Get the object's velocity. In most cases, only Z and Y components are used as forward and vertical velocity. In some cases, primarily NPCs, X component is used as side velocity.

  ### Returns:

  Vec3 current object velocity
Moveable:GetHP()
  Get current HP (hit points/health points)

  ### Returns:

  int the amount of HP the moveable currently has
Moveable:SetHP(HP)
  Set current HP (hit points/health points) Clamped to [0, 32767] for "intelligent" entities (i.e. anything with AI); clamped to [-32767, 32767] otherwise.

  ### Parameters:

  - HP int the amount of HP to give the moveable
Moveable:GetSlotHP()
  Get HP definded for that object type (hit points/health points) (Read Only).

  ### Returns:

  int the moveable's slot default hit points
Moveable:GetOCB()
  Get OCB (object code bit) of the moveable

  ### Returns:

  int the moveable's current OCB value
Moveable:SetOCB(OCB)
  Set OCB (object code bit) of the moveable

  ### Parameters:

  - OCB int the new value for the moveable's OCB
Moveable:GetItemFlags(index)
  Get the value stored in ItemFlags[index]

  ### Parameters:

  - index int of the ItemFlags, can be between 0 and 7.

  ### Returns:

  int the value contained in the ItemFlags[index]
Moveable:SetItemFlags(value, index)
  Stores a value in ItemFlags[index]

  ### Parameters:

  - value short to store in the moveable's ItemFlags[index]
  - index int of the ItemFlags where store the value.
Moveable:GetColor()
  Get the moveable's color

  ### Returns:

  Color a copy of the moveable's color
Moveable:SetColor(color)
  Set the moveable's color

  ### Parameters:

  - color Color the new color of the moveable
Moveable:GetHitStatus()
  Get the hit status of the object

  ### Returns:

  bool true if the moveable was hit by something in the last gameplay frame, false otherwise
Moveable:GetActive()
  Determine whether the moveable is active or not

  ### Returns:

  bool true if the moveable is active
Moveable:GetJointPosition(index[, offset])
  Get the object's joint position

  ### Parameters:

  - index int of a joint to get position
  - offset Vec3 a pre-rotation offset to the joint (optional)

  ### Returns:

  Vec3 a copy of the moveable's joint position
Moveable:GetJointRotation(index)
  Get the object's joint rotation

  ### Parameters:

  - index int of a joint to get rotation

  ### Returns:

  Rotation a calculated copy of the moveable's joint rotation
Moveable:GetRotation()
  Get the moveable's rotation

  ### Returns:

  Rotation a copy of the moveable's rotation
Moveable:SetRotation(rotation)
  Set the moveable's rotation

  ### Parameters:

  - rotation Rotation The moveable's new rotation
Moveable:GetName()
  Get the moveable's name (its unique string identifier) e.g. "door_back_room" or "cracked_greek_statue" This corresponds with the "Lua Name" field in an object's properties in Tomb Editor.

  ### Returns:

  string the moveable's name
Moveable:SetName(name)
  Set the moveable's name (its unique string identifier) e.g. "door_back_room" or "cracked_greek_statue" It cannot be blank and cannot share a name with any existing object.

  ### Parameters:

  - name string the new moveable's name

  ### Returns:

  bool true if we successfully set the name, false otherwise (e.g. if another object has the name already)
Moveable:GetValid()
  Test if the object is in a valid state (i.e. has not been destroyed through Lua or killed by Lara).

  ### Returns:

  bool valid true if the object is still not destroyed
Moveable:Destroy()
  Destroy the moveable. This will mean it can no longer be used, except to re-initialize it with another object.
Moveable:AttachObjCamera(mesh, target, mesh)
  Attach camera to an object.

  ### Parameters:

  - mesh int of a target moveable to use as a camera target
  - target Moveable moveable to attach camera to
  - mesh int of a target moveable to use as a camera target
Moveable:AnimFromObject(ObjectID, animNumber, stateID)
  Borrow animation from an object

  ### Parameters:

  - ObjectID ObjID to take animation and stateID from,
  - animNumber int animation from object
  - stateID int state from object
Moveable:SetOnHit(callback)
  Set the name of the function to be called when the moveable is shot by Lara. Note that this will be triggered twice when shot with both pistols at once.

  ### Parameters:

  - callback function function in LevelFuncs hierarchy to call when moveable is shot
Moveable:SetOnCollidedWithObject(func)
  Set the function to be called when this moveable collides with another moveable

  ### Parameters:

  - func function callback function to be called (must be in LevelFuncs hierarchy). This function can take two arguments; these will store the two Moveables taking part in the collision.

  ### Usage:

      -- obj1 is the collision moveable
      -- obj2 is the collider moveable

      LevelFuncs.objCollided = function(obj1, obj2)
          print(obj1:GetName() .. " collided with " .. obj2:GetName())
      end
      baddy:SetOnCollidedWithObject(LevelFuncs.objCollided)

Moveable:SetOnCollidedWithRoom(func)
  Set the function called when this moveable collides with room geometry (e.g. a wall or floor). This function can take an argument that holds the Moveable that collided with geometry.

  ### Parameters:

  - func function callback function to be called (must be in LevelFuncs hierarchy)

  ### Usage:

      LevelFuncs.roomCollided = function(obj)
          print(obj:GetName() .. " collided with room geometry")
      end
      baddy:SetOnCollidedWithRoom(LevelFuncs.roomCollided)

Moveable:SetOnKilled(callback)
  Set the name of the function to be called when the moveable is destroyed/killed Note that enemy death often occurs at the end of an animation, and not at the exact moment the enemy's HP becomes zero.

  ### Parameters:

  - callback function function in LevelFuncs hierarchy to call when enemy is killed

  ### Usage:

      LevelFuncs.baddyKilled = function(theBaddy) print("You killed a baddy!") end
      baddy:SetOnKilled(LevelFuncs.baddyKilled)

Moveable:GetPosition()
  Get the object's position

  ### Returns:

  Vec3 a copy of the moveable's position
Moveable:SetPosition(position[, updateRoom])
  Set the moveable's position If you are moving a moveable whose behaviour involves knowledge of room geometry, (e.g. a BADDY1, which uses it for pathfinding), then the second argument should be true (or omitted, as true is the default). Otherwise, said moveable will not behave correctly.

  ### Parameters:

  - position Vec3 the new position of the moveable
  - updateRoom bool Will room changes be automatically detected? Set to false if you are using overlapping rooms (default: true) (optional)
Moveable:GetLocationAI()
  Get the location value stored in the Enemy AI

  ### Returns:

  short the value contained in the LocationAI of the creature.
Moveable:SetLocationAI(value)
  Updates the location in the enemy AI with the given value.

  ### Parameters:

  - value short to store.
Moveable:GetAIBits()
  Get AIBits of object This will return a table with six values, each corresponding to an active behaviour. If the object is in a certain AI mode, the table will have a 1 in the corresponding cell. Otherwise, the cell will hold a 0.

  1 - guard
  2 - ambush
  3 - patrol 1
  4 - modify
  5 - follow
  6 - patrol 2

  ### Returns:

  table a table of AI bits
Moveable:SetAIBits(bits)
  Set AIBits of object Use this to force a moveable into a certain AI mode or modes, as if a certain nullmesh (or more than one) had suddenly spawned beneath their feet.

  ### Parameters:

  - bits table the table of AI bits

  ### Usage:

      local sas = TEN.Objects.GetMoveableByName("sas_enemy")
      sas:SetAIBits({1, 0, 0, 0, 0, 0})

Moveable:GetRoom()
  Get the current room of the object

  ### Returns:

  Room current room of the object
Moveable:GetRoomNumber()
  Get the current room number of the object

  ### Returns:

  int number representing the current room of the object
Moveable:SetRoomNumber(roomID)
  Set the room ID of a moveable. Use this if not using SetPosition's automatic room update - for example, when dealing with overlapping rooms.

  ### Parameters:

  - roomID int New room's ID.

  ### Usage:

      local sas = TEN.Objects.GetMoveableByName("sas_enemy")
      sas:SetRoomNumber(newRoomID)
      sas:SetPosition(newPos, false)

Moveable:GetMeshCount()
  Get number of meshes for a particular object Returns number of meshes in an object

  ### Returns:

  int number of meshes
Moveable:GetMeshVisible(index)
  Get state of specified mesh visibility of object Returns true if specified mesh is visible on an object, and false if it is not visible.

  ### Parameters:

  - index int index of a mesh

  ### Returns:

  bool visibility status
Moveable:SetMeshVisible(index, isVisible)
  Makes specified mesh visible or invisible Use this to show or hide a specified mesh of an object.

  ### Parameters:

  - index int index of a mesh
  - isVisible bool true if you want the mesh to be visible, false otherwise
Moveable:ShatterMesh(index)
  Shatters specified mesh and makes it invisible Note that you can re-enable mesh later by using SetMeshVisible().

  ### Parameters:

  - index int index of a mesh
Moveable:GetMeshSwapped(index)
  Get state of specified mesh swap of object Returns true if specified mesh is swapped on an object, and false if it is not swapped.

  ### Parameters:

  - index int index of a mesh

  ### Returns:

  bool mesh swap status
Moveable:SwapMesh(index, slotIndex[, swapIndex])
  Set state of specified mesh swap of object Use this to swap specified mesh of an object.

  ### Parameters:

  - index int index of a mesh
  - slotIndex int index of a slot to get meshswap from
  - swapIndex int index of a mesh from meshswap slot to use (optional)
Moveable:UnswapMesh(index)
  Set state of specified mesh swap of object Use this to bring back original unswapped mesh

  ### Parameters:

  - index int index of a mesh to unswap
Moveable:Enable(timeout)
  Enable the item, as if a trigger for it had been stepped on.

  ### Parameters:

  - timeout float time (in seconds) after which moveable automatically disables (optional).
Moveable:Disable()
  Disable the item, as if an antitrigger for it had been stepped on (i.e. it will close an open door or extinguish a flame emitter). Note that this will not trigger an OnKilled callback.
Moveable:GetCollidable()
  Get the item's collision state.

  ### Returns:

  bool item's collision state
Moveable:SetCollidable(collidable)
  Set the item's collision.

  ### Parameters:

  - collidable bool true if the caller should be collidable, false if no collision should occur.
Moveable:MakeInvisible()
  Make the item invisible. Alias for `Moveable:SetVisible(false)`.
Moveable:SetVisible(visible)
  Set the item's visibility. An invisible item will have collision turned off, as if it no longer exists in the game world.

  ### Parameters:

  - visible bool true if the caller should become visible, false if it should become invisible

generated by TEN-LDoc (a fork of LDoc 1.4.6)