AppleHillsProduction/docs/statue_photo_gallery_setup.md

Photo Gallery Scene Setup Guide

Current Scene Status

✅ MainCanvas exists
✅ StatueDecorationController exists
✅ PhotoCaptureTestController exists (testing only)

---

Required Scene Setup

1. Create UIPage Wrappers

PlayAreaPage

1. Create empty GameObject under MainCanvas → name: PlayAreaPage
2. Add component: PlayAreaPage.cs
3. Move existing decoration UI as children under PlayAreaPage:
   • Decoration menu
   • Take photo button
   • Any other play area UI

PhotoGalleryPage

1. Create empty GameObject under MainCanvas → name: PhotoGalleryPage
2. Add component: PhotoGalleryPage.cs
3. Set initially inactive (will be shown when opened)

---

2. Setup Photo Gallery UI (under PhotoGalleryPage)

PhotoGalleryPage
├── GalleryController (GameObject)
│   └── StatuePhotoGalleryController.cs
├── GridContainer (GameObject with GridLayoutGroup)
├── EnlargedContainer (GameObject - top layer)
├── Backdrop (UI Image - dark/black, alpha 0.8)
├── PageStatusText (UI Text - shows "Page X/Y")
└── Navigation
    ├── PreviousPageButton (UI Button - "< Prev")
    └── NextPageButton (UI Button - "Next >")

Components to assign on StatuePhotoGalleryController:

• gridContainer → GridContainer transform
• gridItemPrefab → Create prefab with PhotoGridItem.cs + UI Image
• enlargedContainer → EnlargedContainer transform
• backdrop → Backdrop GameObject
• enlargedPreviewPrefab → Same as gridItemPrefab (or leave null to clone item)
• previousPageButton → Previous page button
• nextPageButton → Next page button
• pageStatusText → Optional status text showing page info

GridLayoutGroup Settings (on GridContainer):

• Cell Size: e.g., 200x200
• Spacing: e.g., 10x10
• Constraint: Fixed Column Count (3-4 columns recommended)
• Child Alignment: Upper Left (or as preferred)

---

3. Create PhotoGridItem Prefab

1. Create UI → Image in scene
2. Add PhotoGridItem.cs component
3. Assign thumbnailImage → the Image component itself
4. Optional: Add loading indicator child (simple spinner/text)
5. Drag to Prefabs folder → name: PhotoGridItem
6. Delete from scene

---

4. Update StatueDecorationController

Assign in Inspector:

• playAreaPage → PlayAreaPage GameObject
• photoGalleryPage → PhotoGalleryPage GameObject
• openGalleryButton → Create button in PlayAreaPage UI, assign here
• photoArea → RectTransform defining capture area (statue + decorations)
• takePhotoButton → Existing button (uncomment line 97 in code when ready)

---

5. Create Gallery Open Button

1. Add Button in PlayAreaPage UI → name: "OpenGalleryButton"
2. Button Text: "📷 Gallery" or "View Photos"
3. Assign to StatueDecorationController's openGalleryButton field

---

6. Page Navigation (PhotoGalleryPage)

1. Create two buttons for Previous/Next page
2. Buttons will be auto-wired by StatuePhotoGalleryController
3. Controller auto-disables buttons when at first/last page
4. Grid clears and reloads on each page change

---

Key Features

✅ Button-Based Pagination

• Previous/Next buttons navigate pages
• Grid clears completely and shows only current page
• Buttons auto-disable at boundaries (first/last page)
• Status text shows "Page X/Y (total photos)"

✅ Grid Clearing

• Grid is cleared on initialization
• Grid clears when switching pages
• Prevents leftover items from scene setup

✅ Enlarge System

• Click photo → spawns preview clone, animates to center
• Click again → shrinks back, destroys preview
• Original grid items never move
• Backdrop blocks grid interaction

---

Testing Checklist

Photo Capture (Already Working)

• ✅ PhotoCaptureTestController captures and saves photos
• ✅ Photos saved to Application.persistentDataPath/StatuePhotos/

Gallery Integration (New Setup)

1. Play scene
2. Click "Open Gallery" button → Gallery page shows
3. First page of photos loads in grid
4. Click "Next" → Grid clears, next page loads
5. Click "Previous" → Grid clears, previous page loads
6. Click photo → Enlarges to center with backdrop
7. Click enlarged photo → Shrinks back to grid
8. Back button → Returns to play area

---

Quick Setup Time

• PlayAreaPage wrapper: 2 minutes
• PhotoGalleryPage structure: 5 minutes
• PhotoGridItem prefab: 3 minutes
• Wire references: 5 minutes

Total: ~15 minutes

---

Configuration Variables

Set these on StatuePhotoGalleryController:

• itemsPerPage: 20 (photos per page)
• thumbnailSize: 256 (pixels)
• maxCachedThumbnails: 50 (LRU cache)
• enlargedScale: 2.5 (zoom amount)
• animationDuration: 0.3s

---

Cleanup (Optional)

Once gallery works, you can:

• Remove PhotoCaptureTestController GameObject
• Keep for quick testing if preferred