Skip to content

Commit 2f7a679

Browse files
ProspectorProspector
authored
Update README.md
1 parent ebbd73f commit 2f7a679

1 file changed

Lines changed: 218 additions & 23 deletions

File tree

‎README.md‎

Lines changed: 218 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,228 @@
1-
![Mod Menu](https://i.imgur.com/dMYWAjn.png)
1+
# Mod Menu
2+
![Screenshot of the Mods screen, showing a list of a few mods on the left side below a search bar and filters button, where Mod Menu is selected. On the right side of the screen, it shows more details about the mod, such as authors, a description, links, credits, and a button to configure the mod.](https://cdn.modrinth.com/data/mOgUt4GM/images/1b837be3f93c3e99e0ab70600698bd9f37723cec.png)
23

3-
Adds a screen for viewing a list of installed mods.
4-
* The menu is searchable and sortable, libraries can be hidden.
5-
* Client-side and API mods are marked with a special badge in the list.
6-
* When clicking a mod in the list, its homepage, issues link and description are displayed.
7-
* The mod details page also lets the user configure the mod, if available (can be disabled for modpacks via config).
4+
Mod Menu lets you view the mods you have installed and, if supported by the mod, enables quick and easy access to the mod's config screens.
85

9-
<h4 align="center">
10-
Mod Menu requires <a href="https://fabricmc.net/use/">Fabric Loader</a>
11-
</h4>
12-
<h4 align="center">
13-
Check out the <a href="https://discord.gg/jEGF5fb">Terraformers Discord Server</a> to chat about Mod Menu and other Fabric mods!
14-
</h4>
15-
<h4 align="center">
16-
Visit the <a href="https://github.com/TerraformersMC/ModMenu/wiki">Mod Menu Wiki</a> to learn more about the features
17-
</h4>
6+
Mod Menu also supports some more advanced features, such as translatable mod names and descriptions, support for [QuickText formatting](https://placeholders.pb4.eu/user/quicktext/) in mod descriptions thanks to [Patbox](https://ko-fi.com/patbox)'s [Text Placeholder API](https://modrinth.com/mod/placeholder-api), filters library mods out from regular mods, a mod update checker for mods hosted on Modrinth or that provide their own update sources, and deep configuration for all the features we provide.
187

19-
### Features
8+
### Supported Platforms
9+
Mod Menu is currently available for Fabric or Quilt on Minecraft: Java Edition 1.14 or newer.
2010

21-
![Screenshot of the Mods screen](https://camo.githubusercontent.com/3fb56ac264de3a3be29bf2da68f93d667cd773d8285c7b152f1ae8db2cfaffbb/68747470733a2f2f692e696d6775722e636f6d2f79794f6d564d322e706e67)
11+
## Developers
12+
Mod Menu includes a number of APIs for developers to improve how their mod appears in Mod Menu. These come in the form of language keys, JSON metadata, and even a Java API.
2213

23-
You can view the features more in-depth on the [Mod Menu wiki](https://github.com/TerraformersMC/ModMenu/wiki/API)
14+
### Translation API
15+
You can translate your mod's name, summary, and description all without touching any Java code. Simply add translation keys in the supported format to any language you'd like.
2416

25-
### Developers
17+
<details>
18+
<summary>Translation API Documentation</summary>
2619

27-
If you are a developer and would like to see what metadata Mod Menu will make use of, how to add Library or Client-side only badges to your mod, or how to make your Config screens accessible via Mod Menu, check out [the API documentation on the Mod Menu wiki](https://github.com/TerraformersMC/ModMenu/wiki/API)
20+
Here's an example of Mod Menu's translations into Pirate Speak. To create your own, simply replace `modmenu` at the end (***NOT*** the one in the beginning) of the translation key with your own mod ID, for example `modmenu.descriptionTranslation.traverse`.
2821

29-
### Translators
22+
`en_pt.json`
23+
```json
24+
"modmenu.nameTranslation.modmenu": "Menu o' mods!",
25+
"modmenu.descriptionTranslation.modmenu": "Menu o' mods ye installed matey!",
26+
"modmenu.summaryTranslation.modmenu": "Menu o' mods ye installed matey!"
27+
```
3028

31-
Mod Menu uses [Crowdin](https://crowdin.com/project/mod-menu), the same cloud-based localization management tool that Minecraft uses.
29+
> The summary translation is redundant here and does not need to be included because it's the same as the description, but it was included to show that you may translate the summary (a short, one-sentence description of the mod) separately from the description, even in English!
3230
33-
### Mod Menu is a mod for Fabric, and there are no plans to port this mod to Forge.
31+
</details>
32+
33+
34+
35+
### Fabric Metadata API (`fabric.mod.json`)
36+
There's a number of things you can add just with metadata in your `fabric.mod.json`.
37+
38+
All of these are added to a custom block in your `fabric.mod.json` for Mod Menu's metadata. Here's an example usage of many of the features this API provides:
39+
40+
`fabric.mod.json`
41+
```json
42+
"custom": {
43+
"modmenu": {
44+
"links": {
45+
"modmenu.discord": "https://discord.gg/jEGF5fb"
46+
},
47+
"badges": [ "library", "deprecated" ],
48+
"parent": {
49+
"id": "example-api",
50+
"name": "Example API",
51+
"description": "Modular example library",
52+
"icon": "assets/example-api-module-v1/parent_icon.png",
53+
"badges": [ "library" ]
54+
},
55+
"update_checker": true
56+
}
57+
}
58+
```
59+
60+
61+
<details>
62+
<summary>Fabric Metadata API Documentation</summary>
63+
64+
#### Badges (`"badges": [ ]`)
65+
While the `Client` badge is added automatically to mods set as client-side only (set `"environment": "client"` in `fabric.mod.json` to do this.), other badges such as the `Library` and `Deprecated` badges require definition here.
66+
67+
Supported values:
68+
- `library` - should be assigned to mods that are purely dependencies for other mods that should not be shown to the user by default unless they toggle them on.
69+
- `deprecated` - should be assigned to mods that exist purely for legacy reasons, such as an old API module or such.
70+
71+
Any others will be ignored, and Mod Menu does not support adding your own badges. You may open an issue [here](https://github.com/TerraformersMC/ModMenu/issues) if you have a compelling use case for a new badge.
72+
73+
#### Links (`"links": { }`)
74+
The `links` object allows mod authors to add custom hyperlinks to the end of their description. If you specify a `sources` contact in the official `fabric.mod.json` metadata, it will also be included in the links section.
75+
76+
Any key in the `links` object will be included in the links section, with the key being used as a translation key. For example, this:
77+
78+
`fabric.mod.json`
79+
```json
80+
"custom": {
81+
"modmenu": {
82+
"links": {
83+
"modmenu.discord": "https://discord.gg/jEGF5fb"
84+
}
85+
}
86+
}
87+
```
88+
will show as a link with the text "Discord", since "Discord" is the English translation of "modmenu.discord" provided by Mod Menu.
89+
90+
Mod Menu provides several default translations that can be used for links. A full list can be seen in Mod Menu's language file [here](https://github.com/TerraformersMC/ModMenu/blob/-/src/main/resources/assets/modmenu/lang/en_us.json). All default link translation keys take the form `modmenu.<type>`.
91+
92+
You can also provide your own translations if you would like to add custom links. Make sure to use ***your own namespace*** (as opposed to `modmenu`) for any custom keys.
93+
94+
#### Parents (`"parent": "mod_id" or { }`)
95+
<img align="right" width="400" src="https://i.imgur.com/ZutCprf.png">
96+
97+
Parents are used to display a mod as a child of another one. This is meant to be used for mods divided into different modules. The following element in a `fabric.mod.json` will define the mod as a child of the mod 'flamingo':
98+
99+
`fabric.mod.json`
100+
```json
101+
"custom": {
102+
"modmenu": {
103+
"parent": "flamingo"
104+
}
105+
}
106+
```
107+
108+
However, if you want to group mods under a parent, but the parent isn't an actual mod, you can do that too. In the example below, a mod is defining metadata for a parent. Make sure that this metadata is included in all of the children that use the fake/dummy parent. This can also be used as a fallback for an optional parent, it will be replace by the mod's real metadata if present.
109+
110+
111+
`fabric.mod.json`
112+
```json
113+
"custom": {
114+
"modmenu": {
115+
"parent": {
116+
"id": "this-mod-isnt-real",
117+
"name": "Fake Mod",
118+
"description": "Do cool stuff with this fake mod",
119+
"icon": "assets/real-mod/fake-mod-icon.png",
120+
"badges": [ "library" ]
121+
}
122+
}
123+
}
124+
```
125+
126+
Dummy parent mods only support the following metadata:
127+
- `id` (String)
128+
- `name` (String)
129+
- `description` (String)
130+
- `icon` (String)
131+
- `badges` (Array of Strings)
132+
133+
134+
#### Disable update checker (`"update_checker": false`)
135+
By default, Mod Menu's update checker will use the hash of your mod's jar to lookup the latest version on Modrinth. If it finds a matching project, it will check for the latest version that supports your mod loader and Minecraft version, and if it has a different hash from your existing file, it will prompt the user that there is an update available.
136+
137+
You can disable the update checker by setting `update_checker` to false in your Mod Menu metadata like so:
138+
139+
`fabric.mod.json`
140+
```json
141+
"custom": {
142+
"modmenu": {
143+
"update_checker": false
144+
}
145+
}
146+
```
147+
148+
</details>
149+
150+
151+
152+
### Java API
153+
To use the Java API, you'll need to add Mod Menu as a compile-time dependency in your gradle project. This won't make your mod require Mod Menu, but it'll be present in your environment for you to test with.
154+
155+
`build.gradle`
156+
```gradle
157+
// Add the Terraformers maven repo to your repositories block
158+
repositories {
159+
maven {
160+
name = "Terraformers"
161+
url = "https://maven.terraformersmc.com/"
162+
}
163+
}
164+
165+
// Add Mod Menu as a dependency in your environment
166+
dependencies {
167+
modImplementation("com.terraformersmc:modmenu:${project.modmenu_version}")
168+
}
169+
```
170+
Then, define the version of Mod Menu you're using in your `gradle.properties`. You can get the latest version number [here](https://modrinth.com/mod/modmenu/version/latest), but you may need a different version if you're not using the latest Minecraft version. See the [versions page](https://modrinth.com/mod/modmenu/versions) for a full list of versions.
171+
172+
`gradle.properties`
173+
```properties
174+
modmenu_version=VERSION_NUMBER_HERE
175+
```
176+
> If you don't want it in your environment for testing but still want to compile against Mod Menu for using the Java API, you can use `modCompileOnly` instead of `modImplementation` (this will work even if Mod Menu is not updated to the version of Minecraft you're running).
177+
178+
<details>
179+
<summary>Java API Documentation</summary>
180+
181+
### Getting Started
182+
To use the API, implement the ModMenuApi interface on a class and add that as an entry point of type "modmenu" in your `fabric.mod.json` like this:
183+
184+
`fabric.mod.json`
185+
```json
186+
"entrypoints": {
187+
"modmenu": [ "com.example.mod.ExampleModMenuApiImpl" ]
188+
}
189+
```
190+
191+
### Mod Config Screens
192+
Mods can provide a Screen factory to provide a custom config screen to open with the config button. Implement the `getModConfigScreenFactory` method in your API implementation to do this.
193+
194+
The intended use case for this is for mods to provide their own config screens. The mod id of the config screen is automagically determined by the source mod container that the entrypoint originated from.
195+
196+
### Provided Config Screens
197+
Mods can provide Screen factories to provide a custom config screens to open with the config buttons for other mods as well. Implement the `getProvidedConfigScreenFactories` method in your API implementation for this.
198+
199+
The intended use case for this is for a mod like Cloth Config to provide config screens for mods that use its API.
200+
201+
### Modpack Badges
202+
Mods can give other mods the `Modpack` badge by implementing the `attachModpackBadges` method, such as through the following:
203+
204+
```java
205+
@Override
206+
public void attachModpackBadges(Consumer<String> consumer) {
207+
consumer.accept("modmenu"); // Indicates that 'modmenu' is part of the modpack
208+
}
209+
```
210+
211+
Note that 'internal' mods such as Minecraft itself and the mod loader cannot be given the modpack badge, as they are not distributed within a typical modpack.
212+
213+
### Static Helper Methods
214+
`ModMenuApi` also offers a few helper methods for mods that want to work with Mod Menu better, like making their own Mods buttons.
215+
216+
#### Creating a Mods screen instance
217+
You can call this method to get an instance of the Mods screen:
218+
```java
219+
Screen createModsScreen(Screen previous)
220+
```
221+
222+
#### Creating a Mods button `Text`
223+
You can call this method to get the Text that would be displayed on a Mod Menu Mods button:
224+
```java
225+
Text createModsButtonText()
226+
```
227+
228+
</details>

0 commit comments

Comments
 (0)