modrinth / docs Goto Github PK

The Version dependencies model now has a file_name field, but it is undocumented.

Describe the bug

This page https://support.modrinth.com/en/articles/8802351-modrinth-modpack-format-mrpack skips over foundational concepts of your modpack, to the point I can't get started with it, let alone follow it.

Since I can't just download a modpack file from your website, I kept looking and found this page https://support.modrinth.com/en/articles/8802250-modpacks-on-modrinth which says that modpacks can be created via MultiMC, but does not list the steps to do so, nor link to them. Obviously, an internet search was unfruitful, as most of them are nowadays.

I am a dev and a sysadmin, please talk nerdy to me.

Steps to reproduce

1. Read docs.
2. Fail.

Expected behavior

Documentation that explains things, and provides a clear example.

A way to manually download a modpack to compare the documentation to reality and see which wins.

Additional context

Curseforge lets you download their modpacks from the website, and I was able to look at their pack format that way. I don't think it does what I want though. I have not installed their "app" because I think that's a terrible idea.

I am a dev and a sysadmin, please talk nerdy to me.

Describe the bug

There doesn't seem to be any API for organizations (Such as fetching projects or information about the organization).

Steps to reproduce

1. Go to https://docs.modrinth.com/api-spec
2. Look at the sidebar / search for organizations
3. Nothing related to organizations exist

Expected behavior

Requests to https://api.modrinth.com/v2/organization/<name|id> shouldn't return a 404

Additional context

No response

Describe the bug

The all_time and last_month fields for the response in the payouts endpoint are documented as being integers instead of numbers, while the examples, as well as the API itself, give non-integer values for these fields.

Steps to reproduce

1. Go to https://docs.modrinth.com/api-spec/#tag/users/operation/getPayoutHistory
2. Open the 200 dropdown

Expected behavior

all_time and last_month are documented as being numbers.

Additional context

It might also be helpful to specify that these values are expressed in USD.

Is your suggested enhancement related to a problem? Please describe.

No response

Describe the solution you'd like

Superpack is useful for installing modpacks in the Vanilla launcher. In the future, support for automatically installing the appropriate version of Fabric or Quilt is planned.

Describe alternatives you've considered

No response

Additional context

https://github.com/Gaming32/Superpack

Is your suggested enhancement related to a problem? Please describe.

No response

Describe the solution you'd like

No response

Describe alternatives you've considered

No response

Additional context

No response

Problem

Some modpack developers may want to add a lot of optional mods, and it would be helpful if we could put mods into categories

Solution

Add 2 optional tags for instances in the files array:\

• group
  • subgroups with group\subgroup
  • mods with the same group with be listed together under a category named the value of group
  • these groups could have a checkbox on them to enable all the mods within them and a drop down to collapse the group
• description
  • a place to explain what a mod does and why you would want it

Alternative solutions

Create Dummy ""Mods"" and use them as headers for mod groups

The rules for a valid slug are currently not documented on the docs anywhere as far as I can see, which I would recommend given their ability to have some non-standard/unexpected characters such as " in them.

Describe the bug
The Modrinth API spec says that trying to fetch a project with a non existent id or slug (say, api.modrinth.com/v2/project/thisisafakeslug) should return a JSON response such as the following:

{
  "error": "not_found",
  "description": "the requested route does not exist"
}

But it actually returns nothing.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://api.modrinth.com/v2/project/thisisafakeslug
2. See that no JSON is returned :(

Expected behavior
The JSON specified in the api spec would be returned.

Additional context
N/A

Except using some special methods(But this is illegal).

Copied from Discord:

Hey! I've talked about this a bit with Pros and Emma, but I wanna bring it up in a place more dev-associated folks can see - I'd like to propose Java agent support for the Modrinth pack format. Java agents are a huge help for all sorts of modding-related stuff, including pack updaters like PackWiz, instrumentation-based profilers, and even mod loaders like NilLoader. This would also be a huge help for more retro versions of Minecraft and retroforks, which frequently have to rely on javaagents to fix old bugs due to outdated and broken tooling.

I've been discussing NilLoader support on Modrinth for a little while and we've decided that at the moment it's just too niche to recommend supporting on its own, but having javaagent support in modrinth packs would enable a ton more options for keeping packs up to date and profiled for optimal performance, so I'd like to officially propose support!

Is your suggested enhancement related to a problem? Please describe.

Currently, there is no restriction for the path format of files in a mrpacks manifest.

In the docs there are examples for avoiding path traversal attacks: [A-Z]:/, [A-Z]:\, and /. From this I understand that the path format syntax is not restricted to a common type.

By not restricting the path format syntax, the interpretation of paths defined in mrpack files will slightly differ between tools because the developers can implement it on their own discretion.

In the long term, this will lead to a path format syntax that is restricted by the community, based on the paths interpretation of popular tooling.

Describe the solution you'd like

I suggest restricting the allowed path syntax to solely unix path syntax.

Describe alternatives you've considered

No response

Additional context

Related to #84

Conversation on Discord:
[15:44] Emma (triphora): It should probably only be /
[15:44] Emma (triphora): Could you make a docs issue?

The bug

In the API documentation for the "Create a version" route (POST /version), the dependencies field in the request body is not listed as required. However, the API treats it as a required field. (See the relevant labrinth source code, where you can compare the dependencies field to the actually-optional version_body field.)

In addition, the documentation mentions that the dependencies field can be set to null, but this is also contrary to how the API behaves.

API error message

Error while parsing JSON: missing field `dependencies` at line 1 column 240

To Reproduce

Verify that the documentation doesn't mark the dependencies property as required.

Sending a HTTP POST request to https://staging-api.modrinth.com/v2/version with an otherwise-valid payload that doesn't include the dependencies field. Verify that the API responds with an error.

Expected behavior

The documentation would mark the dependencies property as required, and it would not mention the possibility of it being null.

The documentation should also note that to create a version without dependencies, an empty array should be provided. Note that this is what the official frontend does when creating a version.

Notes

Geometrically has confirmed that the current API behaviour is indeed correct in a comment.

Is your suggested enhancement related to a problem? Please describe.

Hey!
I'm the maintainer of mc-modpack-kit which basically provides a template for creating modpacks, updating them and uploading them to e.g. Modrinth

Describe the solution you'd like

I would like to add a mention of my project in the "Creating Modpacks" docs.
Would this be possible?

Describe alternatives you've considered

No response

Additional context

The project is still in its early stages though!

Describe the bug

The page on the modrinth maven (https://docs.modrinth.com/docs/tutorials/maven/) currently recommends using gradle's exclusiveContent filter for adding the repository; it should be noted on that page that this does not work with forgegradle (MinecraftForge/ForgeGradle#925).

Steps to reproduce

No response

Expected behavior

No response

Additional context

No response

Is your feature request related to a problem? Please describe.

It's not uncommon for modpack authors to not know which projects they are allowed to include in their modpacks

Describe the solution you'd like

A page that lists common ways to know, including:

• A list of common licenses that allow it automatically
• Phrases to look out for on project pages
• If in doubt contact the author

Describe alternatives you've considered

The status quo

Additional context

(totally not weeks late)

the possible query parameters apparently are:
https://api.modrinth.com/updates/jei/forge_updates.json?neoforge=only
https://api.modrinth.com/updates/jei/forge_updates.json?neoforge=include

Problem

Optional mods could add new dependencies that are required for the base set of mods.
Including these dependencies even when the mod is not selected is a waste of space

Solution

Add 2 optional tags in the files array:

• hidden
  • boolean, true or false
• requires
  • an array of mod names
  • when a mod with this tag is enabled, so are the mods inside the requires array

Alternative Solutions

You could include all the API mods needed for optional mods by default, but that wastes space.

Prerequisite suggestions

#57

Problem

I am hosting a mod pack where you can choose between Phosphor or Starlight as a light engine optimizer.
If both are marked as optional, a user who is not paying too much attention may end up selecting both, which would be problematic, as they conflict with each other.

Solution

Add 1 optional tag to the files array:

• conflicts
  • a list of names of mods that conflict with this mod

Alternative Solutions

You could rely on modpack developers including a colossal warning message on the modpack page. But that feels very a curseforge solution.

Prerequisite suggestions

#57

For example, it would be nice to have a detailed guide as to why it's not wise to add multiple files to one version, or why Semver should be used.

Is your feature request related to a problem? Please describe.

I can't see any docs explicitly explaining rate limit. https://api.modrinth.com/ gives a documentation link https://modrinth.com/documentation but its a 404.

If I call curl "https://api.modrinth.com/api/v1/mod/wq6HaMZG" --include the headers include

x-ratelimit-limit: 200
x-ratelimit-remaining: 197
x-ratelimit-reset: 59

so it looks like anonymous usage is subject to some fairly restrictive rate limiting. Are you able to link to any docs about rate limits? I think if we were going to take on this integration we'd need to understand this constraint in more detail.

• badges/shields#7078 (comment)

Describe the solution you'd like

A documentation for rate limits

Describe alternatives you've considered

Sending private messages or pings to developers to get information about rate limits :)

Additional context

I'm requesting shields.io to add support for Modrinth.

• badges/shields#7078

Is your suggested enhancement related to a problem? Please describe.

no modrinth docs on modpacks

Describe the solution you'd like

add

Describe alternatives you've considered

No response

Additional context

https://github.com/orgs/modrinth/discussions/153#discussioncomment-6731538

Is your suggested enhancement related to a problem? Please describe.

BakaXL is a launcher targeting Chinese communities and isn't what most Modrinth users would use, so it doesn't make sence that it's above MultiMC and Prism Launcher on the Playing Modpacks documentation page and therefore is made look like the more desirable option.

Describe the solution you'd like

Move BakaXL to the end of the page.

Describe alternatives you've considered

No response

Additional context

No response

For a valid modpack, hashes must include at least a SHA1 hash for every file. This should be documented in https://docs.modrinth.com/docs/modpacks/format_definition/#hashes.

A field to add an Icon for Launchers to download instead of the default modrinth Logo, which Prism Launcher currently uses would be a nice addition.

Hi,
just a few days ago, I searched for documentation on the mrpack format and found this page in the docs. Yesterday, I noticed that the page got moved to the support site (link).

The support site is good. But I think that the documentation is better suited for technical pages. This gives the advantages of having them all in one place and being able to read them better due to features like syntax highlighting and navigation.

So my proposal is to move the following pages back to the documentation:

• Contributing to Modrinth
• Modpack Format
• Modrinth Maven Usage

Maybe there also needs to be some things done to make it easier, and I have not yet figured out how to actually get my local website "authenticated" when connected to a local backend.

1. Create a OAuth App at https://github.com/settings/apps
2. Homepage does not matter, callback =http://localhost:8000/v2/auth/callback
3. Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET according to the application you just created.
4. Start the backend cargo run
5. Open http://localhost:8000/v2/auth/init?url=http://localhost:1234 (the port at the end does not matter as long as it is not currently serving a website)
6. You get the authentication token in the Address bar ?code=gho_oA..... and can use that for local requests now.

The newest version of BakaXL has done with offline authentication features.

Now it won't allow users who haven't logged in with a genuine account to create an offline profile.

Moreover, BakaXL forces users to update to the newest version of itself, so there's no way to skip the authentication.

Like knossos with this PR, maybe add language support (docusaurus already have a feature for that).

If it's a good idea I can do that.

Describe the bug

When looking at the API docs, the sidebar menu will get cut off at the top after reloading the page and opening a dropdown menu on the side. I'm assuming this has to do with the sidebar having a scrollbar/overflow and the website not correctly shifting the start of the sidebar down.

The first image is how it looks when going to the docs directly for the first time, and the second image is after reloading and opening one of the dropdown menus (or entering a link with a section) in either order.

Steps to reproduce

1. Go to https://docs.modrinth.com/api-spec/
2. Click on the "Projects" dropdown menu on the sidebar
3. Refresh the webpage (sometimes, even this is unnecessary)

Expected behavior

The sidebar should not be covered up at the top.

Additional context

I am running a Chromium-based browser on Ubuntu 22.04.1 LTS.

Hey there! I'm working on a project which will be calling the Modrinth API for data, and I'm generating types, clients, etc. for calling the API using a spec-to-code generator.

I noticed that the OpenAPI spec for the facets parameter in /v2/search claims that the parameter can be present multiple times in the query, which is wrong. It appears to actually be describing what the string should deserialise to (an array of an array of strings) instead of what the parameter is on the query level (a string).

From the OpenAPI spec :

Query parameters can be primitive values, arrays and objects. OpenAPI 3.0 provides several ways to serialize objects and arrays in the query string.

Arrays can be serialized as:

• form – /products?color=blue,green,red or /products?color=blue&color=green, depending on the explode keyword
• spaceDelimited (same as collectionFormat: ssv in OpenAPI 2.0) – /products?color=blue%20green%20red
• pipeDelimited (same as collectionFormat: pipes in OpenAPI 2.0) – /products?color=blue|green|red

In this case, I believe the type of the parameter should just be string, since the API expects a string to be sent (which is a JSON-serialised array of array of string).

The parameter is defined in the spec here:
https://github.com/modrinth/docs/blob/master/static/openapi.yaml#L1080-L1089

Working: Passing a string which is a JSON-serialised array of arrays of strings:

https://api.modrinth.com/v2/search?facets=%5B%5B%22project_type%3Amod%22%5D%2C%5B%22versions%3A1.19%22%2C%22versions%3A1.19.1%22%5D%5D&index=downloads&limit=10

Not working: Passing facets multiple times – the expected behaviour for a parameter that's an array of strings (or an array of arrays of strings).

https://api.modrinth.com/v2/search?facets=project_type%3Amod&facets=versions%3A1.19&facets=versions%3A1.19.1&index=downloads&limit=10

Query deserialize error: duplicate field `facets`

Problem

A lot of my feature requests require references to other mods, there is no good way to point to another mod in the files array

Solution

Add 1 optional tag to the files array:\

• name
  • string value passing regex ^\w*$

Alternative Solutions

You could use SHA hashes, but those change version by version

Going off of https://learn.microsoft.com/en-us/dotnet/standard/io/file-path-formats the given warning on https://docs.modrinth.com/docs/modpacks/format_definition/#path that says to "make sure it doesn't contain .. or start with a drive name (i.e., [A-Z]:/, [A-Z]:\, and /).", If implemented at face value, would still result in multiple bad file paths being permitted such as:

• \Program Files\Custom Utilities\StringFinder.exe: A relative path from the root of the current drive.
• \\system07\C$\: The root directory of the C: drive on system07. (A network drive/resource)
• DOS device paths such as \\.\C:\Test\Foo.txt and \\?\C:\Test\Foo.txt
• Paths with ..\

This could be resolved by either adding \ as a disallowed starting character and adding ..\, or promoting normalization checks instead

I'm not sure if to put this on labrinth's repo or this repo, I'll just put it here.

It would be nice if there would be an OpenAPI (formerly Swagger) endpoint.

Definitely not copied from Wikipedia:

The OpenAPI Specification, previously known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. Previously part of the Swagger framework, it became a separate project in 2016, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation. Swagger and some other tools can generate code, documentation, and test cases given an interface file.

1. Request is a mulitpart/form-data request yes, but the "New Project" data is not submitted as a form, but as a JSON stored inside the form field data!
2. categories is required