# 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

```bash
# 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

```yaml
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

```bash
/oyeshops withdraw
```

withdraws all owed items from your shops into your inventory

## configuration

`plugins/oyeShops/config.yml`:

```yaml
# 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)