From 6549f879aa639dbcc6c819f06452cd29fbe00d00 Mon Sep 17 00:00:00 2001 From: tastybento Date: Sat, 14 Nov 2026 19:51:23 -0800 Subject: [PATCH] docs: merge the two blueprint pages into a Starter Islands guide Blueprints.md becomes the single Starter Islands (Blueprints) admin guide; About/BlueprintsSummary.md becomes a pointer. Adds bundle cost, commands, use limits and slot, which the old pages didn't cover. Checked against BentoBox source. Co-Authored-By: Claude Opus 5.5 --- docs/BentoBox/About/BlueprintsSummary.md | 40 +----- docs/BentoBox/About/IslandManagement.md | 4 +- docs/BentoBox/Blueprints.md | 165 ++++++++++++----------- docs/BentoBox/First-Steps.md | 2 +- docs/Glossary.md | 2 +- mkdocs.yml | 3 +- 6 files changed, 95 insertions(+), 121 deletions(-) diff --git a/docs/BentoBox/About/BlueprintsSummary.md b/docs/BentoBox/About/BlueprintsSummary.md index f2053a22..583d3f8c 100644 --- a/docs/BentoBox/About/BlueprintsSummary.md +++ b/docs/BentoBox/About/BlueprintsSummary.md @@ -1,41 +1,3 @@ # Blueprints (Custom Starter Islands) -When a player creates a new island, BentoBox pastes a pre-built starting island for them. These templates are called **Blueprints**. By default, each game mode comes with a basic starter island, but you can design your own. - -## Why Customise Your Starter Island? - -- Give your server a unique look and feel -- Control exactly what resources players start with -- Create different difficulty tiers (easy starter, hard starter) that players can choose between -- Add welcome signs and hints for new players - -## How It Works in Brief - -Blueprints are created entirely inside the game. The basic process is: - -1. Build the island you want players to start with somewhere in the world. -2. Use the admin Blueprint commands to select the area, copy it, and save it. -3. Use the Blueprint Manager GUI to assign it to a **Bundle** (a named set of starter islands). -4. Players will see the available bundles when they create a new island and can pick one. - -You can have different blueprints for the Overworld, Nether, and End, all within the same bundle. - -!!! tip - Keep starter islands small. The fun of Skyblock-style games is in the struggle to grow. Too many resources at the start removes the challenge. - -## Blueprint Manager - -The Blueprint Manager is an in-game GUI opened with: -``` -/[admin_command] blueprint -``` - -From here you can create new bundles, assign blueprints, set icons, add descriptions, and require a permission for specific bundles (e.g. a VIP starter island). - -## Performance - -Blueprint pasting is done asynchronously — it will not freeze your server no matter how large the blueprint is. If you notice lag during island creation, reduce the `paste-speed` setting in BentoBox's `config.yml`. - -## Full Documentation - -For step-by-step instructions, command reference, and tips for working with WorldEdit schematics, see the [full Blueprints page](../Blueprints.md). +This page has moved. Starter islands, blueprints and bundles are now covered on one page: **[Starter Islands (Blueprints)](../Blueprints.md)**. diff --git a/docs/BentoBox/About/IslandManagement.md b/docs/BentoBox/About/IslandManagement.md index 643bef7a..17e7b17c 100644 --- a/docs/BentoBox/About/IslandManagement.md +++ b/docs/BentoBox/About/IslandManagement.md @@ -40,7 +40,7 @@ You can change what happens: | `create-island-on-first-login.enable` | `false` | Create an island automatically when a new player joins | | `teleport-player-to-island-when-created` | `true` | Teleport the player when their island is ready | -**Choice of starter islands.** Each choice in the Create Island menu is a blueprint bundle. To make one available only to some players (for example a VIP island), set it to require a permission in `/bsbadmin blueprint`, then give `bskyblock.island.create.`. See [Starter Islands (Blueprints)](BlueprintsSummary.md) and [Making Blueprints](../Blueprints.md). +**Choice of starter islands.** Each choice in the Create Island menu is a blueprint bundle. To make one available only to some players (for example a VIP island), set it to require a permission in `/bsbadmin blueprint`, then give `bskyblock.island.create.`. See [Starter Islands (Blueprints)](../Blueprints.md). ## Island size (protection range) @@ -225,6 +225,6 @@ Make sure `deleted-sweep` is enabled, and consider `/bsbadmin purge ` or t - [Player Guide](../Player-Guide.md): the commands your players use - [Teams & Ranks](Teams.md) - [Protection, Flags & Ranks](../Island-Protection,-Flags-&-Ranks.md) -- [Starter Islands (Blueprints)](BlueprintsSummary.md) +- [Starter Islands (Blueprints)](../Blueprints.md) - [Multiple Islands](../ConcurrentIslands.md) - [Admin Tools](AdminTools.md) diff --git a/docs/BentoBox/Blueprints.md b/docs/BentoBox/Blueprints.md index deaa4fa4..3a0f11bb 100644 --- a/docs/BentoBox/Blueprints.md +++ b/docs/BentoBox/Blueprints.md @@ -1,112 +1,125 @@ -# Blueprints -**Blueprints** are a simple a quick way to make your own custom starter islands inside the game. +# Starter Islands (Blueprints) -Blueprints are *like* WorldEdit schematics but are **not** compatible. Blueprints are optimized for BentoBox addons and do not require any other plugin or library to use. +When a player creates an island, BentoBox pastes a starter island for them. These starter islands are **blueprints**, which you build and save in game. A **bundle** groups an Overworld, Nether and End blueprint into one choice in the Create Island menu, with its own icon, name and description. -Blueprints are managed with the **Blueprint Manager** and can be bundled together into a **Blueprint Bundle** to contain a set of up to 3 islands for each dimension - normal world, nether and end world. Blueprint Bundles have their own icon, description and can contain other settings, like requiring permission to use. +Each game mode comes with a few bundles. You can change them, add your own, offer VIP-only islands, charge for them, and run commands when one is chosen. -### FAQ: I have a lot of schematics - how do I convert them to Blueprints? +!!! info "Commands on this page" + Commands are shown for BSkyBlock (`/bsbadmin`). Use your game mode's admin command instead, for example `/oba` for AOneBlock or `/acid` for AcidIsland. `blueprint` can be shortened to `bp`. -It's quite easy, but you have to do it in-game because you'll need to add some signs to it. +## Make a starter island -Steps: +1. **Build it.** Build the island somewhere in the game mode's world, away from other islands. Put at least one **bedrock** block in it: the highest bedrock block becomes the island's centre, and BentoBox won't save a blueprint without one. +2. **Add the signs (optional).** Place a sign with `[spawn_here]` on the first line where players should appear, facing the way they should look. Add a sign with `[start]` on the first line for a welcome message. See [Signs](#signs). +3. **Select it.** Stand at one corner and run `/bsbadmin bp pos1`, then at the opposite corner `/bsbadmin bp pos2`. Use these, not WorldEdit's selection. +4. **Copy it.** `/bsbadmin bp copy`. Add `air` if the island will be pasted into water or stone (AcidIsland, CaveBlock, Poseidon), so the air around it is pasted too. Add `biome` to keep the biomes, or `nowater` to leave out water blocks. +5. **Check it.** Go somewhere empty and run `/bsbadmin bp paste` to see what you copied. +6. **Save it.** `/bsbadmin bp save `, for example `/bsbadmin bp save vip_island`. +7. **Offer it to players.** Open `/bsbadmin bp` and put the blueprint into a bundle (next section). -1. Load the schematic using WorldEdit -2. Paste it somewhere, I recommend some space in the BSKyBlock world away from everything -3. Find where you want the player to spawn and place a sign there with the text [spawn_here] on it. -4. (Optional) Place a welcome sign facing the place that has the text [start] on it. For details on these signs, look below -5. Select the island using the admin blueprint commands pos1 and pos2 (Remember to use the blueprint command and not WE!) -6. Copy the island using the admin blueprint copy command -7. Save the island using the admin blueprint save command -8. Repeat for all your islands including Nether and End islands. +To replace a game mode's default island instead of adding a new one, save over its blueprint (usually `island`, `nether-island` and `end-island`). You'll be asked to confirm. -Tips: Make sure you have a bedrock block in the center of the island. This is where the island will be centered around. +!!! tip "Keep it small" + The fun of island game modes is growing from very little. Start players with just enough blocks and items to get going. -## Asynchronous -All Blueprint copying and pasting is done async and should __never__ lag the server no matter how large the Blueprint. It can take a number of seconds to paste very large Blueprints. You can set how many blocks will be copied or pasted by editing the paste speed in BentoBox's config.yml. The default should be acceptable for most systems. If you run timings, you may see the pasting process taking a long time, but it is just doing about 1000 blocks per tick and should not be lagging your system. +**Converting WorldEdit schematics:** blueprints aren't schematics, but you can paste a schematic with WorldEdit, add the bedrock and signs, then select, copy and save it with the blueprint commands as above. Do this for each Nether and End island too. -## Operation -The basic flow for making a custom island: +## Bundles: the choices in the Create Island menu -1. Create a bounding box by setting two positions at opposite corners of the box - set pos1 and pos2 -2. Copy the contents of the box to the clipboard -3. Save the contents. If you just want to overwrite the default islands, save as "island", "nether-island" or "end-island" - you will be asked to confirm the overwriting. -4. Open up the Blueprint Manager, e.g., /bsb blueprint to make a new Bundle, set icons, group Blueprints, etc. +Open the Blueprint Manager with **`/bsbadmin bp`**. It lists the bundles; click one to edit it. -### Video -*Click on the thumbnail!* -[![thumbnail](https://user-images.githubusercontent.com/20014332/62939503-be4c5980-bdd1-11e9-8814-2253845cecd0.png)](https://youtu.be/4gvaG89uxAs) +| To… | Do this | +|---|---| +| Create a bundle | Click the green banner, then type a name in chat | +| Put a blueprint in a bundle | Click a blueprint at the bottom so it glows, then click the green (Overworld), red (Nether) or yellow (End) slot | +| Empty a slot | Right-click it | +| Change the bundle's icon | Click an item in your own inventory | +| Rename it | Right-click the bundle in the main list, then type the name in chat | +| Change the description | Inside the bundle, click its icon (top left), then type in chat. Colour codes like `&c` work | +| Choose where it appears in the menu | Left-click the slot icon to move it later, right-click to move it earlier | +| Make it VIP-only | Click the painting to require a permission. The permission is shown on the icon, for example `bskyblock.island.create.vip_island` | +| Charge for it | Click the gold ingot: left/right click adds/removes 1, shift-click 100. Needs Vault and an economy plugin | +| Run commands when it's chosen | Click the command block and type commands in chat | +| Limit how many times a player can choose it | Click the clock. Only shown when players can own more than one island | +| Delete it | Right-click the TNT | -## Commands -The commands are almost the same as WorldEdit schematic commands. You must be Op or an admin with permissions to use blueprints. Use the admin command and **blueprint** or its alias **bp**: +Every game mode has a bundle called `default`, which can't be deleted. It's used when a player doesn't choose (for example when islands are created automatically on first login). -* /bsb bp pos1 - set one corner of the bounding box to the position of your player -* /bsb bp pos2 - set the other corner -* /bsb bp copy - copy the blocks and entities inside the box to the clipboard -* /bsb bp copy air - copy the blocks, entities, and air inside the box to the clipboard. This is important if you plan to paste the island into water (AcidIsland) or rock (CaveBlock). -* /bsb bp paste - paste the clipboard to your location -* /bsb bp save - saves the clipboard to a file (saved as a `.blueprint` plain JSON file) -* /bsb bp load - load a blueprint file (do not append the `.blueprint` or `.blu` suffix) -* /bsb bp - open the Blueprint Manager GUI +A bundle **must** have an Overworld blueprint; if it doesn't, the default island is used and an error is logged. Nether and End blueprints are optional; without them, nothing is pasted in those worlds. -For AcidIsland, use /acid instead of /bsb. +**Rename bundles and blueprints in the manager or with `/bsbadmin bp rename`**, not by renaming files. -## Blueprint Manager GUI -The Blueprint Manager GUI enables you to create, edit and configure the island sets that players can select when they start a new island or reset. The sets of islands (normal world, nether world, and end world) are called "bundles". There is a default bundle that can be customized, but not deleted. +### Commands when a bundle is chosen -To create a new bundle, click on the green banner in the bottom left corner of the GUI. Text entry is done via the chat interface. Enter a name for the new bundle. You can change it later. +Commands run each time an island is created with the bundle, for example to give a starter kit or set a rank. `[player]` and `[owner]` are replaced with the player's name. Commands run from the console unless they start with `[SUDO]`, which runs them as the player: -The new bundle will have a default red wool icon and a name. It has three slots to the right that represent the places where you can put 3 blueprints: +``` +lp user [player] parent add skyblock-starter +[SUDO] kit starter +``` -* Green glass pane - this is the normal world blueprint slot -* Red glass pane - this is the nether world blueprint slot -* Yellow glass pane - this is the end world blueprint slot +### Charging for a bundle -Right click on these slots to clear them. +Set a cost on the bundle with the gold ingot. The player pays when they create or reset an island with it, and can't pick it if they can't afford it. This needs `use-economy: true` in BentoBox's `config.yml` and Vault with an economy plugin; without them the gold ingot isn't shown. -Below the line of dark gray glass panes, you will see a number of blueprints to choose. Click on the one you want and it will glow. Then click on the slot where you want to put it. You can put the same blueprint in all three slots or have different blueprints for each one, it is up to you. +## Signs -To add a description to the bundle right click on the bundle icon and enter a description in the chat. Keep each line short so the GUI does not look too big. You can set the text color using Bukkit color codes, like &c for red. +| First line of the sign | What happens | +|---|---| +| `[spawn_here]` | Players appear at this spot, facing the way the sign faces. The sign is removed. Works in Nether and End blueprints too | +| `[start]` | Replaced with the welcome text from the game mode's locale file (`bskyblock.sign.line0` to `line3`), in the owner's language. `[name]` in that text becomes the owner's name | +| Anything else | Pasted as written | -To change a bundle's icon, click on an item in your inventory and it will replace the bundle's icon. To change a blueprint's icon, select the blueprint and then click on the inventory item. +**Named mobs:** rename a name tag to include `[name]` in an anvil and put it on a mob in your island before copying. The mob is named after the island owner when the island is pasted. -To limit a bundle to players with the right permission, click the picture item to toggle whether permission is required or not. The icon will show what permission is required in its text (it is based on the name of the bundle). The permission is `GameModeAddonName.island.create.uniqueId` of blueprint bundle. e.g. `bskyblock.island.create.vip`. +## All blueprint commands -To delete a bundle, right click on the TNT. +| Command | What it does | +|---|---| +| `/bsbadmin bp` | Open the Blueprint Manager | +| `/bsbadmin bp pos1`, `pos2` | Set the corners of the area to copy | +| `/bsbadmin bp copy [air] [biome] [nowater]` | Copy the area to your clipboard | +| `/bsbadmin bp origin` | Set the paste origin to the block you're looking at | +| `/bsbadmin bp paste` | Paste your clipboard where you stand | +| `/bsbadmin bp save ` | Save your clipboard as a blueprint | +| `/bsbadmin bp load ` | Load a blueprint into your clipboard to change it | +| `/bsbadmin bp list` | List the blueprints | +| `/bsbadmin bp rename ` | Rename a blueprint | +| `/bsbadmin bp delete ` | Delete a blueprint | +| `/bsbadmin bp sink` | Toggle whether this blueprint sinks to the sea floor when pasted | -Bundles and blueprints must be renamed in the GUI. Do not try to rename them using the file system. +## The files -## Files and Editing -When using blueprints in the game, always use just the name of the blueprint. On the file system, blueprints are now saved as **plain JSON text** files with the `.blueprint` suffix. Blueprint bundles are also saved as `.json` text files. Both `.blueprint` and bundle `.json` files can be edited with any text editor. +Blueprints and bundles are stored per game mode in `plugins/BentoBox/addons//blueprints/`: -!!! note "Legacy `.blu` files" - Blueprint files previously used a compressed binary `.blu` format. BentoBox will automatically load legacy `.blu` files for backward compatibility, but all new blueprints are saved as `.blueprint` (plain JSON). You can version-control and diff `.blueprint` files normally. Do not try to create or edit `.blu` files by hand. +- `.blueprint`: a blueprint, as plain JSON. Older `.blu` files (compressed) still load. +- `.json`: a bundle, as plain JSON. -If you edit or generate these files directly, the full field-level reference is the [Blueprint File Format](Blueprint-Format.md) page, and BentoBox publishes [JSON Schemas](https://github.com/BentoBoxWorld/BentoBox/tree/develop/schemas) you can validate against. +You can copy these files between servers, keep them in version control, or edit them. For every field, see [Blueprint File Format](Blueprint-Format.md). -## Incomplete bundles -Bundles must always have an Overworld/Normal world blueprint. If they do not, then the default island blueprint will be used and an error logged in the console. -Bundles do not have to have Nether or End World blueprints, but if they do not, no island will be pasted in those worlds (obviously). +## Pasting speed -## Entities +Copying and pasting happen a little at a time, so large islands don't freeze the server; a big island can take a few seconds. If island creation causes lag, lower `paste-speed` (blocks per tick) in BentoBox's `config.yml`. -!!! new "Coming in BentoBox 1.14.0" - In this upcoming release, you will also be able to use `[name]`, which will be replaced by the island owner's name when creating the island. +## Troubleshooting -You can use placeholders in entities' names. -Rename a name tag with the placeholder in an anvil, then apply the name tag to the entity. +**"At least one bedrock block must be in a blueprint!"** +Add a bedrock block to the island, copy again, then save. -## Signs -Blueprints can have two special signs in them to help you place where a player will spawn and to give them a welcome message. +**Players appear in the wrong place, or fall.** +Add a `[spawn_here]` sign, with air above it for the player. + +**The island is surrounded by water (or stone) gaps that shouldn't be there**, or water from the world flows into it. +Copy with `air` so the space around the island is part of the blueprint. Keep the selection tight, as air makes the file bigger. + +**My new bundle doesn't show in the Create Island menu.** +Check that it has an Overworld blueprint, that it doesn't require a permission the player lacks, and, if it has a use limit, that the player hasn't used it up. With `hide-used-blueprints: true` in BentoBox's `config.yml`, used-up bundles are hidden. -### Spawn Here Sign -Place a sign with the first line as [spawn_here] (in English) where you want the player to spawn. They will appear in this position and the sign will not be pasted. This applies to all world islands, so you can specify where players will appear in the Nether when they go through a portal, for example. +**The welcome sign shows `[start]`.** +The `[start]` text comes from the game mode's locale file. Check `.sign.line0` to `line3` exist in it. -### Welcome Sign -The welcome sign provides a friendly way to give players a hint about the game and what to do, or not do! Place a sign with [start] (in English) on the first line. The sign's text will be replaced by the sign text in the GameModeAddon's locale file. +## See also -## Tips & Recommendations -* We recommend that you keep starting islands small to make the game a challenge. Put just enough items and blocks on an island for players to be able to grow their island. -* Try making split islands (think up and down, side to side) to give players a target to build to when they have the resources. -* If you are copying with air, try to make your bounding box as small as possible to keep the file size small. -* After copying a blueprint, try pasting it to check it was copied correctly. Then save it. +- [Islands](About/IslandManagement.md): creating, resetting and sizing islands +- [Bigger Create Island Menu](../Tutorials/generic/Bigger-Create-Island-Menu.md) and [Customizing Menus](../Tutorials/generic/Customizable-GUI.md): the menu players choose from +- [Blueprint File Format](Blueprint-Format.md): for editing the files diff --git a/docs/BentoBox/First-Steps.md b/docs/BentoBox/First-Steps.md index 19a63330..8fe3ce7b 100644 --- a/docs/BentoBox/First-Steps.md +++ b/docs/BentoBox/First-Steps.md @@ -116,7 +116,7 @@ Quick summary: 3. Use `/[admin_command] blueprint copy` then `save myisland` 4. Open `/[admin_command] blueprint` to manage bundles -See [Blueprints](About/BlueprintsSummary.md) for the full walkthrough. +See [Starter Islands (Blueprints)](Blueprints.md) for the full walkthrough. --- diff --git a/docs/Glossary.md b/docs/Glossary.md index 64398154..d401fc18 100644 --- a/docs/Glossary.md +++ b/docs/Glossary.md @@ -11,7 +11,7 @@ A file (`.jar`) that extends BentoBox with new features. Addons go in `plugins/B Each game mode has an admin-only command for managing islands, settings, and players. For BSkyBlock it is `/bsb`, for AcidIsland it is `/acid admin`, etc. The exact command is listed in each game mode's documentation. ## Blueprint -A saved template of a built island used when a player creates a new island. BentoBox comes with default blueprints but admins can create their own in-game. Blueprints are stored in `plugins/BentoBox/blueprints/`. See [Blueprints](BentoBox/About/BlueprintsSummary.md). +A saved template of a built island used when a player creates a new island. BentoBox comes with default blueprints but admins can create their own in-game. Each game mode keeps its blueprints in `plugins/BentoBox/addons//blueprints/`. See [Starter Islands (Blueprints)](BentoBox/Blueprints.md). ## Blueprint Bundle A named set of blueprints (one each for the Overworld, Nether, and End) grouped together. When a player creates a new island, they may be presented with a choice of bundles. Each bundle can have its own icon, description, and permission requirement. diff --git a/mkdocs.yml b/mkdocs.yml index 41ae8801..dc32d604 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,8 +21,7 @@ nav: - Islands: BentoBox/About/IslandManagement.md - "Multiple Islands": BentoBox/ConcurrentIslands.md - "Permissions & VIP Perks": BentoBox/Permissions-Guide.md - - "Starter Islands (Blueprints)": BentoBox/About/BlueprintsSummary.md - - "Making Blueprints": BentoBox/Blueprints.md + - "Starter Islands (Blueprints)": BentoBox/Blueprints.md - "Customizing Menus": Tutorials/generic/Customizable-GUI.md - "Bigger Create Island Menu": Tutorials/generic/Bigger-Create-Island-Menu.md - "Languages & Messages": BentoBox/About/Multilingual.md