Documentation/content/gameplay-systems/memories.en.md

---
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());
```