# 📘 BGAddressablesGetAssetAutoCached Toolkit

A utility set for Unity Addressables, designed to work with BGDatabase and PlayMaker. It provides an easy way to load and reuse assets via group-based caching, and manually release unused assets to free memory and avoid redundant loading.

---

## 🔧 Why Use Caching?

In Unity Addressables, loading the same asset multiple times increments its reference count. 
If you do not pair each Load method with a corresponding Release method, the reference count may never reach zero, 
preventing Addressables from unloading the asset when it is no longer needed. 
When using our cache, the usage counter will always be the number of cache groups, 
the asset is included to, allowing you to reduce the counter to zero with just a single Release method call per each group. 
If you forget to release unused assets, it may cause:

- Increased memory usage
- Slower loading times
- Performance issues or crashes

This toolkit introduces **group-based caching**, so you can reuse assets during a feature's lifecycle, and release them as a group when no longer needed.

---

## 📂 Script Overview

### 1. `BGAddressablesGetAssetAutoCached.cs`

- **Purpose**: Loads an Addressable asset from BGDatabase using entity data and caches it under a group name.
- **Caching**: If the asset is already cached, it returns the cached instance immediately.
- **Default Rule**: If `CacheGroup` is left blank, the asset will be cached under the `"Default"` group.

---

### 2. `BGAddressablesReleaseGroupCache.cs`

- **Purpose**: Releases all cached assets under a specified group name.
- **Usage**: Call this when a specific feature (e.g., Shop, Inventory) is closed.
- **Default Rule**: If `CacheGroup` is left blank, it releases assets under the `"Default"` group.

---

### 3. `BGAddressablesReleaseAllCache.cs`

- **Purpose**: Releases **all** cached assets across **all groups**.
- **Usage**: Ideal for returning to title screen, logging out, or resetting game state.
- **Warning**: This action clears **everything**, including `"Default"` and any other groups. It does not preserve any specific group.

---

### 4. `BGAddressablesAssetCache.cs` *(Internal Use)*

- **Purpose**: A static cache manager used by the above actions.
- **Functionality**:
  - `Register(group, key, asset)`
  - `TryGet(group, key)`
  - `Release(group, key)`
  - `ReleaseGroup(group)`
  - `ReleaseAll()`
- **Note**: Not intended for direct use unless you're writing custom logic.

---

## 🧪 Usage Example: Shop Feature

1. **Entering the Shop UI**   Use `BGAddressablesGetAssetAutoCached` to load and cache assets under the `"Shop"` group.

2. **Exiting the Shop UI**   Use `BGAddressablesReleaseGroupCache` to release all assets cached under `"Shop"`.

3. **Returning to Title Screen**   Use `BGAddressablesReleaseAllCache` to release all cached assets and free memory.

---

## 🧠 Example: Shared Asset Across Multiple Features

Imagine a UI sprite used in both **Shop** and **Inventory** screens.

- When entering the **Shop**, `BGAddressablesGetAssetAutoCached` loads and caches the sprite in the `"Shop"` group.
- When entering the **Inventory**, the same asset is requested again and cached under the `"Inventory"` group.

🔁 Even though it's the *same Addressables asset*, the toolkit tracks it separately in both groups.

### What happens when you release one group?

- If you release the `"Shop"` group using `BGAddressablesReleaseGroupCache`, the asset will **still remain in memory** under `"Inventory"`.
- The asset is **only fully released** when all groups that reference it have released it.

✅ This ensures shared assets won't be removed prematurely, and each feature manages its own usage safely.

---

## 📌 Cache Group Naming Tips

- Use a **separate cache group** per feature (e.g., `"Shop"`, `"Inventory"`, `"PopupUI"`)
- Avoid putting everything in `"Default"` to prevent accidental mass-release
- ⚠️ There is no built-in logic to preserve or protect any specific group (e.g., `"Persistent"`). All groups will be cleared by `ReleaseAll()`.

---

## 🛠 Dependencies

- Unity Addressables
- BGDatabase
- PlayMaker

---
