> ## Documentation Index
> Fetch the complete documentation index at: https://toolkit.victorgamestudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Actors Playbook

> Learn how to direct every object in your Poly Plaza world

# Introduction

The Actor system is what brings your Poly Plaza world to life! Every object in the game - from characters to buildings to items - is an Actor. This guide will show you how to control them.

## Core Methods

### Basic Information

#### GetName()

Returns the name of the Actor.

```lua theme={null}
local name = actor:GetName()
print("Actor name:", name)
```

#### GetClassName()

Returns the class type of the Actor.

```lua theme={null}
local className = actor:GetClassName()
print("Actor type:", className)
```

### Location & Movement

#### GetLocation()

Returns the Actor's current position in the world.

```lua theme={null}
local pos = actor:GetLocation()
print("Position:", pos.x, pos.y, pos.z)
```

#### SetLocation(position)

Moves the Actor to a new position.

```lua theme={null}
actor:SetLocation({
    x = 100,
    y = 200,
    z = 50
})
```

### Rotation Control

#### GetRotation()

Gets the Actor's current rotation.

```lua theme={null}
local rot = actor:GetRotation()
print("Rotation - Pitch:", rot.pitch, "Yaw:", rot.yaw, "Roll:", rot.roll)
```

#### SetRotation(rotation)

Sets the Actor's rotation.

```lua theme={null}
actor:SetRotation({
    pitch = 0,  -- Up/down angle
    yaw = 90,   -- Left/right angle
    roll = 0    -- Barrel roll
})
```

### Scale & Size

#### GetScale()

Returns the Actor's current scale.

```lua theme={null}
local scale = actor:GetScale()
print("Scale:", scale.x, scale.y, scale.z)
```

### Physics Controls

#### SetPhysicsEnabled(enable)

Enables or disables physics simulation.

```lua theme={null}
-- Turn on physics
actor:SetPhysicsEnabled(true)

-- Turn off physics
actor:SetPhysicsEnabled(false)
```

#### GetPhysicsEnabled()

Checks if physics is enabled.

```lua theme={null}
local hasPhysics = actor:GetPhysicsEnabled()
print("Physics enabled:", hasPhysics)
```

#### SetCollisionEnabled(enable)

Enables or disables collision detection.

```lua theme={null}
-- Turn on collisions
actor:SetCollisionEnabled(true)

-- Turn off collisions
actor:SetCollisionEnabled(false)
```

#### GetCollisionEnabled()

Checks if collision is enabled.

```lua theme={null}
local hasCollision = actor:GetCollisionEnabled()
print("Collision enabled:", hasCollision)
```

### Physics Properties

#### GetMass()

Gets the Actor's mass in kilograms.

```lua theme={null}
local mass = actor:GetMass()
print("Mass:", mass, "kg")
```

#### SetMass(mass)

Sets the Actor's mass.

```lua theme={null}
actor:SetMass(50) -- Set to 50 kg
```

#### GetGravity()

Checks if gravity affects this Actor.

```lua theme={null}
local hasGravity = actor:GetGravity()
print("Gravity enabled:", hasGravity)
```

#### SetGravity(enable)

Enables or disables gravity for this Actor.

```lua theme={null}
-- Make the actor float
actor:SetGravity(false)

-- Return to normal gravity
actor:SetGravity(true)
```

### Physics Forces

#### AddImpulse(force)

Applies an instant force to the Actor.

```lua theme={null}
-- Launch upward
actor:AddImpulse({
    x = 0,
    y = 0,
    z = 1000
})
```

#### GetVelocity()

Gets the Actor's current velocity.

```lua theme={null}
local velocity = actor:GetVelocity()
print("Speed - X:", velocity.x, "Y:", velocity.y, "Z:", velocity.z)
```

### Actor Lifecycle

#### Destroy()

Removes the Actor from the world.

```lua theme={null}
actor:Destroy()
```

## Advanced Examples

### Creating a Physics Playground

```lua theme={null}
local function setupPhysicsActor(actor)
    -- Enable physics and collision
    actor:SetPhysicsEnabled(true)
    actor:SetCollisionEnabled(true)

    -- Set physical properties
    actor:SetMass(10)
    actor:SetGravity(true)

    -- Position the actor
    actor:SetLocation({
        x = 0,
        y = 0,
        z = 100
    })
end
```

### Creating a Floating Display Item

```lua theme={null}
local function makeFloatingDisplay(actor)
    -- Disable physics interference
    actor:SetPhysicsEnabled(false)
    actor:SetGravity(false)

    -- Set initial position
    actor:SetLocation({
        x = 100,
        y = 100,
        z = 150
    })

    -- Set display rotation
    actor:SetRotation({
        pitch = 0,
        yaw = 45,
        roll = 0
    })
end
```

## Best Practices

<Note>
  Always check if your actor still exists before calling methods on it:

  ```lua theme={null}
  if actor then
      actor:SetLocation(newPosition)
  end
  ```
</Note>

<Warning>
  Be careful with physics forces! Start with small values and adjust as needed.
</Warning>

<Tip>
  When working with multiple actors, consider disabling physics and collision for actors that don't need them to improve performance.
</Tip>

## Troubleshooting

### Common Issues

1. **Actor not moving with AddImpulse**
   * Check if physics is enabled
   * Verify the mass isn't too high
   * Make sure gravity is appropriate for your needs

2. **Collision not working**
   * Confirm collision is enabled
   * Check if physics is enabled
   * Verify the actor has a valid collision shape

3. **Actor disappearing**
   * Make sure the location is within valid world bounds
   * Check if it was accidentally destroyed
   * Verify it hasn't fallen through the world (check Z position)

### Example Debug Function

```lua theme={null}
local function debugActor(actor)
    if not actor then
        print("Actor is nil!")
        return
    end

    local pos = actor:GetLocation()
    local rot = actor:GetRotation()
    local physics = actor:GetPhysicsEnabled()
    local collision = actor:GetCollisionEnabled()

    print("--- Actor Debug Info ---")
    print("Name:", actor:GetName())
    print("Class:", actor:GetClassName())
    print("Position:", pos.x, pos.y, pos.z)
    print("Rotation:", rot.pitch, rot.yaw, rot.roll)
    print("Physics:", physics)
    print("Collision:", collision)
    print("Mass:", actor:GetMass())
    print("Has Gravity:", actor:GetGravity())
end
```

Remember, actors are the building blocks of your Poly Plaza world. Use them wisely, and don't forget to share your creations with the community!