journal-system.md

title	aliases	tags	created	updated
Journal System	Game Journal Event Logging System Action History	core-system logging state-management ui narrative	2024-12-28	2024-12-28

Journal System

Overview

The journal system provides automatic logging of game events, character interactions, and player actions.

Purpose

The Journal System documentation aims to:

• Provide technical implementation details for developers
• Document journal entry types and management
• Serve as a reference for journal-related components
• Maintain consistency across system integrations

Journal System

Overview

The journal system provides automatic logging of game events, character interactions, and player actions while supporting entry creation and organization. It integrates closely with both the [[../core-systems/ai-integration|AI System]] and [[../core-systems/combat-system|Combat System]].

Technical Implementation

Core Types

interface JournalEntry {
  type: 'narrative' | 'combat' | 'inventory' | 'quest';
  timestamp: number;
  content: string;
  narrativeSummary?: string;
}

interface CombatJournalEntry extends JournalEntry {
  type: 'combat';
  combatants: {
    player: string;
    opponent: string;
  };
  outcome: 'victory' | 'defeat' | 'escape' | 'truce';
}

interface InventoryJournalEntry extends JournalEntry {
  type: 'inventory';
  items: {
    acquired: string[];
    removed: string[];
  };
}

Entry Management

The JournalManager class provides core functionality for managing journal entries:

• Narrative entry creation with AI-generated summaries
• Combat result logging with outcome tracking
• Inventory change recording
• Entry filtering and search capabilities

For current enhancements, see [[../features/_current/journal-enhancements|Journal Enhancements]].

Core Components

JournalViewer Component

• Displays chronological entries
• Shows narrative summaries
• Includes combat results
• Maintains formatting
• Implements virtualized scrolling
• Handles different entry types
• Optimized for large journal lists

For UI details, see [[../features/_current/narrative-formatting|Narrative Formatting]].

Entry Types

1. Narrative Entries

   • Story progression
   • Character interactions
   • World events
   • Player decisions

2. Combat Entries

   • Battle outcomes
   • Damage reports
   • Tactical decisions
   • Combat statistics

3. Inventory Entries

   • Item acquisitions
   • Equipment usage
   • Resource management
   • Inventory changes

4. Quest Entries

   • Mission updates
   • Objective tracking
   • Progress markers
   • Completion status

Integration Points

AI System Integration

• Automatic narrative summary generation
• Context-aware entry creation
• Theme-appropriate formatting
• Event significance detection

For AI details, see [[../core-systems/ai-integration|AI Integration]] and [[../ai/prompt-engineering/storytelling|Storytelling Prompts]].

Combat System Integration

• Automatic combat logging
• Wound and damage tracking
• Battle outcome recording
• Statistical tracking

For combat details, see [[../core-systems/combat-system|Combat System]] and [[../boot-hill-rules/combat-rules|Combat Rules]].

State Management

• Automatic state persistence
• Entry versioning
• Data integrity checks
• Recovery mechanisms

For state management details, see [[../core-systems/state-management|State Management]].

Inventory Integration

• Automatic item tracking
• Equipment changes
• Resource management
• Trade records

For inventory details, see [[../features/_current/inventory-interactions|Inventory System]].

Features

Search and Filtering

interface JournalFilter {
  type?: 'narrative' | 'combat' | 'inventory' | 'quest';
  startDate?: number;
  endDate?: number;
  searchText?: string;
}

Entry Processing

• Content cleaning
• Metadata extraction
• Summary generation
• Format standardization

Performance Considerations

Optimization Techniques

• Virtualized scrolling for large lists
• Memoized entry rendering
• Efficient state updates
• Debounced search operations

Data Management

• Entry batching
• Lazy loading
• Cache management
• Storage optimization

Error Handling

Recovery Strategies

• Entry validation
• State restoration
• Corruption detection
• Backup mechanisms

Future Enhancements

1. Enhanced search capabilities
2. Advanced formatting options
3. Media attachments
4. Export functionality
5. Timeline visualization
6. Character relationship tracking
7. Quest progress visualization
8. Custom entry templates

For planned features, see [[../planning/roadmap|Development Roadmap]].

Related Documentation

• [[../features/_current/journal-enhancements|Journal Enhancements]]
• [[../architecture/state-management|State Management Architecture]]
• [[../technical-guides/testing|Testing Guide]]
• [[../boot-hill-rules/game-overview|Game Rules Overview]]