Add docs, cleanup structure
This commit is contained in:
Michal Pikulski
154
docs/statue_minigame_primer.md
Normal file
154
docs/statue_minigame_primer.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# 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()`
|
||||
|
||||
@@ -1,164 +0,0 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user