Init

content/gameplay-systems/memories.en.md

@@ -0,0 +1,225 @@
+---
+title: Memories
+type: docs
+weight: 4
+---
+
+The memories system provides persistent collectible discovery tracking for players.
+
+**Package:** `com.hypixel.hytale.builtin.adventure.memories`
+
+## Architecture
+
+```
+MemoriesPlugin
+├── Components
+│   └── PlayerMemories - Player's collected memories
+├── Memory Types
+│   ├── Memory - Base memory interface
+│   ├── MemoryProvider - Supplies memory instances
+│   └── NPCMemory/NPCMemoryProvider - NPC-based memories
+├── Storage
+│   └── RecordedMemories - Persistent storage (memories.json)
+├── UI
+│   ├── MemoriesWindow - Client window
+│   ├── MemoriesPage - UI page
+│   └── MemoriesPageSupplier
+├── Systems
+│   ├── PlayerAddedSystem - Initialize on player join
+│   ├── NPCMemory.GatherMemoriesSystem - Collect NPC memories
+│   └── TempleRespawnPlayersSystem - Temple respawn logic
+└── Commands
+    └── MemoriesCommand (capacity, clear, level, unlock)
+```
+
+## Core Concepts
+
+### Memory Interface
+
+Base interface for all memory types:
+
+```java
+public interface Memory {
+    // Codec for serialization
+    static final Codec<Memory> CODEC;
+}
+```
+
+### MemoryProvider
+
+Provides memory instances and configuration:
+
+```java
+public interface MemoryProvider<T extends Memory> {
+    String getId();
+    BuilderCodec<T> getCodec();
+    Map<String, Set<Memory>> getAllMemories();
+}
+```
+
+### NPCMemory
+
+Memories discovered from NPCs:
+
+```java
+public class NPCMemory implements Memory {
+    // Collected when player approaches NPC within radius
+}
+
+public class NPCMemoryProvider implements MemoryProvider<NPCMemory> {
+    public double getCollectionRadius();  // From config
+}
+```
+
+## Player Memories Component
+
+```java
+ComponentType<EntityStore, PlayerMemories> type =
+    MemoriesPlugin.get().getPlayerMemoriesComponentType();
+```
+
+The `PlayerMemories` component tracks:
+- Memories discovered by player
+- Memory capacity
+- Transfer to recorded memories
+
+## Recorded Memories
+
+World-persistent memory storage saved to `memories.json`:
+
+```java
+// Check if memory is recorded
+boolean hasMemory = MemoriesPlugin.get().hasRecordedMemory(memory);
+
+// Get all recorded memories
+Set<Memory> recorded = MemoriesPlugin.get().getRecordedMemories();
+
+// Record player's memories
+boolean recorded = MemoriesPlugin.get().recordPlayerMemories(playerMemories);
+
+// Clear all recorded memories
+MemoriesPlugin.get().clearRecordedMemories();
+
+// Record all possible memories
+MemoriesPlugin.get().recordAllMemories();
+```
+
+## Memory Levels
+
+Memory count determines player level:
+
+```java
+// Get current memories level
+int level = MemoriesPlugin.get().getMemoriesLevel(gameplayConfig);
+
+// Get memories needed for next level
+int needed = MemoriesPlugin.get().getMemoriesForNextLevel(gameplayConfig);
+```
+
+### Level Configuration
+
+```java
+public class MemoriesGameplayConfig {
+    int[] memoriesAmountPerLevel;  // Thresholds for each level
+}
+```
+
+## Interactions
+
+| Interaction | Type ID | Description |
+|-------------|---------|-------------|
+| `SetMemoriesCapacityInteraction` | `SetMemoriesCapacity` | Set player memory capacity |
+| `MemoriesConditionInteraction` | `MemoriesCondition` | Condition based on memories |
+
+## UI Integration
+
+### Memory Window
+
+Client-requestable window for viewing memories:
+
+```java
+Window.CLIENT_REQUESTABLE_WINDOW_TYPES.put(WindowType.Memories, MemoriesWindow::new);
+```
+
+### Custom UI Page
+
+```java
+OpenCustomUIInteraction.registerCustomPageSupplier(
+    this,
+    MemoriesPage.class,
+    "Memories",
+    new MemoriesPageSupplier()
+);
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/memories` | Base memories command |
+| `/memories capacity <amount>` | Set memory capacity |
+| `/memories clear` | Clear recorded memories |
+| `/memories level` | Show current level |
+| `/memories unlock` | Unlock all memories |
+
+## Configuration
+
+### Plugin Config
+
+```java
+public class MemoriesPluginConfig {
+    // Collection radius per memory type
+    Object2DoubleMap<String> collectionRadius;
+
+    public Object2DoubleMap<String> getCollectionRadius();
+}
+```
+
+### Gameplay Config
+
+```yaml
+# gameplay_config.json
+{
+  "Memories": {
+    "MemoriesAmountPerLevel": [5, 15, 30, 50, 75, 100]
+  }
+}
+```
+
+## Temple System
+
+The Forgotten Temple system for memory-related respawns:
+
+```java
+public class ForgottenTempleConfig {
+    // Temple configuration for respawn
+}
+
+public class TempleRespawnPlayersSystem {
+    // Handles respawn at temples
+}
+```
+
+## Events
+
+Player memories feature status is sent on join:
+
+```java
+// Sent to client when player joins
+playerConnection.writeNoCache(new UpdateMemoriesFeatureStatus(isFeatureUnlocked));
+```
+
+## API Usage
+
+```java
+MemoriesPlugin memories = MemoriesPlugin.get();
+
+// Get all available memories
+Map<String, Set<Memory>> allMemories = memories.getAllMemories();
+
+// Register custom memory provider
+memories.registerMemoryProvider(new CustomMemoryProvider());
+
+// Check player memories component
+PlayerMemories playerMemories = store.getComponent(ref, PlayerMemories.getComponentType());
+```