Components
Polygon Engine scenes are built from GameObjects. Every GameObject has a Transform, and optional components add rendering, gameplay, collision, audio, camera, lighting, animation, and scripting behavior.
The component model is intentionally small. Each component should serialize cleanly to scene JSON, validate in the editor, and stage predictably into the PS1 runtime.
Component Families
| Family | Components |
|---|---|
| Core | Transform, Mesh Renderer, Camera, Lua Behaviour |
| Collision and movement | Collider, Character Controller |
| Native player stack | Player Input, Player Motor, First Person Controller, Third Person Controller, Camera Rig |
| Interaction | Interaction Ray, Interactable, Spawn Point |
| Presentation | Directional Light, Transform Animator, Animator, Player Animator, Audio Source, Particle System |
| World | Room, Portal, NavMesh Surface, Navigation Modifier, NavMesh Agent |
| UI | Authored UI Canvases, Text, Button, Image, Panel, ProgressBar, bitmap fonts |
UI elements are stored in the scene's named UI canvases, not as GameObject components. See UI Canvas.
Transform
Present on every GameObject.
| Property | Description |
|---|---|
| Position | Local position relative to the parent |
| Rotation | Local Euler rotation in degrees |
| Scale | Local scale |
| Parent | Optional parent GameObject |
Child transforms are resolved into world transforms before rendering, collision, camera, and script queries.
Mesh Renderer
Draws either a built-in primitive or an imported mesh asset.
| Property | Description |
|---|---|
| Mesh Type | builtin or asset |
| Mesh | Built-in primitive name or imported mesh GUID |
| Material Type | Built-in material or material asset |
| Material | Built-in name or material GUID |
| Primitive Tessellation | Segment controls for compatible built-in primitives |
| Vertex Color Mode | Material, Mesh Vertex Colors, GTE Vertex Lighting, or Flat Color |
| Flat Color | Renderer color override used by Flat Color mode |
| Receive Fog | Participate in the PS1 per-vertex distance-fog blend |
| Renderer Room | Optional Room GameObject used by room-connectivity rejection |
Built-in primitives include Cube, Plane, and Capsule. For PS1 builds, static built-in Plane and Cube geometry can be baked into safer staged mesh chunks. Rounded primitives should be used sparingly in PS1-facing scenes.
Mesh Vertex Colors and GTE Vertex Lighting use native Gouraud G3/GT3 primitives on supported paths. GTE Vertex Lighting is evaluated at runtime from mesh normals; it is not an offline lighting bake.
Camera
Defines a render viewpoint.
| Property | Description |
|---|---|
| FOV | Field of view in degrees |
The runtime uses an enabled camera or a camera driven by a CameraRig/player setup.
Lua Behaviour
Attaches a Lua script file to the GameObject.
| Property | Description |
|---|---|
| Script Path | Relative path to a .lua file |
| Script Properties | Inspector-exposed key/value strings passed to the script |
Engine lifecycle callbacks use exact PascalCase names:
Awake,OnEnable,Start,FixedUpdate,Update, andLateUpdate;OnCollisionEnter,OnCollisionStay, andOnCollisionExit;OnTriggerEnter,OnTriggerStay, andOnTriggerExit;OnDisableandOnDestroy.
Buttons, Interactables, Timelines, and GameObject.Invoke call custom Lua
functions by their exact configured name. Those functions are project-defined
and are not lifecycle aliases.
See Lua API Overview.
Collider
Defines a collision volume for blocking and triggers.
| Property | Description |
|---|---|
| Type | Box or sphere |
| Size / Radius | Shape dimensions |
| Is Trigger | Overlap only, no blocking response |
Colliders are used by collision callbacks, trigger callbacks, interactables, pickups, stations, and blocking world geometry.
Level Builder scene placement creates an AABB Collider for the placed mesh. Tune it in the Inspector if the generated bounds are too broad or too narrow.
The PS1 runtime uses a fixed-capacity sweep-and-prune broad phase for active Collider pairs, then runs normal shape tests on the resulting candidates. Invalid or unavailable broad-phase state falls back conservatively to the full pair path. This optimization requires no project setting and does not change collision or trigger callbacks.
Character Controller
High-level locomotion collider for player-style movement.
| Property | Description |
|---|---|
| Height | Capsule height |
| Radius | Capsule radius |
| Step Offset | Small step climbing |
| Slope Limit | Maximum traversable slope |
| Skin Width | Collision padding |
| Use Gravity | Apply gravity through the controller |
Use Character Controller for first-person and third-person player movement instead of manually translating through world Colliders.
Step, ground, and slope tests sample the true upper plane of rotated box
Colliders. Step Offset controls small upward rises and Slope Limit rejects
steeper top faces. This is controller-specific surface handling, not a general
rigid-body OBB solver or moving-platform system.
Player Input
Maps pad input into movement, look, run, and interaction actions. Movement uses the left stick or D-Pad. Camera look uses the right stick when an analog pad is available. The native player stack does not repurpose shoulder or trigger buttons as camera axes.
| Property | Description |
|---|---|
| Scheme | FirstPerson, ThirdPersonTank, or ThirdPersonCameraRelative |
| Move Action | Named movement axis |
| Look Action | Named look axis |
| Run Button | Button name, default Circle |
| Interact Button | Button name, default Cross |
| Look Sensitivity X/Y | Camera/controller sensitivity |
| Invert Look Y | Invert vertical look |
| Dead Zone | Analog dead zone |
Use Player Input with Player Motor and one controller component. In DuckStation, select a Digital Controller for D-Pad-only projects, or an Analog/DualShock controller with analog mode enabled for right-stick camera input.
Player Motor
Controls core movement values used by native player controllers.
| Property | Description |
|---|---|
| Move Speed | Normal movement speed |
| Run Speed | Running speed |
| Turn Speed | Rotation speed |
| Gravity | Gravity strength |
| Acceleration | Movement acceleration |
| Allow Run | Enables run input |
| Use Gravity | Applies gravity through the motor/controller stack |
First Person Controller
Adds first-person camera behavior to a player GameObject.
| Property | Description |
|---|---|
| Eye Height | Camera height above the player base |
| Lock Cursor On Play | Editor play-mode behavior |
| Head Bob | Optional camera bob |
| Head Bob Amount | Bob intensity |
Typical setup: Player Input, Player Motor, Character Controller, First Person Controller, Camera Rig, and an Interaction Ray.
Third Person Controller
Adds third-person movement behavior.
| Property | Description |
|---|---|
| Control Scheme | Tank or camera-relative movement |
| Camera Distance | Follow distance |
| Camera Height | Follow height |
| Use Camera Zones | Allows CameraZone overrides |
Typical setup: Player Input, Player Motor, Character Controller, Third Person Controller, Camera Rig, a visible Mesh Renderer, and optional Player Animator.
Camera Rig
Controls a camera relative to a target GameObject.
| Property | Description |
|---|---|
| Mode | FirstPerson, ThirdPersonFollow, ThirdPersonOrbit, or Fixed |
| Target GameObject ID | GameObject to follow or orbit |
| Offset | Local camera offset |
| Eye Height | First-person camera height |
| Distance / Height | Third-person placement |
| Follow Smooth | Follow smoothing |
| Collide With World | Camera collision option |
| Pitch Min / Max | Vertical look limits |
Camera Zone
Defines a volume that can override camera behavior.
| Property | Description |
|---|---|
| Mode | Fixed, Follow, or Orbit |
| Camera GameObject ID | Camera or rig target |
| Priority | Higher priority wins |
| Size | Zone bounds |
| Cut On Enter | Instant switch instead of blend |
| Blend Time | Transition time |
Camera zones are most useful in third-person scenes.
Interaction Ray
Lets a player query interactable objects in front of them.
| Property | Description |
|---|---|
| Cast Mode | Ray or sphere |
| Distance | Interaction reach |
| Radius | Sphere cast radius |
| Prompt | Prompt text |
| Target GameObject ID | Optional explicit target |
| Function Name | Exact custom Lua function to call, commonly interact |
| Require Line Of Sight | Blocks interaction through geometry |
Interactable
Marks a GameObject as an interaction target.
| Property | Description |
|---|---|
| Enabled | Include the target in interaction queries and prompts |
| Prompt | Text shown to the player |
| Function Name | Lua Behaviour function invoked by interaction |
| Radius | Interaction radius |
| Button | Target-specific button, or inherit Player Input.Interact Button |
| Cooldown | Seconds before the target can be used again, 0..3600 |
| Repeatable | Allow later interactions; when off, consume after the first accepted activation |
| Prompt Canvas | Optional named canvas shown while this target is in range |
Supported target-specific names are Cross, Circle, Square, Triangle, L1, L2,
R1, R2, L3, R3, Start, and Select. Interaction uses the button's pressed edge,
not a continuously held state. When Prompt Canvas is empty or cannot resolve,
the runtime displays its built-in Button: Prompt text. Pair Interactable with
a Lua Behaviour component when the object should react to player input. Lua can
temporarily disable or re-enable the component through the
Interactable API.
Spawn Point
Defines where player-style systems should spawn or respawn.
| Property | Description |
|---|---|
| Spawn ID | Named spawn point |
| Default Spawn | Used when no specific spawn is requested |
Particle System
Emits deterministic bounded billboard particles from authored settings.
| Property | Description |
|---|---|
| Enabled / Play On Start | Runtime participation and automatic startup |
| Loop / Duration / Start Delay | Emitter timing |
| Rate | Particles per second, capped at 60 |
| Lifetime | Minimum and maximum particle life |
| Local Offset | Emission origin relative to the GameObject |
| Velocity / Randomness | Base and per-axis randomized velocity |
| Color | 8-bit RGBA particle tint |
| Seed | Deterministic random sequence |
The Dust, Sparks, and Steam presets provide PS1-safe starting points.
The Inspector estimates peak occupancy against the shared 32-particle pool.
Lua's ParticleSystem.Emit is the global one-shot path;
it does not start or stop an authored component.
Audio Source
Plays a VAG-backed audio clip through the PS1 SPU.
| Property | Description |
|---|---|
| Audio Clip | Imported WAV converted to .vag |
| Volume | Playback volume |
| Loop | Whether playback loops |
| Play On Start | Start automatically when the scene loads |
Audio is scene-resident. Imported clips must fit the runtime audio budget. Long background music should normally use Streaming Music (CD-XA) and the global Music Lua API instead of an Audio Source.
Directional Light
Adds directional lighting data.
| Property | Description |
|---|---|
| Direction | Main light direction |
| Color | Directional light color |
| Intensity | Directional contribution multiplier |
| Ambient | Ambient contribution |
The PS1 runtime uses a limited directional lighting path. Keep lighting simple and motivated.
Transform Animator
Controls named transform animation states on a GameObject.
| Property | Description |
|---|---|
| States | Named animation states |
| Default State | State played initially |
| Speed | Playback speed |
| Loop | Whether playback loops |
| Play On Start | Start automatically |
Lua can play, stop, set speed, query state, and change animation state through
the TransformAnimator API. This component animates
transform states; it is not the imported skeletal component.
A scene supports at most 32 Transform Animator components and four states per component. The PS1 runtime assigns state storage from a deterministic component pool only for GameObjects that own this component, instead of reserving four state records inside every scene GameObject. Validation blocks scenes that exceed either limit.
Animator
Plays clips imported from a hard-skinned FBX asset.
| Property | Description |
|---|---|
| Enabled | Participate in update and rendering |
| Skin | Imported .skn asset |
| Default Clip | Initial named clip |
| Playback Speed | Clip time multiplier |
| Loop | Restart after the final frame |
| Play On Start | Start the default clip automatically |
The GameObject also uses its Mesh Renderer material and texture. See Skeletal
Animation for import, hard-skin behavior, limits,
and Animator playback.
Player Animator
Maps native player movement states to Transform Animator state names.
| Property | Description |
|---|---|
| Idle State | Transform Animator state for idle |
| Walk State | Transform Animator state for walking |
| Run State | Transform Animator state for running |
| Interact State | Transform Animator state for interaction |
| Speed Damp | Dampening for state changes |
Use this with Third Person Controller or any visible player representation that needs state-driven transform animation.
Room and Portal
Room defines an axis-aligned named volume with offset and overlap priority.
Portal references two Rooms and controls directed visibility connectivity with
enabled, open, and two-sided state. Portal state can change through
Portal.SetOpen().
The PS1 runtime admits the first room behind each adjacent valid opening, then uses conservative aperture-cone overlap for later Portal traversal. Ambiguous data fails open. Editor Play Mode and PS1 share the aperture-cone tests for equivalent scene/camera state. This remains a conservative visibility system rather than exact portal-plane or hardware occlusion. See Rooms, Portals, and Navigation.
NavMesh Surface, Navigation Modifier, and NavMesh Agent
NavMesh Surface describes a bounded height-aware graph bake with X/Z Cell Size, vertical Cell Height, agent clearance, Max Step, Max Slope, and Max Drop. It supports surface Y rotation and deterministic four-neighbour links. Multiple height samples may exist at one X/Z coordinate.
Navigation Modifier classifies a root Collider as Obstacle, Walkable, Platform, or WalkOff. Walkable/Platform require solid box Colliders and sample their true rotated upper face. WalkOff requires a trigger and permits bounded one-way descents. Platform remains static bake data; it does not implement moving platforms. Ordinary obstacle geometry remains root and yaw-only for the bake.
NavMesh Agent references a surface and stores speed, acceleration, stopping distance, and rotate-to-velocity behavior. Agents must remain root GameObjects because baked paths and runtime movement use world-space positions. Agent path queries are filtered to the referenced surface.
Use the NavMesh Lua API to request paths and move agents.