https://github.com/olivegamestudio/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.
https://github.com/olivegamestudio/pilgrimage
games inventory items player quests
Last synced: 4 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/olivegamestudio/pilgrimage
- Owner: olivegamestudio
- Created: 2025-08-09T19:48:34.000Z (10 months ago)
- Default Branch: develop
- Last Pushed: 2025-12-18T12:30:56.000Z (5 months ago)
- Last Synced: 2025-12-21T18:27:40.023Z (5 months ago)
- Topics: games, inventory, items, player, quests
- Language: C#
- Homepage:
- Size: 120 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Pilgrimage
Bring story-driven quests and loot loops to your game with one drop-in .NET library. Pilgrimage gives you a single facade (`IPilgrimage`), clean domain models, and optional persistence so you can ship questing and inventory fast without building the plumbing yourself.
## Targets & Install
- Targets: `net8.0` and `netstandard2.0` (compatible with Unity/Framework hosts).
- Install from NuGet:
```bash
dotnet add package Pilgrimage
```
## Dependency Injection
Register the library with the built-in DI container:
```csharp
using Microsoft.Extensions.DependencyInjection;
using Pilgrimage;
IServiceCollection services = new ServiceCollection();
services.AddPilgrimage();
IServiceProvider provider = services.BuildServiceProvider();
IPilgrimage pilgrimage = provider.GetRequiredService();
```
## Domain Models
- `Player` - the actor.
- `Quest` - quest definition and rewards.
- `QuestState` - the player-specific status of a quest (`Available`, `InProgress`, `Completed`).
- `Inventory` / `InventorySlot` - simple slot-and-capacity model with stacking support.
- `ItemRequirement` - describes required items for eligibility and rewards.
## IPilgrimage API
All interactions go through the facade:
- `ErrorOr StartQuest(Player player, int questId)`
- `ErrorOr CheckStartingRequirements(Player player, int questId)`
- `ErrorOr CompleteQuest(Player player, int questId)`
- `ErrorOr CheckCompletingRequirements(Player player, int questId)`
- `ErrorOr GetQuestDefinition(int questId)`
- `ErrorOr CanAddItem(Player player, int itemId, int quantity)`
- `ErrorOr AddItem(Player player, int itemId, int quantity)`
- `ErrorOr HasItem(Player player, int itemId, int quantity)`
## Usage Example
```csharp
PlayerProgress progress = new(new Dictionary());
Inventory inventory = new(new List(), capacity: 20);
Player player = new(id: 1, inventory, progress);
// Check if the player can start quest 10
var eligibility = pilgrimage.CheckStartingRequirements(player, questId: 10);
if (!eligibility.IsError)
{
pilgrimage.StartQuest(player, questId: 10);
}
// Add loot
var canAdd = pilgrimage.CanAddItem(player, itemId: 42, quantity: 3);
if (!canAdd.IsError)
{
pilgrimage.AddItem(player, itemId: 42, quantity: 3);
}
```
## License
MIT