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.

local name = actor:GetName()
print("Actor name:", name)

GetClassName()

Returns the class type of the Actor.

local className = actor:GetClassName()
print("Actor type:", className)

Location & Movement

GetLocation()

Returns the Actor’s current position in the world.

local pos = actor:GetLocation()
print("Position:", pos.x, pos.y, pos.z)

SetLocation(position)

Moves the Actor to a new position.

actor:SetLocation({
    x = 100,
    y = 200,
    z = 50
})

Rotation Control

GetRotation()

Gets the Actor’s current rotation.

local rot = actor:GetRotation()
print("Rotation - Pitch:", rot.pitch, "Yaw:", rot.yaw, "Roll:", rot.roll)

SetRotation(rotation)

Sets the Actor’s rotation.

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.

local scale = actor:GetScale()
print("Scale:", scale.x, scale.y, scale.z)

Physics Controls

SetPhysicsEnabled(enable)

Enables or disables physics simulation.

-- Turn on physics
actor:SetPhysicsEnabled(true)

-- Turn off physics
actor:SetPhysicsEnabled(false)

GetPhysicsEnabled()

Checks if physics is enabled.

local hasPhysics = actor:GetPhysicsEnabled()
print("Physics enabled:", hasPhysics)

SetCollisionEnabled(enable)

Enables or disables collision detection.

-- Turn on collisions
actor:SetCollisionEnabled(true)

-- Turn off collisions
actor:SetCollisionEnabled(false)

GetCollisionEnabled()

Checks if collision is enabled.

local hasCollision = actor:GetCollisionEnabled()
print("Collision enabled:", hasCollision)

Physics Properties

GetMass()

Gets the Actor’s mass in kilograms.

local mass = actor:GetMass()
print("Mass:", mass, "kg")

SetMass(mass)

Sets the Actor’s mass.

actor:SetMass(50) -- Set to 50 kg

GetGravity()

Checks if gravity affects this Actor.

local hasGravity = actor:GetGravity()
print("Gravity enabled:", hasGravity)

SetGravity(enable)

Enables or disables gravity for this Actor.

-- 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.

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

GetVelocity()

Gets the Actor’s current velocity.

local velocity = actor:GetVelocity()
print("Speed - X:", velocity.x, "Y:", velocity.y, "Z:", velocity.z)

Actor Lifecycle

Destroy()

Removes the Actor from the world.

actor:Destroy()

Advanced Examples

Creating a Physics Playground

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

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

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

if actor then
    actor:SetLocation(newPosition)
end

Be careful with physics forces! Start with small values and adjust as needed.

When working with multiple actors, consider disabling physics and collision for actors that don’t need them to improve performance.

Troubleshooting

Common Issues

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
Collision not working
- Confirm collision is enabled
- Check if physics is enabled
- Verify the actor has a valid collision shape
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

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!

Get Started

Scripting Reference

Game Assets

The Actors Playbook

Introduction

Core Methods

Basic Information

GetName()

GetClassName()

Location & Movement

GetLocation()

SetLocation(position)

Rotation Control

GetRotation()

SetRotation(rotation)

Scale & Size

GetScale()

Physics Controls

SetPhysicsEnabled(enable)

GetPhysicsEnabled()

SetCollisionEnabled(enable)

GetCollisionEnabled()

Physics Properties

GetMass()

SetMass(mass)

GetGravity()

SetGravity(enable)

Physics Forces

AddImpulse(force)

GetVelocity()

Actor Lifecycle

Destroy()

Advanced Examples

Creating a Physics Playground

Creating a Floating Display Item

Best Practices

Troubleshooting

Common Issues

Example Debug Function

​Introduction

​Core Methods

​Basic Information

​GetName()

​GetClassName()

​Location & Movement

​GetLocation()

​SetLocation(position)

​Rotation Control

​GetRotation()

​SetRotation(rotation)

​Scale & Size

​GetScale()

​Physics Controls

​SetPhysicsEnabled(enable)

​GetPhysicsEnabled()

​SetCollisionEnabled(enable)

​GetCollisionEnabled()

​Physics Properties

​GetMass()

​SetMass(mass)

​GetGravity()

​SetGravity(enable)

​Physics Forces

​AddImpulse(force)

​GetVelocity()

​Actor Lifecycle

​Destroy()

​Advanced Examples

​Creating a Physics Playground

​Creating a Floating Display Item

​Best Practices

​Troubleshooting

​Common Issues

​Example Debug Function

Introduction

Core Methods

Basic Information

GetName()

GetClassName()

Location & Movement

GetLocation()

SetLocation(position)

Rotation Control

GetRotation()

SetRotation(rotation)

Scale & Size

GetScale()

Physics Controls

SetPhysicsEnabled(enable)

GetPhysicsEnabled()

SetCollisionEnabled(enable)

GetCollisionEnabled()

Physics Properties

GetMass()

SetMass(mass)

GetGravity()

SetGravity(enable)

Physics Forces

AddImpulse(force)

GetVelocity()

Actor Lifecycle

Destroy()

Advanced Examples

Creating a Physics Playground

Creating a Floating Display Item

Best Practices

Troubleshooting

Common Issues

Example Debug Function