Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/crafttweaker.md
Original file line number Diff line number Diff line change
Expand Up @@ -1005,7 +1005,7 @@ block using it is created.
## Creative tabs

Scripts can make creative tabs, and change the tabs that `mmdlib/creative_tab/`
JSON files declare (see [creative tabs](creative-tabs.md) for the file format).
XML or JSON files declare (see [creative tabs](creative-tabs.md) for the file formats).

```zenscript
#loader mmdlib
Expand All @@ -1026,14 +1026,13 @@ workshop.build();
```

`new CreativeTabBuilder("tools")` starts the tab `mmdlib:tools`; other namespaces
are rejected, as for materials. A name a JSON file already declares is rejected
are rejected, as for materials. A name a file already declares is rejected
too: change that tab with `edit` instead.

`CreativeTabBuilder.edit(id)` starts from the tab a JSON file declares, in any
`CreativeTabBuilder.edit(id)` starts from the tab a file declares, in any
namespace, with all its settings and contents. Building it replaces the file's
version, so the changed tab is the one registered. A tab in another mod's namespace
is registered by that mod; the change applies when it registers its tabs from
`MMDLib.creativeTabs()`, as [creative tabs](creative-tabs.md) describes.
version, so the changed tab is the one automatically registered by MMDLib,
including tabs in another mod's namespace.
`CreativeTabBuilder.exists(id)` tells whether a file declares a tab, and
`CreativeTabBuilder.declared()` lists every file tab's ID.

Expand All @@ -1044,6 +1043,10 @@ is registered by that mod; the change applies when it registers its tabs from
| `titleFallback` | string | `""`: none |
| `icon` | item ID | `""`: the first item or material entry |
| `searchBar` | bool | `false` |
| `defaultForMod` | bool | `false`; sends the owning mod's generated content to this tab (one default per mod) |
| `includeModItems` | bool | `false`; includes all registered items in the owning namespace |
| `exclude` | item IDs, string[] | empty; exclusions override explicit and automatic entries |
| `excludeTags` | item tag IDs, string[] | empty; bare IDs (no `#`), resolved when tabs rebuild |
| `before`, `after` | tab IDs, string[] | empty |
| `contents` | string[], read-only | empty |

Expand Down
114 changes: 93 additions & 21 deletions docs/creative-tabs.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,66 @@
# Creative tabs

A mod using MMDLib can describe its creative tabs in JSON, next to its material and
A mod using MMDLib can describe its creative tabs in XML or JSON, next to its material and
other definitions. Each file in `mmdlib/creative_tab/` becomes one tab:

```text
src/main/resources/mmdlib/
material/copper.json
creative_tab/tools.json -> tab example:tools
creative_tab/main.xml -> tab example:main
creative_tab/blocks/deco.json -> tab example:blocks/deco
```

The tab's ID is the mod's ID and the file's path below `creative_tab/`, without
`.json`, as for every other [definition file](definition-loading.md).
`.xml` or `.json`. Defining the same ID in both formats is an error.

## XML

```xml
<creative-tab xmlns="https://moddev.zone/mmdlib/creative-tab" version="1"
title="itemGroup.example" title-fallback="Example Mod"
icon="example:copper_hammer" default-for-mod="true"
include-mod-items="true" search-bar="true">
<exclude tag="example:internal_items"/>
<after id="minecraft:tools_and_utilities"/>
</creative-tab>
```

The namespace and `version="1"` are required. Root attributes are `title`,
`title-fallback`, `icon`, `search-bar`, `default-for-mod` and `include-mod-items`;
boolean attributes default to `false`. Children are `item`, `tag`, `material`,
`before`, `after` and `exclude`. Entries use `id`; `exclude` requires exactly one
of `id` (an item) or `tag` (an item tag). Unknown attributes/elements are errors. DTDs and
external entities are not allowed. XML and JSON use the same validation and
runtime behavior.

`include-mod-items="true"` includes every registered item whose namespace matches
the tab's owning mod, including native Java items and generated block/material
items. No item list is needed. New items appear automatically after restarting.
Items are sorted by registry ID. Optional `item`, `tag` and `material` entries
come first, allowing favorites at the top without duplicates.

`exclude` accepts exact item IDs or item tags and wins over all inclusion sources, including
explicit entries and `default-for-mod` generated content. It affects this tab's
display and contribution to creative search; another tab may still list the item.
Unknown exclusions are harmless, allowing optional or retired internal items.
Supply an `icon` when there are no explicit item/material entries.

For `<exclude tag="example:internal_items"/>`, put the members in
`data/example/tags/item/internal_items.json`:

```json
{
"replace": false,
"values": ["example:internal_part", "example:legacy_alias"]
}
```

Use the bare tag ID in XML (no `#`). Tag files can include nested tags using
`"#example:other_internal_items"`. Exclusion tags are resolved whenever the tab
is rebuilt, using the current datapack tags; missing or empty tags exclude nothing.
Both shipped mod tabs use their own `internal_items` tag.

## The file
## JSON

```json
{
Expand All @@ -29,7 +76,11 @@ The tab's ID is the mod's ID and the file's path below `creative_tab/`, without
}
```

Only `contents` is required.
`contents` may be omitted or empty only when `include_mod_items` or
`default_for_mod` is true. Otherwise an empty definition is rejected, including
one that accidentally uses `content` instead of `contents`. Without an explicit
item/material entry, an `icon` is required. The same rules apply to XML and Java
builders.

| Field | Meaning |
|---|---|
Expand All @@ -39,6 +90,10 @@ Only `contents` is required.
| `icon` | The item shown on the tab. Defaults to the first item or material entry in `contents`; a tab whose contents are all tags needs one. |
| `before`, `after` | Tab IDs this tab is placed before or after, such as `"minecraft:combat"`. |
| `search_bar` | `true` gives the tab a search bar. |
| `default_for_mod` | `true` sends generated machines and registrar items in this tab's namespace here. At most one default per mod. XML spells this `default-for-mod`. |
| `include_mod_items` | `true` appends every enabled item registered in the owning namespace, sorted by ID. Defaults to `false`. XML spells this `include-mod-items`. |
| `exclude` | Item IDs to omit from all inclusion sources, e.g. `["example:internal_part"]`. Defaults to `[]`. XML uses `<exclude id="example:internal_part"/>`. |
| `exclude_tags` | Item tag IDs to omit, e.g. `["example:internal_items"]` (no `#`). Defaults to `[]`. XML uses `<exclude tag="example:internal_items"/>`. |

An item appears once, where it is first listed: a tag or material that includes an
item already shown does not repeat it. Items whose feature flags are disabled are
Expand All @@ -57,19 +112,29 @@ Tags are filled in when the game builds the tab, so tags from datapacks work.

## Registering the tabs

MMDLib registers the tabs in its own namespace. As with materials, your mod
registers its own, through its `RuntimeContentRegistrar`. `MMDLib.creativeTabs()`
lists every tab file; queue yours once loading is done:

```java
MMDLib.creativeTabs().forEach((id, tab) -> {
if (id.getNamespace().equals("example"))
registrar.queueTab(id, tab);
});
```

`queueTab` returns the tab's `DeferredHolder`. It only takes IDs in the
registrar's namespace, and not `<mod>:materials`, which is the registrar's own tab.
MMDLib automatically registers file-defined tabs for every owning mod. No Java
tab registration is needed. `MMDLib.creativeTabs()` lists the loaded definitions.
Existing consumers that queue file tabs through a `RuntimeContentRegistrar`
remain supported; a queued tab is not registered a second time.

Generated machines and material/standalone items join their owner's default tab,
after its explicit contents, without duplicates. Without an explicit default,
MMDLib selects a same-namespace Java or file tab: `main`, then `machines`, then
other names alphabetically, then `materials`, then `mmdlib_content`. A namespace
with generated items gets a fallback only
if it has no authored, queued or registered Java tab after its own tab registration
handlers run. Registrar namespaces retain `<mod>:materials` and the existing
`itemGroup.<mod>.materials` translation key; other namespaces get
`<mod>:mmdlib_content`. Both use the mod display name when their title is untranslated.
No unused placeholder tab is registered. Routing is selected once after registration;
Tag exclusions and feature flags are still evaluated on each contents rebuild.
There is no shared data-defined machines tab. MMDLib's Range, Gearbox and Capacitor Upgrades live in `mmdlib:main`.

Use `include-mod-items` to discover manually registered Java items too, and
exclude internal parts and compatibility aliases. Without that option, list
Java items explicitly or use the Java tab's display callback.

When replacing a Java tab with XML, remove the old registration for that ID.

## Building a tab in code

Expand All @@ -86,9 +151,16 @@ registrar.queueTab(ResourceLocation.parse("example:tools"),
.tag(ResourceLocation.parse("c:gears"))
.after(ResourceLocation.parse("minecraft:tools_and_utilities"))
.searchBar()
.defaultForMod()
.includeModItems()
.exclude(ResourceLocation.parse("example:internal_part"))
.excludeTag(ResourceLocation.parse("example:internal_items"))
.build());
```

`queueTab` returns the tab's `DeferredHolder`. It only takes IDs in the
registrar's namespace, and not `<mod>:materials`, which is reserved for its fallback.

## From CraftTweaker scripts

`#loader mmdlib` scripts can make tabs with `mods.mmdlib.CreativeTabBuilder`, and
Expand All @@ -100,6 +172,6 @@ ID replaces it.

## The materials tab

Every registrar also has its automatic `<mod>:materials` tab, holding every item it
registers; its title is the translation key `itemGroup.<mod>.materials`. It is
unchanged by tab files, so an item listed in your own tab also appears there.
Every registrar retains `<mod>:materials` as a fallback, using translation key
`itemGroup.<mod>` and the mod's display name. It receives generated content only
when the mod has no preferred tab; otherwise it stays empty and hidden.
5 changes: 3 additions & 2 deletions docs/definition-loading.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,12 @@ src/main/resources/mmdlib/
sound/machine/hum.json
sound_type/steel_plate.json
creative_tab/tools.json
creative_tab/main.xml
machine/simple_crusher.xml
```

IDs use the owning mod's namespace and the relative path below the section,
without `.json`. For mod ID `example`, the gear above is `example:components/gear`
without `.json` or `.xml`. For mod ID `example`, the gear above is `example:components/gear`
and the material is `example:copper`. For a file declaring several mods, the
root-level directory belongs to the first mod declared in its metadata. Extension
files also have file IDs, but their callable handler IDs come from the explicit
Expand Down Expand Up @@ -174,7 +175,7 @@ in datapacks, and code playing it through its registry holder.

## Creative tabs

`mmdlib/creative_tab/<path>.json` describes one creative tab: its title, icon,
`mmdlib/creative_tab/<path>.xml` (or `.json`) describes one creative tab: its title, icon,
placement and contents (items, item tags and whole materials). See
[creative tabs](creative-tabs.md).

Expand Down
2 changes: 1 addition & 1 deletion docs/machine-companion.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ those mods' login payloads; real client smoke runs include them.
| `dual_crusher` | Two independently pausable processors share the same input and output slots |
| `logistics` | Seven independent resource groups for testing automation, filters and side configuration; no recipe processing |
| `creative_power` | Refills its buffer and supplies up to 1,000 FE per enabled adjacent face per tick |
| `simple_crusher` | XML-only definition with inherited power, generated screen contents, and tag-generated ore-to-ingot recipes; in the **Data-defined Machines** tab |
| `simple_crusher` | XML-only definition with inherited power, generated screen contents, and tag-generated ore-to-ingot recipes; in the companion mod's own tab |
| `multiblock_demo` | One item places a controller and two linked parts; the far part exposes item/fluid/energy ports; breaking a member dismantles the machine |

The **Multiblock Test Bench** is in the Machines tab. It occupies the controller position and two
Expand Down
2 changes: 1 addition & 1 deletion docs/xml-machines.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ The example reuses vanilla textures; your own textures can use names such as
blockstates, block/item models, English labels, mining tags and a self-drop loot
table in a low-priority resource pack. Authored resources can override these
defaults. Crafting recipes remain ordinary files under `data/<modid>/recipe/`.
The companion's SimpleCrusher is in the **Data-defined Machines** creative tab.
The companion's SimpleCrusher is in the companion mod's own creative tab.

## Ghost inventory inputs

Expand Down
10 changes: 9 additions & 1 deletion scripts/gui-smoke.init.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,15 @@ allprojects {
// The GUI smoke doesn't test CraftTweaker (the game tests do); keep it out of this client.
configurations.named('craftTweakerDevRuntime') { dependencies.clear() }
sourceSets.main.java.srcDir(file('src/runtimeTest/java'))
sourceSets.main.resources.srcDir(file('src/runtimeTest/resources'))
// Test resources overlay production resources, as they do in the runtime-test pack.
def runtimeResources = file('src/runtimeTest/resources')
sourceSets.main.resources.srcDir(runtimeResources)
tasks.named('processResources') {
eachFile { entry ->
def overlay = new File(runtimeResources, entry.path)
if (overlay.isFile() && entry.file != overlay) entry.exclude()
}
}
def ghostOnly = providers.gradleProperty('ghostSmokeOnly').isPresent()
def transferOnly = providers.gradleProperty('transferSmokeOnly').isPresent()
if (ghostOnly && transferOnly) throw new GradleException('Choose one focused GUI runner')
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,37 @@
public final class CompanionGameTests {
private static final BlockPos CENTER = new BlockPos(2, 2, 2);

@GameTest(template = "empty")
public static void nativeCreativeTabSuppressesGeneratedFallback(
GameTestHelper helper) {
var tabs = BuiltInRegistries.CREATIVE_MODE_TAB;
var namespace = CompanionMod.ID;
require(
tabs.containsKey(net.minecraft.resources.ResourceLocation
.fromNamespaceAndPath(namespace, "machines")),
"Consumer's Java machines tab is registered");
require(
!tabs.containsKey(net.minecraft.resources.ResourceLocation
.fromNamespaceAndPath(namespace, "materials"))
&& !tabs.containsKey(net.minecraft.resources.ResourceLocation
.fromNamespaceAndPath(namespace, "mmdlib_content")),
"Consumer registration after MMDLib does not leave empty fallback tabs");
var tab = tabs.get(net.minecraft.resources.ResourceLocation
.fromNamespaceAndPath(namespace, "machines"));
var level = helper.getLevel();
tab.buildContents(
new net.minecraft.world.item.CreativeModeTab.ItemDisplayParameters(
level.enabledFeatures(), false, level.registryAccess()));
var simple = zone.moddev.mc.lib.machine.neoforge.MachineContent
.item(net.minecraft.resources.ResourceLocation
.fromNamespaceAndPath(namespace, "simple_crusher"));
require(
tab.getDisplayItems().stream().filter(stack -> stack.is(simple))
.count() == 1,
"Generated XML machine is routed into the consumer's Java tab exactly once");
helper.succeed();
}

@GameTest(template = "empty")
public static void poweredBasePreservesSavesAndSeparatesFeatureUpdates(
GameTestHelper helper) {
Expand Down
1 change: 1 addition & 0 deletions src/main/java/zone/moddev/mc/lib/MMDLib.java
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,7 @@ public MMDLib(IEventBus modBus, ModContainer container) {
MMDLibConfig.SERVER_SPEC);
zone.moddev.mc.lib.gui.runtime.ScreenRuntime.register(modBus);
zone.moddev.mc.lib.machine.neoforge.MachineContent.register(modBus);
zone.moddev.mc.lib.common.runtime.ModCreativeTabs.register(modBus);
BLOCKS.register(modBus);
ITEMS.register(modBus);
machineTypes.register(modBus);
Expand Down
Loading
Loading