stewbeet.plugins.datapack.sorters

The datapack.sorters plugin generates efficient sorting functions for Minecraft datapacks.
It creates optimized mcfunction files at compile time that can sort lists stored in NBT storage
using configurable algorithms (Quick Sort and Selection Sort), with support for custom comparison
keys, scaling factors, and performance optimizations tailored for Minecraft's execution environment.

Source Code: stewbeet/plugins/datapack/sorters/__init__.py

Source Code: stewbeet/plugins/datapack/sorters/constants.py

Source Code: stewbeet/plugins/datapack/sorters/extend_datapack.py

Source Code: stewbeet/plugins/datapack/sorters/match.py

Source Code: stewbeet/plugins/datapack/sorters/quick_sort.py

Source Code: stewbeet/plugins/datapack/sorters/selection_sort.py

What it does

  • Generate high-performance sorting functions for NBT storage lists
  • Support multiple sorting algorithms optimized for Minecraft's execution model
  • Handle complex data structures with configurable comparison keys
  • Provide in-place sorting with minimal memory overhead
  • Enable precision control through scaling for decimal values
  • Support partial sorting with element limits for performance optimization

Credits

Author: Darukshock - Original implementation of the quick sort algorithm

Dependencies

  • βœ… Required: Beet context with datapack namespace support
  • πŸ“ Position: Can run at any point during compilation
  • πŸ”§ Extension: Requires stewbeet.plugins.datapack.sorters.extend_datapack to register sorter namespace

Quick Example

Sorters are declared in the sorters registry under data/<namespace>, like so:
data/<namespace>/sorter/<sorter_name>.json

Alternatively, they can be generated with python:

The list can now be sorted:

Configuration

Configuration Options

OptionTypeDefaultDescription
algorithmstringRequiredSorting algorithm to use: "selection_sort" (recommended) or "quick_sort"
functions_locationstringRequiredNamespaced function ID where sorting functions are generated
to_sortobjectRequiredStorage location containing storage and target keys
to_sort.storagestringRequiredStorage namespace (e.g., "switch:stats")
to_sort.targetstringRequiredNBT path to the list (e.g., "all.modes.sheepwars.played")
keystringRequiredKey within each list element to compare for sorting
scalefloat1.0Optional: Scaling factor for numeric values (negative for descending order)
limitintegernullOptional: Maximum elements to sort (selection_sort only)

⚑ Performance Note: Selection sort significantly outperforms quick sort in Minecraft's storage environment due to quick sort's heavy reliance on macro expansions. Each recursive call in quick sort generates multiple macro invocations for parameter passing and storage manipulation, creating substantial overhead that negates the theoretical O(n log n) advantage. Selection sort's straightforward O(n²) approach with minimal macro usage proves more efficient for typical Minecraft datapack sorting operations.

Basic Example Configuration

yaml
require:
  - ...
  - stewbeet.plugins.datapack.sorters.extend_datapack # Required: register "data/<namespace>/sorter/" as a custom resource
  - ...

pipeline:
  - ...
  - stewbeet.plugins.datapack.sorters  # Place this plugin in the pipeline
  - ...  # Other plugins follow

Example Sorter Configuration

json
{
	"algorithm": "selection_sort",
	"functions_location": "switch:stats/minigame/sort_leaderboard",
	"to_sort": {
		"storage": "switch:stats",
		"target": "all.modes.sheepwars.played"
	},
	"key": "count",
	"scale": 100,
	"limit": 10
}

Spyglass implementation

Combined with the Spyglass extension for Visual Studio Code, auto-completion and syntax checking can be obtained on sorter files.
Here's how:

  • If you haven't already, open your project on Visual Studio Code and install the Spyglass extension.
  • Create a Spyglass Config File, and under the env field, add the following :
json
"customResources": {
	"sorter": {
		"category": "sorter"
	}
}

Features

Algorithm Selection System

  • πŸ₯‡ Selection Sort - Recommended for better Minecraft performance
  • ⚑ Quick Sort - Alternative using recursive function calls
  • πŸ“Š Automatic Routing - Algorithm selection based on configuration

Extended Datapack Support

  • πŸ—„οΈ Custom Resource Type - Sorter objects at data/<namespace>/sorter/path.json
  • πŸ‘“ Spyglass Support - Syntax checking and auto-completion
  • βœ… Multi-Datapack Support - Independent configurations

Advanced Scaling System

  • πŸ“Š Precision Control - Scale factor for decimal precision (e.g., 1000 for 3 decimals)
  • πŸ”„ Reverse Sorting - Negative scale values for descending order

Selection Sort Implementation

  • πŸ” Minimum Finding - Efficient linear search
  • πŸš€ Partial Sorting - Optional limit parameter for top-N sorting
  • πŸ’Ύ Memory Efficient - In-place sorting with minimal storage overhead

Quick Sort Implementation

  • πŸ“Š Pivot Selection - Last element partitioning
  • πŸ”„ Recursive Calls - Function-based recursion with macros
  • ⚠️ Performance Note - Less efficient than selection sort due to macro overhead

Configuration & Generation

  • βœ… Input Validation - Type checking and required field validation
  • οΏ½ Function Generation - Dynamic mcfunction file creation with macro integration
  • οΏ½ Memory Management - Temporary storage with automatic cleanup

Next steps