Tutorial Item Field Scripts

Tutorial: Item Field Scripts

Give one of your items a job. An item record can name a script that runs when the player uses it from the bag — with no target, or pointed at a party member.

The block

field sits beside the battle block you may already know from held items:

{
 "id": "item:scanner",
 "name": "SCANNER",
 "key_item": true,
 "field": {
  "use_on": "script:appraise",
  "close": false
 }
}

• use — the player picks USE and your script runs immediately, with no target.
• use_on — the engine opens the ordinary party picker first, and your script receives the chosen slot as the variable slot.
• close — true leaves the field after the use (how the ITEMFINDER behaves); leave it off and the bag comes back (how the TOWN MAP behaves). Your choice, not an inherited one.

Declare either form, or both.

The script

Field scripts get exactly the surface run_script gets — the same readable state, the same command library:

let grade = get_mon_ext(slot, "grade")
if grade == 0 {
  say("The SCANNER hums, then goes quiet.")
  return true
}
say("Reading: grade {var:last_grade}.")
set_var("last_grade", grade)
return true

slot is only present for use_on. Everything else — has_flag, set_var, item_count, party_count, say, give_item, warp_to, and the rest — is the list in the HatchScript reference.

Two rules worth knowing

Return a value, or nothing happens. A script that ends without returning something is treated as a refusal: any flags or variables it set are rolled back, and the bag says the ordinary "not the time to use that" line. That way a half-written script is a visible no-op instead of a silent success. The same applies if the script hits a runtime error.

The engine never consumes your item. If the SCANNER should be single-use, call take_item("item:scanner") in the script yourself. Key items and reusable tools just don't.

Why use_on matters

get_mon_ext(slot, field) can read any party member's per-individual fields — but only if something tells it which member. Before this, a script invoked from an event could only ever assume slot 0, which made an appraisal tool an NPC you walk to rather than a device you carry. use_on closes that gap: the player points the item at a monster, and the script reads that monster.

Pairs with Per-Individual Fields and Abilities & Battle Hooks. Gate: --itemfieldtest.