Datapack Sandbox Development Roadmap
When to use this page
This page is for contributors who need the completed capabilities, future priorities, acceptance criteria, and clean-room boundary. Most datapack authors can skip it.
Prerequisites
Read the user-facing command, resource, and version references first. Code contributors also need JDK 25 and the repository Gradle wrapper.
Minimal runnable example
Run .\gradlew.bat releaseCheck from PowerShell to exercise the module, documentation, schema, API, example, and release-artifact gates described by the roadmap.
Full capabilities
This roadmap describes the documentation-facing development direction for Datapack Sandbox. It mirrors the Chinese roadmap at a higher level and gives English readers the project structure, priority model, and verification expectations.
Goals
Datapack Sandbox is a clean-room runtime for deterministic local datapack tests. The project aims to make datapack behavior testable without launching a full Minecraft server, while still keeping resource validation, command behavior, and observable output close enough to vanilla semantics for practical regression testing.
The documentation site is organized around four audiences:
| Audience | Primary docs |
|---|---|
| Library users writing JVM tests | Code Test API |
| Datapack authors checking runtime support | Command Support and Resource Formats |
| Tool authors integrating the sandbox | Runtime World Model and Version Profiles |
| Contributors extending behavior | This roadmap and implementation-linked command/resource matrices |
Phase 1: Resource Coverage
Improve resource indexing and validation for functions, tags, advancements, loot tables, predicates, recipes, and related JSON/SNBT inputs.
Expected documentation outcomes:
- Resource behavior levels remain explicit.
- Manifest examples cover common and failure cases.
pack_format,supported_formats,min_format, andmax_formatbehavior is documented with warnings and version-profile guidance.
Phase 2: Command Semantics
Expand command modeling from parse-level checks to observable runtime behavior.
Expected documentation outcomes:
- The command support matrix stays synchronized with implementation.
- Each modeled command records behavior level, limitations, trace visibility, and output behavior.
- Text-producing commands expose both rendered output and raw message content where applicable.
Phase 3: World, Entity, and Player State
Keep the runtime model intentionally sparse, deterministic, and test-oriented while covering the state that datapacks commonly inspect or mutate.
Expected documentation outcomes:
- The runtime world model explains what is stored, what is approximated, and what is intentionally out of scope.
- Fixture and Java save import behavior is documented with clear boundaries.
- Snapshot and diff assertions remain stable enough for regression tests.
Phase 4: Player Events
Expose reproducible player interaction events for testing advancement, predicate, item, block, damage, and input-driven logic.
Expected documentation outcomes:
- REPL, CLI, manifest, and code-test entry points use the same event vocabulary.
- Event traces document success, matching context, and relevant metadata.
Phase 5: Test API Ergonomics
Make the code API easy to discover from IDE completion.
Expected documentation outcomes:
- String parameters that represent fixed option sets also have enum overloads.
- Assertions document required parameters, optional filters, count semantics, and failure reporting.
- Examples prefer practical test workflows instead of only low-level runtime construction.
Phase 6: Version Profiles
Version profiles should keep Minecraft format decisions explainable and reproducible.
Expected documentation outcomes:
- Profile tables list pack/resource formats and vanilla-data assumptions.
- Incompatibilities should be warnings when the sandbox can still continue.
- Array format values such as
[104, 1]are documented as dotted format values.
Release Quality
Before a release, the documentation should satisfy these checks:
- VitePress builds successfully.
- CLI-generated command, resource, and version-profile tables pass their drift checks.
- Code API examples compile or are covered by focused tests.
- Chinese and English navigation expose equivalent core pages.
Limitations
This roadmap records direction and acceptance criteria, not release-date commitments. Current behavior is defined by drift-checked command, resource, and version references plus the public API baselines.