# runtoolkit/datalib architecture

> Architecture diagram of the GitHub repository runtoolkit/datalib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/runtoolkit/datalib
- Repository: https://github.com/runtoolkit/datalib

## Overview

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: [`data/datalib/function/core/tick.mcfunction`](https://github.com/runtoolkit/datalib/blob/main/data/datalib/function/core/tick.mcfunction) (Core Tick), [`data/datalib/function/api`](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/api) (API Surface), [`data/dl_load`](https://github.com/runtoolkit/datalib/tree/main/data/dl_load) (DL Load), [`data/datalib/function/systems`](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/systems) (Systems Layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Bootstrapping"]
  node_minecraft_hooks["Vanilla Hooks<br/>entry tags"]
  node_load_pipeline["Load Pipeline<br/>bootstrap flow"]
  node_dl_load["DL Load<br/>bootstrap flow"]
end

subgraph group_runtime["Runtime Core"]
  node_core_tick["Core Tick<br/>runtime loop<br/>[tick.mcfunction]"]
  node_core_queue["Queue Engine<br/>scheduler"]
  node_core_state[("Engine State<br/>persistent state")]
  node_core_security["Security Gate<br/>policy layer"]
  node_core_events["Event Core<br/>dispatch model"]
  node_core_internal_schedulers["Dispatch Lib<br/>execution internals"]
end

subgraph group_surface["Public Surface"]
  node_api_surface["API Surface<br/>public functions"]
  node_systems_surface["Systems Layer<br/>library systems"]
  node_player_abstractions["Player Tools<br/>player facade"]
  node_world_abstractions["World Tools<br/>world facade"]
end

subgraph group_events["Event Pipelines"]
  node_hook_system["Hook System<br/>event bridge"]
  node_region_watch["Region Watch<br/>spatial watch"]
  node_player_action["Player Action<br/>advancement pipeline"]
end

subgraph group_content["Data Assets"]
  node_data_assets["Data Assets<br/>vanilla data"]
  node_stringlib_vendor["StringLib Vendor<br/>vendored lib"]
end

node_minecraft_hooks -->|"load"| node_load_pipeline
node_minecraft_hooks -->|"tick"| node_core_tick
node_load_pipeline -->|"handoff"| node_dl_load
node_dl_load -->|"init state"| node_core_state
node_dl_load -->|"validate"| node_core_security
node_dl_load -->|"register data"| node_data_assets
node_core_tick -->|"process"| node_core_queue
node_core_tick -->|"fire events"| node_core_events
node_core_tick -->|"scan hooks"| node_hook_system
node_core_tick -->|"scan regions"| node_region_watch
node_core_tick -->|"scan actions"| node_player_action
node_core_internal_schedulers -->|"backing ops"| node_core_queue
node_core_internal_schedulers -->|"dispatch support"| node_core_events
node_api_surface -->|"enqueue"| node_core_queue
node_api_surface -->|"guarded exec"| node_core_security
node_api_surface -->|"wraps"| node_player_abstractions
node_api_surface -->|"wraps"| node_world_abstractions
node_systems_surface -->|"uses"| node_hook_system
node_systems_surface -->|"uses"| node_region_watch
node_systems_surface -->|"adapts"| node_stringlib_vendor
node_hook_system -->|"consumes"| node_player_action
node_player_action -->|"depends on"| node_data_assets
node_data_assets -->|"feeds"| node_core_events

click node_minecraft_hooks "https://github.com/runtoolkit/datalib/tree/main/data/minecraft/tags/function"
click node_load_pipeline "https://github.com/runtoolkit/datalib/tree/main/data/load"
click node_dl_load "https://github.com/runtoolkit/datalib/tree/main/data/dl_load"
click node_core_tick "https://github.com/runtoolkit/datalib/blob/main/data/datalib/function/core/tick.mcfunction"
click node_core_queue "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/queue"
click node_core_state "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/state"
click node_core_security "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/security"
click node_core_events "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/internal/events"
click node_core_internal_schedulers "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/internal/core/lib"
click node_api_surface "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/api"
click node_systems_surface "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/systems"
click node_player_abstractions "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/player"
click node_world_abstractions "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/world"
click node_hook_system "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/systems/hook"
click node_region_watch "https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/systems/geo/region_watch"
click node_player_action "https://github.com/runtoolkit/datalib/tree/main/data/player_action"
click node_data_assets "https://github.com/runtoolkit/datalib/tree/main/data/datalib"
click node_stringlib_vendor "https://github.com/runtoolkit/datalib/tree/main/data/stringlib"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_minecraft_hooks,node_load_pipeline,node_dl_load toneBlue
class node_core_tick,node_core_queue,node_core_state,node_core_security,node_core_events,node_core_internal_schedulers toneAmber
class node_api_surface,node_systems_surface,node_player_abstractions,node_world_abstractions toneMint
class node_hook_system,node_region_watch,node_player_action toneRose
class node_data_assets,node_stringlib_vendor toneIndigo
```

## Components

### Bootstrapping

Vanilla entrypoints and deterministic load pipeline.

- [Vanilla Hooks](https://github.com/runtoolkit/datalib/tree/main/data/minecraft/tags/function): entry tags · Minecraft load/tick function tags that start the pack lifecycle. · `data/minecraft/tags/function`
- [Load Pipeline](https://github.com/runtoolkit/datalib/tree/main/data/load): bootstrap flow · Deterministic load ordering, validation, safe-load confirmation, and finalize/disable paths. · `data/load`
- [DL Load](https://github.com/runtoolkit/datalib/tree/main/data/dl_load): bootstrap flow · 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](https://github.com/runtoolkit/datalib/blob/main/data/datalib/function/core/tick.mcfunction): runtime loop · Central tick loop and channel dispatch orchestration. · `data/datalib/function/core/tick.mcfunction`
- [Queue Engine](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/queue): scheduler · Queued execution, batching, flushing, and rate-controlled processing. · `data/datalib/function/core/queue`
- [Engine State](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/state): persistent state · Global, player, config, and scoreboard-backed state access for the engine. · `data/datalib/function/core/state`
- [Security Gate](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/security): policy layer · Sandboxing, type checks, confirmations, and permission enforcement for command execution. · `data/datalib/function/core/security`
- [Event Core](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/internal/events): dispatch model · Event registry plus immediate, deferred, queued, and sequenced firing paths. · `data/datalib/function/core/internal/events`
- [Dispatch Lib](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/core/internal/core/lib): execution internals · 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](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/api): public functions · Stable callable boundary for command, callback, permission, trigger, wand, dialog, and utility helpers. · `data/datalib/function/api`
- [Systems Layer](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/systems): library systems · Reusable gameplay and utility subsystems built on top of the kernel. · `data/datalib/function/systems`
- [Player Tools](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/player): player facade · Convenience wrappers for player stats, inventory, variables, teams, and execution helpers. · `data/datalib/function/player`
- [World Tools](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/world): world facade · 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](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/systems/hook): event bridge · Registered gameplay hooks for clicks, dimension changes, combat, trading, interaction, and movement. · `data/datalib/function/systems/hook`
- [Region Watch](https://github.com/runtoolkit/datalib/tree/main/data/datalib/function/systems/geo/region_watch): spatial watch · Tick-scanned enter/leave callbacks for configured regions and nearby players. · `data/datalib/function/systems/geo/region_watch`
- [Player Action](https://github.com/runtoolkit/datalib/tree/main/data/player_action): advancement pipeline · 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](https://github.com/runtoolkit/datalib/tree/main/data/datalib): vanilla data · Predicates, advancements, loot tables, item modifiers, localization, and sounds supporting the library. · `data/datalib`
- [StringLib Vendor](https://github.com/runtoolkit/datalib/tree/main/data/stringlib): vendored lib · Upstream StringLib implementation with private helpers and public adapters. · `data/stringlib`

## Connections

- 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.
