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

title, type, weight

title	type	weight
Memories	docs	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:

public interface Memory {
    // Codec for serialization
    static final Codec<Memory> CODEC;
}

MemoryProvider

Provides memory instances and configuration:

public interface MemoryProvider<T extends Memory> {
    String getId();
    BuilderCodec<T> getCodec();
    Map<String, Set<Memory>> getAllMemories();
}

NPCMemory

Memories discovered from NPCs:

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

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:

// 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:

// Get current memories level
int level = MemoriesPlugin.get().getMemoriesLevel(gameplayConfig);

// Get memories needed for next level
int needed = MemoriesPlugin.get().getMemoriesForNextLevel(gameplayConfig);

Level Configuration

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:

Window.CLIENT_REQUESTABLE_WINDOW_TYPES.put(WindowType.Memories, MemoriesWindow::new);

Custom UI Page

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

public class MemoriesPluginConfig {
    // Collection radius per memory type
    Object2DoubleMap<String> collectionRadius;

    public Object2DoubleMap<String> getCollectionRadius();
}

Gameplay Config

# gameplay_config.json
{
  "Memories": {
    "MemoriesAmountPerLevel": [5, 15, 30, 50, 75, 100]
  }
}

Temple System

The Forgotten Temple system for memory-related respawns:

public class ForgottenTempleConfig {
    // Temple configuration for respawn
}

public class TempleRespawnPlayersSystem {
    // Handles respawn at temples
}

Events

Player memories feature status is sent on join:

// Sent to client when player joins
playerConnection.writeNoCache(new UpdateMemoriesFeatureStatus(isFeatureUnlocked));

API Usage

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