Modpack Guide

Modpack Guide: Overview and Getting Started

Home › Modpack Developers › Overview and Getting Started

This page is the main starting point for modpack developers.

Use it to do three things:

1. Choose an entry point: JSON or KubeJS
2. Understand which groups players can edit and which become read-only
3. Know where to look when group behavior is not what you expected

Related pages:

• JSON Guide — JSON format and full examples
• KubeJS Guide — KubeJS API, compile / fallback behavior, and full examples

---

When to Read This Page

• You are not sure whether to use JSON or KubeJS
• You want the model first, before you start copying examples
• You are troubleshooting read-only groups, overrides, missing groups, or unexpected members

Quick Decision

If you only need the short version:

• Use JSON when you want clear rules, easy reviews, and long-term maintainability
• Use KubeJS when you want group rules to live next to existing scripts
• For complex nested logic that still needs to stay readable, JSON is usually the better choice
• If you are unsure, start with JSON and only switch to KubeJS when script integration is the real requirement

Need	Recommended
Stable maintenance for fixed groups	JSON
Keep rules with existing KubeJS scripts	KubeJS
Heavy AND / NOT / nested logic	JSON
Reuse KubeJS ingredient mental model	KubeJS
Make rules easy for others to read	JSON

Core Concepts

1. All entry points converge on the same filter model

The core model supports these nodes:

• Any
• All
• Not
• Id
• Tag
• Namespace
• ExactStack
• HasComponent

These nodes are not just data shapes. They also affect:

• whether the in-game editor can edit the group
• how rule summaries are displayed
• whether KubeJS can compile the rule into a structured filter
• whether the rule falls back to lowering

Keep these two points in mind:

• JSON, KubeJS, and the Java API all describe the same rule model
• The main differences between entry points are readability, maintainability, and editability

2. The player editor is not a full rule editor

The in-game editor only supports a flat, low-risk, easy-to-understand subset.

If a group uses these structures, players can usually view the summary but not fully edit the rule:

• All
• Not
• Namespace
• HasComponent
• nested composite structures

That is expected behavior, not a bug.

Limits and Boundaries

• JSON files live at config/collapsiblegroups/groups/*.json
• JSON rules must use filter
• ExactStack only supports item
• HasComponent only supports item; groups that use it are read-only in the player editor
• The player editor is usually read-only for All, Not, Namespace, HasComponent, and nested structures
• item KubeJS filters are more expressive than fluid / generic filters
• JS functions are not supported for generic types

In practice:

• The more advanced the logic is, the more JSON tends to be the right fit
• If players will see a group that uses advanced structures, say clearly that the group is intentionally read-only
• Keep fluid / generic rules conservative

---

Behavior and Priority

Start with these two facts:

• User JSON groups override built-in default groups with the same ID
• During matching, JSON groups are checked before KubeJS groups

The more useful rule of thumb is this:

• If an ingredient is already consumed by an earlier visible group, later groups may no longer match it
• This is one of the first things to check when a group ends up with fewer members than expected

Why the Player Editor Becomes Read-Only

The reason is straightforward: the player editor is designed for flat, easy-to-understand groups.

Once a JSON or KubeJS group uses advanced structures, players can usually view the summary but cannot fully maintain that rule in the GUI.

If your pack relies heavily on these structures, say so explicitly in your documentation.

---

Troubleshooting

A group does not appear

Check in this order:

1. JEI actually has at least 2 visible members at the moment
2. Those members were not already matched by earlier groups
3. The JSON or KubeJS rule does not contain a typo
4. If this is KubeJS, whether the rule is compile-based or fallback-based

Group members are not what you expected

First decide whether you are using:

• a clear structured filter
• or runtime predicate / fallback lowering

If it is the latter, check these first:

• what JEI is actually showing at that moment
• whether other scripts removed some entries first
• whether some ingredients were never exposed by the viewer in the first place

A player reports that a group cannot be edited

Check whether the group uses advanced structures. If it does, read-only is usually expected.

---

Recommendations

• Use JSON as rule structure becomes more complex
• On the item side, prefer structured rules over JS predicates whenever possible
• For fluid / generic, stay with exact, tag, namespace, and list patterns
• Keep every groupId namespaced
• Prefer one group per file, or one logical family per script, over giant mixed files
• If a group is intentionally read-only for players, document that as a design choice

Next Step

• If you already chose data files, go to JSON Guide
• If you are already in KubeJS and want rules to live with scripts, go to KubeJS Guide
• If you are only troubleshooting one broken group, return to the sections on priority, read-only behavior, and troubleshooting

---

Continue reading:

• JSON Guide
• KubeJS Guide