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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Written for Consumers: what a mod building against Example Module can use, or wi

## Unreleased

- `libworks-plugin` 0.4.5: `checkPlaysAlone` knows A Touch Of's Pillars as `atouchofdarkness`, `atouchofmadness` and `atouchofwickedness`. The shelved `atouchofcold` is retired, so no Pillar or FactoryWorks Module may name it (A Touch Of #5, #6). A Pillar may add entries to another Pillar's tag with a file under `data/<other>/tags/` whose `replace` is absent or false and whose every entry is `{"id": "<its own id or #tag>", "required": false}`. Any other file in that namespace still fails, and the failure says why (ADR 0014, A Touch Of ADR-0002). FactoryWorks Modules get no such exception. Forbidding `atouchofcold` and `atouchofwickedness` tightens the check, but no Module ships either, so it is a patch, as 0.4.4 was (ADR 0001). A Module edits nothing.
- `libworks-plugin` 0.4.4: `checkPlaysAlone` also checks a Module against every other suite's Modules, bases included (ADR 0013): a Pillar may not name a FactoryWorks Module, Groundworks included, and a FactoryWorks Module may not name a Pillar or A Touch Of's Runtime, `atouchof`. 0.4.3 let a Pillar name a FactoryWorks Module and the reverse. A mod no suite lists is still checked against every suite's Modules but Groundworks and `atouchof`. A Module edits nothing: none names the other suite.
- `libworks-plugin` 0.4.3: `checkPlaysAlone` checks a Module against its own suite's Modules, which its `mod_id` picks (ADR 0013). A Touch Of's Pillars, `atouchofcold`, `atouchofdarkness` and `atouchofmadness`, are checked against one another and may name their Runtime, `atouchof`, and no longer against FactoryWorks' Modules. A FactoryWorks Module's check is unchanged. A mod no suite lists is checked against every suite's Modules but Groundworks and `atouchof`. A Module edits nothing.
- `libworks-runtime` 0.1.12: libworks-gametest's `GalleryCheck.MAX_SCENES` is 24, up from 16, so `builds` and `withPack` take a gallery of up to 24 scenes.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,7 @@ template's own build would need an exception.
**Amended 2026-10-25 (plugin 0.4.4).** Plugin 0.4.3 checked a Module only against its own suite, so a Pillar
could name any FactoryWorks Module and a FactoryWorks Module any Pillar, which neither suite's rule
allows. 0.4.4 adds every other suite's Modules, bases included, as above.

**Amended 2026-10-27 (plugin 0.4.5, ADR 0014).** A Touch Of's Pillars are `atouchofdarkness`, `atouchofmadness` and
`atouchofwickedness` (A Touch Of #6). `atouchofcold` is shelved in favour of Tough As Nails (A Touch Of #5) and
retired, so none may name it. A Pillar may add optional entries to another Pillar's tag (ADR 0014).
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
status: accepted
---

# A Pillar may add optional entries to another Pillar's tag

A Touch Of ADR-0002, as amended by A Touch Of #6, lets one Pillar add an entry to another Pillar's
tag. It does this with a vanilla tag file that has `replace: false` and marks every entry
`required: false`. Without the other Pillar the tag is never read, so neither Pillar requires the
other. The first use is A Touch of Wickedness shipping
`data/atouchofmadness/tags/entity_type/unsettling.json`, which adds its Bailiff. `checkPlaysAlone`
(ADR 0005, ADR 0013) failed any `data/<ns>` folder in another Pillar's namespace, so that file
failed.

**Decision.** Each suite states what a Module may ship in another Module's tags: A Touch Of takes
optional entries, and FactoryWorks takes none, since FactoryWorks ADR-0127 allows none. In a suite
that takes them, a Module other than the base may ship files under another Module's
`data/<ns>/tags/<registry>/`. Each must be a tag whose `replace` is absent or false, with no
NeoForge `remove` list, which would take entries out of the other tag, and whose every entry is an
object with `"required": false` naming one of the Module's own ids or tags. The scan reads that
namespace's data folder file by file, and reports each file that fails with why: outside `tags/`,
not a tag or not valid JSON, a bare or required entry, an entry with no id, a `replace` that is
true or not a boolean, a `remove`, or an id that is not the Module's own. The exception does not
cover an `assets/<ns>` folder, the base, a retired id such as the shelved `atouchofcold`, or
another suite's namespace.

`atouchofcold` is retired while A Touch of Cold is shelved (A Touch Of #5), so its own build would
fail: no suite lists it, and its ids are forbidden. Reviving it means a patch release that moves it
from the suite's retired ids back to its Pillars.

**Versioning.** Forbidding `atouchofcold` and `atouchofwickedness` tightens the check, but no
Module ships either, so none has to edit its build, and the release is a patch (ADR 0001), as
0.4.4's tightening was (ADR 0013).

**Considered.** Allowing any id an optional entry names, such as `minecraft:zombie`: a Pillar
could then retune another Pillar's tag with vanilla content, which goes further than ADR-0002's
"adds an entry" allows. The exception in every suite: FactoryWorks has not asked for it, and its
ADR-0127 forbids it. A list of allowed files in the plugin: narrower, but every new use would need
a plugin release. A Module declaring its tag files in `libworks { }`: every Module would carry a
line, and the plugin would still need the rule to check it.
2 changes: 1 addition & 1 deletion docs/plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The plugin adds a `gametest` source set to the mod, which the dev runs load and

`buildGametestStructures` writes the default `gametest/platform.nbt` into `src/gametest/resources/data/<mod_id>/structure/`, leaves an identical one alone, and fails naming the file when the Module has committed a different one: a Module needing another structure commits it (ADR 0003).

`checkPlaysAlone`, which `check` runs, fails when the Module ships something that names another Module of its suite (FactoryWorks ADR-0127, A Touch Of ADR-0002, ADR 0005, ADR 0013): an id in its namespace, such as `pipeworks:pipe`, in a resource or in Java source; an `assets/<ns>` or `data/<ns>` folder; the namespace as a string in Java source, `"pipeworks"`; or a required dependency on it in `neoforge.mods.toml`, where an optional one is allowed. A structure's `.nbt` is read unzipped, so the block ids saved in it count. The resources are read as `processResources` leaves them, so generated ones and the expanded mods.toml count; the code is `src/main`'s Java source, and the `gametest` source set is not read. The suites are `PlaysAlone.SUITES`, and the Module's suite is the one whose list holds its `mod_id`. FactoryWorks' Modules are Beltworks, Craftworks, Fieldworks, Gearworks, Groundworks, Pipeworks, Voidworks and Wireworks: every one but the Module built and Groundworks is forbidden, and the retired `factoryworks`. A Touch Of's are its Runtime, `atouchof`, and the Pillars `atouchofcold`, `atouchofdarkness` and `atouchofmadness`: every one but the Pillar built and the Runtime is forbidden. A Module is also checked against every other suite's Modules, bases included: a Pillar may not name `pipeworks:pipe` or `groundworks:wrench`, nor a FactoryWorks Module `atouchof:meter`. A mod no suite lists, such as the template's `examplelib`, is checked against every suite's Modules but Groundworks and `atouchof`. A new Module is added to its suite there, and reaches the others by a plugin release they move to. The failure lists each finding under its folder, such as `build/resources/main/data/beltworks/recipe/x.json names gearworks:gear`.
`checkPlaysAlone`, which `check` runs, fails when the Module ships something that names another Module of its suite (FactoryWorks ADR-0127, A Touch Of ADR-0002, ADR 0005, ADR 0013, ADR 0014): an id in its namespace, such as `pipeworks:pipe`, in a resource or in Java source; an `assets/<ns>` or `data/<ns>` folder; the namespace as a string in Java source, `"pipeworks"`; or a required dependency on it in `neoforge.mods.toml`, where an optional one is allowed. A structure's `.nbt` is read unzipped, so the block ids saved in it count. The resources are read as `processResources` leaves them, so generated ones and the expanded mods.toml count; the code is `src/main`'s Java source, and the `gametest` source set is not read. The suites are `PlaysAlone.SUITES`, and the Module's suite is the one whose list holds its `mod_id`. FactoryWorks' Modules are Beltworks, Craftworks, Fieldworks, Gearworks, Groundworks, Pipeworks, Voidworks and Wireworks: every one but the Module built and Groundworks is forbidden, and the retired `factoryworks`. A Touch Of's are its Runtime, `atouchof`, and the Pillars `atouchofdarkness`, `atouchofmadness` and `atouchofwickedness`: every one but the Pillar built and the Runtime is forbidden, and the shelved `atouchofcold` (A Touch Of #5). A Pillar may still ship a tag file under another Pillar's `data/<ns>/tags/`, to add entries to that Pillar's tag, when `replace` is absent or false and every entry is an object with `"required": false` naming one of its own ids or tags, such as Wickedness's `data/atouchofmadness/tags/entity_type/unsettling.json` holding `{"id": "atouchofwickedness:bailiff", "required": false}` (A Touch Of ADR-0002, ADR 0014). Each other file in that folder is reported, with why: outside `tags/`, not a tag or not valid JSON, a bare or required entry, an entry with no id, a `replace` that is true or not a boolean, a NeoForge `remove` list, or an id not its own. While `atouchofcold` is retired its own build would fail, so reviving it means a patch release moving it back to the Pillars. FactoryWorks has no such exception, nor does the Runtime, the shelved `atouchofcold` or another suite's namespace. A Module is also checked against every other suite's Modules, bases included: a Pillar may not name `pipeworks:pipe` or `groundworks:wrench`, nor a FactoryWorks Module `atouchof:meter`. A mod no suite lists, such as the template's `examplelib`, is checked against every suite's Modules but Groundworks and `atouchof`. A new Module is added to its suite there, and reaches the others by a plugin release they move to. The failure lists each finding under its folder, such as `build/resources/main/data/beltworks/recipe/x.json names gearworks:gear`.

### Moving to 0.4.0

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
// SPDX-FileCopyrightText: 2026 5thlayer
// SPDX-License-Identifier: MIT

package io.github._5thlayer.libworks.plugin

import groovy.json.JsonOutput
import groovy.json.JsonSlurper

import java.nio.file.Path

/**
* A file a Module ships in another Module's data folder, which passes only as a tag of optional entries of the Module's own ids that keeps
* the tag's other entries (libworks ADR 0014, A Touch Of ADR-0002).
*/
final class OptionalTagFile {

private OptionalTagFile() {
}

/** Why {@code file}, under the other Module's {@code namespace} folder and shown as {@code name}, is not such a tag; empty when it is. */
static List<String> findings(Path namespace, Path file, String name, String modId, List<String> forbidden) {
def tags = namespace.resolve('tags')
if (!file.startsWith(tags)) return ["$name is outside tags/".toString()]
// A tag file sits in its registry's folder, tags/<registry>/; vanilla reads none directly under tags/.
if (file.parent == tags || !file.toString().endsWith('.json')) return ["$name is not a tag".toString()]
def tag
try {
tag = new JsonSlurper().parse(file.toFile())
} catch (Exception ignored) {
return ["$name is not valid JSON".toString()]
}
if (!(tag instanceof Map)) return ["$name is not a tag".toString()]
def found = []
// NeoForge reads a tag's "remove" list too, which would take entries out of the other Module's tag.
if (tag.containsKey('remove')) found << "$name removes from the tag".toString()
if (!(tag.values instanceof List)) return found ?: ["$name is not a tag".toString()]
if (tag.replace == true) found << "$name replaces the tag".toString()
else if (tag.containsKey('replace') && tag.replace != false) found << "$name sets replace to ${JsonOutput.toJson(tag.replace)}, not a boolean".toString()
tag.values.each { entry ->
def id = entry instanceof Map ? entry.id : entry
if (!(id instanceof String)) {
found << "$name has an entry with no id".toString()
return
}
// A bare id, or an entry with no "required", is required: the tag fails to load without it.
if (!(entry instanceof Map) || entry.required != false) {
found << "$name requires $id".toString()
return
}
def tagRef = id.startsWith('#') ? '#' : ''
def path = id - ~/^#/
// Vanilla reads an id with no namespace as minecraft's.
def full = path.contains(':') ? path : "minecraft:$path"
def namespaceOf = full.split(':')[0]
// An id in a forbidden namespace is already named by PlaysAlone.ids.
if (namespaceOf != modId && !forbidden.contains(namespaceOf)) found << "$name adds $tagRef$full, not $modId's own".toString()
}
found
}
}
Loading
Loading