Home

📖 dataLib v6.0.0 — The Ultimate Mega-Wiki & Advanced Runtime Reference

Welcome to the official, authoritative, and exhaustive Mega-Wiki for dataLib (v6.0.0).
dataLib is an enterprise-grade, high-performance, multiplayer-safe standard library and advanced runtime engine for Minecraft Java Edition datapacks. Engineered for massive scale, modularity, security, and developer ergonomics, it completely eliminates command boilerplate by providing an extensive suite of macro-powered APIs, coroutines (fibers), vector and scalar mathematics, dynamic event hooks, sliding-window rate limiters, inventory management, dialog UIs, and robust persistent NBT storage mechanisms.

---

📑 Comprehensive Table of Contents

1. 🚀 Executive Summary & Architectural Foundations
2. 📦 Installation, Initialization & Dependency Ecosystem
3. 🏗️ Global Engine Storage Architecture & NBT Schemas
4. 🧵 Thread & Execution Management (Standard Library: core/lib/*)
5. ⚙️ Advanced Engine Systems (systems/*)
6. 🔌 High-Level API & Functional Wrappers (api/*)
7. 👤 Player, Core & Events Internals (player/*, core/*, events/*)
8. 🌍 World & Entity Operations (world/*)
9. 📊 Complete Resource Reference (Predicates, Modifiers & Loot Tables)
10. 🛡️ Security Policy, Governance & Contribution Guidelines

---

1. 🚀 Executive Summary & Architectural Foundations

Project Vision & Enterprise Tenets

dataLib transforms standard Minecraft datapack development from a collection of hardcoded /execute chains into a structured, highly organized software engineering environment. It achieves this through strict adherence to its foundational tenets:

┌───────────────────────────────────────────────────────────────────────────┐
│                          DATALIB CORE TENETS                              │
├─────────────────────────────┬──────────────────────────────┬──────────────┤
│ Deterministic Execution     │ Server-Side Optimization     │ Multi-Tenant │
│ (Strict Load & Boot Chains) │ (Zero Unnecessary Tick Loops)│ Isolation    │
└─────────────────────────────┴──────────────────────────────┴──────────────┘

• Deterministic & Predictable Behavior: Every function, coroutine, and event hook runs in a highly auditable order. Initialization occurs through strict pre-load, load, and post-load pipelines.
• Server-Side Performance Optimization: Uncontrolled tick.mcfunction execution is the primary cause of server lag in Minecraft. dataLib aggressively minimizes per-tick execution. It relies on event-driven hooks, scheduled queues, and dynamic NBT storage rather than global entity scans (@e) or bloated scoreboard objectives.
• Multiplayer-Safe Architecture: Designed from the ground up for concurrent execution across dozens of players. By utilizing dynamic UUID caching, contextual execution markers (datalib.pid), and per-player NBT isolation, dataLib ensures that macro variables and storage paths never collide between players.
• Broad Version Compatibility: Supports Minecraft Java Edition 1.20.3 through 1.21.6+ (Pack formats 26 to 106+) by implementing advanced multi-version pack overlays (1_20_3, 1_20_5, _pre_1_21_4, compat_1_21_4, 1_21_5, 1_21_6, 26_1, 26_2).

The Macro Engine & The with storage datalib:input {} Calling Convention

With the introduction of function macros ($) in Minecraft, dataLib replaces hundreds of static helper files with elegant, dynamic templates. While Minecraft supports passing inline JSON literals like {key:"value"} to macros, dataLib strictly enforces and optimizes for the with storage datalib:input {} calling convention.

By writing parameters directly to temporary NBT storage (datalib:input), developers can invoke macro functions that expand dynamically at runtime, returning their computed outputs directly to datalib:output. This ensures clean separation of concerns, allows complex NBT objects to be passed without string escaping issues, and maintains peak performance.

# Canonical Macro Data Flow in dataLib
# [Caller] ──(writes NBT)──> [datalib:input] ──(executes with storage)──> [dataLib API] ──(writes NBT)──> [datalib:output]

---

2. 📦 Installation, Initialization & Dependency Ecosystem

Step-by-Step Installation Guide

To install dataLib into your world or bundle it as the foundational library for your custom datapack environment:

1. Place the dataLib-v6.0.0 folder/zip into your <world>/datapacks/ directory.
2. Run /reload in-game or via the server console to initialize the pack structure.
3. Explicitly confirm and boot the core library engine:
   /function dl_load:load/yes
4. Grant yourself administrator security tags:
   /tag @s add datalib.admin
5. Elevate your permission level to maximum (Level 3) to unlock advanced command execution:
   /scoreboard players set @a[tag=datalib.admin] dl.perm_level 3

Dependency Stack

dataLib integrates and embeds top-tier open-source infrastructure to maintain flawless execution mechanics across all Minecraft versions.

┌────────────────────────────────────────────────────────────────────────┐
│                        DATALIB DEPENDENCY STACK                        │
├──────────────────────────┬──────────────────────────┬──────────────────┤
│       Lantern Load       │        StringLib         │   PlayerAction   │
│   (Load Order Engine)    │   (String Manipulation)  │  (Event Hooks)   │
└──────────────────────────┴──────────────────────────┴──────────────────┘

1. Lantern Load (data/load)

• Repository: LanternMC/load | License: BSD 0-Clause (Public Domain)
• Purpose: Provides a deterministic load order, version tracking, and pre/load/post-load hooks. Ensures that dependent datapacks do not execute until dataLib has fully initialized its engine storage.
• Implementation & Validation:

  # Confirm dataLib is active before executing dependent logic
  execute if score #dataLib load.status matches 1.. run say dataLib engine is fully operational!
  
  # Retrieve exact active version integer (Major*10000 + Minor*100 + Patch → v6.0.0 = 50000)
  scoreboard players get dataLib load.status

2. StringLib (data/stringlib)

• Repository: CMDred/StringLib | License: MIT
• Purpose: Provides highly optimized string manipulation, concatenation, substring searching, splitting, and casing operations. Exposed cleanly via datalib:core/lib/string/* wrapper functions.

3. PlayerAction (data/player_action)

• Repository: ICY105/PlayerAction | License: MIT
• Purpose: Embedded runtime for detecting nuanced player actions, including inventory clicks, offhand swapping, and precise block interactions.

---

3. 🏗️ Global Engine Storage Architecture & NBT Schemas

dataLib maintains an elegant, isolated NBT storage hierarchy to prevent namespace collisions and provide a standardized interface for macro functions.

The Enterprise NBT Storage Hierarchy (datalib:engine)

datalib:engine  (Persistent Engine Data)
├── global
│   ├── version: "v6.0.0"
│   └── tick: <int>
├── players
│   └── <PlayerName> { coins:150, level:5, xp:2300, online:1b, ... }
├── queue
│   └── [{func:"mypack:event/end", delay:100}]
├── cooldowns
│   └── <PlayerName> { fireball: 2460, dash: 1870 }  ← Expiry tick timestamps
├── events
│   └── on_join: [{func:"mypack:welcome"}, {func:"mypack:xp_bonus"}]
├── flags
│   └── <flag_key>: 1b
├── rate_limit
│   └── rules: { <rule_key>: { window: 100, limit: 5, ... } }
├── permissions
│   └── <PlayerName>: { <perm_node>: 1b }
├── perm_triggers
│   └── <TriggerName>: [{value: 1, func: "mypack:execute", perm: "mypack.node"}]
├── dialog
│   └── DIALOG: { type: "modal", title: "Welcome", ... }
└── multiCommands
    ├── active: 1b
    └── type: "multi_cmd"

datalib:input   (Temporary Storage for Function Argument Passing)
datalib:output  (Temporary Storage for Function Return Values)
datalib:rl_work (Ephemeral Execution Buffer for Rate Limiting)

Interfacing with datalib:input and datalib:output

Whenever interacting with datalib functions that require arguments, adhere to the standard calling convention: write your arguments to datalib:input, invoke the function using with storage datalib:input {}, and read the results from datalib:output.

# 1. Populate arguments in datalib:input
data modify storage datalib:input string set value "DataLib v6.0.0 is amazing"
data modify storage datalib:input find set value "amazing"
data modify storage datalib:input replace set value "legendary"

# 2. Invoke the standard library function using the correct storage context
function datalib:core/lib/string/replace with storage datalib:input {}

# 3. Read the computed return value from datalib:output
# datalib:output string.result → "DataLib v6.0.0 is legendary"

Memory Management & Cleanup Best Practices

To maintain peak server performance, dataLib functions automatically wipe datalib:input upon successful execution. When writing custom execution loops, ensure that temporary execution structures or large arrays in datalib:output are explicitly cleared after use:

data remove storage datalib:input {}
data remove storage datalib:output {}

---

4. 🧵 Thread & Execution Management (Standard Library: core/lib/*)

The core/lib/* namespace functions as the standard execution library, providing control flow structures commonly found in higher-level asynchronous programming languages.

┌───────────────────────────────────────────────────────────────────────────┐
│                    THREAD & EXECUTION MANAGEMENT                          │
├─────────────────────────────┬──────────────────────────────┬──────────────┤
│ Fibers & Coroutines         │ Command Batching             │ Debounce     │
│ (Asynchronous Threads)      │ (Queued Execution Flushes)   │ & Throttle   │
└─────────────────────────────┴──────────────────────────────┴──────────────┘

Fibers & Coroutines (core/lib/fiber/*)

Fibers allow you to write complex, long-running execution sequences across multiple ticks without setting up messy scoreboard timers or individual /schedule files.

Function	Description	Macro Input (datalib:input)	Output (datalib:output)
core/lib/fiber/spawn	Spawns a new coroutine fiber from the given macro context.	func: "<namespaced_func>"	{fiber_id: <uuid>, status: "running"}
core/lib/fiber/yield	Pauses execution of the current fiber until explicitly resumed.	None (Inherits active fiber context)	{status: "yielding"}
core/lib/fiber/resume	Resumes a yielding fiber from its exact paused state.	fiber_id: <uuid>	{status: "resumed"}
core/lib/fiber/kill	Terminates an active fiber immediately, cleaning up memory.	fiber_id: <uuid>	{status: "killed"}
core/lib/fiber/is_alive	Verifies if a specific fiber is currently active or yielding.	fiber_id: <uuid>	{result: 1b} (if alive)

Fiber Execution Example

# Spawning a fiber to manage an epic boss battle sequence
data modify storage datalib:input func set value "my_pack:boss/phase_one"
function datalib:core/lib/fiber/spawn with storage datalib:input {}

# Inside my_pack:boss/phase_one:
say Boss Phase 1 Initiated!
# Pause execution until players defeat the first wave
function datalib:core/lib/fiber/yield
say Boss Phase 2 Initiated! (Resumed seamlessly)

Command Batching (core/lib/batch/*)

Batching allows you to queue a massive list of commands and execute them inside a highly optimized single-tick flush or across structured ticks.

• core/lib/batch/begin: Initializes a new command batch queue in memory.
• core/lib/batch/add: Pushes a command string into the active batch.
• core/lib/batch/flush: Executes all queued commands in the batch sequentially.
• core/lib/batch/cancel: Purges the active batch without executing.

# Building and flushing a command batch dynamically
function datalib:core/lib/batch/begin
data modify storage datalib:input cmd set value "setblock ~ ~1 ~ diamond_block"
function datalib:core/lib/batch/add with storage datalib:input {}
data modify storage datalib:input cmd set value "summon firework_rocket ~ ~2 ~"
function datalib:core/lib/batch/add with storage datalib:input {}
function datalib:core/lib/batch/flush

Debouncing & Throttling (core/lib/debounce, core/lib/throttle)

Prevent command spam and protect server performance by regulating execution rates.

# Debounce: Ensure a function is only executed after a quiet period of N ticks
# Useful for saving player data only after they stop interacting
data modify storage datalib:input set value {func:"mypack:save_data", delay:40}
function datalib:core/lib/debounce with storage datalib:input {}

# Throttle: Limit execution of a function to at most once every N ticks
# Useful for limiting weapon attack speeds or custom chat broadcasts
data modify storage datalib:input set value {func:"mypack:weapon_swing", cooldown:15}
function datalib:core/lib/throttle with storage datalib:input {}

Queue & Scheduling Engines (core/lib/schedule*, core/lib/queue*)

Enhanced task delegation mechanisms.

• core/lib/schedule: Enhanced wrapper over /schedule with automatic cancellation checks.
• core/lib/schedule_as: Schedules a function while preserving the executing entity's UUID context.
• core/lib/schedule_cancel: Cancels a pending scheduled task.
• core/lib/schedule_renew: Renews a running task timer to its initial duration.
• core/lib/queue_add: Pushes a custom function object into the global execution queue.
• core/lib/process_queue: Forces a manual step execution of the global queue.

# Scheduling a function with context preservation
data modify storage datalib:input set value {func:"mypack:delayed_strike", delay:100}
function datalib:core/lib/schedule_as with storage datalib:input {}

Looping, Repetition & Synchronization (core/lib/repeat*, core/lib/wait*, core/lib/tick_guard*)

# Repeat N: Loop a specific function N times instantly within the same tick
data modify storage datalib:input set value {func:"mypack:spawn_flames", count:100}
function datalib:core/lib/repeat_n with storage datalib:input {}

# Once Per Player: Execute a welcome command exactly once per unique UUID
data modify storage datalib:input set value {func:"mypack:tutorial_show"}
function datalib:core/lib/once_per_player with storage datalib:input {}

# Wait: Halts further macro execution in a sequence for N ticks
data modify storage datalib:input set value {ticks:60}
function datalib:core/lib/wait with storage datalib:input {}

# Tick Guard: Prevents a function from executing more than once per tick globally
data modify storage datalib:input set value {func:"mypack:heavy_calculation"}
function datalib:core/lib/tick_guard with storage datalib:input {}

String Manipulation Standard Library (core/lib/string/*)

Direct exposure of StringLib algorithms utilizing datalib:input and datalib:output.

Function	Description	Input (datalib:input)	Output (datalib:output)
lib/string/concat	Joins an array of strings into a single string.	strings: ["A", "B", "C"]	string.result: "ABC"
lib/string/find	Returns the zero-indexed position of a substring.	string: "Hello", find: "ll"	string.index: 2
lib/string/replace	Replaces occurrences of a substring.	string, find, replace	string.result: "..."
lib/string/split	Splits a string into an NBT list by a separator.	string: "a,b,c", separator: ","	string.list: ["a", "b", "c"]
lib/string/insert	Inserts a substring at a specific index.	string, insert, index	string.result: "..."
lib/string/to_lowercase	Ultra-fast lowercase transformation (A–Z).	string: "TEXT"	string.result: "text"
lib/string/to_uppercase	Ultra-fast uppercase transformation (a–z).	string: "text"	string.result: "TEXT"
lib/string/to_number	Converts string tokens into numeric NBT values.	string: "125"	number.result: 125
lib/string/to_string	Converts raw NBT/numbers into string tokens.	value: 450	string.result: "450"

Invocation Example

data modify storage datalib:input set value {strings:["Data", "Lib", " ", "v6.0.0"]}
function datalib:core/lib/string/concat with storage datalib:input {}
# datalib:output string.result → "DataLib v6.0.0"

---

5. ⚙️ Advanced Engine Systems (systems/*)

The systems/* namespace provides comprehensive engine subsystems for advanced physics, logic, mathematics, and server administration.

┌───────────────────────────────────────────────────────────────────────────┐
│                         ADVANCED ENGINE SYSTEMS                           │
├─────────────────────────────┬──────────────────────────────┬──────────────┤
│ Event Hooks & Raycasting    │ Rate Limiting Engine         │ Vector Math  │
│ (17+ Hooks, 3D Rays)        │ (Sliding Window Buckets)     │ & Geometry   │
└─────────────────────────────┴──────────────────────────────┴──────────────┘

Event Hooks & Listeners (systems/hook/*)

dataLib exposes a highly optimized event dispatcher. You can bind custom functions to fire automatically when specific events occur without running constant background scoreboards.

Complete List of Event Hooks

1. on_break_block: Fires when a player breaks any block.
2. on_dimension_change: Fires when a player shifts between Overworld, Nether, or End.
3. on_drop: Fires when an item is dropped from the inventory.
4. on_eat: Fires when a player consumes food or potions.
5. on_entity_kill: Fires when a player eliminates an entity.
6. on_fish_caught: Fires upon successfully reeling in a catch.
7. on_hero_of_the_village: Fires when the raid victory status is awarded.
8. on_interact_anvil: Fires upon right-clicking an anvil.
9. on_interact_shulker_box: Fires upon opening a shulker box.
10. on_item_use: Fires upon right-clicking with an eligible item.
11. on_jump: Fires the exact tick a player jumps.
12. on_killed_by_arrow: Fires when a target is hit/killed by an arrow.
13. on_open_chest: Fires upon accessing a chest container.
14. on_placed_block: Fires when a player places any block.
15. on_target_hit: Fires when a projectile hits a target block.
16. on_trade: Fires upon completing a villager trade.
17. on_using_item: Continuous active usage hook (bow pulling, eating).

# Binding a custom function to an event hook using with storage
data modify storage datalib:input bind set value {event:"on_jump", func:"mypack:player/jumped"}
function datalib:systems/hook/bind with storage datalib:input bind

# Unbinding a hook
data modify storage datalib:input unbind set value {event:"on_jump", func:"mypack:player/jumped"}
function datalib:systems/hook/unbind with storage datalib:input unbind

# Inspecting active bindings
function datalib:systems/hook/list

3D Raycasting Engine (systems/hook/raycast/*)

An out-of-the-box 3D raycasting engine for tracking line-of-sight interactions, guns, wands, and custom block selection.

[Entity Eye] ───(step 1)───> ───(step 2)───> ───(collision hit!)───> [Target Entity / Solid Block]

• raycast/start: Initializes the ray vector from the executing entity's eye position (^ ^ ^1). Resets the internal distance counter (dl.tmp).
• raycast/loop: Steps forward along the directional vector, checking for block/entity collisions. Loops up to 50 times (5 blocks default).
• raycast/found: Dispatches when a target hit box or solid block is intersected.

# Initiating a custom raycast for a laser weapon
execute as @a[tag=firing_laser] at @s anchored eyes run function datalib:systems/hook/raycast/start

Rate Limiting Engine (systems/rate_limit/*)

Implement sliding-window rate limiting to protect your server from packet spam, rapid clickers, or heavy function calls.

# 1. Configure a rule (e.g., allow 3 executions every 100 ticks)
# Run once during setup via datalib:systems/rate_limit/config or global/config
data modify storage datalib:input set value {key:"boss_spawn",limit:1,window:24000}
function datalib:systems/rate_limit/global/config with storage datalib:input {}

# 2. Check and consume a token in your operational function:
data modify storage datalib:input set value {key:"global:boss_spawn"}
function datalib:systems/rate_limit/check with storage datalib:input {}
execute if data storage datalib:output {result:1b} run function my_ns:spawn_boss

• systems/rate_limit/global/check: System-wide rate limits.
• systems/rate_limit/player/check: Per-player isolated rate limits (automatically appends UUID context).
• systems/rate_limit/channel/check: Custom channel isolation.

Mathematics & Vector Geometry (systems/math/*)

A fully realized arithmetic and vector mathematics library operating via NBT and scoreboards.

Scalar Mathematics Reference

• abs: Returns absolute value.
• atan2: Two-argument arctangent.
• average: Averages a set of scores.
• ceil_div: Ceiling division.
• clamp: Clamps a value between a min and max integer.
• cos / sin: Trigonometric functions.
• distance2d / distance3d: Pythagorean distance calculations.
• divmod: Returns both quotient and remainder simultaneously.
• factorial: Calculates $N!$.
• gcd / lcm: Greatest Common Divisor and Least Common Multiple.
• is_between: Evaluates boundary conditions.
• lerp / lerp_clamped: Linear interpolation between two points.
• log2: Base-2 logarithm.
• map: Remaps a number from one range to another.
• max / min / minmax: Bounding evaluations.
• mod: Modulo arithmetic.
• mul_div: Combined multiplication and division ($A \times B / C$) designed to prevent integer overflow.
• pow: Exponentiation ($A^B$).
• random / weighted_random: Uniform and weighted random number generation.
• round, sign, sign_nonzero, sqrt, sum3, wrap.

3D Vector Calculus (systems/math/vec/*)

Calculates complex 3D vector operations instantly:

• vec/add, vec/sub: Vector addition and subtraction.
• vec/dot: Dot product ($A \cdot B$).
• vec/cross: Cross product ($A \times B$).
• vec/normalize: Normalizes a vector to a unit length of 1.
• vec/angle_between: Returns the angle between two 3D vectors.

# Adding two 3D vectors using with storage datalib:input {}
data modify storage datalib:input set value {ax:1.0, ay:2.0, az:0.0, bx:3.0, by:1.0, bz:0.0}
function datalib:systems/math/vec/add with storage datalib:input {}
# datalib:output → {x:4.0, y:3.0, z:0.0}

Geographic & Regional Monitoring (systems/geo/*)

Perform advanced geometric bounds checking without needing heavy entity selectors.

Function	Description	Macro Input (datalib:input)	Output (datalib:output)
systems/geo/in_region	Checks if the executor is within a cuboid bounded by (x1,y1,z1) and (x2,y2,z2).	x1, y1, z1, x2, y2, z2	result: 1b (if inside)
systems/geo/in_region_unless	Inverted cuboid boundary check.	x1, y1, z1, x2, y2, z2	result: 1b (if outside)
systems/geo/in_sphere	Checks if the executor is within a specific radius of a center point.	x, y, z, radius	result: 1b
systems/geo/near_entity	Evaluates proximity to target entities efficiently.	target: "<selector>", distance: <int>	result: 1b
systems/geo/as_nearby_player	Delegates execution to the nearest player within range.	distance: <int>, func: "<func>"	Executes function

# Checking if a player is in a specific region using with storage
data modify storage datalib:input set value {x1:0, y1:50, z1:0, x2:50, y2:100, z2:50}
function datalib:systems/geo/in_region with storage datalib:input {}
execute if data storage datalib:output {result:1b} run say Player is inside the zone!

Region Watch (systems/geo/region_watch/*)

Registers cuboid regions to automatically fire events when players enter or exit.

• region_watch/register: Registers a region boundary with an entry/exit callback function.
• region_watch/unregister: Removes an active watch region.
• region_watch/list: Displays all active monitored zones in chat.

Logging & Debug Engine (systems/log/*, systems/dev_settings/*)

Provides standardized logging infrastructure with filtering by severity level.

• systems/log/debug: Logs verbose troubleshooting data.
• systems/log/info: Informational broadcasts.
• systems/log/warn: Warning messages (yellow formatting).
• systems/log/error: Critical exceptions (red formatting, admin alert).
• systems/log/set_level: Configures the active logging threshold.
• systems/dev_settings/menu: Interactive chat UI for toggling developer modes and inspecting engine state.
• systems/dev_settings/other/toggle_admin_mode: Toggles administrative command bypasses.

Flag System (systems/flag/*)

A robust boolean flag engine for setting global or per-player states.

• systems/flag/set: Sets a flag key to 1b ({key:"my_flag"}).
• systems/flag/unset: Removes a flag key.
• systems/flag/toggle: Swaps flag state between 0b and 1b.
• systems/flag/get: Retrieves flag status into datalib:output.
• systems/flag/get_or_default: Retrieves flag status or applies a fallback default.
• systems/flag/any: Verifies if any flag in a provided array is active.
• systems/flag/list: Outputs active flags to chat.
• systems/flag/toggle_system: Toggles core engine subsystem flags.

# Setting a flag using with storage datalib:input {}
data modify storage datalib:input set value {key:"boss_defeated"}
function datalib:systems/flag/set with storage datalib:input {}

NBT & UUID Manipulation (systems/nbt/*, systems/uuid/*)

• NBT Management (systems/nbt/*): Deep manipulation tools (append, clear, copy, count, exists, first, merge, move, pop, swap). All expect arguments via with storage datalib:input {}.
• UUID Engine (systems/uuid/*): Cache, store, and match Entity UUIDs dynamically (store, recall, match, from_entity, from_array, forget, cache_clear).

Advanced String & UI Formatting (systems/string/*)

Creates beautiful visual components in chat and UI screens.

• progress_bar / progress_bar_self: Generates a fully customized visual progress bar component.
• format_coords, format_number, format_ticks: Localized string formatters.
• pad_left, truncate, repeat, pluralize: Structural string styling.
• header, separator, tag_badge, tooltip_item, hover_text: Pre-made professional chat UI widgets.
• announce, announce_prefix, score_display: Server-wide formatted broadcasts.

# Displaying a progress bar using with storage datalib:input {}
data modify storage datalib:input set value {title:"Boss Health", current:45, max:100, color:"green"}
function datalib:systems/string/progress_bar with storage datalib:input {}

---

6. 🔌 High-Level API & Functional Wrappers (api/*)

The api/* namespace exposes high-level wrappers around vanilla commands and complex mechanics, optimized for macro expansion.

┌───────────────────────────────────────────────────────────────────────────┐
│                       HIGH-LEVEL API WRAPPERS                             │
├─────────────────────────────┬──────────────────────────────┬──────────────┤
│ Vanilla Command Macros      │ Command Block Delegation     │ UI Dialogs   │
│ (Actionbars, Attributes...) │ (Asynchronous World Threads) │ & Item Wands │
└─────────────────────────────┴──────────────────────────────┴──────────────┘

Command Wrappers (api/cmd/*)

Provides dynamic macro execution for commands that normally require hardcoded values. All api/cmd/* functions are architected to receive parameters via with storage datalib:input {}.

# Actionbar broadcast
data modify storage datalib:input set value {player:"Steve", text:"Hello World", color:"yellow"}
function datalib:api/cmd/actionbar with storage datalib:input {}

# Bossbar management
data modify storage datalib:input set value {id:"boss1", text:"Epic Dragon", color:"red"}
function datalib:api/cmd/bossbar_add with storage datalib:input {}

# Attribute modification
data modify storage datalib:input set value {player:"Steve", attribute:"generic.max_health", value:40.0}
function datalib:api/cmd/attribute_set with storage datalib:input {}

# Damage invocation (Requires executing entity to be creative admin with dl.perm_level=2..)
data modify storage datalib:input set value {player:"Steve", amount:5.0, type:"minecraft:on_fire"}
function datalib:api/cmd/damage with storage datalib:input {}

# Effect handling
data modify storage datalib:input set value {player:"Steve", effect:"minecraft:speed", duration:60, amplifier:1}
function datalib:api/cmd/effect_give with storage datalib:input {}

# Structural placement & cloning
data modify storage datalib:input set value {x1:0, y1:60, z1:0, x2:10, y2:70, z2:10, tx:20, ty:60, tz:20}
function datalib:api/cmd/clone with storage datalib:input {}

# Entity freezing (Powder Snow effect)
# Freezes a player in place using an invisible marker armor stand.
# Every tick the frozen player is teleported back to the stand's position!
data modify storage datalib:input set value {player:"Steve"}
function datalib:api/cmd/freeze with storage datalib:input {}
function datalib:api/cmd/unfreeze with storage datalib:input {}

Complete Catalog of api/cmd/* Wrappers

actionbar, advancement_check, advancement_grant, advancement_revoke, as_player, attribute_add_modifier, attribute_get, attribute_get_modifier, attribute_remove_modifier, attribute_set, bossbar_add, bossbar_remove, bossbar_set_max, bossbar_set_players, bossbar_set_value, clear, clear_item, clone, clone_masked, console_me, console_say, damage, damage_typed, data_remove_block, data_remove_entity, data_remove_storage, deop, difficulty, display_name, effect_clear, effect_clear_one, effect_give, effect_give_all, enchant, execute_if_pred, fill, forceload_add, forceload_remove, freeze, gamemode, gamerule, give, give_one, heal, item_modify, item_rename, kill, locate_structure, loot_drop, loot_give, msg, msg_raw, particle, place_feature, place_structure, ride, ride_dismount, run_cb_reset, run_with_cb, scoreboard_add, scoreboard_get, scoreboard_set, setblock, sound, sound_all, spectate, spectate_stop, spreadplayers, stopsound, storage_set, subtitle, summon, tag_add, tag_remove, time_add, time_set, title, title_all, title_bold, title_clear, title_reset, title_sub, title_times, tp, tp_facing, tp_to_coords, tp_to_entity, tp_to_player, trigger_set, unfreeze, weather, whitelist, xp_add, xp_get, xp_set.

Multi-Command Batch Processing (api/cmd/other/multi_cmd*)

Execute arrays of dynamic commands loaded from NBT strings, complete with pre/post execution hooks and performance metrics tracking.

• other/multi_cmd: Executes an array of command strings sequentially.
• other/multi_cmd/advanced/run_with_options: Executes with precise flow control (error_mode, profile, spread).
• other/multi_cmd/advanced/run_spread: Spreads command execution across multiple server ticks to prevent lag spikes.

# Running a multi-command array using with storage datalib:input {}
data modify storage datalib:input set value {commands:["say First!", "summon pig ~ ~ ~", "say Second!"]}
function datalib:api/cmd/other/multi_cmd with storage datalib:input {}

Command Block Asynchronous Delegation (api/cb/*)

Schedules command strings to execute via physical command blocks in the world. Ideal for bypassing macro permission limits or delegating execution to the world thread.

• api/cb/run: Instantly executes a command via a command block.
• api/cb/run_delayed: Executes after a specified tick delay ({cmd:"say delayed!", delay:40}).
• api/cb/run_sequence: Executes a chain of commands sequentially across ticks.
• api/cb/cancel: Cancels pending command block executions.
• api/cb/list / queue_size: Inspects active command block delegation buffers.

# Scheduling a delayed command block execution using with storage
data modify storage datalib:input cb set value {cmd:"say delayed!", delay:40}
function datalib:api/cb/run_delayed with storage datalib:input cb

Permission Engine (api/perm/*)

A comprehensive permission hierarchy integrated directly into the datapack layer.

• api/perm/grant: Grants a permission node to a player ({player:"Steve", perm:"admin.build"}).
• api/perm/revoke: Revokes a permission node.
• api/perm/check / has: Validates if a player holds a specific permission level.
• api/perm/exec / run: Executes a command only if the caller passes the security gate.
• api/perm/trigger/bind: Binds a scoreboard trigger objective to execute a permission-gated function ({name:"my_trig", value:1, func:"mypack:do", perm:"admin.run"}).
• api/perm/trigger/bind_cmd, enable, unbind, clear.

# Granting a permission using with storage datalib:input {}
data modify storage datalib:input set value {player:"Steve", perm:"admin.build"}
function datalib:api/perm/grant with storage datalib:input {}

Wand Item Framework (api/wand/*)

Create custom functional items utilizing minecraft:custom_data.

# Grants a custom wand item using with storage datalib:input {}
data modify storage datalib:input set value {player:"Steve", tag:"fire_wand", name:"Fire Wand"}
function datalib:api/wand/give with storage datalib:input {}

# Bind a function to be executed when the wand is used
data modify storage datalib:input set value {tag:"fire_wand", func:"mypack:shoot_fireball"}
function datalib:api/wand/bind with storage datalib:input {}

• api/wand/bind_cmd: Binds a raw command string to a wand tag.
• api/wand/unbind, list.

Interaction Varlık Entity Yönetimi (api/interaction/*)

Manages invisible minecraft:interaction entities for custom hitboxes and clicking mechanics.

• api/interaction/spawn: Spawns an interaction hitbox ({width:2.0, height:2.0, response:true, tag:"my_box"}).
• api/interaction/bind_attack / bind_use: Binds custom macro functions to left-click (attack) and right-click (use) actions.
• api/interaction/remove, unbind_attack, unbind_use, list.

# Spawning an interaction entity using with storage datalib:input {}
data modify storage datalib:input set value {width:2.0, height:2.0, response:true, tag:"custom_button"}
function datalib:api/interaction/spawn with storage datalib:input {}

Dialog UI Screens (api/dialog/*)

Direct integration with the Minecraft 1.21.6+ /dialog UI system.

• api/dialog/open: Opens a custom dialog screen configured in datalib:engine dialog.DIALOG.
• api/dialog/close: Forces the dialog to close.
• api/dialog/show: Displays a dialog directly to targeted players.
• api/dialog/load, is_open, notify_admins.

# Configuring and opening a dialog screen
data modify storage datalib:engine dialog.DIALOG set value {type:"modal", title:"Welcome to dataLib"}
function datalib:api/dialog/open

Color Engine (api/color/*)

Advanced color manipulation for UI, text, and leather armor/particles.

• api/color/from_score: Converts a scoreboard integer into a hex color code.
• api/color/lerp: Blends smoothly between two colors.
• api/color/gradient_set: Generates smooth multi-color text gradients.
• api/color/palette_*: Saves and restores reusable color palettes (palette_set, palette_get, palette_list, palette_delete).
• api/color/resolve, validate.

# Creating a color palette using with storage datalib:input {}
data modify storage datalib:input set value {palette_id:"fire", colors:["#ff0000", "#ffaa00", "#ffff00"]}
function datalib:api/color/palette_set with storage datalib:input {}

Macro Generation & Helpers (api/macro/*)

• api/macro/with_advancement: Invokes a macro passing advancement completion state.
• api/macro/with_function: Invokes a macro passing functional execution outputs.
• api/macro/with_score: Invokes a macro passing active scoreboard values.

Security Levels & Allowlists (api/security/*)

• api/security/allowlist_add: Registers a trusted player or entity to the allowlist.
• api/security/allowlist_clear: Purges the allowlist.
• api/security/set_level / get_level: Sets the global security enforcement level (0 to 3).

Subsystem Toggles (api/toggle/*)

Master switches to dynamically enable or disable entire subsystems at runtime:

• api/toggle/cb/true / false
• api/toggle/geo/true / false
• api/toggle/hook/true / false
• api/toggle/interaction/true / false
• api/toggle/perm/true / false
• api/toggle/wand/true / false
• api/toggle/list: Displays active subsystem states.

---

7. 👤 Player, Core & Events Internals (player/*, core/*, events/*)

Player Context & Variables (player/*)

Provides an isolated, dynamic variable table per player UUID, bypassing standard scoreboard limitations.

┌───────────────────────────────────────────────────────────────────────────┐
│                          PLAYER CONTEXT SYSTEM                            │
├─────────────────────────────┬──────────────────────────────┬──────────────┤
│ NBT Variable Tables         │ Player Status Readers        │ Inventory    │
│ (Set, Get, Clamp, Swap)     │ (Health, Food, Armor, Air)   │ Scanners     │
└─────────────────────────────┴──────────────────────────────┴──────────────┘

Dynamic NBT Variable Management

• player/set_var: Sets a custom NBT variable for the player ({var:"mana", value:100}).
• player/get_var: Retrieves a variable into datalib:output.
• player/has_var: Checks if a variable exists.
• player/del_var: Deletes a variable.
• player/copy_var: Copies a variable from one player to another.
• player/transfer_var: Moves a variable to another player.
• player/swap_var: Swaps variable values between two players.
• player/clamp_var: Clamps a variable within a numeric boundary.
• player/increment / decrement: Adjusts variable values incrementally.
• player/add_to_var: Adds a dynamic value to an existing variable.
• player/list_vars: Outputs all active player variables to chat.

# Setting a player variable using with storage datalib:input {}
data modify storage datalib:input set value {var:"mana", value:100}
function datalib:player/set_var with storage datalib:input {}

Player Status Readers

• player/get_air, get_armor, get_dimension, get_food, get_gamemode, get_health, get_name, get_pos, get_xp, get_online_count.
• State Checkers: is_burning, is_flying, is_gliding, is_in_water, is_on_ground, is_online, is_sneaking, is_sprinting.

Inventory Scanners (player/inv/*)

• player/inv/chest_minecart_if_item / unless_item: Validates items within a chest minecart inventory.
• player/inv/clear_custom: Clears items matching custom NBT definitions.
• player/inv/count_item: Returns the exact count of a specified item across the entire inventory.
• player/inv/cursor_item: Inspects the item currently held in the active UI cursor.
• player/inv/offhand_item: Inspects the offhand slot.
• player/inv/selected_item: Inspects the active hotbar selection.
• player/inv/transfer_item: Moves items between containers and player inventories.

Team Management (player/team/*)

• player/team/create, delete, add, remove, count, has, list, set_color, set_friendly_fire.

Core Engine Subsystems (core/*)

The internal engine execution architecture. These modules manage the lifecycle, security pipelines, and tick loops of the entire library.

• core/cmd/*: Internal command delegation logic.
• core/config/*: Global engine configuration key-value storage (set, get, has, delete, list, reset, score_set, score_get, set_default, set_int).
• core/cooldown/*: High-performance cooldown manager (set, check, is_ready, remaining, extend, pause, resume, clear, clear_all, reset_all, detail).
• core/disable/*: Emergency kill switches.
• core/dispatch/*: Execution routers.
• core/engine/call/execute_validated: Core validator for macro execution pipelines.
• core/fallback/*: Graceful error handlers for missing entities, uninitialized storage, or permission failures (entity_missing, storage_missing, no_permission, not_loaded, invalid_score, generic, check, clear).
• core/handle_trigger: Global trigger objective routing.
• core/internal/*: Deeply internal execution loops for wands, triggers, freezing, multi-commands, and command blocks.
• core/load/warn: System warnings during initialization.
• core/queue/*: Internal priority task queue (push, push_as, flush, clear, size, set_rate).
• core/security/*: Security gates, namespace violation detectors, canary triggers, and execution pipelines (cmd_gate, cmd_perm_denied, input_ns_violation, multi_type_check, type_violation, pipeline/*).
• core/state/*: Engine state markers (set, get, is, toggle, clear, clear_all, list, set_score, get_score, reset_score).
• core/tick: The master tick loop. Routes to admin_systems, hud_systems, player_systems, queue_systems, time_systems, disabled, config, pause, resume, status, init_channels, reset_channels, dispatch/*, channel/*.

Custom Event Registry (events/*)

Allows datapack developers to register custom event channels and fire them globally or to specific player contexts.

• events/register: Registers a custom event string.
• events/unregister / unregister_one: Removes event registrations.
• events/fire: Instantly fires an event to all subscribers.
• events/fire_as: Fires an event while preserving the executing entity's context.
• events/fire_queued: Pushes an event into the asynchronous processing queue.
• events/fire_to_player: Directs an event exclusively to a targeted player.
• events/has, list, count, clear_context.

---

8. 🌍 World & Entity Operations (world/*)

Advanced World Manipulation (world/*)

• world/fill_hollow, world/fill_keep, world/fill_outline, world/fill_replace: Advanced area filling algorithms that bypass standard command block limits.
• world/block_if, world/block_unless, world/setblock_if: Conditional block placement mechanics based on NBT or scoreboard validation.
• world/clone_to: Structural cloning helpers.
• world/get_time, world/time_phase: Analyzes current daytime ticks and categorizes the world phase into distinct, readable states (Morning, Noon, Dusk, Midnight).

Performance-Optimized Entity Control (world/entity/*)

High-performance entity manipulation without resorting to global @e selector spam:

• world/entity/for_each: Iterates efficiently over targeted entity collections.
• world/entity/for_each_in_radius: Scans and iterates entities within a localized radius.
• world/entity/nearest, world/entity/random: Targeted entity filtering.
• world/entity/damage, world/entity/set_health, world/entity/set_name: Direct property manipulation.
• world/entity/give_effect, world/entity/clear_effects: Status effect handling.
• world/entity/summon_at_player, world/entity/tp_to: Precise logistical positioning.
• world/entity/tag_add, tag_remove, kill_tagged, count.

---

9. 📊 Complete Resource Reference (Predicates, Modifiers & Loot Tables)

Predicates (datalib:*)

Used seamlessly with execute if predicate datalib:<id>.

┌───────────────────────────────────────────────────────────────────────────┐
│                          DATALIB PREDICATES                               │
├─────────────────────────────┬──────────────────────────────┬──────────────┤
│ Player Mode & Inventory     │ Environmental & Weather      │ Dimensional  │
│ (Survival, Empty Hand...)   │ (Daytime, Raining, Clear...) │ (Nether, End)│
└─────────────────────────────┴──────────────────────────────┴──────────────┘

Predicate	Exact Internal Condition	Usage Example
datalib:is_survival	Evaluates if gamemode is Survival.	execute if predicate datalib:is_survival run say Survival!
datalib:is_creative	Evaluates if gamemode is Creative.	execute if predicate datalib:is_creative run say Creative!
datalib:has_empty_mainhand	Checks if mainhand slot matches minecraft:air.	execute if predicate datalib:has_empty_mainhand run ...
datalib:has_empty_offhand	Checks if offhand slot matches minecraft:air.	execute if predicate datalib:has_empty_offhand run ...
datalib:is_full_health	Validates Health NBT equals 20.0f.	execute if predicate datalib:is_full_health run ...
datalib:health_below_half	Validates Health NBT is < 10.0f.	execute if predicate datalib:health_below_half run ...
datalib:is_sneaking	Checks entity flags for sneaking status.	execute if predicate datalib:is_sneaking run ...
datalib:is_sprinting	Checks entity flags for sprinting status.	execute if predicate datalib:is_sprinting run ...
datalib:is_burning	Evaluates if Fire NBT is > 0.	execute if predicate datalib:is_burning run ...
datalib:is_on_ground	Checks OnGround: 1b NBT flag.	execute if predicate datalib:is_on_ground run ...
datalib:is_flying	Checks player abilities NBT for active flight.	execute if predicate datalib:is_flying run ...
datalib:is_gliding	Checks entity flags for Elytra flight status.	execute if predicate datalib:is_gliding run ...
datalib:is_in_water	Checks environmental immersion status.	execute if predicate datalib:is_in_water run ...
datalib:is_hungry	Checks if foodLevel NBT is < 20.	execute if predicate datalib:is_hungry run ...
datalib:is_baby	Checks IsBaby: 1b or Age < 0 flags.	execute if predicate datalib:is_baby run ...
datalib:is_holding_bow	Checks mainhand for minecraft:bow.	execute if predicate datalib:is_holding_bow run ...
datalib:is_holding_shield	Checks offhand/mainhand for Shield.	execute if predicate datalib:is_holding_shield run ...
datalib:is_holding_sword	Checks hand slots for any sword tag.	execute if predicate datalib:is_holding_sword run ...
datalib:is_holding_trident	Checks hand slots for minecraft:trident.	execute if predicate datalib:is_holding_trident run ...
datalib:is_daytime	Evaluates world time between 0–12000 ticks.	execute if predicate datalib:is_daytime run ...
datalib:is_raining	Checks global weather status for rain.	execute if predicate datalib:is_raining run ...
datalib:is_thundering	Checks global weather status for thunder.	execute if predicate datalib:is_thundering run ...
datalib:weather_clear	Checks global weather status for clear skies.	execute if predicate datalib:weather_clear run ...
datalib:in_overworld	Checks dimension matches overworld.	execute if predicate datalib:in_overworld run ...
datalib:in_nether	Checks dimension matches the_nether.	execute if predicate datalib:in_nether run ...
datalib:in_end	Checks dimension matches the_end.	execute if predicate datalib:in_end run ...

Item Modifiers (datalib:*)

Used with item modify entity <target> <slot> datalib:<id>.

• damage_random: Randomly degrades item durability.
• enchant_randomly: Applies a random applicable enchantment.
• enchant_with_levels_5 / enchant_with_levels_30: Simulates enchanting table rolls at specific level tiers.
• glint_add / glint_remove: Manages the foil/glint visual override (enchantment_glint_override).
• hide_tooltip: Hides standard item tooltips (hide_tooltip component).
• lore_add_custom / lore_clear: Modifies or wipes item lore lines.
• rename_to_custom: Dynamically renames an item based on input storage.
• repair_full: Fully restores item durability (Damage: 0).
• set_count_1 / set_count_64: Quantifies item stacks.
• set_custom_model_data: Assigns custom model data integers (custom_model_data component).
• strip_enchants: Disenchants an item completely (enchantments reset).
• unbreakable: Applies the Unbreakable component (unbreakable: {}).

Loot Tables (datalib:*)

• player/head: Drops the executing player's custom skull (minecraft:player_head[profile=...]).
• util/empty: Suppresses default drops (returns an empty array).
• util/self_drop: Simulates an identical entity/item drop.
• util/xp_only: Drops experience orbs without item clutter.

---

10. 🛡️ Security Policy, Governance & Contribution Guidelines

Security Policy (SECURITY.md)

dataLib strictly defines supported versions and vulnerability handling to maintain enterprise trust in multiplayer server environments.

┌───────────────────────────────────────────────────────────────────────────┐
│                         SECURITY & GOVERNANCE                             │
├─────────────────────────────┬──────────────────────────────┬──────────────┤
│ Version Maintenance         │ Zero-Day Protection          │ Contributor  │
│ (Active 5.0.x & 6.0.x)      │ (Private Bug Bounty Routing) │ Covenant     │
└─────────────────────────────┴──────────────────────────────┴──────────────┘

• Supported Versions: Security updates are actively maintained for the 5.0.x and 6.0.x release series. Legacy versions (3.0.x and below) are unsupported. Snapshot versions are explicitly excluded from official security coverage.
• Vulnerability Definition: Critical flaws include permission bypasses via /execute, scoreboard manipulation exploits, NBT injection, unauthorized storage tampering, or crash loops (intentional DoS).
• Reporting Protocol: Do NOT open public issues for security vulnerabilities. Report privately via the GitHub Security Advisory system or directly to the project maintainers. Initial response is guaranteed within 72 hours, status updates within 7 days, and target fix times within 14 days for critical exploits.

Contributing Standards (CONTRIBUTING.md)

We welcome community pull requests! To maintain optimal performance and stability, ensure your contributions adhere to the following strict guidelines:

1. Namespacing: All functions must be correctly isolated within the project namespace (datalib). Do not pollute the minecraft: namespace under any circumstances.
2. Function Design: Avoid infinite recursion loops. Minimize raw command logic inside tick.mcfunction (on_tick). Prefer NBT storage over scoreboards for complex structural data.
3. Clean Environments: Ensure no temporary debug scoreboards or test values remain in your submitted files.
4. Testing: All submissions must be tested on a pristine vanilla server running the targeted Minecraft version.

Code of Conduct (CODE_OF_CONDUCT.md)

We are committed to providing a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, level of experience, or nationality. We uphold high technical rigor while maintaining a respectful, collaborative community environment. Unacceptable behaviors (flame wars, uncoordinated vulnerability disclosures, harassment, or malicious code submissions) will result in prompt moderation and potential permanent bans across all project spaces.

Licensing & Legal Notices (LICENSE, NOTICE)

dataLib is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) License.

• Attribution: You must credit "Legends11 / runtoolkit" and link to the original repository in any public redistribution or derivative work.
• NonCommercial: You may not use this work for commercial purposes.
• ShareAlike: Derivative works must be distributed under the identical CC BY-NC-SA 4.0 license.
• AI & Infrastructure Restrictions: You may not use this repository or its code for AI model training, automated harvesting, or benchmarking without explicit prior written permission. You may not abuse or overload associated GitHub Actions workflows, Codespaces, or devcontainer configurations for crypto mining, stress testing, or spam operations.

---

dataLib v6.0.0 | Pure Datapack Engine | CC BY-NC-SA 4.0 License | Maintained by Legends11 / runtoolkit