Data Packets

A Data Packet is the core unit of the innate skill & animations system's condition/state engine: a single, typed piece of information stored on an entity (as NBT) that can be read (as a condition) or written (as an instruction).

Every data packet is built around three concerns:

• A type what kind of value it holds (numeric, boolean, string, etc.), which determines how it's read from and written to NBT.
• An identity (dataId) the key the value is stored under.
• An operation either a comparison (Read side) against the current stored value, or an instruction (Write side) that mutates it.

This page covers the general concept and the pieces shared across the system. The Read and Write JSON formats themselves are documented on their own pages.

---

🔀 Read vs Write

Side	Purpose
Read	Evaluates the current value of a data packet as a condition — true/false.
Write	Mutates the current value of a data packet.

Both sides work off the same DataPacketType, so a packet's type only has to be declared once conceptually the Read and Write sides simply interpret it differently (as something to compare, or something to change).

---

🧮 Comparators (Read side)

Reading a data packet doesn't just check "does it exist" it evaluates the stored value against an expected one, using a comparator appropriate to the value's kind.

Numeric

• EQUALS
• NOT_EQUALS
• GREATER_THAN
• GREATER_EQUAL
• LESS_THAN
• LESS_EQUAL
• IN_RANGE
• INCLUSIVE_UPPER_RANGE
• INCLUSIVE_LOWER_RANGE
• INCLUSIVE_RANGE

💡 The *_RANGE variants compare against both max and min at once instead of a single value; the inclusivity suffix controls which bound is closed.

String

• EQUALS
• CONTAINS

Logical (boolean) data packets don't use a comparator they're read by direct equality against an expected boolean.

---

🛠 Instructions (Write side)

Writing to a data packet applies an instruction to its current value rather than always overwriting it outright — this is what lets data packets act as counters, toggles, and accumulators, not just flags.

Arithmetic

• SET
• ADD
• SUBTRACT
• MULTIPLY
• DIVIDE
• MIN
• MAX
• MOD

⚠️ DIVIDE and MOD guard against a zero operand: the operation is skipped and the current value is returned unchanged, with a warning logged.

Logical

• SET
• TOGGLE
• AND
• OR
• XOR

String

• SET
• APPEND
• PREPEND

Each instruction family is applied per numeric primitive it supports (int, long, float, double, byte), with byte results clamped (and logged) if the operation overflows the byte range.

---

🧩 Group Logic

A single Read condition is rarely enough on its own, so reads are combined through ReadDataPacketsGroup — four flat lists of IDataRead entries, evaluated as logical sets rather than a nested expression tree:

Group	Passes when
AND	Every entry in the list evaluates to true.
OR	At least one entry evaluates to true (an empty list always passes).
XOR	Exactly one entry evaluates to true (an empty list always passes).
NOT	None of the entries evaluate to true.

The group is satisfied only if all four lists pass their own condition this is intentionally flat (no recursive nesting of groups) to keep the JSON simple to write and reason about.

---

🔄 Sync (Server ↔ Client)

Whether a read/write targets the server or client copy of a value is resolved automatically from the entity's side , not declared in the JSON:

• On the server, a data packet operation is STC (Server-To-Client): it updates the server's NBT and syncs the change to the owning client.
• On the client, it's CTS (Client-To-Server): the change is sent up to the server to apply.

This keeps the JSON format side-agnostic the same data packet definition works whether it happens to run on the logical server or the logical client.

---

⚠️ Notes

• A data packet's type is fixed by DataPacketType. the same type drives both how a Read comparator interprets its value and how a Write instruction mutates it.
• delete is available on Read entries: if the condition passes, the underlying data can be removed immediately as a side effect of reading it.
• Group logic (AND/OR/XOR/NOT) only combines Read entries. Write operations are applied directly, not gated through a group.