Easy Items

ไอเทม ร้านค้า กระเป๋า ของดรอป และสูตรคราฟต์ สำหรับเกม 2D · ตลาดเช้า ร้านโชห่วย ตลาดรายอ
Describe a game's items, shops, loot tables and crafting recipes in a small JSON format (easyitems/1). Every item has Thai / English / Malay names and a 24 or 32 px pixel icon drawn from code. Easy Items validates the whole database (including the item ids your Easy Quest quests give and take), simulates buying, selling, equipping, crafting and loot with one deterministic rule set, and exports a Godot 4.3+ project (Resources, an Items autoload, a shop UI scene) or a PixiJS v8 runtime. CLI, web editor and MCP server; local only, no network.

Starter catalog

44 items in two documents that merge into one database, so the Thai village and its Muslim neighbours share one economy. Everything is halal-appropriate: no pork, no alcohol.

Loot tables: delivery_tip, market_basket, scrap_pile, raya_visit. Recipes: bicycle (2 wheels + chain + bell), mango sticky rice, krathong, ketupat, pelita set. Item ids match the Easy Quest samples (village_delivery, ramadan_raya): check reports 11 of 11 quest item ids found.

Content rules (enforced by check where they can be): halal shops may not stock pork, alcohol or halal: false items; no Quran, Arabic calligraphy, sacred figures or depictions of the Prophet as items or icons.

Related MCP server: pixelbolt

Quick start

npm ci && npm run build
npx easyitems init                      # items/ quests/ exports/ with the starter catalog
npx easyitems list --tag raya
npx easyitems shops raya_bazaar         # stock with buy / sell prices
npx easyitems check                     # database + Easy Quest cross-check, exit 1 on errors
npx easyitems loot market_basket --seed 42 --times 3
npx easyitems render --out icons.png --scale 3
npx easyitems export --preset all       # exports/easyitems-{godot,pixi,png,json}
npx easyitems serve                     # editor at http://127.0.0.1:8878

add-item <id> --th --en --icon [--ms --category --price --stack --tag] writes items/game.easyitems.json. icons lists the 44 built-in icons. Set EASYITEMS_WORKSPACE or pass --workspace.

The format

{
  "format": "easyitems/1",
  "items": [
    { "id": "ketupat", "name": { "th": "ตูปะ", "en": "Ketupat", "ms": "Ketupat" }, "category": "food",
      "price": 15, "stack": 20, "icon": "ketupat", "effects": [{ "kind": "heal", "amount": 20 }], "tags": ["raya", "halal"] }
  ],
  "shops": [
    { "id": "raya_bazaar", "name": { "th": "ตลาดรายอ", "en": "Raya bazaar" }, "keeper": "kakna", "halal": true,
      "buyMod": 1, "sellMod": 0.5, "tagMods": { "raya": 0.9 }, "stock": [{ "item": "ketupat", "qty": 20, "restock": 1 }] }
  ],
  "loot": [{ "id": "raya_visit", "rolls": [1, 2], "entries": [{ "item": "kurma", "weight": 3 }], "guaranteed": [{ "item": "coin_pouch_gift", "n": 1 }] }],
  "recipes": [{ "id": "ketupat", "name": { "th": "สานตูปะ", "en": "Weave ketupat" }, "inputs": [{ "item": "ketupat_shell", "n": 1 }, { "item": "rice_bag", "n": 1 }], "outputs": [{ "item": "ketupat", "n": 4 }] }]
}

Prices: buy = stock.price or round(price × buyMod × tagMods); sell = floor(price × sellMod), only for categories in buys. Full reference: docs/FORMAT.md.

Export

The TypeScript engine, the Pixi runtime and the Godot autoload follow the same rules and the same seeded mulberry32 loot rolls. Tests replay a 27-step script (buy, sell, out of stock, not enough coins, equip, craft, loot, restock) in all three and compare canonical JSON states.

Items.buy("raya_bazaar", "ketupat")         # {ok, coins} or {ok: false, reason: "not_enough_coins"}
Items.use("ketupat")                         # applies effects, returns them
var drops = Items.loot("raya_visit", 7)      # same drops as the CLI with --seed 7
$ShopUI.open("market")

Web editor

easyitems serve (port 8878; npm run dev uses Vite on 5185). Tabs: Items (form, icon picker, where it is sold, recipes, export), Shops (play the shop with the real rules: buy, sell, next day restock), Loot & recipes (12 seeds side by side) and Check (validation and quest cross-reference). Thai / English / Malay switch.

MCP server

npm run mcp (stdio) or npm run mcp:http (port 8879). Tools: workspace_info, list_items, get_item, write_items (validates against the whole workspace, dryRun), check_items, render_icons (returns the PNG), roll_loot, simulate, export_items. See docs/MCP.md.

Ports

Writes from the browser need same-origin requests plus a per-run token; the server only answers to loopback hosts. Workspace paths outside the workspace or EASYITEMS_ALLOWED_DIRS are refused.

Development

npm test                  # vitest
GODOT=/path/to/godot npx vitest run test/godot.test.ts   # headless Godot check
npm run typecheck
npm run smoke             # CLI + MCP (stdio and HTTP)
npm run check:pixi -- exports/easyitems-pixi shot.png     # headless Chrome clicks buy / sell in the Pixi demo
node scripts/render-docs.mjs                              # contact sheets

Easy Suite

Thirteen small, local-first tools that share one look (teak, lantern gold, Kanit, 16/48px pixels), one workflow (CLI · web editor · MCP server) and the same targets (Godot 4.3+ and PixiJS v8). ชุดเครื่องมือทำเกมพิกเซลสไตล์ไทย ใช้ร่วมกันได้ทั้งชุด · Easy Kit builds a whole playable game from the other twelve.
The samples share one multicultural southern Thai village: Buddhist temple, wooden kampung mosque and Chinese-Thai shrine on the same street. หมู่บ้านพหุวัฒนธรรม วัด มัสยิด ศาลเจ้า อยู่ร่วมกันในเมืองเดียว

Works with

• Easy Quest: check reads .ezq files and reports item ids that quests give, take or test with has() / count() but the database lacks (with a suggestion).

• Easy UI: icons follow its 24px icon style; the Godot shop UI picks up its teak theme when installed.

• Easy Dialogue cast ids work as shop keepers; Easy SFX coin and Easy FX coin-burst pair with Items.coins_changed.

• Easy Save: the Godot autoload's to_dict() / from_dict() state is what a save slot stores, and item names extract into its string tables.

Credits

Icons and sample data are drawn and written in code and dedicated to the public domain (CC0 1.0). Kanit is bundled under the SIL OFL 1.1. See CREDITS.md. Code: MIT.