Lua Scripting Overview

Polygon Engine uses Lua Behaviours for project gameplay. Each Lua Behaviour is attached to a GameObject and receives that GameObject's stable numeric ID. Editor Play Mode and the PlayStation runtime expose the same case-sensitive public API.

Lifecycle

Define only the callbacks the script needs:

function Awake(gameObjectId) end
function OnEnable(gameObjectId) end
function Start(gameObjectId) end
function FixedUpdate(gameObjectId, fixedDeltaTime) end
function Update(gameObjectId, deltaTime) end
function LateUpdate(gameObjectId, deltaTime) end

function OnCollisionEnter(gameObjectId, otherGameObjectId) end
function OnCollisionStay(gameObjectId, otherGameObjectId) end
function OnCollisionExit(gameObjectId, otherGameObjectId) end
function OnTriggerEnter(gameObjectId, otherGameObjectId) end
function OnTriggerStay(gameObjectId, otherGameObjectId) end
function OnTriggerExit(gameObjectId, otherGameObjectId) end

function OnDisable(gameObjectId) end
function OnDestroy(gameObjectId) end

Awake runs once after the Lua Behaviour loads. OnEnable runs whenever it becomes active, and Start runs before its first Update. FixedUpdate uses the bounded 30 Hz simulation step. Collision and trigger callbacks require the corresponding Collider setup. OnDestroy runs before the script environment is released during teardown or a scene transition.

Exposed Properties

Top-level scalar declarations before the first function become Inspector fields:

moveSpeed = 3.0
doorGameObjectId = -1
promptTextName = "Prompt Text"

The editor preserves per-GameObject overrides. Use exposed properties for scene references and tuning values instead of embedding IDs throughout a script.

Minimal Script

rotationSpeed = 30.0

function Update(gameObjectId, deltaTime)
  Transform.RotateY(gameObjectId, rotationSpeed * deltaTime)
end

Input and Collision Example

moveSpeed = 2.0

function Start(gameObjectId)
  Log.Print(GameObject.GetName(gameObjectId) .. " ready")
end

function Update(gameObjectId, deltaTime)
  if Input.GetButton(Input.RIGHT) then
    Transform.Translate(gameObjectId, moveSpeed * deltaTime, 0.0, 0.0)
  end
end

function OnCollisionEnter(gameObjectId, otherGameObjectId)
  Log.Print("Touched " .. GameObject.GetName(otherGameObjectId))
end

API Families

Area	Public tables
Core	GameObject, Transform, Time, Log, Engine
Input and feedback	Input, PlayerInput, Rumble
Physics and movement	Collider, Physics, CharacterController
Scene presentation	Camera, Light, AudioSource, Music, ParticleSystem
Animation	TransformAnimator, Animator, Animation, Timeline
World	SceneManager, NavMesh, NavMeshAgent, Portal, Interactable
UI	UI, Canvas, Text, Image, Button, RectTransform, Graphic, Selectable, ProgressBar
Persistence	PlayerPrefs, SaveData

See API Summary for every method and constant, then use the topic pages for examples and component requirements.

Runtime Rules

• Cache GameObject and UI IDs instead of performing name lookups every frame.
• Treat false, nil, and -1 as normal failure results and validate the required component before using its API.
• Prefer semantic Input Actions such as "Move" and "Interact" to physical buttons for remappable gameplay.
• Keep lifecycle callbacks bounded and avoid per-frame temporary strings and tables.
• Run Validate Project, Show PS1 Budget, and Production Acceptance, then test the release CUE on the target hardware path.

See Authoring Workflow, Scripting Runtime Reference, and PS1 Runtime Limits.