beet-datapack-utils 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- beet_datapack_utils-0.1.0/CHANGELOG.md +31 -0
- beet_datapack_utils-0.1.0/LICENSE +21 -0
- beet_datapack_utils-0.1.0/PKG-INFO +104 -0
- beet_datapack_utils-0.1.0/README.md +79 -0
- beet_datapack_utils-0.1.0/docs/DEVELOPMENT.md +77 -0
- beet_datapack_utils-0.1.0/docs/INSTALLATION.md +49 -0
- beet_datapack_utils-0.1.0/docs/USAGE.md +111 -0
- beet_datapack_utils-0.1.0/pyproject.toml +82 -0
- beet_datapack_utils-0.1.0/pyproject.toml.orig +63 -0
- beet_datapack_utils-0.1.0/src/beet_datapack_utils/__init__.py +37 -0
- beet_datapack_utils-0.1.0/src/beet_datapack_utils/density.py +39 -0
- beet_datapack_utils-0.1.0/src/beet_datapack_utils/fields.py +61 -0
- beet_datapack_utils-0.1.0/src/beet_datapack_utils/py.typed +0 -0
- beet_datapack_utils-0.1.0/src/beet_datapack_utils/registries.py +52 -0
- beet_datapack_utils-0.1.0/src/beet_datapack_utils/targets.py +126 -0
- beet_datapack_utils-0.1.0/src/beet_datapack_utils/trees.py +62 -0
- beet_datapack_utils-0.1.0/src/beet_datapack_utils/versions.py +61 -0
- beet_datapack_utils-0.1.0/tests/conftest.py +80 -0
- beet_datapack_utils-0.1.0/tests/test_density.py +10 -0
- beet_datapack_utils-0.1.0/tests/test_fields.py +41 -0
- beet_datapack_utils-0.1.0/tests/test_registries.py +37 -0
- beet_datapack_utils-0.1.0/tests/test_targets.py +97 -0
- beet_datapack_utils-0.1.0/tests/test_trees.py +29 -0
- beet_datapack_utils-0.1.0/tests/test_versions.py +24 -0
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
### Deprecated
|
|
15
|
+
|
|
16
|
+
### Removed
|
|
17
|
+
|
|
18
|
+
### Fixed
|
|
19
|
+
|
|
20
|
+
### Security
|
|
21
|
+
|
|
22
|
+
### Dependencies
|
|
23
|
+
|
|
24
|
+
## [v0.1.0](https://github.com/Neluxx/beet-datapack-utils/releases/tag/v0.1.0) - 2026-11-17
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
- `Targets` service and `Target.patch` to copy, modify and write vanilla files for the base pack and every overlay
|
|
28
|
+
- `CARVER` and `FEATURE` registries for the 26.3 folder renames, `VersionedRegistry` for custom ones
|
|
29
|
+
- `worldgen_config`, `provider`, `set_range`, `resolve_key` and `octave_key` for fields that changed between versions
|
|
30
|
+
- `find_nodes` and `replace_nodes` for JSON trees, `unwrap` and `is_reference` for density functions
|
|
31
|
+
- `Version` for comparing Minecraft release versions
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Fabian Arndt
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: beet-datapack-utils
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Python library that provides helper functions for Minecraft datapacks using beet.
|
|
5
|
+
Keywords: minecraft,datapack,beet,worldgen,utility
|
|
6
|
+
Author: Fabian Arndt
|
|
7
|
+
Author-email: Fabian Arndt <fabian.arndt96@proton.me>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
+
Classifier: Topic :: Games/Entertainment
|
|
17
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Dist: beet>=0.119.0
|
|
20
|
+
Requires-Python: >=3.14
|
|
21
|
+
Project-URL: Repository, https://github.com/Neluxx/beet-datapack-utils
|
|
22
|
+
Project-URL: Issues, https://github.com/Neluxx/beet-datapack-utils/issues
|
|
23
|
+
Project-URL: Changelog, https://github.com/Neluxx/beet-datapack-utils/blob/main/CHANGELOG.md
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# beet-datapack-utils
|
|
27
|
+
|
|
28
|
+
A Python library with helpers for building multi-version Minecraft datapacks with [beet](https://github.com/mcbeet/beet).
|
|
29
|
+
|
|
30
|
+
Minecraft changes the datapack format regularly: folders are renamed, fields move or disappear. To support several Minecraft versions from one build, you need a base pack plus one overlay per version, and each of them needs its own patched copy of every vanilla file you change.
|
|
31
|
+
|
|
32
|
+
This library does that work for you. For the base pack and every overlay, it copies the matching vanilla file, smooths over the format differences and writes the patched file back. Your plugin only describes *what* to change.
|
|
33
|
+
|
|
34
|
+
## Features
|
|
35
|
+
|
|
36
|
+
- **One plugin for all versions:** loop over the base pack and all overlays with `Targets`.
|
|
37
|
+
- **Vanilla patching:** copy, edit and write a vanilla file in a single `with` block. Each vanilla version is downloaded once, and only when needed.
|
|
38
|
+
- **Version differences:** helpers for moved registries and renamed or restructured fields.
|
|
39
|
+
- **Safe density function edits:** search and replace nodes in JSON trees, and fail the build if the vanilla structure has changed.
|
|
40
|
+
|
|
41
|
+
## Quick start
|
|
42
|
+
|
|
43
|
+
**Requirements:** Python 3.14 or newer and a package manager. [uv](https://docs.astral.sh/uv/) is recommended.
|
|
44
|
+
|
|
45
|
+
**1. Install** the package in your datapack project:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
uv add beet-datapack-utils
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
**2. Configure `beet.yml`.** Set the Minecraft version of the base pack and of each overlay:
|
|
52
|
+
|
|
53
|
+
```yaml
|
|
54
|
+
pipeline:
|
|
55
|
+
- src.plugins.canyon
|
|
56
|
+
|
|
57
|
+
meta:
|
|
58
|
+
base_version: "1.21.9"
|
|
59
|
+
overlay_versions:
|
|
60
|
+
v26_3: "26.3"
|
|
61
|
+
|
|
62
|
+
data_pack:
|
|
63
|
+
min_format: 88 # 1.21.9
|
|
64
|
+
max_format: 121 # 26.3
|
|
65
|
+
overlays:
|
|
66
|
+
- directory: v26_3
|
|
67
|
+
min_format: 121
|
|
68
|
+
max_format: 121
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**3. Write a plugin** in e.g. `src/plugins/canyon.py`:
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
from beet import Context
|
|
75
|
+
|
|
76
|
+
from beet_datapack_utils import CARVER, Targets, worldgen_config
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def beet_default(ctx: Context):
|
|
80
|
+
for target in ctx.inject(Targets):
|
|
81
|
+
with target.patch(CARVER, "minecraft:canyon") as carver:
|
|
82
|
+
worldgen_config(carver)["probability"] = 0
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
**4. Build** the datapack:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
uv run beet build
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
This one plugin disables canyons in every version. Before 26.3 the file is `worldgen/configured_carver/canyon.json` and has a `config` object. From 26.3 on it is `worldgen/carver/canyon.json` and has no `config` object.
|
|
92
|
+
|
|
93
|
+
## Documentation
|
|
94
|
+
|
|
95
|
+
| Guide | Contents |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| [Installation](https://github.com/Neluxx/beet-datapack-utils/blob/main/docs/INSTALLATION.md) | Requirements, installing, building and updating |
|
|
98
|
+
| [Usage](https://github.com/Neluxx/beet-datapack-utils/blob/main/docs/USAGE.md) | Configuring `beet.yml` and an overview of all helpers |
|
|
99
|
+
| [Development](https://github.com/Neluxx/beet-datapack-utils/blob/main/docs/DEVELOPMENT.md) | Setup, tests, conventions and releasing |
|
|
100
|
+
| [Changelog](https://github.com/Neluxx/beet-datapack-utils/blob/main/CHANGELOG.md) | Changes in each release |
|
|
101
|
+
|
|
102
|
+
## License
|
|
103
|
+
|
|
104
|
+
[MIT](https://github.com/Neluxx/beet-datapack-utils/blob/main/LICENSE)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# beet-datapack-utils
|
|
2
|
+
|
|
3
|
+
A Python library with helpers for building multi-version Minecraft datapacks with [beet](https://github.com/mcbeet/beet).
|
|
4
|
+
|
|
5
|
+
Minecraft changes the datapack format regularly: folders are renamed, fields move or disappear. To support several Minecraft versions from one build, you need a base pack plus one overlay per version, and each of them needs its own patched copy of every vanilla file you change.
|
|
6
|
+
|
|
7
|
+
This library does that work for you. For the base pack and every overlay, it copies the matching vanilla file, smooths over the format differences and writes the patched file back. Your plugin only describes *what* to change.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **One plugin for all versions:** loop over the base pack and all overlays with `Targets`.
|
|
12
|
+
- **Vanilla patching:** copy, edit and write a vanilla file in a single `with` block. Each vanilla version is downloaded once, and only when needed.
|
|
13
|
+
- **Version differences:** helpers for moved registries and renamed or restructured fields.
|
|
14
|
+
- **Safe density function edits:** search and replace nodes in JSON trees, and fail the build if the vanilla structure has changed.
|
|
15
|
+
|
|
16
|
+
## Quick start
|
|
17
|
+
|
|
18
|
+
**Requirements:** Python 3.14 or newer and a package manager. [uv](https://docs.astral.sh/uv/) is recommended.
|
|
19
|
+
|
|
20
|
+
**1. Install** the package in your datapack project:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
uv add beet-datapack-utils
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
**2. Configure `beet.yml`.** Set the Minecraft version of the base pack and of each overlay:
|
|
27
|
+
|
|
28
|
+
```yaml
|
|
29
|
+
pipeline:
|
|
30
|
+
- src.plugins.canyon
|
|
31
|
+
|
|
32
|
+
meta:
|
|
33
|
+
base_version: "1.21.9"
|
|
34
|
+
overlay_versions:
|
|
35
|
+
v26_3: "26.3"
|
|
36
|
+
|
|
37
|
+
data_pack:
|
|
38
|
+
min_format: 88 # 1.21.9
|
|
39
|
+
max_format: 121 # 26.3
|
|
40
|
+
overlays:
|
|
41
|
+
- directory: v26_3
|
|
42
|
+
min_format: 121
|
|
43
|
+
max_format: 121
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**3. Write a plugin** in e.g. `src/plugins/canyon.py`:
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from beet import Context
|
|
50
|
+
|
|
51
|
+
from beet_datapack_utils import CARVER, Targets, worldgen_config
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def beet_default(ctx: Context):
|
|
55
|
+
for target in ctx.inject(Targets):
|
|
56
|
+
with target.patch(CARVER, "minecraft:canyon") as carver:
|
|
57
|
+
worldgen_config(carver)["probability"] = 0
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
**4. Build** the datapack:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
uv run beet build
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
This one plugin disables canyons in every version. Before 26.3 the file is `worldgen/configured_carver/canyon.json` and has a `config` object. From 26.3 on it is `worldgen/carver/canyon.json` and has no `config` object.
|
|
67
|
+
|
|
68
|
+
## Documentation
|
|
69
|
+
|
|
70
|
+
| Guide | Contents |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| [Installation](https://github.com/Neluxx/beet-datapack-utils/blob/main/docs/INSTALLATION.md) | Requirements, installing, building and updating |
|
|
73
|
+
| [Usage](https://github.com/Neluxx/beet-datapack-utils/blob/main/docs/USAGE.md) | Configuring `beet.yml` and an overview of all helpers |
|
|
74
|
+
| [Development](https://github.com/Neluxx/beet-datapack-utils/blob/main/docs/DEVELOPMENT.md) | Setup, tests, conventions and releasing |
|
|
75
|
+
| [Changelog](https://github.com/Neluxx/beet-datapack-utils/blob/main/CHANGELOG.md) | Changes in each release |
|
|
76
|
+
|
|
77
|
+
## License
|
|
78
|
+
|
|
79
|
+
[MIT](https://github.com/Neluxx/beet-datapack-utils/blob/main/LICENSE)
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Development
|
|
2
|
+
|
|
3
|
+
## Requirements
|
|
4
|
+
|
|
5
|
+
- [Python](https://www.python.org/) 3.14 or newer
|
|
6
|
+
- [uv](https://docs.astral.sh/uv/)
|
|
7
|
+
|
|
8
|
+
## Setup
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
git clone https://github.com/Neluxx/beet-datapack-utils.git
|
|
12
|
+
cd beet-datapack-utils
|
|
13
|
+
uv sync
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`uv sync` creates the virtual environment and installs the package together with its development dependencies.
|
|
17
|
+
|
|
18
|
+
## Tests and code style
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
uv run pytest # tests, including doctests in src/
|
|
22
|
+
uv run ruff check # linting
|
|
23
|
+
uv run ruff format # formatting
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The tests replace beet's `Vanilla` service with a small in-memory fake (see `tests/conftest.py`), so they run offline and never download Minecraft.
|
|
27
|
+
|
|
28
|
+
CI runs `ruff format --check`, `ruff check`, `pytest` and `uv build` on every pull request and on every push to `main`.
|
|
29
|
+
|
|
30
|
+
## Testing changes in a datapack
|
|
31
|
+
|
|
32
|
+
To try unreleased changes, point your datapack's `pyproject.toml` to your local checkout:
|
|
33
|
+
|
|
34
|
+
```toml
|
|
35
|
+
[tool.uv.sources]
|
|
36
|
+
beet-datapack-utils = { path = "../beet-datapack-utils", editable = true }
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Then run `uv sync` and `uv run beet build` in the datapack. Remove the entry again before you commit.
|
|
40
|
+
|
|
41
|
+
## Project structure
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
.
|
|
45
|
+
├── docs/ # Documentation
|
|
46
|
+
├── src/beet_datapack_utils/
|
|
47
|
+
│ ├── __init__.py # Public API
|
|
48
|
+
│ ├── targets.py # Targets service and Target
|
|
49
|
+
│ ├── registries.py # CARVER, FEATURE, VersionedRegistry
|
|
50
|
+
│ ├── fields.py # Fields that changed between versions
|
|
51
|
+
│ ├── trees.py # find_nodes, replace_nodes
|
|
52
|
+
│ ├── density.py # Density function helpers
|
|
53
|
+
│ └── versions.py # Version parsing and comparison
|
|
54
|
+
├── tests/
|
|
55
|
+
├── CHANGELOG.md
|
|
56
|
+
└── pyproject.toml
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
When you add a public helper, export it in `__init__.py` (including `__all__`) and add it to the helper tables in [USAGE.md](USAGE.md).
|
|
60
|
+
|
|
61
|
+
## Conventions
|
|
62
|
+
|
|
63
|
+
- **Commits** follow [Conventional Commits](https://www.conventionalcommits.org/): `<type>: <short description>`. Common types are `feat`, `fix`, `docs`, `refactor`, `chore`, `build` and `style`.
|
|
64
|
+
- **Changelog:** add every user-facing change to the `Unreleased` section of [CHANGELOG.md](../CHANGELOG.md).
|
|
65
|
+
- **Versioning** follows [Semantic Versioning](https://semver.org/). Renaming or removing a public function requires a major version bump.
|
|
66
|
+
|
|
67
|
+
## Releasing
|
|
68
|
+
|
|
69
|
+
1. Update `version` in `pyproject.toml` and move the `Unreleased` entries in `CHANGELOG.md` to a new version section.
|
|
70
|
+
2. Commit, tag and push:
|
|
71
|
+
```bash
|
|
72
|
+
git tag v1.1.0
|
|
73
|
+
git push origin v1.1.0
|
|
74
|
+
```
|
|
75
|
+
3. The release workflow checks that the tag matches the package version, runs the tests, builds the package and publishes it to [TestPyPI](https://test.pypi.org/project/beet-datapack-utils/).
|
|
76
|
+
4. Check the TestPyPI release, then approve the `pypi` deployment in the workflow run. The same files are then published to [PyPI](https://pypi.org/project/beet-datapack-utils/) and attached to a new GitHub release.
|
|
77
|
+
5. In each datapack, run `uv lock --upgrade-package beet-datapack-utils`.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Installation
|
|
2
|
+
|
|
3
|
+
## Requirements
|
|
4
|
+
|
|
5
|
+
- [Python](https://www.python.org/) 3.14 or newer
|
|
6
|
+
- [beet](https://github.com/mcbeet/beet) 0.119.0 or newer (installed automatically as a dependency)
|
|
7
|
+
- A package manager. [uv](https://docs.astral.sh/uv/) is recommended.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
Run this in your datapack project:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
uv add beet-datapack-utils
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
If you use pip instead:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install beet-datapack-utils
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
You can also add the package to your `pyproject.toml` yourself and then run `uv lock`:
|
|
24
|
+
|
|
25
|
+
```toml
|
|
26
|
+
[project]
|
|
27
|
+
dependencies = [
|
|
28
|
+
"beet>=0.119.0",
|
|
29
|
+
"beet-datapack-utils>=0.1.0",
|
|
30
|
+
]
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Build
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
uv run beet build
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Use `uv run beet`, not `uvx beet`. `uvx` runs beet in an isolated environment without your project's dependencies, so importing `beet_datapack_utils` fails.
|
|
40
|
+
|
|
41
|
+
The first build that reads vanilla files downloads the Minecraft versions it needs. Packs that only write their own files build offline.
|
|
42
|
+
|
|
43
|
+
## Update
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
uv lock --upgrade-package beet-datapack-utils
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Check the [changelog](../CHANGELOG.md) before updating. A new major version may rename or remove public functions.
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Usage
|
|
2
|
+
|
|
3
|
+
## Configuring `beet.yml`
|
|
4
|
+
|
|
5
|
+
The library reads two keys from `meta`:
|
|
6
|
+
|
|
7
|
+
| Key | Required | Description |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `base_version` | Yes | Minecraft version of the base pack |
|
|
10
|
+
| `overlay_versions` | No | Mapping of overlay directory to Minecraft version |
|
|
11
|
+
|
|
12
|
+
```yaml
|
|
13
|
+
pipeline:
|
|
14
|
+
- src.plugins.canyon
|
|
15
|
+
|
|
16
|
+
meta:
|
|
17
|
+
base_version: "1.21.9"
|
|
18
|
+
overlay_versions:
|
|
19
|
+
v26_3: "26.3"
|
|
20
|
+
|
|
21
|
+
data_pack:
|
|
22
|
+
min_format: 88 # 1.21.9
|
|
23
|
+
max_format: 121 # 26.3
|
|
24
|
+
overlays:
|
|
25
|
+
- directory: v26_3
|
|
26
|
+
min_format: 121
|
|
27
|
+
max_format: 121
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- **Base version:** use the oldest version you support. The base pack is built from that version's vanilla files, but every version in its format range that no overlay covers loads it.
|
|
31
|
+
- **Overlays:** add one for each version that changed a file you patch. Each key in `overlay_versions` should match a `directory` in `data_pack.overlays`. If a directory isn't listed there, it gets beet's default pack format.
|
|
32
|
+
- **Pack formats:** the library doesn't set them. Set them in `data_pack` as you normally would in beet. If you leave them out, beet uses the format of the newest Minecraft version it knows.
|
|
33
|
+
- **Versions:** only release versions like `1.21.9` or `26.3` work. Snapshots and pre-releases (`25w45a`, `1.21.9-pre1`) don't.
|
|
34
|
+
- **Pipeline:** `src.plugins.canyon` refers to `src/plugins/canyon.py` in your project. That file must contain a `beet_default(ctx)` function.
|
|
35
|
+
|
|
36
|
+
## Writing a plugin
|
|
37
|
+
|
|
38
|
+
Inject `Targets` and loop over it. You get one `Target` for the base pack and one for each overlay:
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
from beet import Context
|
|
42
|
+
|
|
43
|
+
from beet_datapack_utils import CARVER, Targets, worldgen_config
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def beet_default(ctx: Context):
|
|
47
|
+
for target in ctx.inject(Targets):
|
|
48
|
+
with target.patch(CARVER, "minecraft:canyon") as carver:
|
|
49
|
+
worldgen_config(carver)["probability"] = 0
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Helpers
|
|
53
|
+
|
|
54
|
+
Everything below can be imported directly from `beet_datapack_utils`.
|
|
55
|
+
|
|
56
|
+
### Targets
|
|
57
|
+
|
|
58
|
+
| Name | Description |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `Targets` | Beet service (`ctx.inject(Targets)`) that yields one `Target` for the base pack and one for each overlay. All plugins in a build share it, so each vanilla version is loaded only once. Supports `len()`. Raises `KeyError` if `meta.base_version` is missing. |
|
|
61
|
+
| `Target.pack` | The output pack this target writes to |
|
|
62
|
+
| `Target.version` | The target's Minecraft `Version` |
|
|
63
|
+
| `Target.directory` | The overlay directory, or `None` for the base pack |
|
|
64
|
+
| `Target.is_overlay` | `True` for overlays, `False` for the base pack |
|
|
65
|
+
| `Target.at_least(version)` | `True` if the target's version is `version` or newer |
|
|
66
|
+
| `Target.patch(registry, name)` | Context manager that copies a vanilla file, yields its JSON for editing and writes it into the target pack. Nothing is written if the block raises an error. |
|
|
67
|
+
| `Target.copy(registry, name)` | Returns an independent copy of a vanilla file. Raises `KeyError` if the file doesn't exist in the target's version. |
|
|
68
|
+
| `Target.write(registry, name, file)` | Writes a file into the target pack |
|
|
69
|
+
| `Target.file_type(registry)` | The beet file type that `registry` resolves to for the target's version |
|
|
70
|
+
| `Target.vanilla` | The vanilla data pack for the target's version. It is downloaded the first time you access it. |
|
|
71
|
+
| `Target.inline_density_function(node)` | If `node` is an ID, returns a copy of that vanilla density function. Otherwise returns `node` unchanged. |
|
|
72
|
+
|
|
73
|
+
### Registries
|
|
74
|
+
|
|
75
|
+
You can pass any beet file type (for example, `WorldgenNoise`) as `registry`. For resources whose folder moved between versions, pass a `VersionedRegistry` instead.
|
|
76
|
+
|
|
77
|
+
| Name | Description |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| `CARVER` | `worldgen/configured_carver` before 26.3, `worldgen/carver` from 26.3 on |
|
|
80
|
+
| `FEATURE` | `worldgen/configured_feature` before 26.3, `worldgen/feature` from 26.3 on |
|
|
81
|
+
| `VersionedRegistry(default, changes)` | Defines your own moved registry. Example: `VersionedRegistry(OldType, (("26.3", NewType),))` |
|
|
82
|
+
| `resolve_registry(registry, version)` | Returns the file type a registry uses in a given version |
|
|
83
|
+
|
|
84
|
+
### Fields
|
|
85
|
+
|
|
86
|
+
| Name | Description |
|
|
87
|
+
| --- | --- |
|
|
88
|
+
| `worldgen_config(data)` | Returns the settings object of a carver or feature (the `config` wrapper was removed in 26.3) |
|
|
89
|
+
| `provider(config, name)` | Returns the int/float provider `name`, unwrapping the `value` object used before 1.20.5. Raises `TypeError` if the field is a constant. |
|
|
90
|
+
| `set_range(provider, minimum, maximum)` | Sets `min_inclusive` and either `max_exclusive` or `max_inclusive`, whichever the provider uses. Raises `KeyError` if the provider isn't a range. |
|
|
91
|
+
| `resolve_key(data, *candidates)` | Returns the first key that exists, for renamed fields (e.g. `yScale` → `room_vertical_radius_multiplier`). Raises `KeyError` if none of them exist. |
|
|
92
|
+
| `octave_key(noise)` | Returns `firstOctave` or `base_octave`, the name used from 26.3 on |
|
|
93
|
+
|
|
94
|
+
### JSON trees and density functions
|
|
95
|
+
|
|
96
|
+
| Name | Description |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| `find_nodes(tree, match)` | Yields every node below `tree` (depth first, not including `tree` itself) for which `match(node)` returns `True` |
|
|
99
|
+
| `replace_nodes(tree, match, replacement, expected=None)` | Replaces matching nodes below `tree` and returns how many it replaced. It doesn't descend into replaced nodes. If you pass `expected` and the number of matches differs, it raises `ValueError` and changes nothing. |
|
|
100
|
+
| `unwrap(node)` | Removes caching and interpolation wrappers (`cache_once`, `interpolated`, …) from a density function |
|
|
101
|
+
| `is_reference(node, function_id)` | `True` if `node` references `function_id`, directly or through wrappers |
|
|
102
|
+
| `WRAPPER_TYPES` | The set of density function types that `unwrap` removes |
|
|
103
|
+
|
|
104
|
+
### Versions
|
|
105
|
+
|
|
106
|
+
| Name | Description |
|
|
107
|
+
| --- | --- |
|
|
108
|
+
| `Version(version)` | A Minecraft release version that compares with other versions and plain strings, e.g. `Version("1.21.9") < "26.3"`. `1.21` and `1.21.0` count as equal. Raises `ValueError` for snapshots and pre-releases. |
|
|
109
|
+
| `parse_version(version)` | Same as `Version(version)` |
|
|
110
|
+
| `VersionLike` | Type alias for `Version \| str` |
|
|
111
|
+
| `RegistryLike` | Type alias for a beet file type or a `VersionedRegistry` |
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build>=0.13.8,<0.14"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "beet-datapack-utils"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "A Python library that provides helper functions for Minecraft datapacks using beet."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.14"
|
|
13
|
+
keywords = [
|
|
14
|
+
"minecraft",
|
|
15
|
+
"datapack",
|
|
16
|
+
"beet",
|
|
17
|
+
"worldgen",
|
|
18
|
+
"utility",
|
|
19
|
+
]
|
|
20
|
+
classifiers = [
|
|
21
|
+
"Development Status :: 4 - Beta",
|
|
22
|
+
"Intended Audience :: Developers",
|
|
23
|
+
"Operating System :: OS Independent",
|
|
24
|
+
"Programming Language :: Python :: 3",
|
|
25
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
26
|
+
"Programming Language :: Python :: 3.14",
|
|
27
|
+
"Topic :: Games/Entertainment",
|
|
28
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
29
|
+
"Typing :: Typed",
|
|
30
|
+
]
|
|
31
|
+
dependencies = ["beet>=0.119.0"]
|
|
32
|
+
|
|
33
|
+
[[project.authors]]
|
|
34
|
+
name = "Fabian Arndt"
|
|
35
|
+
email = "fabian.arndt96@proton.me"
|
|
36
|
+
|
|
37
|
+
[project.urls]
|
|
38
|
+
Repository = "https://github.com/Neluxx/beet-datapack-utils"
|
|
39
|
+
Issues = "https://github.com/Neluxx/beet-datapack-utils/issues"
|
|
40
|
+
Changelog = "https://github.com/Neluxx/beet-datapack-utils/blob/main/CHANGELOG.md"
|
|
41
|
+
|
|
42
|
+
[dependency-groups]
|
|
43
|
+
dev = [
|
|
44
|
+
"pytest>=8",
|
|
45
|
+
"ruff>=0.6",
|
|
46
|
+
]
|
|
47
|
+
|
|
48
|
+
[tool.uv.build-backend]
|
|
49
|
+
source-include = [
|
|
50
|
+
"tests/**",
|
|
51
|
+
"docs/**",
|
|
52
|
+
"CHANGELOG.md",
|
|
53
|
+
]
|
|
54
|
+
|
|
55
|
+
[tool.pytest.ini_options]
|
|
56
|
+
testpaths = [
|
|
57
|
+
"src",
|
|
58
|
+
"tests",
|
|
59
|
+
]
|
|
60
|
+
addopts = [
|
|
61
|
+
"--doctest-modules",
|
|
62
|
+
"--import-mode=importlib",
|
|
63
|
+
]
|
|
64
|
+
|
|
65
|
+
[tool.ruff]
|
|
66
|
+
line-length = 100
|
|
67
|
+
src = [
|
|
68
|
+
"src",
|
|
69
|
+
"tests",
|
|
70
|
+
]
|
|
71
|
+
|
|
72
|
+
[tool.ruff.lint]
|
|
73
|
+
select = [
|
|
74
|
+
"E",
|
|
75
|
+
"F",
|
|
76
|
+
"W",
|
|
77
|
+
"I",
|
|
78
|
+
"B",
|
|
79
|
+
"UP",
|
|
80
|
+
"SIM",
|
|
81
|
+
"RUF",
|
|
82
|
+
]
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build>=0.13.8,<0.14"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "beet-datapack-utils"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "A Python library that provides helper functions for Minecraft datapacks using beet."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "Fabian Arndt", email = "fabian.arndt96@proton.me" }]
|
|
13
|
+
requires-python = ">=3.14"
|
|
14
|
+
keywords = [
|
|
15
|
+
"minecraft",
|
|
16
|
+
"datapack",
|
|
17
|
+
"beet",
|
|
18
|
+
"worldgen",
|
|
19
|
+
"utility",
|
|
20
|
+
]
|
|
21
|
+
classifiers = [
|
|
22
|
+
"Development Status :: 4 - Beta",
|
|
23
|
+
"Intended Audience :: Developers",
|
|
24
|
+
"Operating System :: OS Independent",
|
|
25
|
+
"Programming Language :: Python :: 3",
|
|
26
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
27
|
+
"Programming Language :: Python :: 3.14",
|
|
28
|
+
"Topic :: Games/Entertainment",
|
|
29
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
30
|
+
"Typing :: Typed",
|
|
31
|
+
]
|
|
32
|
+
dependencies = [
|
|
33
|
+
"beet>=0.119.0",
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Repository = "https://github.com/Neluxx/beet-datapack-utils"
|
|
38
|
+
Issues = "https://github.com/Neluxx/beet-datapack-utils/issues"
|
|
39
|
+
Changelog = "https://github.com/Neluxx/beet-datapack-utils/blob/main/CHANGELOG.md"
|
|
40
|
+
|
|
41
|
+
[dependency-groups]
|
|
42
|
+
dev = [
|
|
43
|
+
"pytest>=8",
|
|
44
|
+
"ruff>=0.6",
|
|
45
|
+
]
|
|
46
|
+
|
|
47
|
+
[tool.uv.build-backend]
|
|
48
|
+
source-include = [
|
|
49
|
+
"tests/**",
|
|
50
|
+
"docs/**",
|
|
51
|
+
"CHANGELOG.md",
|
|
52
|
+
]
|
|
53
|
+
|
|
54
|
+
[tool.pytest.ini_options]
|
|
55
|
+
testpaths = ["src", "tests"]
|
|
56
|
+
addopts = ["--doctest-modules", "--import-mode=importlib"]
|
|
57
|
+
|
|
58
|
+
[tool.ruff]
|
|
59
|
+
line-length = 100
|
|
60
|
+
src = ["src", "tests"]
|
|
61
|
+
|
|
62
|
+
[tool.ruff.lint]
|
|
63
|
+
select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Helper functions for Minecraft datapacks using beet.
|
|
2
|
+
|
|
3
|
+
A datapack build has a base pack and overlays, each for a Minecraft version
|
|
4
|
+
(`meta.base_version` and `meta.overlay_versions` in the beet config). These
|
|
5
|
+
helpers copy the matching vanilla files, hide format differences between
|
|
6
|
+
versions and write the patched files back.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from .density import WRAPPER_TYPES, is_reference, unwrap
|
|
10
|
+
from .fields import octave_key, provider, resolve_key, set_range, worldgen_config
|
|
11
|
+
from .registries import CARVER, FEATURE, RegistryLike, VersionedRegistry, resolve_registry
|
|
12
|
+
from .targets import Target, Targets
|
|
13
|
+
from .trees import find_nodes, replace_nodes
|
|
14
|
+
from .versions import Version, VersionLike, parse_version
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"CARVER",
|
|
18
|
+
"FEATURE",
|
|
19
|
+
"WRAPPER_TYPES",
|
|
20
|
+
"RegistryLike",
|
|
21
|
+
"Target",
|
|
22
|
+
"Targets",
|
|
23
|
+
"Version",
|
|
24
|
+
"VersionLike",
|
|
25
|
+
"VersionedRegistry",
|
|
26
|
+
"find_nodes",
|
|
27
|
+
"is_reference",
|
|
28
|
+
"octave_key",
|
|
29
|
+
"parse_version",
|
|
30
|
+
"provider",
|
|
31
|
+
"replace_nodes",
|
|
32
|
+
"resolve_key",
|
|
33
|
+
"resolve_registry",
|
|
34
|
+
"set_range",
|
|
35
|
+
"unwrap",
|
|
36
|
+
"worldgen_config",
|
|
37
|
+
]
|