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
• Quick References
  • Adding Audio/Visual Feedback
  • Loading Decoration Data & Settings
  • Adding New Decorations
  • Changing UI Layout
  • Tweaking Behavior
  • Photo Saving/Loading
• Class Reference
  • Controllers
  • Drag & Drop
  • Data & Events
  • Display
  • Settings
• Common Tasks
• 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()