Set it up.
Understand every part.

Getting started

CobbleBet connects your Minecraft server to the CobbleBet website. Players use /gamble to get a private sign-in link, then play in their browser using a wallet backed by your server’s economy.

Install the plugin

1. Download CobbleBet.jar and put it in your server’s plugins folder.
2. Start the server once. CobbleBet creates plugins/CobbleBet/config.yml.
3. Set your economy options in that file, then restart the server or run /cobblebet reload.
4. Check the server console for a successful connection. Use In-game permissions in the owner panel to decide whether commands require their permission nodes.

The plugin connects securely to wss://cobblebet.com/mc; no plugin key is required.

Economy and wallet

Choose the wallet source in /cobblebet panel under Your server economy. Pick Vault to use your existing server money, or Item to choose a Minecraft material such as DIAMOND. Apply the change while the server is online; CobbleBet validates it, updates plugins/CobbleBet/config.yml, and refreshes player balances.

• Vault: requires Vault and an active Vault-compatible economy plugin. Deposits are withdrawn from the player’s economy, and withdrawals are returned to it.
• Item: players deposit whole items into their CobbleBet wallet and can withdraw them later. Use a Bukkit material name such as DIAMOND or AMETHYST_SHARD.

Balances are kept separately for Vault and each item. Switching economies does not convert balances; switching back restores the prior balance for that source. Wallet data is stored locally under plugins/CobbleBet/wallets/. Back up that folder with your world and plugin data.

Commands and permissions

Minecraft 1.21.7 and newer use the native dialog interface. Earlier Paper 1.21 releases automatically use the compatible inventory menus.

Plugin configuration

These options are read from plugins/CobbleBet/config.yml. Edit the file and use /cobblebet reload where noted, or restart the server.

The permanent server ID, physical models, and updater state are stored in plugins/CobbleBet/data.yml. CobbleBet Plus status is verified by cobblebet.com for that server ID rather than trusted from a local switch.

PlaceholderAPI and leaderboards

Install PlaceholderAPI and restart the server. CobbleBet detects it automatically and registers the cobblebet expansion; there is no expansion download or extra configuration. PlaceholderAPI is optional, so CobbleBet still runs normally when it is absent.

Example: use %cobblebet_top_1_name% — %cobblebet_top_1_balance_formatted% %cobblebet_currency% as the first line of a hologram leaderboard. Empty positions return blank text. If Minecraft has not cached an offline player’s name yet, the name placeholder safely falls back to that player’s UUID.

Owner panel

1. Give trusted owners the cobblebet.admin permission.
2. In game, run /cobblebet panel.
3. Open the one-use link sent privately to that player. It expires after five minutes.
4. Choose a player theme, welcome message, available games, public join address, economy, broadcasts, and command permission requirements.

The Activity console, player-site controls, and non-classic model skins require CobbleBet Plus. CobbleBet site administrators can inspect those tabs while supporting a connected server. Settings are associated with the plugin’s permanent server ID and persist across reconnects.

Plugin updates

Open /cobblebet → Server settings → Updates to enable or disable automatic updates, view the installed and published versions, see the current download state, or run a fresh check. Automatic updates are enabled by default.

A published release only installs automatically when the CobbleBet administrator explicitly marks that upload as approved for automatic update. The plugin validates the downloaded JAR name, version, size, and SHA-256 checksum before placing it in Paper’s plugins/update folder. Perform a full server restart to install a staged release.

Operators and players with cobblebet.admin receive a join message when an update is downloading, staged for restart, requires manual installation, or failed. Development test mode checks localhost:8908; production uses https://cobblebet.com.

Game payouts, backgrounds and saved settings

Every game has one optional modifier named Extra house edge. It defaults to 0%. Open Manage games, choose a game, and use its slider or percentage input from 0–50%. Coinflip also has a maximum stake field which applies to its website and in-game lobbies. Press Save changes. Bets already placed keep their locked settings, and open Coinflip listings keep the value used when they were created.

The extra house edge reduces the game’s normal payout by the selected percentage. For example, 10% changes a normal 2× payout to 1.8×. It does not change random mine positions, cards, Roulette numbers, Coinflip odds, or Plinko bounces. Players always see the normal game explanation below its controls. When an extra edge is above 0%, a separate yellow notice shows the exact percentage set by the owner.

Payouts include the original stake and are rounded down to 0.1 currency units, which can increase the effective edge for small bets. Existing saved values remain in place after updating; set a game to 0% in the owner panel to remove its extra edge.

Under Choose a look, select a theme or upload a PNG, JPEG or WebP background up to 10 MB. Images are resized and compressed to at most 500 KB. The blur slider ranges from 0 to 30 pixels; the preview shows the result before saving.

The updated plugin saves themes, messages, game availability, extra house edge values, backgrounds and blur in websiteCustomization at the bottom of plugins/CobbleBet/config.yml. Generated state such as the permanent server ID, staged updater state, and physical game locations is kept separately in plugins/CobbleBet/data.yml. Player balances remain in the wallets folder. Existing values migrate automatically on first startup. The website waits for the plugin to confirm the file was saved. Economy, permissions and broadcasts continue to use their existing config fields. After manual config edits, use /cobblebet reload.

CobbleBet staff can open a connected server’s owner panel from the site admin dashboard. The internal admin can activate or disable CobbleBet Plus for a subscribed server, and that status is saved against the server’s permanent CobbleBet identity.

Games and broadcasts

The website offers Mines, Blackjack, Roulette, Coinflip, Plinko, Dice, and Crash. The owner panel can enable or disable each game for your players. Disabling a game hides its card and blocks its game page for that server.

Coinflip is a player-versus-player lobby. A creator’s stake is reserved while the listing stays open. The first different player to match that stake starts one fair 50/50 flip; the winner receives the pot after the fee shown on the listing. The creator can cancel an open listing to get the reserved stake back. Players are matched only with players using the same server economy.

Big-win broadcasts can be switched on or off in the owner panel and in broadcastingEnabled / broadcastEvents.bigWin. A win must pay more than 3× its bet and meet bigWinThreshold (in the same currency units as your wallet). The plugin’s broadcast listener formats {player}, {amount}, and {currency} in your prefix/message. Coinflip results also send the player a private in-game result message.

Troubleshooting

• Server won’t connect: check outbound WebSocket access to wss://cobblebet.com/mc, and check the server console.
• Players cannot open the games: make sure the plugin is connected and the player has permission to use /gamble.
• Placeholders stay unchanged: install PlaceholderAPI, restart the server, and confirm the console says the %cobblebet_*% expansion registered. Do not use /papi ecloud download; the expansion is built into CobbleBet.
• Plugin update does not download: open /cobblebet → Server settings → Updates and read the displayed status. Confirm automatic updates are enabled and that the uploaded release was marked Allow automatic update. Use Check now after changing the setting.
• Update downloaded but version did not change: perform a full server restart. A plugin reload does not install JARs staged in plugins/update.
• Vault deposits fail: verify Vault and an economy provider are installed and enabled.
• Item wallet doesn’t change: make sure economyType: "item" and a valid material name are configured.
• Owner panel link expired: request a new link with /cobblebet panel.

Physical games

Use /cobblebet game to create and manage persistent Coinflip boards, Mines fields, Blackjack tables, Plinko boards, and Roulette tables. Each game keeps its position and appearance in plugins/CobbleBet/data.yml. The management screen separates position, play settings, appearance, and permanent removal actions.

All five models support fine 22.5° rotation with Rotate left and Rotate right. The command equivalents are rotateleft and rotateright; use rotate90left or rotate90right for a full quarter turn. Mines can switch between horizontal or vertical layouts and GUI or world play. Blackjack can switch between GUI and world play. Plinko is always played directly on its world board. Roulette uses a square table and opens a color-or-number betting board when a player right-clicks it.

Roulette spins are settled by the CobbleBet server using the same payout rules, extra house edge, wallet checks, fairness record, and game history as browser Roulette. Owners can choose classic, royal, modern, or nether table styles.

For Plinko, players choose a stake, ball count, 8–16 rows, and a risk level. A player can right-click anywhere across the board to open its controls. Landing bins appear during an active drop and the CobbleBet server supplies the verified path and payout.

Build a CobbleBet integration

Third-party plugins can connect to CobbleBet and let their players use the games through a server-side economy connection. The WebSocket service does not require an approval key. Your plugin is responsible for checking Minecraft permissions before requesting player links or owner actions.

Use the official CobbleBet plugin source as the current reference implementation. For protocol questions and integration review, join the CobbleBet Discord.

Integration requirements

• Use a supported server API and document the tested Minecraft/server versions.
• Check permissions on the server before requesting player login links or owner actions.
• Use TLS (wss://) in production and do not disable certificate validation.
• Validate message fields, handle reconnects safely, and avoid sending duplicate token requests.
• Explain data collection and only send the server/player details needed for the integration.
• Keep the integration source available for review and report changes that affect CobbleBet messages or permissions.

Connect to the service

Connect a WebSocket client to wss://cobblebet.com/mc. On open, send a JSON text frame with server metadata. The server replies with approvalAccepted for compatibility with the current CobbleBet JAR; this is a connection acknowledgement and does not validate a key.

{
  "type": "connect",
  "serverId": "PERSISTENT_SERVER_UUID",
  "serverPort": 25565,
  "serverName": "My Server",
  "pluginName": "ExampleIntegration",
  "pluginVersion": "1.0.0",
  "currencyName": "Coins",
  "bigWinThreshold": 500
}

Once connected, the connection may send supported message types. Generate one UUID on first startup, persist it, and send it as serverId on every connection; CobbleBet uses that stable identity for settings and Plus access even when the network address changes. Send a serverStatus update periodically with the server name, plugin version, public join address, server software, and current online player list.

Open the games for a player

1. On the Minecraft server, confirm the player has your permission to use CobbleBet.
2. Send {"type":"requestToken","playerUUID":"PLAYER_UUID"} over the WebSocket.
3. Handle tokenResponse for that UUID. The reply contains a one-use token, not a URL. Build https://cobblebet.com/auth/magic-login?token=TOKEN and send it privately to the same player.
4. The player opens the link and is linked to your plugin connection. Balance requests and game updates then use the existing CobbleBet protocol.

Player login tokens are still required for private sign-in links. Treat them as temporary passwords: never broadcast them or write them to logs.

Minimal Java connection example

This sketch shows the connection handshake using the bundled Java-WebSocket library. Include imports for Bukkit, Gson, Java-WebSocket, Adventure text, URI encoding, and UUIDs in a working plugin.

var client = new WebSocketClient(URI.create("wss://cobblebet.com/mc")) {
    private volatile boolean connected;

    @Override public void onOpen(ServerHandshake handshake) {
        JsonObject hello = new JsonObject();
        hello.addProperty("type", "connect");
        hello.addProperty("serverPort", Bukkit.getPort());
        hello.addProperty("serverName", Bukkit.getMotd());
        hello.addProperty("pluginName", "ExampleIntegration");
        hello.addProperty("pluginVersion", plugin.getDescription().getVersion());
        send(hello.toString());
    }

    @Override public void onMessage(String text) {
        JsonObject message = JsonParser.parseString(text).getAsJsonObject();
        if ("approvalAccepted".equals(message.get("type").getAsString())) {
            connected = true;
            return;
        }
        if (!connected) return;
        if ("tokenResponse".equals(message.get("type").getAsString())) {
            String uuid = message.get("playerUUID").getAsString();
            String token = URLEncoder.encode(message.get("token").getAsString(), StandardCharsets.UTF_8);
            String loginUrl = "https://cobblebet.com/auth/magic-login?token=" + token;
            Player player = Bukkit.getPlayer(UUID.fromString(uuid));
            if (player != null) {
                player.sendMessage(Component.text("Open your CobbleBet games: ")
                    .append(Component.text(loginUrl).clickEvent(ClickEvent.openUrl(loginUrl))));
            }
        }
    }
};
client.connect();

// After checking the sender's permission:
JsonObject request = new JsonObject();
request.addProperty("type", "requestToken");
request.addProperty("playerUUID", player.getUniqueId().toString());
client.send(request.toString());

In production, also provide reconnect/backoff handling, bound input sizes, verify required fields and message types, and schedule Bukkit API calls on the server thread.

Message reference

See the official CobbleBet plugin source for the complete current message shapes and callbacks. The protocol may evolve; integrations should ignore unknown message types and validate all values before acting.

Customization persistence protocol

Send playerName with requestToken and requestAdminPanel for the greetings. To support panel customization, add supportsWebsiteSettings: true, websiteSettingsInitialized and websiteSettings to the connection handshake. Persist the received settings before replying to setWebsiteSettings with {type: "websiteSettingsResult", requestId, success: true, settings}. An unsuccessful disk save must return success: false. On future connections, send the saved settings with the initialized flag set to true. The object contains theme, playerMessage, enabledGames, gameRules (each game has percent), and background (image data URL and blur).

For broadcast settings, accept setBroadcastSettings with requestId and broadcastingEnabled, persist the setting, and reply with broadcastSettingsResult. Report the effective flag on connection and status updates. Big-win requests include betAmount and multiplier; only accept payouts strictly over 3× the bet which also meet the configured minimum amount.

Security checklist

• Check in-game permissions before sending requestToken or requestAdminPanel.
• Deliver login links only to the matching player over a private channel.
• Use TLS in production and close the socket when the plugin shuts down.
• Treat all network messages as untrusted input and validate UUIDs, amounts, names, and message lengths.