Task Module Specification

Overview

The task channel is the core communication channel of the Yeow plugin, used to perform all game-state-related operations.

Message Format

{
  "type": "player.get",
  "params": { "key": "value" },
  "cb": "cb_42"
}

Field	Type	Required	Description
type	string	Yes	Task type identifier, named by functional module (e.g. player.get)
params	object	No	Task parameters, each task has its own fields
cb	string	No	Callback ID. Present → asynchronous: the runtime immediately returns null and delivers the result through the callback. Absent → synchronous: the runtime blocks JS until completion and returns the result synchronously
noReply	boolean	No	Control frames only: true → run asynchronously and do not deliver a result (the JS thread does not wait). When both noReply and cb are present, noReply wins

What noReply is for: event.complete (releasing an event) and command.tabComplete (returning completions) are notifications — "sent means done" — and nobody consumes their result. Sending them with an empty cb makes the implementation take the synchronous path, so a plugin's JS thread blocks on a cross-thread round trip for every event. noReply still routes the task through the scheduler (it runs on the game thread), but neither delivers a result nor blocks the sender. It is not plugin API: plugins use the yeow-api wrappers and should not hand-write this field.

Priority

Task priority can be controlled via the message top-level priority field (at the same level as cb):

Value	Budget share	Description
high	50%	High priority (must be requested explicitly)
normal	30%	Default priority (post lands here unless specified)
low	20%	Low priority

{ "type": "player.get", "params": { "identifier": "uuid" }, "priority": "high" }

If not provided or an invalid value is given, it falls back to normal. The runtime allocates execution time each tick according to the budget proportions. If the high-priority budget is not fully used, the remainder spills over to the next level. Once all budgets are exhausted, the remaining tasks queue up for the next tick. Finally, it enters a greedy phase (ignoring the budget and consuming as much as possible in priority order).

Return Value Conventions

• Returns true/false — whether the operation succeeded
• Returns null — entity/player/world does not exist
• Returns {} object — contains specific data
• Returns [] array — list data
• Asynchronous tasks deliver results through the cb channel

Error Handling

If an exception is thrown during task execution, the callback data field r is an object containing detailed error information:

{
  "err": "java.lang.NullPointerException",
  "type": "NullPointerException",
  "task": "pdc.get",
  "stack": "java.lang.NullPointerException\n\tat ...\n\tat ..."
}

Field	Type	Description
err	string	Exception message
type	string	Java exception class name
task	string	Task type that triggered the exception
stack	string	Full Java stack trace

---

Module List

Module	Description	Task count
player	Player operations	51
entity	Entity + potion effects	38
world	World + block + chunk snapshot + sound + particle + entity spawn + WorldBorder	49
inventory	Inventory + container blocks + custom Inventory	17
server	Server-global operations + Material queries + permission registration	13
command	Command registration + Tab completion	4
event-system	Event subscription/completion	3
bossbar	BossBar	12
scoreboard	Scoreboard	24
pdc	Custom persistent data	6
advancement	Advancements	5
recipe	Recipes	3

Total: 225 tasks (permission.register counted in the server module; material.* counted in server; block.breakNaturally, chunk.* counted in world). The Paper and Folia task sets are strictly identical (Folia's recipe.add is dispatched internally by recipe type shaped/shapeless/furnace/blast/smoker/campfire, not as separate tasks). Counting basis: number of task-semantics cases in Tasks.java / FoliaTasks.java, 2026-08-18.