Making resources optional

The optional resources system

Starting from 2.0, the mod now has a system of optional resources in place. It allows modpack devs to give the players the choice to install or not a particular resource.

The way it works is very simple, you have menus that represent a particular choice to give to the user (you can have multiple menus to ask for different kinds of mods for example). Those menus contain a few settings like the minimum and maximum amount of selectable items at once.

Those menus also contain options which represent a single button, or a choice in one particular menu if you prefer. Those options can have a list of resources to install based on their resource name (see below).

NOTE: For now, the optional resources system only works on the client side. This is because this system uses a custom GUI.

Adding a way to use it for servers is planned. In the mean time, the optional resources are just ignored when on the server side.

Marking a resource as optional

In order to use the optional resources system, you first have to mark your optional resources as optional. Doing so prevents those resources from automatically getting downloaded and adds them to the optional resources dictionary.

To mark them, just set the optional property of your resource to true (not case-sensitive) like so:

[My resource]
# ...

optional = true

Creating the optionals.packconfig file

Now that our resources are correctly marked as optional, we need to create the menus.

To get started, just create another packconfig file and rename it optionals.packconfig. Then, as usual, put it on the root of your pack.mcinstance.

Creating and configuring the menus

Just like resources, menus are also objects defined inside a packconfig file.

A menu is just a collection of settings and options that will get displayed to the user. Each menu is independant of the others. They will get displayed in the order they've been created inside the optionals.packconfig file.

To create your first menu, just create a packconfig object like so:

[My menu]   # The internal menu name. Isn't used for anything for now. Should be unique by convention.

title = Please choose an option below. # The menu's title, displayed at the top of the GUI.

# The amount of items you can select in the menu.
# Everything selected by the user will be downloaded once they click the "Confirm and continue" button.

# maxchoices defines the maximum amount of options the player can select at once. 
# If the user selects more options than this number, the first checked one will automatically be unchecked.

# minchoices defines the minimum amount of options.
# If the user seless less options than this number, the "Confirm and continue" button won't work and will be grayed out.

# If maxchoices is at 0 or below the minchoices value, there won't be any limit to how many options the user can select.
# If minchoices is at 0, the user will be able to validate and continue without checking any option.
maxchoices = 1
minchoices = 0

# ...

Adding options to your menu

Now that we created our first menu, you will quickly notice it is empty. This is because we didn't add any option yet.

An option is just a small object defined inside a menu. Each option represents a different choice the user can choose in the menu.

They're defined in a pretty unique way, to create your first option, add properties to your menu like such:

[My menu]
# ...

# The name of the option, displayed on the button to select it.
option1.name = My first option

# The description of the option, displayed below the button in gray.
option1.description = A one-line description about this particular option.

# Optional, defaults to false.
# Whether the option is selected by default.
# NOTE: This acts like the user selected it himself, and thus respects your maxchoices setting the same way.
option1.default = true

# The list of resources to download with this option, separated by commas.
# Just like other places in the format, commas can be included inside a resource's name with "\,".
# This uses the resource's name, that is inside brackets in the resources.packconfig file.
# Any undefined or non-optional resource will be ignored.
option1.resources = My resource, My second resource

To add a second option, just replace option1 with option2, a third option with option3 and so on...

Only options where the ID is in sequence with the previous ones will be added. So you can't have any hole in the sequence.

You can add as many options as you want, the mod will automatically split them into pages of 3 options if needed.