sampleproj/Assets/SETUP.md

# PSXSplash Test Scene - Unity Setup Guide

This test scene exercises every Lua API namespace and callback. Follow these steps to set it up in SplashEdit.

## Prerequisites

- Unity project with SplashEdit (the `splashedit` package)
- A font atlas configured (for UI text)
- Audio clips imported (or skip audio-related tests)

## Step 1: Create the Scene

1. Create a new Unity scene
2. Add a **PSXSceneExporter** component to a root GameObject
3. Add a **PSXPlayer** prefab (for player movement, gravity, collision)
4. Add **PSXNavRegion** components to define walkable floor areas

## Step 2: Create Lua Files

Create **LuaFile** ScriptableObjects (Assets > Create > PSXSplash > Lua File) for each script:

| Lua File Name | Script |
|---------------|--------|
| `scene` | `scene.lua` (attach to scene, not an object) |
| `collectible` | `collectible.lua` |
| `door` | `door.lua` |
| `npc` | `npc.lua` |
| `switch` | `switch.lua` |
| `spinner` | `spinner.lua` |
| `movable` | `movable.lua` |
| `entity_scanner` | `entity_scanner.lua` |

Paste each `.lua` file's content into the corresponding LuaFile asset's text field.

## Step 3: Set Up Scene Script

On the PSXSceneExporter, assign the `scene` LuaFile to the **Scene Script** field. This handles `onSceneCreationStart`, `onSceneCreationEnd`, and `onTriggerEnter/Exit`.

## Step 4: Create Game Objects

For each entity script, create a GameObject in the scene:

### Collectibles (x3)
- Create 3 GameObjects with mesh renderers (cubes, spheres, etc.)
- Add **PSXObjectExporter** to each, assign the `collectible` LuaFile
- Space them around the scene so the player can walk into them
- They use `onCollideWithPlayer` - no PSXInteractable needed

### NPC
- Create a GameObject with a character mesh
- Add **PSXObjectExporter**, assign `npc` LuaFile
- Add **PSXInteractable** component (so `onInteract` fires when player presses Cross nearby)

### Door
- Create a door mesh GameObject
- Add **PSXObjectExporter**, assign `door` LuaFile
- Add **PSXInteractable** component
- Create a second GameObject named exactly **"DoorBlocker"** (invisible wall blocking the doorway)
  - Add **PSXObjectExporter** to DoorBlocker (no script needed)
  - The door script finds it by name and hides it when opened

### Switch
- Create a switch/lever mesh GameObject
- Add **PSXObjectExporter**, assign `switch` LuaFile
- Add **PSXInteractable** component
- Create a second GameObject named exactly **"SwitchTarget"**
  - Add **PSXObjectExporter** (no script needed)
  - The switch toggles this object's active state

### Spinner
- Create a decorative mesh (pillar, gem, etc.)
- Add **PSXObjectExporter**, assign `spinner` LuaFile
- Add **PSXInteractable** component (so player can start/stop the spin)

### Movable
- Create a box/crate mesh
- Add **PSXObjectExporter**, assign `movable` LuaFile
- Add **PSXInteractable** component (interact to select, then D-pad to move)

### Entity Scanner
- Create a terminal/pedestal mesh
- Add **PSXObjectExporter**, assign `entity_scanner` LuaFile
- Add **PSXInteractable** component

## Step 5: Create Trigger Boxes

Add **PSXTriggerBox** components to empty GameObjects. The scene script handles these by index:

| Trigger Index | Purpose | Placement |
|---------------|---------|-----------|
| 0 | Cutscene zone | Near a scenic viewpoint |
| 1 | Damage zone | In a hazard area (lava, spikes, etc.) |
| 2 | Scene transition portal | At a doorway/exit |
| 3 | Heal zone | Near a health pickup area |

Trigger indices are assigned in the order they appear in the scene hierarchy.

## Step 6: Create UI Canvases

In the SplashEdit UI editor, create two canvases:

### Canvas: "HUD"
| Element Name | Type | Purpose |
|-------------|------|---------|
| ScoreText | Text | Shows "Score: 0" |
| StatusText | Text | Shows status messages |
| HealthBar | Progress | Shows health 0-100 |

### Canvas: "Dialogue"
| Element Name | Type | Purpose |
|-------------|------|---------|
| DialogueText | Text | Shows NPC dialogue lines |

Set the Dialogue canvas to **initially hidden**.

## Step 7: Create Cutscenes

Create **PSXCutsceneClip** assets for:

| Cutscene Name | Type | Description |
|---------------|------|-------------|
| `ambient_spin` | Looping | Background ambient animation (object rotation, etc.) |
| `camera_flyover` | One-shot | Camera pan across the scene (Camera Position + Rotation tracks) |
| `door_open` | One-shot | Door opening animation (Object Position track) |
| `spin_loop` | Looping | Full 360-degree rotation for the spinner object (Object Rotation track) |

## Step 8: Audio Clips

Import or create placeholder audio clips named:
- `collect` - pickup sound
- `door_open` - door opening
- `switch_on` / `switch_off` - switch toggle sounds
- `heal` - healing sound

## Step 9: Build and Test

1. Open Splash Control Panel (Window > PSXSplash > Control Panel)
2. Click **Build and Run**
3. Watch the PSX Console for Debug.Log output from all scripts
4. Walk around and interact with objects to test each callback

## What Each Script Tests

| Script | Callbacks | API Namespaces |
|--------|-----------|----------------|
| scene.lua | onSceneCreationStart, onSceneCreationEnd, onTriggerEnter, onTriggerExit | Scene, Persist, UI, Audio, Controls, Cutscene, Timer, Debug, PSXMath, Vec3 |
| collectible.lua | onCreate, onDestroy, onEnable, onDisable, onCollideWithPlayer | Entity, Audio, Persist |
| door.lua | onCreate, onInteract | Entity, Audio, Controls, Cutscene |
| npc.lua | onCreate, onInteract, onButtonPress | Input, Controls, UI |
| switch.lua | onCreate, onInteract | Entity, Audio |
| spinner.lua | onCreate, onInteract, onCollideWithPlayer | Cutscene, Entity, Timer |
| movable.lua | onCreate, onInteract, onButtonPress | Entity, Vec3, Camera, Input |
| entity_scanner.lua | onInteract | Entity, Vec3 |

## Key Design Notes

- **No onUpdate anywhere.** All logic is event-driven. Rotation uses a looping cutscene.
- **No float literals.** PS1 Lua uses integer-only numbers. Use `1/2` instead of `0.5`, `1/4` instead of `0.25`, etc.
- **Scene globals.** `scene.lua` defines `addScore()`, `setStatus()`, `startDialogue()`, `advanceDialogue()`, `isInDialogue()`, `endDialogue()` as globals. Other scripts call these directly.