forgot to do small contribs lmao
This commit is contained in:
187
README.md
Normal file
187
README.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user