From f7d9db397590632781e7ae64d64c9677e914fa7a Mon Sep 17 00:00:00 2001 From: tastybento Date: Fri, 7 Aug 2026 10:57:24 -0700 Subject: [PATCH 1/2] docs(TradeWinds): add the TradeWinds game mode section Five pages under Game Modes: the overview pitch, The Sailor's Handbook (full gameplay guide - trading loop, One Boat rule, charts, claiming, crime layer, the Interstice), Commands, Permissions, and Placeholders, plus the nav entry and the tradewinds placeholder rows in data/placeholders.csv. Command/permission tables are generated from the addon's own locale and addon.yml, so they match the shipped build. Cross-links from Comparison.md and the homepage are deliberately NOT in this PR - they follow once the section itself is settled. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_014as2obVi1QJj8CRTSqXBRr --- data/placeholders.csv | 4 + docs/gamemodes/TradeWinds/Commands.md | 41 +++++++++ docs/gamemodes/TradeWinds/Gameplay.md | 105 ++++++++++++++++++++++ docs/gamemodes/TradeWinds/Permissions.md | 40 +++++++++ docs/gamemodes/TradeWinds/Placeholders.md | 3 + docs/gamemodes/TradeWinds/index.md | 85 ++++++++++++++++++ mkdocs.yml | 6 ++ 7 files changed, 284 insertions(+) create mode 100644 docs/gamemodes/TradeWinds/Commands.md create mode 100644 docs/gamemodes/TradeWinds/Gameplay.md create mode 100644 docs/gamemodes/TradeWinds/Permissions.md create mode 100644 docs/gamemodes/TradeWinds/Placeholders.md create mode 100644 docs/gamemodes/TradeWinds/index.md diff --git a/data/placeholders.csv b/data/placeholders.csv index 0aba5d57..a8ad0825 100644 --- a/data/placeholders.csv +++ b/data/placeholders.csv @@ -134,3 +134,7 @@ TopBlock,aoneblock_island_lifetime_top_,Lifetime count of magic blocks m Border,Border_color,Current border color (red/green/blue) for the player,4.8.0 InvSwitcher,[gamemode]_invswitcher_balance,The player's money balance for this gamemode's world,1.18.0 InvSwitcher,[gamemode]_invswitcher_balance_formatted,The player's money balance for this gamemode's world formatted with currency name,1.18.0 +TradeWinds,tradewinds_rank,The player's Seafarer rank name (Deck Hand ... Mythic Mariner),0.1.0 +TradeWinds,tradewinds_charted,How many islands the player has charted (including any admin adjustment),0.1.0 +TradeWinds,tradewinds_top_name_<1-10>,Name of the sailor at this position on the charted-islands top ten,0.1.0 +TradeWinds,tradewinds_top_charted_<1-10>,Charted-island count of the sailor at this position on the top ten,0.1.0 diff --git a/docs/gamemodes/TradeWinds/Commands.md b/docs/gamemodes/TradeWinds/Commands.md new file mode 100644 index 00000000..b6dd2c29 --- /dev/null +++ b/docs/gamemodes/TradeWinds/Commands.md @@ -0,0 +1,41 @@ +# TradeWinds Commands + +The player command is **`/tw`** (alias `/tradewinds`); the admin command is **`/twadmin`**. Running bare `/tw` performs the default action, `go`. + +## Player commands + +| Command | Description | Permission | +|---------|-------------|------------| +| `/tw go` (aliases: `spawn`, `sail`) | Set sail — enter the ocean where you left it. On your own island: step to your home point. At sea: toggle a course home (bearing by day, exact distance under the stars at night). Never a ride across the sea. | `tradewinds.island.spawn` | +| `/tw chart` | Raise the chart compass — hologram markers for charted islands, the dock, your boats, and home. `/tw chart list` prints the text version. | `tradewinds.island.chart` | +| `/tw starchart` | Receive a Star Chart map of your charted islands. | `tradewinds.island.starchart` | +| `/tw rank` (alias: `ranks`) | Your Seafarer rank and the top ten sailors by islands charted. | `tradewinds.island.rank` | +| `/tw claim` | Claim the wild islet you are standing on as your island (rank and price gates apply). | `tradewinds.island.claim` | +| `/tw sethome` | Set your home point — only while standing on your own island. | `tradewinds.island.sethome` | +| `/tw home` | Step to your home point — only while already standing on your own island. | `tradewinds.island.home` | +| `/tw unclaim` | Give your claimed islet back to the wild. Owner only, team must be emptied first, no refund; every block stays as it was left. | `tradewinds.island.unclaim` | +| `/tw fine` | Settle your criminal record at a port (returns you to Clean). | `tradewinds.island.fine` | +| `/tw restart` | Restart your trading career (limited uses, config-capped). | `tradewinds.island.restart` | +| `/tw info` | Information about the island you are on. | `tradewinds.island.info` | +| `/tw settings` | View island settings. | `tradewinds.island.settings` | +| `/tw language` | Select your language. | `tradewinds.island.language` | +| `/tw warp` | Open the warp dialog from anywhere in island waters. **Op by default** — the intended path is sailing to the border curtain, which offers the dialog automatically. | `tradewinds.island.warp` | +| `/tw trade` | Open the island market from anywhere in its protection range. **Op by default** — the intended path is docking and right-clicking a trader. | `tradewinds.island.trade` | +| `/tw prices` | Your price logbook — what ports you have called at were paying, and how long ago. Only registered when the `economy.price-logbook-enabled` feature flag is on (off by default). | `tradewinds.island.prices` | + +## Admin commands + +`/twadmin` carries all the standard BentoBox admin commands (`version`, `tp`, `getrank`, `setrank`, blueprints, and so on), plus the TradeWinds-specific set: + +| Command | Description | Permission | +|---------|-------------|------------| +| `/twadmin islands` | List the nearest trading islands with type, tech level, band, and distance. | `tradewinds.admin.islands` | +| `/twadmin tpisland <#>` | Teleport to a trading island from the islands list. | `tradewinds.admin.tpisland` | +| `/twadmin boat ` | Inspect a player's boat records straight from the database: material, cargo, fuel, last-seen position, and whether a hull is actually loaded there or in someone's pack. | `tradewinds.admin.boat` | +| `/twadmin boat restore` | Regenerate a lost active boat as a stamped item in the player's pack, cargo record intact. Refuses while the real hull is loaded or carried. | `tradewinds.admin.boat` | +| `/twadmin rank ` | Show a player's Seafarer rank: effective islands, real charted count, and adjustment. | `tradewinds.admin.rank` | +| `/twadmin rank ` | Set a player's rank by rank slug or island count, or reset the adjustment. Real charting keeps counting on top. | `tradewinds.admin.rank` | +| `/twadmin customs` | Show what customs make of you where you stand: contraband aboard, scan odds, patrol strength. | `tradewinds.admin.customs` | +| `/twadmin priceaudit` | Audit price coverage — what can be sold, what is salvage, what is unsellable — and write the full report to `price-audit.txt`. | `tradewinds.admin.priceaudit` | +| `/twadmin warpfail ` | Rig a player's next warp to fail into the Interstice (run again to clear). For testing the misjump path on demand. | `tradewinds.admin.warpfail` | +| `/twadmin reflag` | Re-apply security-band flags to all trading islands. | `tradewinds.admin.reflag` | diff --git a/docs/gamemodes/TradeWinds/Gameplay.md b/docs/gamemodes/TradeWinds/Gameplay.md new file mode 100644 index 00000000..6228ac7b --- /dev/null +++ b/docs/gamemodes/TradeWinds/Gameplay.md @@ -0,0 +1,105 @@ +# 🧭 The Sailor's Handbook + +Everything a player discovers in their first weeks on the water, in one place—and everything an admin needs to know about how the pieces interlock. TradeWinds is a game of simple rules with deep consequences; the rules are below, the consequences are up to your players. + +## ⛵ Your first hour + +You arrive at the **spawn port** with a starter Oak Boat—3 cargo slots, coal already in the tank—and a piece of advice worth repeating: *the boat is your hold and your livelihood; keep it close.* + +1. **Right-click your boat** to open the hold. Cargo and fuel live here—never in your pockets. Trading at any market moves goods in and out of the hold directly. +2. **Talk to the traders** on the plaza. Every island posts buy and sell prices; the spread is the game. +3. **Set sail** and row away from the island. When you are far enough out you can chose to warp or carry on rowing. Crossing a new island's waters **charts** it permanently on your map, and adds a small step up the Seafarer ladder. +4. **Sell high.** Congratulations: you are a trader. Everything else in this handbook is about doing this faster, bigger, and closer to the edge. + +## 🚢 One boat, twenty hulls + +Your boat is your only hold, and you have exactly one. Its hull decides your cargo slots: + +| | | | +|---|---|---| +| Bamboo Raft: 2 | Oak Boat: 3 | Spruce Boat: 4 | +| Bamboo Chest Raft: 5 | Birch Boat: 6 | Oak Chest Boat: 7 | +| Jungle Boat: 8 | Spruce Chest Boat: 9 | Acacia Boat: 10 | +| Birch Chest Boat: 11 | Dark Oak Boat: 12 | Jungle Chest Boat: 13 | +| Mangrove Boat: 14 | Acacia Chest Boat: 15 | Cherry Boat: 16 | +| Dark Oak Chest Boat: 17 | Pale Oak Boat: 18 | Mangrove Chest Boat: 19 | +| Cherry Chest Boat: 20 | Pale Oak Chest Boat: 21 | | + +- **Shipwrights sell** every hull the island's tech level can build, except the size you already sail. Bring your ship to the quay and buy bigger: that's a **trade-in**: same hold, same cargo, more slots, and the hull under you (or in your pack, or moored at the dock) visibly becomes the new type. Buy with your ship an ocean away and it's an **outright purchase**: new boat in hand, the old one left **UNOWNED** wherever it lies, cargo aboard, first come first served. The dialog warns you before your money moves. +- **Boats can be captured.** Board or pick up a hull that isn't yours and you'll be asked: take the boat (abandoning yours where it lies), take just its cargo (only if your own ship is close enough to load—cargo never teleports), or leave it. An owned boat parked inside a lawful island's protection is untouchable; the same boat parked in anarchic water is not. +- **Death is not the end.** Your boat stays afloat where you left it, still yours, and the chart marks it. If you were *carrying* it, the wreck site is marked instead. Respawn boatless and the port lends you a raft for the recovery row. +- **Lava is the only true destroyer.** Everything else just changes who's holding the hull. +- **The endgame is expanders.** Top-tech ports sell cargo expanders that grow the hold beyond the ladder—at a price that doubles per unit installed. The wallet is the only cap. + +## 🏝️ Reading the ocean + +Every trading island has a **type** (what it grows, digs, or builds—and therefore what it sells cheap and buys dear), a **tech level** (what its shipwright can build and its outfitter stocks), and a **security band**: + +| Band | The water | The rules | +|------|-----------|-----------| +| **SAFE** | Around spawn | Patrolled, no hostile spawns ashore, customs sharp-eyed | +| **POLICED** | The trade lanes | Law present, contraband risky, guardians picket by day | +| **FRONTIER** | The long routes | Thin law, better margins, worse company | +| **ANARCHIC** | The edge | No law at all—contraband gold, pirate crews, and other players | + +Prices follow the geography: the farther from safety, the better the deals—on both sides of the law. Every purchase and sale also **drifts the local price**, so a route can be fished out and a neglected port can quietly become a goldmine. + +## 🗺️ Getting around + +**Rowing** is free and charts everything you pass. **Warping** happens at the island border—sail into the visible curtain and the dialog offers every charted destination with its fuel price (about 1 fuel unit per 100 blocks). Fuel is anything that burns, valued sensibly: logs 1, kelp blocks 4, coal and charcoal 8, blaze rods 12, coal blocks 80, a lava bucket 100—all carried in the hold's fuel row, eating into cargo space. That tradeoff is what player's will have to make. + +- `/tw chart` raises the **hologram compass**: charted islands, the dock bearing, your boats, and—if you own one—home. +- `/tw starchart` draws your charted world onto a **map item** you can take out and put away. +- `/tw rank` shows your Seafarer rank and the top ten sailors by islands charted. + +!!! danger "The misjump" + Every warp carries a small chance (5% by default) of dropping you in the **Interstice**—a dark nether sea under a burning sky. Re-engaging the warp to your original destination is **always free**… but the Interstice is the only place in the game where nether wart grows on the soul-sand shoals, blaze pickets man their crow's nests, and wither watchtowers keep loot worth the detour. What starts as an accident becomes a destination. There are no nether portals in TradeWinds—the sea has its own way in, and the lore-books ashore explain why the portals refuse to light. + +## 🎖️ Ranks and the ladder + +Charting islands is the game's odometer, and 19 Seafarer ranks mark the distance—**Deck Hand** at the start; **Bay Explorer** at 10; **Chart Maker** at 20; **Tide Captain** at 36, where claiming unlocks; **Salty Commodore** at 56; all the way to **Mythic Mariner** at 100. The `/tw rank` top ten and the `%tradewinds_rank%` / `%tradewinds_top_name_1%` placeholders give servers a ready-made leaderboard culture. Admins can promote, demote, or reset with `/twadmin rank`. + +## 🏠 An island of your own + +Scattered between the trading islands are **wild islets**—small, unowned, and claimable: + +- **The gates:** stand on the islet, hold **Tide Captain** rank, and pay the price (default **$150,000**—deliberately above the top boat, because the hull ladder comes first). First come, first claimed. +- **What you get:** BentoBox protection with the standard flags GUI, a team, `/tw sethome` and `/tw home` around the base, and `/tw go` steps you home when you're standing on your island. If the Bank addon is installed, your island gets an account automatically. +- **Getting home across the sea:** your claim becomes a **members-only warp node** in every border dialog. Prefer to sail? `/tw go` at sea sets a **course home**: a rough compass bearing by day, and at night—when the stars come out—exact distance and progress. Teach the kids to navigate by the night sky; it works. +- **Team members need no rank.** Only the claimer passes the gate; a Tide Captain can bring the whole crew home. +- **Unclaiming hurts on purpose.** Owner only, the team must be emptied first, and there's no refund—everything stays exactly as it was left, back in the wild for the next captain. + +## 🚨 The law and the lawless + +The crime layer (one master switch in config) is what turns the map's geography into a story: + +- **Reputation** runs from Upstanding to **Fugitive**. Customs scans at lawful ports catch contraband in the hold; get caught enough and safe markets close their doors to you. +- **Contraband** (sugar, configurable) is worthless where it's legal to be poor and priceless where nobody asks questions. The scan risk—not the price—is the cost of smuggling. +- **Fines** (`/tw fine`) buy a record clean at any port that will still talk to you. +- **Bounties** on wanted players can be collected by anyone, lawfully, in the water where fugitives are forced to trade. Police mobs enforce the peace at lawful islands—and never drop loot, so there is nothing to farm. + +The design is deliberate: crime pays, and it pays you *into danger*. The richest smugglers end up trading exactly where the pirate crews and the bounty hunters already are. + +## 🌊 Things that find you at sea + +Open water rolls encounters scaled by distance from the dock and the band you're in: + +| Encounter | Waters | When | +|-----------|--------|------| +| 🐡 Puffer shoal | SAFE–POLICED | Any time—a sting, not an ambush, and never worth farming | +| 🔱 Guardian picket | POLICED+ | Day | +| 🧟 Drowned raiders | POLICED+ | Night—some carry tridents | +| 👻 Phantom flight | FRONTIER+ | Night, above the mast | +| 🦑 Deep terror | FRONTIER+ | Below the keel | +| 🏴‍☠️ Pirate crew | ANARCHIC | Boat-borne, they fight from the deck | +| 🧪 Sea witch | ANARCHIC | Boat-borne, keeps her distance | + +Encounter kills pay **booty**—customs-stamped salvage straight into the hold, the only money the sea itself pays. Every roster, pack size, and chance is in `encounters` in the config. + +## 🛠️ For the admin at the helm + +- **The seed is the world.** Back up `config.yml` with the database; `galaxy.seed` *is* your world. Publish it if you want players theory-crafting routes on Discord, keep it secret if you want explorers. +- **The boat logbook** (`boats.logbook`, on by default) writes one console line per boat lifecycle event—placed, broken up, captured, bought, went down with its sailor—with coordinates. When a player asks *"where did my boat go?"*, the answer is in the log. +- **`/twadmin boat `** reads their boat records straight from the database: cargo, fuel, last-seen position, and whether the hull is actually afloat there, in someone's pack, or sitting in an unloaded chunk. `restore` regenerates a genuinely lost boat, cargo intact—it refuses while the real hull is loaded, so it can't be used to duplicate. +- **`/twadmin islands` / `tpisland`** for touring, **`customs`** to see the law's view of any spot, **`priceaudit`** to verify every good has a price, and **`warpfail`** to test the Interstice on demand. +- **Dropped-boat cleanup**: abandoned boat *items* (and their cargo records) expire after a configurable TTL. Boat *entities* never expire—an abandoned ship stays part of the world until someone takes it. diff --git a/docs/gamemodes/TradeWinds/Permissions.md b/docs/gamemodes/TradeWinds/Permissions.md new file mode 100644 index 00000000..a70b3b12 --- /dev/null +++ b/docs/gamemodes/TradeWinds/Permissions.md @@ -0,0 +1,40 @@ +# TradeWinds Permissions + +Defaults are chosen so a vanilla install plays the intended game with no permissions plugin at all: everything a sailor needs is `true`, shortcuts that skip the sailing are `op`, and the real gates (claim rank, claim price) live in `config.yml` rather than in permissions. + +## Player permissions + +| Permission | Description | Default | +|------------|-------------|---------| +| `tradewinds.island` | Allow use of the TradeWinds player command | `true` | +| `tradewinds.island.spawn` | Allow `/tw go` — the door into the ocean, and the way home within the rules. From outside it returns the player to the water they left; on their own island it steps them to their home point; anywhere else at sea it tells them the direction and distance home, never a ride. | `true` | +| `tradewinds.island.chart` | Allow viewing the chart (holograms afloat, list ashore) | `true` | +| `tradewinds.island.starchart` | Allow receiving the Star Chart map | `true` | +| `tradewinds.island.rank` | Allow viewing Seafarer rank and the charted-islands top ten | `true` | +| `tradewinds.island.claim` | Allow claiming a wild islet as a player island. The real gates are in config — Seafarer rank (`claims.minimum-rank`) and price (`claims.price`) — so this stays on by default; turn it off to disable claiming outright. | `true` | +| `tradewinds.island.sethome` | Allow setting a home point on your own island — only while standing inside its protection range (owner or team member). | `true` | +| `tradewinds.island.home` | Allow teleporting to your home point — only while already standing on your own island, so it is a convenience around the base and never a way home across the sea. | `true` | +| `tradewinds.island.unclaim` | Allow the owner to give a claimed islet back to the wild. Requires the team to be emptied first; no refund; every block stays as it was left. | `true` | +| `tradewinds.island.fine` | Allow settling a criminal record at a port. On by default — a player who cannot pay off a reputation has no way back except waiting it out. | `true` | +| `tradewinds.island.restart` | Allow restarting the trading career (config-capped) | `true` | +| `tradewinds.island.prices` | Allow the trader's logbook — what ports you have called at were paying, and how long ago. Prices only enter it by visiting a market or buying a harbour report, so this reads a player's own knowledge back to them. | `true` | +| `tradewinds.island.info` | Allow use of the island info command | `true` | +| `tradewinds.island.settings` | Allow viewing island settings (editing is rank-gated) | `true` | +| `tradewinds.island.language` | Allow use of the language command | `true` | +| `tradewinds.island.warp` | Shortcut: open the warp dialog from anywhere in island waters. Off by default — the intended path is to row to the island border, which offers the dialog automatically. Grant to bypass the sailing. | `op` | +| `tradewinds.island.trade` | Shortcut: open the market from anywhere in an island's protection range. Off by default — the intended path is to dock and right-click a trader on the plaza. Grant to bypass the walk. | `op` | + +## Admin permissions + +| Permission | Description | Default | +|------------|-------------|---------| +| `tradewinds.admin` | Allow use of the TradeWinds admin command | `op` | +| `tradewinds.admin.islands` | Allow listing the nearest trading islands | `op` | +| `tradewinds.admin.tpisland` | Allow teleporting to trading islands | `op` | +| `tradewinds.admin.boat` | Inspect a player's boat records — cargo, fuel, last-seen position, whether a hull is actually loaded there — and restore a lost active boat from the database as an item in their pack. | `op` | +| `tradewinds.admin.rank` | Inspect or set a player's Seafarer rank — stores an adjustment on top of their real charted count, so promotion, demotion and reset all work and the claim gate and leaderboard follow. | `op` | +| `tradewinds.admin.customs` | Show the customs state at your position (contraband, scan odds, patrol) | `op` | +| `tradewinds.admin.priceaudit` | Audit price coverage and write the report to `price-audit.txt` | `op` | +| `tradewinds.admin.warpfail` | Rig a player's next warp to fail, dropping them into the interstice | `op` | +| `tradewinds.admin.reflag` | Allow re-applying security-band flags to all islands | `op` | +| `tradewinds.admin.*` | All TradeWinds admin permissions | `op` | diff --git a/docs/gamemodes/TradeWinds/Placeholders.md b/docs/gamemodes/TradeWinds/Placeholders.md new file mode 100644 index 00000000..dc1059c5 --- /dev/null +++ b/docs/gamemodes/TradeWinds/Placeholders.md @@ -0,0 +1,3 @@ +# TradeWinds placeholders + +{{ placeholders_bundle(gamemode_name="tradewinds") }} diff --git a/docs/gamemodes/TradeWinds/index.md b/docs/gamemodes/TradeWinds/index.md new file mode 100644 index 00000000..da1b7b61 --- /dev/null +++ b/docs/gamemodes/TradeWinds/index.md @@ -0,0 +1,85 @@ + + +# 🌬️ TradeWinds + +Created and maintained by [tastybento](https://github.com/tastybento). + +**TradeWinds** is a sea-trading game mode for BentoBox: an endless, procedurally generated ocean scattered with NPC trading islands. Your players start with nothing but a rowing boat and a pocketful of coal—and the boat **is** their cargo hold. Buy low at a farming island, sell high at an industrial port, and watch the money roll in… or take the shortcut through smuggling, bounty hunting, and piracy, and deal with what follows. + +If you ever lost a weekend to *Elite* or *TradeWars 2002*, this is that feeling, rebuilt in Minecraft. If you didn't—your players are about to find out why you would have. + +## 🧭 Why players get hooked + +- 🏝️ **An endless seeded ocean world.** Every island's position, type, tech level, security band, biome, and name derives from a single seed. Players can explore and find novel locations. Use the default seed or pick a new one to have a unique world. Share your seed and another server gets the exact same world. +- ⛵ **The boat IS the hold.** Cargo lives in the ship, the ship can be upgraded through **20 hull ranks** (Bamboo Raft → Pale Oak Chest Boat), and losing the ship *means something*. One player, one boat—every hull decision matters. +- 📈 **A market worth reading.** Eight island personalities (farms, mines, fisheries, forests, industry, luxury, frozen ports…) each buy and sell differently, and every trade nudges local prices. The good routes are *discovered*, not posted. +- ⚡ **Two ways to travel, both fair.** Rowing is free, slow, and takes you through lawless water, but potential riches. Warping is instant but burns fuel from the hold—and a 5% misjump drops you into the **Interstice**, a hostile nether sea where the wart, the blaze rods, and the wither watchtowers are. Neither way ever strictly beats the other; that tension is the game. +- 🗺️ **Charts, stars, and rank.** Raising the chart floats a hologram compass of everything you've charted. Every island charted by players climbs the **Seafarer ladder**—19 ranks from Deck Hand to Mythic Mariner, with a built-in top-ten leaderboard and placeholders for your scoreboard. +- 🏠 **An island of your own—earned.** Reach **Tide Captain** (36 islands charted) and carry serious coin, and any wild islet you find can become yours: protection, team, home point, a members-only warp node, and night-sky navigation home by the stars. First come, first claimed. +- 🚨 **Crime that pays you into danger.** Contraband only sells where the law is thin; a criminal record locks you out of safe markets and puts a bounty on your head that other players can lawfully collect. The richest smugglers are structurally pushed toward the dangerous edge of the map—where the pirates already are. +- 🐡 **A sea that pushes back.** Guardian pickets by day, drowned raiders by night, phantoms, deep terrors, boat-borne pirate crews, sea witches—scaled by how lawless the water is. Even the safe lanes get the occasional puffer shoal, just to keep the helmsman awake. + +**Difficulty is geography.** The waters near spawn are patrolled and calm—new and younger players can trade in peace. Danger, contraband, and PvP bounty space are all *somewhere else*, and going there is always a choice. That makes TradeWinds one of the few economy games that works for a family server and a cut-throat one at the same time, from the same config. + +## ⚓ How a session feels + +You cast off from the spawn port with three slots of cargo and a hunch: the fishing village two islands east was paying double for wheat. You row the first leg—fuel is money—and chart a new islet on the way, one more notch toward Tide Captain. At the border curtain the warp dialog offers the crossing for 14 units of coal; you take it, because the sun is setting and drowned raiders own the night out here. The market pays out, the hold refills with cheap cod, and on the chart home you notice a red-banded island you've never dared visit is buying fish at *silly* prices. It would only take one quiet run… + +That loop—plan, sail, trade, risk a little more than last time—is the whole game, and it does not let go. + +## 🔧 Setup + +!!! warning "Vault and an economy plugin are required" + All trading runs through Vault. Install Vault plus any Vault-compatible economy (EssentialsX Economy, CMI, etc.) before first launch. TradeWinds formats money itself—whole coins, no cents—using the `economy.currency-symbol` from its config. If you want BentoBox's option, use InvSwitcher with money turned on - it's an economy for BentoBox. + +1. **Download the TradeWinds addon** and place it in `/plugins/BentoBox/addons/` +2. **Start the server**—`tradewinds_world` (the ocean) and `tradewinds_world_nether` (the Interstice) generate automatically. There is deliberately **no End world**. +3. **Log in and look around as Op**: `/twadmin islands` lists the nearest trading islands and `/twadmin tpisland <#>` teleports you to one. +4. **Pick your world seed** *(optional, before players join)*: set `galaxy.seed` in `config.yml`. Every island position, type, and name flows from this one number—change it later and it is a different ocean. +5. **Tune the economy to taste** *(optional)*: prices, boat costs, warp fuel rates, crime, and encounter tables are all in `config.yml` with the intended defaults already in place. + +!!! tip "Recommended companions" + - **InvSwitcher**—keeps inventories, health and hunger separate from your other game modes. Includes an economy. + - **Bank**—claimed player islands attach to the Bank addon automatically if it is installed. Allows pooling of money between team members. + +## ✅ Compatibility + +| Feature | Supported | +|-------------------|------------------------------------| +| Server | ✅ Paper 26.2+ | +| BentoBox Version | ✅ 3.18.0 or later | +| Java Version | ✅ Java 25 | +| Economy | ⚠️ Vault + economy plugin required | + +## 🎮 Commands + +The player command is `/tw` (or `/tradewinds`); the admin command is `/twadmin`. Bare `/tw` sets sail—it is the door into the ocean, and the game's one careful teleport: it returns you to the water you left, steps you to your home point if you are standing on your own island, and anywhere else at sea it tells you the **bearing and distance** home rather than giving you a ride. Nothing in TradeWinds teleports cargo. + +The full command reference is [here](Commands.md). + +## ⚙️ Configuration + +Everything gameplay-shaped lives in `config.yml`, introduced stage by stage with comments explaining *why* each default is what it is. The one setting every admin should look at before launch: + +```yaml +galaxy: + # The galaxy seed. Every island position, type, security band, biome, name and + # route cost derives deterministically from this one number - share it and another + # server gets the same trading galaxy. 0 means: use the world seed. + seed: 20260729 +``` + +Other sections worth a skim: `boats` (the hull ladder and prices), `travel.warp` (fuel cost and misjump chance), `ranks` (the Seafarer ladder), `claims` (the price of a player island), `crime` (the whole law layer has a master switch), and `encounters`. + +## 📄 More documentation + +- **[The Sailor's Handbook](Gameplay.md)**—the full gameplay guide: trading, boats, charts, claiming, crime, and the Interstice. Read this one to see what your players will see. +- **[Commands](Commands.md)**—every player and admin command. +- **[Permissions](Permissions.md)**—every permission node and its default. +- **[Placeholders](Placeholders.md)**—rank and leaderboard placeholders for scoreboards. + +## Translations + +{{ translations("TradeWinds") }} diff --git a/mkdocs.yml b/mkdocs.yml index 8244f07f..bac65489 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,6 +28,12 @@ nav: - Poseidon: gamemodes/Poseidon/index.md - SkyGrid: gamemodes/SkyGrid/index.md - Stranger Realms: gamemodes/StrangerRealms/index.md + - TradeWinds: + - Overview: gamemodes/TradeWinds/index.md + - The Sailor's Handbook: gamemodes/TradeWinds/Gameplay.md + - Commands: gamemodes/TradeWinds/Commands.md + - Permissions: gamemodes/TradeWinds/Permissions.md + - Placeholders: gamemodes/TradeWinds/Placeholders.md - Addons: - Bank: addons/Bank/index.md From adc5a6dfb7189fccad56928e164af51d7bae3af2 Mon Sep 17 00:00:00 2001 From: tastybento Date: Fri, 7 Aug 2026 17:28:33 -0700 Subject: [PATCH 2/2] docs(TradeWinds): galaxy -> ocean, matching the addon rename Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_014as2obVi1QJj8CRTSqXBRr --- docs/gamemodes/TradeWinds/Gameplay.md | 2 +- docs/gamemodes/TradeWinds/index.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/gamemodes/TradeWinds/Gameplay.md b/docs/gamemodes/TradeWinds/Gameplay.md index 6228ac7b..8d87982b 100644 --- a/docs/gamemodes/TradeWinds/Gameplay.md +++ b/docs/gamemodes/TradeWinds/Gameplay.md @@ -98,7 +98,7 @@ Encounter kills pay **booty**—customs-stamped salvage straight into the hold, ## 🛠️ For the admin at the helm -- **The seed is the world.** Back up `config.yml` with the database; `galaxy.seed` *is* your world. Publish it if you want players theory-crafting routes on Discord, keep it secret if you want explorers. +- **The seed is the world.** Back up `config.yml` with the database; `ocean.seed` *is* your world. Publish it if you want players theory-crafting routes on Discord, keep it secret if you want explorers. - **The boat logbook** (`boats.logbook`, on by default) writes one console line per boat lifecycle event—placed, broken up, captured, bought, went down with its sailor—with coordinates. When a player asks *"where did my boat go?"*, the answer is in the log. - **`/twadmin boat `** reads their boat records straight from the database: cargo, fuel, last-seen position, and whether the hull is actually afloat there, in someone's pack, or sitting in an unloaded chunk. `restore` regenerates a genuinely lost boat, cargo intact—it refuses while the real hull is loaded, so it can't be used to duplicate. - **`/twadmin islands` / `tpisland`** for touring, **`customs`** to see the law's view of any spot, **`priceaudit`** to verify every good has a price, and **`warpfail`** to test the Interstice on demand. diff --git a/docs/gamemodes/TradeWinds/index.md b/docs/gamemodes/TradeWinds/index.md index da1b7b61..c2d98cf1 100644 --- a/docs/gamemodes/TradeWinds/index.md +++ b/docs/gamemodes/TradeWinds/index.md @@ -37,7 +37,7 @@ That loop—plan, sail, trade, risk a little more than last time—is the whole 1. **Download the TradeWinds addon** and place it in `/plugins/BentoBox/addons/` 2. **Start the server**—`tradewinds_world` (the ocean) and `tradewinds_world_nether` (the Interstice) generate automatically. There is deliberately **no End world**. 3. **Log in and look around as Op**: `/twadmin islands` lists the nearest trading islands and `/twadmin tpisland <#>` teleports you to one. -4. **Pick your world seed** *(optional, before players join)*: set `galaxy.seed` in `config.yml`. Every island position, type, and name flows from this one number—change it later and it is a different ocean. +4. **Pick your world seed** *(optional, before players join)*: set `ocean.seed` in `config.yml`. Every island position, type, and name flows from this one number—change it later and it is a different ocean. 5. **Tune the economy to taste** *(optional)*: prices, boat costs, warp fuel rates, crime, and encounter tables are all in `config.yml` with the intended defaults already in place. !!! tip "Recommended companions" @@ -64,10 +64,10 @@ The full command reference is [here](Commands.md). Everything gameplay-shaped lives in `config.yml`, introduced stage by stage with comments explaining *why* each default is what it is. The one setting every admin should look at before launch: ```yaml -galaxy: - # The galaxy seed. Every island position, type, security band, biome, name and +ocean: + # The ocean seed. Every island position, type, security band, biome, name and # route cost derives deterministically from this one number - share it and another - # server gets the same trading galaxy. 0 means: use the world seed. + # server gets the same trading ocean. 0 means: use the world seed. seed: 20260729 ```