188 lines
4.4 KiB
Markdown
188 lines
4.4 KiB
Markdown
# 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)
|