AppleHillsProduction/docs/statue_minigame_primer.md

# Statue Decoration Minigame - Primer

A quick-start guide for designers and programmers working on the statue decoration minigame.

## Table of Contents
- [Overview](#overview)
- [Quick References](#quick-references)
  - [Adding Audio/Visual Feedback](#adding-audiovisual-feedback)
  - [Loading Decoration Data & Settings](#loading-decoration-data--settings)
  - [Adding New Decorations](#adding-new-decorations)
  - [Changing UI Layout](#changing-ui-layout)
  - [Tweaking Behavior](#tweaking-behavior)
  - [Photo Saving/Loading](#photo-savingloading)
- [Class Reference](#class-reference)
  - [Controllers](#controllers)
  - [Drag & Drop](#drag--drop)
  - [Data & Events](#data--events)
  - [Display](#display)
  - [Settings](#settings)
- [Common Tasks](#common-tasks)
- [Known TODOs](#known-todos)

## Overview
Players drag sticker decorations from a menu onto a statue, decorate it however they like, and take photos. Photos are saved to a gallery with decoration metadata so the statue can be restored in the town map miniature.

## Quick References

### Adding Audio/Visual Feedback
**Location:** `DecorationEventsManager.cs` in `Events/`  
All decoration interactions broadcast events (tap, drag start, drag end, place, etc.). Subscribe to events or edit the stub handler methods to add your SFX/VFX. Just add a `DecorationEventsManager` component to the scene.

### Loading Decoration Data & Settings
**Location:** `DecorationDataManager.cs` in `Controllers/`  
This singleton loads settings from GameManager, then loads all decoration sprites via Addressables. Everything happens automatically on scene start. Use `DecorationDataManager.WhenReady(() => { ... })` to wait for data before accessing.

### Adding New Decorations
**Location:** Create a `DecorationData` ScriptableObject in Unity  
Set the sprite, ID, and name. Add it to the Addressables group specified in `StatueDressupSettings`. It'll appear in the menu automatically.

### Changing UI Layout
**Location:** `StatueDressupMinigame` scene  
- Menu grid: `DecorationMenuController` → `ItemsContainer`
- Statue area: `StatueDecorationController` → `StatueImage` and `DecorationsParent`
- Photo gallery: `StatuePhotoGalleryController` → Grid and pagination UI

### Tweaking Behavior
**Location:** `StatueDressupSettings` ScriptableObject  
Contains all tunable values: animation durations, menu items per page, gallery settings, drag thresholds, etc.

### Photo Saving/Loading
**Location:** `StatueDecorationController.cs` - `TakePhoto()` method  
Photos are captured with metadata (decoration positions, scales, IDs). Use `PhotoManager` for save/load operations. Metadata is read by `StatueDecorationLoader` to restore decorations on the town map.

---

## Class Reference

### Controllers

**`DecorationDataManager`**  
- **What it does:** Loads settings and all decoration data from Addressables. Single source of truth for both.
- **When you might need it:** Accessing decoration sprites/data, checking if a decoration ID exists, waiting for data to be ready.

**`StatueDecorationController`**  
- **What it does:** Main minigame controller - manages decoration placement, photo capture, and save/load of decoration state.
- **When you might need it:** Taking photos, getting/setting decoration placements, loading saved decorations, accessing statue UI references.

**`DecorationMenuController`**  
- **What it does:** Manages the scrollable decoration picker menu with pagination and spawns draggable instances.
- **When you might need it:** Changing menu behavior, adding categories/filters, modifying how decorations are displayed.

**`StatuePhotoGalleryController`**  
- **What it does:** Displays saved photos in a paginated grid with thumbnail caching and enlarged preview.
- **When you might need it:** Modifying gallery UI, changing thumbnail behavior, adding photo delete/share functionality.

---

### Drag & Drop

**`DecorationDraggableInstance`**  
- **What it does:** The actual draggable decoration instance that follows the cursor and can be placed on the statue.
- **When you might need it:** Changing drag behavior, adding visual effects during drag, modifying placement validation.

**`DecorationGridIcon`**  
- **What it does:** Static menu icon that spawns a draggable instance when clicked/dragged.
- **When you might need it:** Adding icon animations, tooltips, or preview functionality to menu items.

**`DecorationDragContext`**  
- **What it does:** Data container passed to draggable instances with all references and callbacks needed for dragging.
- **When you might need it:** Adding new data that draggables need during their lifecycle.

---

### Data & Events

**`DecorationData`** (ScriptableObject)  
- **What it does:** Defines a single decoration (sprite, ID, name, authored size).
- **When you might need it:** Creating new decorations or querying decoration properties.

**`DecorationPlacement`**  
- **What it does:** Serializable data for a placed decoration (position, scale, rotation, sorting order).
- **When you might need it:** Saving/loading decoration state, modifying what gets persisted.

**`DecorationMetadata`**  
- **What it does:** Complete metadata for all decorations on a photo (list of placements + coordinate system type).
- **When you might need it:** Working with photo save/load system, adding new metadata fields.

**`DecorationEventData`**  
- **What it does:** Event payload containing decoration, instance GameObject, position, and context flags.
- **When you might need it:** Handling decoration events for SFX/VFX, adding new event data fields.

**`DecorationEventsManager`**  
- **What it does:** Broadcasts and handles all decoration interaction events (tap, drag, place, etc.).
- **When you might need it:** Playing sounds/effects in response to decoration interactions, adding telemetry.

---

### Display

**`StatueDecorationLoader`**  
- **What it does:** Loads saved decoration metadata and spawns decorations on a statue (used in town map).
- **When you might need it:** Displaying decorations outside the minigame, fixing coordinate conversion bugs.

---

### Settings

**`StatueDressupSettings`** (ScriptableObject in `Core/Settings`)  
- **What it does:** All configuration values for the minigame (durations, counts, labels, thresholds).
- **When you might need it:** Tuning any minigame behavior without touching code.

**`StatueDressupConstants`**  
- **What it does:** Fallback constant values if settings are missing.
- **When you might need it:** Setting default values or adding new configurable parameters.

---

## Common Tasks

**Add a new decoration:**  
Create `DecorationData` ScriptableObject → Set sprite/ID → Add to Addressables group

**Change drag feel:**  
Edit `StatueDressupSettings` → Adjust `DragSnapThreshold` or animation durations

**Add sound to decoration tap:**  
Edit `DecorationEventsManager.HandleDecorationTappedInGrid()` → Play your audio clip

**Change menu layout:**  
Edit `StatueDressupSettings` → Adjust `ItemsPerPage` or edit menu prefab

**Debug save/load:**  
Check `PhotoManager.SavePhoto()` and `StatueDecorationLoader.LoadAndDisplayDecorations()`