oyeshops/README.md

oyeShops

deterministic item-for-item chest barter plugin for minecraft paper 1.21.11

core identity

• plugin name: oyeShops
• purpose: deterministic item-for-item chest barter using sign text
• no economy, no currency, no ml, no heuristics
• explicit opt-in only
• deterministic and reversible

features

permission-gated shops

• only players with oyeshops.create can create shops
• only players with oyeshops.use can buy from shops
• ops bypass all permission checks

sign-based activation

shops activate when all conditions are met:

• wall sign attached to chest
• sign text contains at least one "." character
• sign text parses cleanly into exactly one trade
• player has oyeshops.create permission

deterministic parsing

sign parser is strict and deterministic:

• normalizes text (lowercase, strip punctuation)
• resolves material aliases from config
• detects quantities (explicit numbers or implicit: a/one/each → 1)
• requires directional keywords (for/per/costs/= or get/gives/buy/selling)
• ambiguity equals no shop - no auto-fixing

atomic transactions

• buyer inventory verified before transaction
• chest stock verified before transaction
• all steps succeed or all rollback
• crash-safe via sqlite

profit withdrawal

• sellers withdraw owed items via /oyeshops withdraw
• partial fills allowed if inventory full
• remainder stays owed in database

admin tools

• /oyeshops inspect - toggle inspect mode
• right-click shops while inspecting to view details
• /oyeshops enable <id> - enable shop
• /oyeshops disable <id> - disable shop
• /oyeshops unregister <id> - delete shop
• /oyeshops reload - reload config

building

requirements

• java 21 or higher
• gradle (wrapper included)

build commands

# build plugin jar
./gradlew build

# output jar location
build/libs/oyeShops-1.0.0.jar

installation

1. build the plugin (see above)
2. copy oyeShops-1.0.0.jar to your server's plugins/ directory
3. restart server
4. configure permissions in your permission plugin
5. optionally edit plugins/oyeShops/config.yml

permissions

oyeshops.create       # allows placing valid shop signs (default: false)
oyeshops.use          # allows buying from shops (default: false)
oyeshops.withdraw     # allows withdrawing owed items (default: false)
oyeshops.inspect      # allows admin inspection (default: op)
oyeshops.admin        # full control (default: op)
oyeshops.break.override  # allows breaking any shop (default: op)

usage

creating a shop

1. place a chest
2. attach a wall sign to the chest
3. write trade on sign, for example:
   • 5 diamonds
   • for
   • 1 netherite
   • (blank line)

this creates a shop that sells 1 netherite_ingot for 5 diamonds

sign format examples

5 dia for 1 iron
→ 5 diamonds for 1 iron_ingot

1 emerald per cobble
→ 1 emerald for 1 cobblestone

10 stone = 1 diamond
→ 10 stone for 1 diamond

buy 1 pick for 5 ems
→ 5 emeralds for 1 diamond_pickaxe

buying from a shop

1. right-click the shop chest
2. click any item in the fake chest gui
3. confirmation gui opens showing the trade
4. click green pane to confirm, red pane to cancel

withdrawing profits

/oyeshops withdraw

withdraws all owed items from your shops into your inventory

configuration

plugins/oyeShops/config.yml:

# hopper protection
hoppers:
  allow-product-output: true  # allow hoppers to extract product items
  block-price-input: true     # block hoppers from inserting price items

# transaction history
history:
  max-transactions-per-shop: 100  # max transactions to keep per shop
  auto-prune: true                # automatically prune old transactions

# material aliases
aliases:
  dia: diamond
  dias: diamond
  iron: iron_ingot
  gold: gold_ingot
  emerald: emerald
  ems: emerald
  # add more as needed

database

shops and transactions are stored in plugins/oyeShops/oyeshops.db (sqlite)

• crash-safe
• atomic updates
• bounded transaction history

failure philosophy

• ambiguity equals no shop
• no auto-fixing
• no warnings unless inspected
• deterministic parser output

if a sign doesn't parse cleanly, it simply won't activate as a shop. no error messages, no warnings.

non-goals

• no economy integration
• no pricing gui
• no machine learning
• no market mechanics
• no abstraction creep

license

created by cybsec (party.cybsec)