Merge remote-tracking branch 'origin/master-1.20-lts' into master-1.21-lts

Author: rubensworks

AGENTS.md

@@ -0,0 +1,182 @@
+# AGENTS.md - Developer and AI Agent Guide
+
+This document provides essential information for developers and AI agents working on this Minecraft mod's codebase.
+
+## Project Overview
+
+This is a Minecraft mod. See README.md for a description of what this mod does. The project is written in Java and uses Gradle as its build system.
+
+## Multi-Loader Architecture
+
+**This repo only uses a multi-loader architecture if you can find a `loader-common` directory in the root of this repo!**
+
+In Minecraft 1.21 and above, this repository uses a **multi-loader setup**, meaning the mod is available on multiple Minecraft mod loaders.
+The Minecraft version can be found in `gradle.properties`.
+Understanding this architecture is crucial when making changes:
+
+### Directory Structure
+
+- **`loader-common/`**: Contains source code that is common across all mod loaders. Most shared functionality should be implemented here.
+- **`loader-fabric/`**: Fabric-specific implementation and integration code.
+- **`loader-forge/`**: Forge-specific implementation and integration code (for older Minecraft versions).
+- **`loader-neoforge/`**: NeoForge-specific implementation and integration code (for newer Minecraft versions).
+
+### Making Changes in Multi-loader Setups
+
+When adding features or fixing bugs:
+1. Place shared logic in `loader-common/` whenever possible
+2. Only add loader-specific code to the respective `loader-*` directories when platform-specific APIs are required
+3. Ensure your changes work across all supported loaders
+
+## Testing
+
+This mod uses two types of tests:
+
+### 1. Unit Tests
+
+**Location**: `src/test/java/`
+
+Traditional JUnit tests for testing isolated functionality without requiring a full Minecraft instance.
+
+**Running unit tests**:
+```bash
+./gradlew test
+```
+
+Unit tests are automatically executed when running the `build` command.
+
+### 2. Game Tests
+
+**Location**: Within normal sources, typically in the `org/cyclops/*/gametest` package (e.g., `loader-common/src/main/java/org/cyclops/cyclopscore/gametest/`)
+
+Game tests run an actual Minecraft instance to test code with real game logic. These are essential for testing features that interact with Minecraft's gameplay systems.
+Game tests only exist in Minecraft 1.21 and higher.
+
+**Running game tests**:
+```bash
+./gradlew runGameTestServer
+```
+
+**Important**:
+- Game tests are **NOT** run automatically during the build process
+- For Minecraft 1.21 and above, game tests must be run manually before committing
+- Game tests must pass before finalizing your changes
+
+### When to Add Tests
+
+When adding new features or fixing bugs:
+- **Always** add unit tests when possible for isolated logic
+- **Always** add game tests when the feature interacts with Minecraft gameplay systems
+- Look at existing tests in the respective directories for examples of test patterns and conventions
+
+## Building the Project
+
+### Prerequisites
+
+- Java version is specified in `gradle.properties` (otherwise, default to version 17)
+- Gradle (use the provided wrapper: `./gradlew`)
+
+### Build Command
+
+Before every commit, ensure the project builds successfully:
+
+```bash
+./gradlew build
+```
+
+This command will:
+- Compile all source code
+- Run unit tests automatically
+- Generate build artifacts
+
+### Full Pre-Commit Validation
+
+Run build:
+
+```bash
+./gradlew build
+```
+
+Only for Minecraft 1.21 and above, also run game tests:
+```bash
+./gradlew runGameTestServer
+```
+
+Both must pass before committing changes.
+
+## Code Formatting
+
+This project uses Spotless for code formatting:
+
+```bash
+./gradlew spotlessApply
+```
+
+The pre-commit script in `scripts/pre-commit` automatically formats staged files. Consider setting it up as a Git hook:
+
+```bash
+ln -s ../../scripts/pre-commit .git/hooks/pre-commit
+```
+
+## Development Workflow
+
+1. **Understand the change**: Read the issue/feature request thoroughly
+2. **Explore the codebase**: Use tools like `grep` to find relevant code
+3. **Make minimal changes**: Focus on the specific issue/feature
+4. **Add tests**: Write unit tests and/or game tests as appropriate
+5. **Build and test**:
+   ```bash
+   ./gradlew build
+   ./gradlew runGameTestServer  # For MC 1.21+
+   ```
+6. **Format code**: `./gradlew spotlessApply`
+7. **Commit**: Use clear, descriptive commit messages
+
+## Project Dependencies
+
+## Release Management
+
+Version bumping and release management helper scripts are available in the [CyclopsMC/ReleaseHelpers](https://github.com/CyclopsMC/ReleaseHelpers) repository. These bash scripts assist with:
+- Version bumping across all loaders
+- Changelog management
+- Release preparation
+
+## Gradle Tasks Reference
+
+Common Gradle tasks for development:
+
+| Task | Purpose |
+|------|---------|
+| `./gradlew build` | Build the project and run unit tests |
+| `./gradlew test` | Run unit tests only |
+| `./gradlew runGameTestServer` | Run game tests (manual, required for MC 1.21+) |
+| `./gradlew spotlessApply` | Format code according to project standards |
+| `./gradlew publishToMavenLocal` | Publish to local Maven for testing in other projects |
+
+If for any reason gradle fails due to internet connection issues, try running offline instead by running the gradle command with the `--offline` flag.
+
+## CI/CD
+
+GitHub Actions automatically:
+- Builds the project on every push and pull request
+- Runs unit tests
+- Runs game tests (including `runGameTestServer`)
+- Generates coverage reports
+- Deploys to CurseForge, Modrinth, and Maven on appropriate branches/tags
+
+See `.github/workflows/ci.yml` for the full CI configuration.
+
+## Additional Resources
+
+- **README.md**: Project overview and usage information
+- **CONTRIBUTING.md**: Contribution guidelines and issue reporting
+- **Build configuration**: `build.gradle` and loader-specific build files
+- **Project properties**: `gradle.properties` (Minecraft version, mod version, etc.)
+
+## Key Principles
+
+1. **Minimal changes**: Make the smallest possible changes to achieve your goal
+2. **Test coverage**: Always try to add tests for new features and bug fixes (may be difficult or impossible for things related to GUIs)
+3. **Multi-loader compatibility**: Ensure changes work across all supported loaders
+4. **Build validation**: Never commit without running `build` (and `runGameTestServer` for MC 1.21+)
+5. **Code quality**: Follow existing patterns and conventions in the codebase

loader-common/src/main/java/org/cyclops/cyclopscore/client/gui/component/input/WidgetNumberField.java

@@ -59,6 +59,13 @@ public int getMinValue() {
      */
     public void setMinValue(int minValue) {
         this.minValue = minValue;
+        try {
+            if (this.minValue > Integer.parseInt(getValue())) {
+                setValue(Integer.toString(this.minValue));
+            }
+        } catch (NumberFormatException e) {
+            setValue(Integer.toString(this.minValue));
+        }
         updateArrowsState();
     }
 

loader-neoforge/src/main/java/org/cyclops/cyclopscore/nbt/path/NbtPath.java

@@ -21,12 +21,17 @@ public class NbtPath {
             new NbtPathExpressionParseHandlerListElement(),
             new NbtPathExpressionParseHandlerListSlice(),
             new NbtPathExpressionParseHandlerUnion(),
+            new NbtPathExpressionParseHandlerGrouping(),
             new NbtPathExpressionParseHandlerBooleanRelationalLessThan(),
             new NbtPathExpressionParseHandlerBooleanRelationalLessThanOrEqual(),
             new NbtPathExpressionParseHandlerBooleanRelationalGreaterThan(),
             new NbtPathExpressionParseHandlerBooleanRelationalGreaterThanOrEqual(),
+            new NbtPathExpressionParseHandlerBooleanRelationalNotEqual(),
             new NbtPathExpressionParseHandlerBooleanRelationalEqual(),
             new NbtPathExpressionParseHandlerStringEqual(),
+            new NbtPathExpressionParseHandlerBooleanLogicalAnd(),
+            new NbtPathExpressionParseHandlerBooleanLogicalOr(),
+            new NbtPathExpressionParseHandlerBooleanLogicalNot(),
             new NbtPathExpressionParseHandlerFilterExpression()
     );
 

loader-neoforge/src/main/java/org/cyclops/cyclopscore/nbt/path/parse/NbtPathExpressionParseHandlerBooleanLogicalAdapter.java

@@ -0,0 +1,151 @@
+package org.cyclops.cyclopscore.nbt.path.parse;
+
+import net.minecraft.nbt.ByteTag;
+import net.minecraft.nbt.Tag;
+import org.cyclops.cyclopscore.nbt.path.INbtPathExpression;
+import org.cyclops.cyclopscore.nbt.path.NbtParseException;
+import org.cyclops.cyclopscore.nbt.path.NbtPath;
+import org.cyclops.cyclopscore.nbt.path.NbtPathExpressionMatches;
+
+import javax.annotation.Nullable;
+import java.util.function.Supplier;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
+
+/**
+ * @author rubensworks
+ */
+public abstract class NbtPathExpressionParseHandlerBooleanLogicalAdapter implements INbtPathExpressionParseHandler {
+
+    private final Pattern regex;
+
+    protected NbtPathExpressionParseHandlerBooleanLogicalAdapter(String relation) {
+        this.regex = Pattern.compile("^ *" + relation + " *");
+    }
+
+    protected abstract boolean getLogicalValue(boolean left, Supplier<Boolean> right);
+
+    /**
+     * Determine if a tag is truthy.
+     * ByteTag with value 1 is true, 0 is false.
+     * Any other non-null tag is considered true.
+     * This follows the same logic as {@link org.cyclops.cyclopscore.nbt.path.INbtPathExpression#test(Tag)}.
+     *
+     * @param tag The tag to check
+     * @return true if the tag is truthy, false otherwise
+     */
+    public static boolean isTruthy(Tag tag) {
+        if (tag == null) {
+            return false;
+        }
+        if (tag.getId() == Tag.TAG_BYTE) {
+            return ((ByteTag) tag).getAsByte() == (byte) 1;
+        }
+        // Non-null non-ByteTags are truthy
+        return true;
+    }
+
+    /**
+     * Find the end position of an expression, stopping at logical operators or closing parenthesis.
+     * This method is shared by logical operator handlers to identify expression boundaries.
+     *
+     * @param expression The full expression string
+     * @param start The starting position to search from
+     * @return The position where the expression ends
+     */
+    public static int findExpressionEnd(String expression, int start) {
+        int depth = 0;
+        for (int i = start; i < expression.length(); i++) {
+            char c = expression.charAt(i);
+
+            if (c == '(') {
+                depth++;
+            } else if (c == ')') {
+                if (depth == 0) {
+                    return i;
+                }
+                depth--;
+            } else if (depth == 0) {
+                // Check for logical operators at top level
+                if (i + 1 < expression.length()) {
+                    String twoChar = expression.substring(i, i + 2);
+                    if (twoChar.equals("&&") || twoChar.equals("||")) {
+                        return i;
+                    }
+                }
+                // Check for NOT operator (but not != which is handled differently)
+                if (c == '!' && (i + 1 >= expression.length() || expression.charAt(i + 1) != '=')) {
+                    return i;
+                }
+            }
+        }
+        return expression.length();
+    }
+
+    @Nullable
+    @Override
+    public HandleResult handlePrefixOf(String nbtPathExpression, int pos) {
+        Matcher matcher = this.regex
+                .matcher(nbtPathExpression)
+                .region(pos, nbtPathExpression.length());
+        if (!matcher.find()) {
+            return HandleResult.INVALID;
+        }
+
+        // Parse the right-hand side expression
+        int rightPos = pos + matcher.group().length();
+        if (rightPos >= nbtPathExpression.length()) {
+            return HandleResult.INVALID;
+        }
+
+        // Find the end of the right expression
+        int endPos = findExpressionEnd(nbtPathExpression, rightPos);
+        if (endPos == rightPos) {
+            return HandleResult.INVALID;
+        }
+
+        String rightExpressionString = nbtPathExpression.substring(rightPos, endPos);
+        try {
+            INbtPathExpression rightExpression = NbtPath.parse(rightExpressionString.trim());
+            return new HandleResult(new Expression(rightExpression, this),
+                    matcher.group().length() + rightExpressionString.length());
+        } catch (NbtParseException e) {
+            return HandleResult.INVALID;
+        }
+    }
+
+    public static class Expression implements INbtPathExpression {
+
+        protected final INbtPathExpression expression;
+        protected final NbtPathExpressionParseHandlerBooleanLogicalAdapter handler;
+
+        public Expression(INbtPathExpression expression, NbtPathExpressionParseHandlerBooleanLogicalAdapter handler) {
+            this.expression = expression;
+            this.handler = handler;
+        }
+
+        @Override
+        public NbtPathExpressionMatches matchContexts(Stream<NbtPathExpressionExecutionContext> executionContexts) {
+            return new NbtPathExpressionMatches(executionContexts
+                    .map(executionContext -> {
+                        Tag currentTag = executionContext.getCurrentTag();
+
+                        // The left side is the current tag (should be a boolean result from previous expression)
+                        boolean leftValue = isTruthy(currentTag);
+
+                        // Evaluate the right expression against the root context
+                        // This ensures both sides of the expression are evaluated against the same base context
+                        Tag rootTag = executionContext.getRootContext().getCurrentTag();
+
+                        // AND operation
+                        boolean result = handler.getLogicalValue(leftValue, () -> expression.test(rootTag));
+
+                        return new NbtPathExpressionExecutionContext(ByteTag.valueOf(result), executionContext);
+                    })
+            );
+        }
+
+    }
+
+}

loader-neoforge/src/main/java/org/cyclops/cyclopscore/nbt/path/parse/NbtPathExpressionParseHandlerBooleanLogicalAnd.java

@@ -0,0 +1,18 @@
+package org.cyclops.cyclopscore.nbt.path.parse;
+
+import java.util.function.Supplier;
+
+/**
+ * A handler that handles boolean AND expressions in the form of "expression1 {@literal &&} expression2".
+ */
+public class NbtPathExpressionParseHandlerBooleanLogicalAnd extends NbtPathExpressionParseHandlerBooleanLogicalAdapter {
+
+    public NbtPathExpressionParseHandlerBooleanLogicalAnd() {
+        super("&&");
+    }
+
+    @Override
+    protected boolean getLogicalValue(boolean left, Supplier<Boolean> right) {
+        return left && right.get();
+    }
+}