|
1 | | -Modrinth.Api |
2 | | -======= |
| 1 | + |
3 | 2 |
|
4 | | -## How to use Modrinth.Api in your project |
| 3 | +# Modrinth.Api |
5 | 4 |
|
6 | | -To use the `Modrinth.Api` in your project, follow these steps: |
| 5 | +A robust and easy-to-use C# library for interacting with the Modrinth API, enabling developers to search, filter, and download mods and projects effortlessly. |
7 | 6 |
|
8 | | -### Step 1: Import the necessary namespaces |
| 7 | +## Table of Contents |
| 8 | +- [Features](#features) |
| 9 | +- [Installation](#installation) |
| 10 | +- [Usage](#usage) |
| 11 | + - [Initializing the API](#initializing-the-api) |
| 12 | + - [Searching for Projects](#searching-for-projects) |
| 13 | + - [Retrieving and Downloading Mods](#retrieving-and-downloading-mods) |
| 14 | +- [Examples](#examples) |
| 15 | +- [Contributing](#contributing) |
| 16 | +- [License](#license) |
| 17 | + |
| 18 | +## Features |
| 19 | +- **Search and Filter**: Query Modrinth projects and mods with customizable filters (e.g., categories, versions, or search terms). |
| 20 | +- **Download Mods**: Download specific mod versions along with their dependencies. |
| 21 | +- **Asynchronous Operations**: Fully async/await compatible for efficient API calls. |
| 22 | +- **Type-Safe Models**: Strongly-typed DTOs for seamless integration with Modrinth's API responses. |
| 23 | + |
| 24 | +## Installation |
| 25 | +1. Add the `Modrinth.Api` NuGet package to your project: |
| 26 | + ```bash |
| 27 | + dotnet add package Modrinth.Api |
| 28 | + ``` |
| 29 | +2. Ensure your project targets .NET Framework or .NET Core compatible with the library. |
| 30 | + |
| 31 | +## Usage |
| 32 | + |
| 33 | +### Initializing the API |
| 34 | +To start using the `Modrinth.Api`, import the required namespaces and create an instance of `ModrinthApi`. |
9 | 35 |
|
10 | 36 | ```csharp |
11 | 37 | using Modrinth.Api; |
12 | 38 | using Modrinth.Api.Core.Filter; |
13 | 39 | using Modrinth.Api.Core.Projects; |
14 | 40 | using Modrinth.Api.Models.Dto; |
15 | 41 | using Modrinth.Api.Models.Projects; |
16 | | -``` |
17 | 42 |
|
18 | | -### Step 2: Create an instance of ModrinthApi |
19 | | - |
20 | | -```csharp |
21 | 43 | namespace YourNamespace |
22 | 44 | { |
23 | | - ModrinthApi api = new ModrinthApi(); |
| 45 | + public class Program |
| 46 | + { |
| 47 | + private readonly ModrinthApi _api = new ModrinthApi(); |
| 48 | + } |
24 | 49 | } |
25 | 50 | ``` |
26 | 51 |
|
27 | | -## How to Get a List of Projects |
28 | | - |
29 | | -To retrieve a list of projects from Modrinth using the `Modrinth.Api`, follow these steps: |
30 | | - |
31 | | -### Step 1: Set Up Project Filter |
| 52 | +### Searching for Projects |
| 53 | +Retrieve a list of projects by applying filters such as search queries, categories, or Minecraft versions. |
32 | 54 |
|
33 | 55 | ```csharp |
34 | | - |
35 | | -var projectFilter = new ProjectFilter() |
| 56 | +var projectFilter = new ProjectFilter |
36 | 57 | { |
37 | | - Query = "your_search_query", |
38 | | - Limit = 50, // Set the number of projects to retrieve |
| 58 | + Query = "fabric", |
| 59 | + Limit = 50, |
39 | 60 | Index = FaceIndexEnum.Follows, |
40 | 61 | Offset = 0 |
41 | 62 | }; |
42 | 63 |
|
| 64 | +// Add facets for finer control |
43 | 65 | projectFilter.AddFacet(ProjectFilterTypes.Category, "forge", LogicalOperator.Or); |
44 | | -projectFilter.AddFacet(ProjectFilterTypes.Version, "1.16.5", LogicalOperator.Or); |
45 | | - |
46 | | -``` |
| 66 | +projectFilter.AddFacet(ProjectFilterTypes.Version, "1.20.1", LogicalOperator.Or); |
47 | 67 |
|
48 | | -### Step 2: Retrieve Projects List |
49 | | - |
50 | | -```csharp |
| 68 | +// Fetch projects |
51 | 69 | var projects = await _api.Projects.FindAsync<SearchProjectResultDto>(projectFilter, CancellationToken.None); |
| 70 | +foreach (var project in projects.Hits) |
| 71 | +{ |
| 72 | + Console.WriteLine($"Project: {project.Title} (ID: {project.ProjectId})"); |
| 73 | +} |
52 | 74 | ``` |
53 | | -This code snippet demonstrates how to set up a project filter and retrieve a list of projects based on your search criteria. Adjust the filter parameters according to your specific requirements. |
54 | | - |
55 | | -## How to Get a List of Mods and Download a Version with Dependencies |
56 | | - |
57 | | -To interact with Modrinth and retrieve a list of mods while also downloading a specific version with all dependencies, follow these steps: |
58 | 75 |
|
59 | | -### Step 1: Set Up Mod Filter |
60 | | - |
61 | | -Before fetching the list of mods or downloading a version, you can set up a filter to narrow down the results. For example, you can filter mods by name, category, version, etc. |
| 76 | +### Retrieving and Downloading Mods |
| 77 | +Search for mods and download specific versions, including their dependencies, to a designated folder. |
62 | 78 |
|
63 | 79 | ```csharp |
64 | | -var modFilter = new ProjectModFilter() |
| 80 | +var modFilter = new ProjectModFilter |
65 | 81 | { |
66 | | - Query = "your_search_query", |
67 | | - Limit = 50, // Set the number of mods to retrieve |
| 82 | + Query = "sodium", |
| 83 | + Limit = 50, |
68 | 84 | Index = FaceIndexEnum.Follows, |
69 | 85 | Offset = 0 |
70 | 86 | }; |
71 | 87 |
|
72 | | -// Add facets to filter mods further (optional) |
73 | | -modFilter.AddFacet(ProjectFilterTypes.Category, "forge", LogicalOperator.Or); |
74 | | -modFilter.AddFacet(ProjectFilterTypes.Version, "1.16.5", LogicalOperator.Or); |
| 88 | +// Add facets to narrow down results |
| 89 | +modFilter.AddFacet(ProjectFilterTypes.Category, "optimization", LogicalOperator.Or); |
| 90 | +modFilter.AddFacet(ProjectFilterTypes.Version, "1.20.1", LogicalOperator.Or); |
75 | 91 |
|
76 | | -``` |
| 92 | +// Retrieve mod project |
| 93 | +var modProject = await _api.Mods.FindAsync<ModProject>("sodium", CancellationToken.None); |
| 94 | +if (modProject == null) return; |
77 | 95 |
|
78 | | -### Step 2: Download a Mod Version with Dependencies |
| 96 | +// Get all versions |
| 97 | +var versions = await modProject.GetVersionsAsync(CancellationToken.None); |
| 98 | +var latestVersion = versions.MaxBy(v => v.DatePublished); |
79 | 99 |
|
80 | | -```csharp |
81 | | -// Retrieve the ModProject instance for the mod |
82 | | -var modProject = await _api.Mods.FindAsync<ModProject?>(ProjectId, CancellationToken.None); |
| 100 | +if (latestVersion != null) |
| 101 | +{ |
| 102 | + var downloadFolder = Path.Combine(Environment.CurrentDirectory, "mods"); |
| 103 | + await _api.Mods.DownloadAsync(downloadFolder, latestVersion, true, CancellationToken.None); |
| 104 | + Console.WriteLine($"Downloaded {latestVersion.Name} to {downloadFolder}"); |
| 105 | +} |
| 106 | +``` |
83 | 107 |
|
84 | | -// Retrieve all versions for the mod |
85 | | -var versions = await modProject?.GetVersionsAsync(CancellationToken.None)!; |
| 108 | +## Examples |
| 109 | +Here’s a complete example combining project search and mod download: |
86 | 110 |
|
87 | | -// Assuming you want to download the latest version |
88 | | -var latestVersion = versions.MaxBy(c => c.DatePublished); |
| 111 | +```csharp |
| 112 | +using Modrinth.Api; |
| 113 | +using Modrinth.Api.Core.Filter; |
| 114 | +using Modrinth.Api.Core.Projects; |
| 115 | +using Modrinth.Api.Models.Dto; |
89 | 116 |
|
90 | | -if (latestVersion != null) |
| 117 | +namespace ModrinthExample |
91 | 118 | { |
92 | | - // Set up the folder where you want to download the mod |
93 | | - var folder = Path.Combine(Environment.CurrentDirectory, "mods"); |
94 | | - |
95 | | - // Download the mod with all dependencies |
96 | | - await _api.Mods.DownloadAsync(folder, latestVersion, true, CancellationToken.None); |
| 119 | + public class Program |
| 120 | + { |
| 121 | + public static async Task Main() |
| 122 | + { |
| 123 | + var api = new ModrinthApi(); |
| 124 | + |
| 125 | + // Search for projects |
| 126 | + var filter = new ProjectFilter |
| 127 | + { |
| 128 | + Query = "adventure", |
| 129 | + Limit = 10 |
| 130 | + }; |
| 131 | + var projects = await api.Projects.FindAsync<SearchProjectResultDto>(filter, CancellationToken.None); |
| 132 | + Console.WriteLine($"Found {projects.Hits.Count} projects."); |
| 133 | + |
| 134 | + // Download a mod |
| 135 | + var mod = await api.Mods.FindAsync<ModProject>("fabric-api", CancellationToken.None); |
| 136 | + if (mod != null) |
| 137 | + { |
| 138 | + var versions = await mod.GetVersionsAsync(CancellationToken.None); |
| 139 | + var latest = versions.MaxBy(v => v.DatePublished); |
| 140 | + if (latest != null) |
| 141 | + { |
| 142 | + await api.Mods.DownloadAsync("mods", latest, true, CancellationToken.None); |
| 143 | + Console.WriteLine("Downloaded Fabric API."); |
| 144 | + } |
| 145 | +} |
| 146 | + } |
| 147 | + } |
97 | 148 | } |
98 | 149 | ``` |
99 | 150 |
|
100 | | -This code snippet demonstrates how to set up a mod filter, retrieve a list of mods, and download a specific version with all dependencies. Customize the search query, filter options, and version selection according to your project's requirements. |
| 151 | +## Contributing |
| 152 | +Contributions are welcome! To contribute: |
| 153 | +1. Fork the repository. |
| 154 | +2. Create a feature branch (`git checkout -b feature/YourFeature`). |
| 155 | +3. Commit your changes (`git commit -m 'Add YourFeature'`). |
| 156 | +4. Push to the branch (`git push origin feature/YourFeature`). |
| 157 | +5. Open a Pull Request. |
| 158 | + |
| 159 | +Please ensure your code follows the project's coding standards and includes appropriate tests. |
| 160 | + |
| 161 | +## License |
| 162 | +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. |
0 commit comments