Pilgrimage 4.0.0

Pilgrimage

A .NET 8 library for quest and inventory management systems in games and applications. This library provides a comprehensive framework for managing players, quests, inventories, and item systems.

Features

• Quest System: Create and manage quests with dependencies, repeatability, and rewards
• Inventory System: Flexible slot-based inventory with weight limits and item stacking
• Player Management: Unified player interface for quest and inventory operations
• Requirement System: Extensible system for quest prerequisites

Installation

Install the package via NuGet Package Manager:

dotnet add package Pilgrimage

Or via Package Manager Console:

Install-Package Pilgrimage

Key Concepts

Inventory Management

• Slot Containers: Each container has a fixed number of slots and optional weight limit
• Item Stacking: Items stack up to their MaxQuantityPerSlot value
• Weight System: Items can have weight, and containers can have weight limits
• Multiple Containers: Players can have multiple containers for organization

Quest Flow

1. Requirements Check: Quest dependencies must be met
2. Start Quest: Player receives up-front items (if any)
3. Complete Quest: Player receives reward items (if inventory has space)
4. Repeatability: Some quests can be repeated with cooldowns and limits

Extensibility

• RequirementBase: Create custom quest requirements by inheriting from this class
• Item System: Extend the item system by inheriting from Item or WorldItem

License

This project is licensed under the MIT License.

Quick Start

using Pilgrimage;

// Create a player
Player player = new();

// Add inventory space (16 slots, max 100 weight)
player.AddSlotContainer(16, 100);

// Create a quest system
Quests questSystem = new();

// Create and add a quest
Quest welcomeQuest = new()
{
    Id = 1
};
questSystem.AddQuest(welcomeQuest);

// Start the quest
if (questSystem.CanStartQuest(player, welcomeQuest, DateTime.Now))
{
    questSystem.StartQuest(player, welcomeQuest, DateTime.Now);
}

Core Components

Player

The Player class is the main interface for managing a player's inventory and quest progress.

Player player = new();

// Inventory management
player.AddSlotContainer(maxSlots: 20, maxWeight: 150);
player.AddItem(sword, quantity: 1);
bool hasPotion = player.HasItem(healthPotion, quantity: 5);

// Quest management
bool canStart = player.CanStartQuest(quest, DateTime.Now);
player.StartQuest(quest, DateTime.Now);
bool hasCompleted = player.HasCompletedQuest(quest);
bool canComplete = player.CanCompleteQuest(quest);
player.CompleteQuest(quest, DateTime.Now);

Inventory System

Creating Items

// Create a basic item
WorldItem sword = new()
{
    Id = 1,
    MaxQuantityPerSlot = 1,  // Only one sword per slot
    Weight = 5               // Each sword weighs 5 units
};

// Create a stackable item
WorldItem arrow = new()
{
    Id = 2,
    MaxQuantityPerSlot = 99, // Up to 99 arrows per slot
    Weight = 1               // Each arrow weighs 1 unit
};

Adding Inventory Space

Player player = new();

// Add a container with 16 slots and no weight limit
player.AddSlotContainer(16);

// Add a container with 8 slots and 50 weight limit
player.AddSlotContainer(8, 50);

// Add multiple containers for different purposes
player.AddSlotContainer(20);     // General inventory
player.AddSlotContainer(10, 25); // Equipment bag with weight limit

Managing Items

// Add items to inventory
bool success = player.AddItem(sword, 1);
player.AddItem(arrows, 50);

// Check if player has items
bool hasSword = player.HasItem(sword, 1);
bool hasEnoughArrows = player.HasItem(arrows, 30);

Quest System

Creating Quests

// Basic quest
Quest deliveryQuest = new()
{
    Id = 100
};

// Quest with rewards
Quest treasureHunt = new()
{
    Id = 101,
    Rewards = new List<RewardItem>
    {
        new() { WorldItem = goldCoin, Quantity = 50 },
        new() { WorldItem = magicRing, Quantity = 1 }
    }
};

// Repeatable quest
Quest dailyQuest = new()
{
    Id = 102,
    Repeatable = new QuestRepeatable
    {
        IsRepeatable = true,
        TimeBeforeRepeatable = TimeSpan.FromHours(24),
        MaxTimes = 10  // Can only be done 10 times total
    }
};

Quest Dependencies

Quest advancedQuest = new()
{
    Id = 200,
    Requirements = new List<RequirementBase>
    {
        new QuestRequirement { Id = 100 }, // Must complete quest 100 first
        new QuestRequirement { Id = 101 }  // Must complete quest 101 first
    }
};

Managing Quests

Quests questSystem = new();

// Add quests to the system
questSystem.AddQuest(deliveryQuest);
questSystem.AddQuest(treasureHunt);
questSystem.AddQuest(dailyQuest);

// Check if player can start a quest
if (questSystem.CanStartQuest(player, deliveryQuest, DateTime.Now))
{
    questSystem.StartQuest(player, deliveryQuest, DateTime.Now);
}

// Complete a quest
if (questSystem.CanCompleteQuest(player, deliveryQuest))
{
    bool completed = questSystem.CompleteQuest(player, deliveryQuest, DateTime.Now);
    if (completed)
    {
        Console.WriteLine("Quest completed! Rewards added to inventory.");
    }
    else
    {
        Console.WriteLine("Quest completion failed - not enough inventory space for rewards.");
    }
}

Advanced Quest Features

Up-Front Items

Up-front items are given to players when they start a quest (like quest items or tools):

Quest escortQuest = new()
{
    Id = 300,
    UpFrontItems = new List<UpFrontItem>
    {
        new() { WorldItem = questMap, Quantity = 1 },
        new() { WorldItem = specialKey, Quantity = 1 }
    }
};

Quest Repeatability

// Daily quest that can be repeated indefinitely
Quest dailyChallenge = new()
{
    Id = 400,
    Repeatable = new QuestRepeatable
    {
        IsRepeatable = true,
        TimeBeforeRepeatable = TimeSpan.FromDays(1)
    }
};

// Weekly quest with limited repetitions
Quest weeklyRaid = new()
{
    Id = 401,
    Repeatable = new QuestRepeatable
    {
        IsRepeatable = true,
        TimeBeforeRepeatable = TimeSpan.FromDays(7),
        MaxTimes = 4  // Can only be done 4 times total
    }
};

Complete Example

Here's a complete example showing how to set up a simple quest and inventory system:

using Pilgrimage;

// Create items
WorldItem sword = new() { Id = 1, MaxQuantityPerSlot = 1, Weight = 5 };
WorldItem potion = new() { Id = 2, MaxQuantityPerSlot = 10, Weight = 1 };
WorldItem gold = new() { Id = 3, MaxQuantityPerSlot = 100, Weight = 0 };

// Create a player with inventory
Player player = new();
player.AddSlotContainer(20, 100); // 20 slots, 100 weight limit

// Add some starting items
player.AddItem(sword, 1);
player.AddItem(potion, 5);

// Create quest system
Quests questSystem = new();

// Create a simple quest with rewards
Quest firstQuest = new()
{
    Id = 1,
    Rewards = new List<RewardItem>
    {
        new() { WorldItem = gold, Quantity = 100 },
        new() { WorldItem = potion, Quantity = 3 }
    }
};

// Create a follow-up quest that requires the first quest
Quest secondQuest = new()
{
    Id = 2,
    Requirements = new List<RequirementBase>
    {
        new QuestRequirement { Id = 1 } // Must complete quest 1 first
    },
    Rewards = new List<RewardItem>
    {
        new() { WorldItem = gold, Quantity = 250 }
    }
};

// Add quests to system
questSystem.AddQuest(firstQuest);
questSystem.AddQuest(secondQuest);

// Player completes first quest
if (questSystem.CanStartQuest(player, firstQuest, DateTime.Now))
{
    questSystem.StartQuest(player, firstQuest, DateTime.Now);
    
    // Simulate quest completion
    if (questSystem.CanCompleteQuest(player, firstQuest))
    {
        questSystem.CompleteQuest(player, firstQuest, DateTime.Now);
        Console.WriteLine("First quest completed!");
    }
}

// Player can now start second quest
if (questSystem.CanStartQuest(player, secondQuest, DateTime.Now))
{
    questSystem.StartQuest(player, secondQuest, DateTime.Now);
    Console.WriteLine("Second quest started!");
}

// Check inventory
Console.WriteLine($"Player has {(player.HasItem(gold, 100) ? "at least 100" : "less than 100")} gold");
Console.WriteLine($"Player has {(player.HasItem(potion, 8) ? "at least 8" : "less than 8")} potions");