How runtoolkit/datalib works
1. What this repo is
- dataLib is a pure Minecraft Java datapack: there are no external binaries or scripts, only .mcfunction, JSON, and resource assets.
- The architecture is built around vanilla datapack primitives: function tags, scoreboards, storage NBT, predicates, advancements, loot tables, and item modifiers.
2. Bootstrapping and lifecycle
- Startup is split across the vanilla load/tick hooks and a Lantern Load–style load pipeline.
- data/minecraft/tags/function/load.json and tick.json are the main engine entrypoints.
- data/load and data/dl_load provide deterministic load ordering, validation, version checks, safe-load/confirmation flow, and failure/disable paths before the library is considered ready.
3. Main runtime kernel
- The data/datalib/function/core tree is the execution kernel.
- It contains the scheduler/queue, batch execution, cooldowns, state/config storage, dispatch, fallback handling, and the central tick loop.
- Persistent engine state is centered on the datalib:engine storage described in the README, with separate areas for global state, players, queue, cooldowns, and event registrations.
4. Public API surface
- data/datalib/function/api is the low-level callable API for pack authors.
- It exposes wrappers for commands, player/title/chat helpers, permissions, triggers, wands, dialogs, toggles, security, and generic callback/macro helpers.
- These API functions are meant to be the stable boundary; the implementation details live under core/internal.
5. Higher-level systems layer
- data/datalib/function/systems contains user-facing subsystems built on top of the kernel.
- Major groups include math, string, nbt, uuid, geo, hook, rate_limit, log, sound, flag, logic, and security.
- This layer is where most reusable game logic lives; it is the main “library” surface for other datapacks.
6. Event and callback model
- Events are first-class: there is an event registry and fire/queue flow under data/datalib/function/events and core/internal/events.
- Callbacks support immediate, delayed, queued, and sequenced execution.
- The system is designed so gameplay actions become event emissions, and downstream functions are invoked through the queue/dispatch layer rather than directly.
7. Player action detection subsystem
- data/player_action is a separate compatibility and detection pipeline for player interactions that vanilla does not expose directly as simple function hooks.
- It uses advancement-driven triggers plus versioned functions (v1.7) to detect actions such as left click, right click, GUI opening, jumping, joining, dying, and many block interactions.
- This subsystem bridges vanilla advancement events into the library’s internal hook/event system.
8. Hooking, region watching, and gameplay triggers
- systems/hook and core/internal/systems/hook connect detected player/world actions to registered handlers.
- systems/geo/region_watch tracks player movement across configured regions and fires enter/leave style callbacks.
- These systems are tick-scanned and rely on per-player/per-region bookkeeping, making them stateful and performance-sensitive parts of the library.
9. Security, permissions, and rate limiting
- The repo has a substantial safety boundary in core/security and systems/security.
- Command execution can be sandboxed, blocked, type-checked, or routed through confirmation flows.
- Permissions and triggers are separate concepts: permissions control authorization, while triggers/wands/hooks control what action fires.
- Rate limiting exists at global, channel, and player scope, so expensive or spammy actions can be throttled.
10. Utility libraries and data flow conventions
- Many functions follow a storage-in / storage-out convention.
- The README’s datalib:input and datalib:output storages are the main functional I/O boundary for utilities like string processing.
- data/stringlib vendors the upstream StringLib implementation, while datalib:core/lib/string/* acts as the public adapter.
- UUID, NBT, math, and string helpers are implemented as internal function graphs with private helper namespaces.
11. Player/world abstractions
- data/datalib/function/player and world provide convenience wrappers for common game-state operations: health, position, inventory, gamemode, entity iteration, fills, teleportation, and block checks.
- These are not the core runtime; they are ergonomic utility façades over Minecraft commands and storage/state operations.
- The repository also includes helper predicates, loot tables, and item modifiers that support these abstractions.
12. UI, audio, and localization
- assets/ contains localized language files and sound assets used by dialogs, menus, notifications, and feedback events.
- This is a small but important presentation layer for player-facing interactions such as confirmations, errors, and permission grants/denials.
13. Pack data and content definitions
- data/datalib/predicate, data/datalib/advancement, data/datalib/item_modifier, and data/datalib/loot_table define reusable vanilla data assets.
- These definitions are part of the architecture because they power event detection, item transformation, and environment checks without requiring extra code paths.
14. How to diagram it
- A good architecture diagram should show:
- Vanilla entrypoints → load/tick tags
- Bootstrapping layer → dl_load / load
- Core runtime → queue, dispatcher, state, security, scheduler
- Public API / systems → reusable functions for other packs
- Event sources → advancements, player_action, hooks, region watchers
- Persistent storage → datalib:engine, datalib:input, datalib:output
- Data assets → predicates, advancements, loot tables, modifiers, sounds, langs
- The key boundary is between the stable public surface and the internal execution engine.
Main entry points: tick.mcfunction Core Tick · api API Surface · dl_load DL Load · systems Systems Layer
Components 18
Bootstrapping
Vanilla entrypoints and deterministic load pipeline.
- Vanilla Hooks · Minecraft load/tick function tags that start the pack lifecycle.
data/minecraft/tags/function - Load Pipeline · Deterministic load ordering, validation, safe-load confirmation, and finalize/disable paths.
data/load - DL Load · Lantern-style load stage handling version checks, fork warnings, and readiness setup.
data/dl_load
Runtime Core
Scheduler, queue, dispatch, state, security, and engine internals.
- Core Tick · Central tick loop and channel dispatch orchestration.
data/datalib/function/core/tick.mcfunction - Queue Engine · Queued execution, batching, flushing, and rate-controlled processing.
data/datalib/function/core/queue - Engine State · Global, player, config, and scoreboard-backed state access for the engine.
data/datalib/function/core/state - Security Gate · Sandboxing, type checks, confirmations, and permission enforcement for command execution.
data/datalib/function/core/security - Event Core · Event registry plus immediate, deferred, queued, and sequenced firing paths.
data/datalib/function/core/internal/events - Dispatch Lib · Batch, fiber, repeat, schedule, debounce, and queue primitives used by the runtime kernel.
data/datalib/function/core/internal/core/lib
Public Surface
Stable API and reusable systems for pack authors.
- API Surface · Stable callable boundary for command, callback, permission, trigger, wand, dialog, and utility helpers.
data/datalib/function/api - Systems Layer · Reusable gameplay and utility subsystems built on top of the kernel.
data/datalib/function/systems - Player Tools · Convenience wrappers for player stats, inventory, variables, teams, and execution helpers.
data/datalib/function/player - World Tools · Block, entity, fill, teleport, and world-state helpers exposed as ergonomic wrappers.
data/datalib/function/world
Event Pipelines
Vanilla-to-library event sources and hook bridges.
- Hook System · Registered gameplay hooks for clicks, dimension changes, combat, trading, interaction, and movement.
data/datalib/function/systems/hook - Region Watch · Tick-scanned enter/leave callbacks for configured regions and nearby players.
data/datalib/function/systems/geo/region_watch - Player Action · Versioned advancement-driven detection for interactions vanilla does not expose directly.
data/player_action
Data Assets
Predicates, advancements, loot tables, item modifiers, and assets.
- Data Assets · Predicates, advancements, loot tables, item modifiers, localization, and sounds supporting the library.
data/datalib - StringLib Vendor · Upstream StringLib implementation with private helpers and public adapters.
data/stringlib
Connections 23
- Vanilla Hooks → Load Pipeline: load · Load tag enters the deterministic bootstrap flow.
- Vanilla Hooks → Core Tick: tick · Tick tag drives the main runtime loop.
- Load Pipeline → DL Load: handoff · Bootstrap validation and confirmation proceed through the load stages.
- DL Load → Engine State: init state · Load stages prepare persistent storage and engine readiness.
- DL Load → Security Gate: validate · Safe-load and confirmation flows route through security checks.
- DL Load → Data Assets: register data · Load stage wires predicates, advancements, and other reusable data assets.
- Core Tick → Queue Engine: process · Tick loop flushes queued work and scheduled actions.
- Core Tick → Event Core: fire events · Tick processing advances deferred and queued events.
- Core Tick → Hook System: scan hooks · Tick scans gameplay hooks and dispatches registered handlers.
- Core Tick → Region Watch: scan regions · Tick updates region membership and enter/leave callbacks.
- Core Tick → Player Action: scan actions · Versioned detection pipeline advances player interaction triggers.
- Dispatch Lib → Queue Engine: backing ops · Internal batch, fiber, schedule, and queue primitives power the queue engine.
- Dispatch Lib → Event Core: dispatch support · Deferred and sequenced event execution depends on internal dispatch primitives.
- API Surface → Queue Engine: enqueue · Public callbacks and helpers schedule work through the queue layer.
- API Surface → Security Gate: guarded exec · Command-facing APIs are filtered through the security gate.
- API Surface → Player Tools: wraps · Player-oriented API calls delegate to player façade functions.
- API Surface → World Tools: wraps · World-oriented API calls delegate to world façade functions.
- Systems Layer → Hook System: uses · User-facing systems expose hook registration and event reactions.
- Systems Layer → Region Watch: uses · Geo utilities expose region registration and scanning.
- Systems Layer → StringLib Vendor: adapts · Public string helpers bridge to the vendored StringLib implementation.
- Hook System → Player Action: consumes · Hook handlers consume advancement-driven action detections.
- Player Action → Data Assets: depends on · Advancement and predicate assets drive action detection.
- Data Assets → Event Core: feeds · Advancements and predicates emit events into the library event model.