Write Packets

Writing a Data Packet means applying an instruction to a stored value on an entity, identified by a dataId. It's always triggered by an event most commonly an Data Time Events entry which decides when the write happens and, if it's a synced event, on which side it's considered "real."

This page only covers the write_data array itself:

"write_data": [
  { "type": "int", "dataId": "my_sword.air_slash.executed.count", "instruction": "ADD", "value": 1 },
  { "type": "bool", "dataId": "my_sword.air_slash.executed", "instruction": "TOGGLE" }
]

---

📋 Fields

Field	Type	Description
type	String	The kind of value stored under dataId. Determines which instructions are valid and how value is interpreted.
dataId	String	The key the value is saved under on the entity. Convention: dot-separated, e.g. mymod.skill_name.thing.
instruction	String	What to do to the current value. Valid options depend on type (see below).
value	Number / Boolean / String	The operand for the instruction. Not required for instructions that don't take one (e.g. TOGGLE).

---

🔢 Numeric Types (int, long, float, double, byte)

Instruction	Effect
SET	Overwrites the stored value with value.
ADD	Stored value = stored value + value.
SUBTRACT	Stored value = stored value − value.
MULTIPLY	Stored value = stored value × value.
DIVIDE	Stored value = stored value ÷ value. If value is 0, the write is skipped and the current value is kept.
MOD	Stored value = stored value % value. If value is 0, the write is skipped and the current value is kept.
MIN	Stored value = the smaller of the stored value and value.
MAX	Stored value = the larger of the stored value and value.

⚠️ byte values are clamped to the byte range (-128 to 127) if an operation would push them out of bounds.

In the example, { "type": "int", ..., "instruction": "ADD", "value": 1 } increments my_sword.air_slash.executed.count by 1 every time the write fires.

---

✅ Boolean (bool)

Instruction	Effect
SET	Overwrites the stored value with value (true/false).
TOGGLE	Flips the stored value true becomes false and vice versa. Doesn't need a value.

In the example, { "type": "bool", ..., "instruction": "TOGGLE" } flips my_sword.air_slash.executed every time the write fires — no value needed.

---

🔤 String (string)

Instruction	Effect
SET	Overwrites the stored value with value.
APPEND	Adds value to the end of the stored string.
PREPEND	Adds value to the start of the stored string.

---

🔄 Sync Behavior

Whether a write is visible to both sides depends entirely on the event that triggers it, not on anything declared in write_data itself:

• Non-synced write the value is only saved on the side where the event actually runs. Works on both entities and players.
• Synced write the value is saved on both sides, and the side that executed the write is treated as the "source of truth." Synced writes only exist for players entities have no client counterpart to sync to. This is why choosing a synced vs. non-synced event (see Data Time Events) matters just as much as the instruction itself: it decides whether the resulting data is purely local bookkeeping or something both client and server agree on.

---

⚠️ Notes

• dataId doesn't need to be declared or registered anywhere beforehand the first write creates it.
• Reading back a value written here uses the same dataId on the Data Packets - Read side, and must use a compatible type.
• Picking an instruction that doesn't apply to the declared type (e.g. APPEND on an int) is invalid.