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