Skip to content

Commit 34620cc

Browse files
objzobjz
committed
doc: revised for 3.4.0
1 parent 099bebf commit 34620cc

1 file changed

Lines changed: 187 additions & 107 deletions

File tree

‎README.md‎

Lines changed: 187 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -8,152 +8,244 @@
88
[![Issues][issues-shield]][issues-url]
99
[![GPL-3.0 License][license-shield]][license-url]
1010

11-
**Cross-server command execution for Minecraft networks**
11+
**cross-server command execution for Minecraft networks**
1212

13-
A WebSocket bridge for Velocity and Paper servers to run commands anywhere, anytime.
13+
define commands in YAML on Velocity, dispatch them across all connected backends over WebSocket or Redis.
14+
no plugin messaging, no player-online requirements, no limitations.
15+
16+
[![Documentation](https://img.shields.io/badge/Documentation-cb.objz.dev-7c3aed?style=for-the-badge)](https://cb.objz.dev)
17+
[![Discord](https://img.shields.io/badge/Discord-Join_Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/QPqBYb44ce)
1418

1519
[Report Bug](https://github.com/objz/CommandBridge/issues) · [Request Feature](https://github.com/objz/CommandBridge/issues)
1620

1721
</div>
1822

1923
---
2024

21-
## About The Project
25+
## about
26+
27+
CommandBridge is a proxy-to-backend command bridge for Minecraft networks running on Velocity. you write commands as YAML scripts on the proxy, CB validates them, registers them on whichever servers you specified, and handles dispatch. a player runs `/lobby` on a backend, the proxy picks it up. an admin runs `/alert` on Velocity, every backend executes it. commands go through instantly.
28+
29+
the whole reason this exists: plugin messages need a connected player to work. if a server is empty, you can't send commands to it. CB uses persistent WebSocket connections (or Redis) to fix that. commands work regardless of player presence.
30+
31+
one jar works everywhere. install the same file on Velocity and all your backends. it auto-detects the platform.
32+
33+
for the full writeup with visuals check the [documentation](https://cb.objz.dev), the [Modrinth page](https://modrinth.com/plugin/commandbridge), [Hangar](https://hangar.papermc.io/objz/CommandBridge/), or [SpigotMC](https://www.spigotmc.org/resources/commandbridge.133217/).
34+
35+
## features
36+
37+
| | |
38+
|---|---|
39+
| **scripting** | YAML command definitions with aliases, permissions, cooldowns, 22 argument types |
40+
| **transport** | WebSocket (default, TLS built in) or Redis |
41+
| **execution** | `CONSOLE`, `PLAYER`, `OPERATOR` modes |
42+
| **security** | HMAC-SHA256 mutual auth, TLS 1.3 (PLAIN / TOFU / STRICT) |
43+
| **offline queue** | queues commands for offline players, survives restarts |
44+
| **multi-proxy** | primary + client mode for additional proxies |
45+
| **player tracking** | network-wide, real-time |
46+
| **admin CLI** | `/cb help`, `info`, `scripts`, `reload`, `list`, `ping`, `debug`, `dump`, `migrate` |
47+
| **developer API** | message channels, event subscriptions, player locator, broadcast |
48+
| **optional integrations** | PlaceholderAPI, PacketEvents |
49+
50+
---
51+
52+
## how it's built
53+
54+
everything gets shaded into a single fat jar. there are a few modules but you only ever deal with one file.
2255

23-
CommandBridge connects your Velocity proxy to your backend servers using WebSockets(version 3.1.0 covers redis as alternative). It lets you run commands across your network even if no players are online.
56+
`core` is the shared library that both sides depend on. networking (WebSocket via Undertow, Redis via Jedis), the YAML scripting engine with validation, security (TLS, auth), config management, and logging. anything that isn't platform-specific lives here.
2457

25-
### The Problem
58+
`velocity` is the proxy-side plugin. command registration, the dispatch pipeline, the admin CLI, and the UI output all live here. this is the "server" side of the bridge.
2659

27-
Plugin messages need a player to work. If a server is empty, you can't send commands to it. CommandBridge uses persistent connections(or redis) to fix this.
60+
`backends` is the shared client library for all backend platforms. it handles connecting to the proxy, routing incoming messages, and platform abstraction. underneath it there are platform-specific adapters for Bukkit, Paper, Folia, and Velocity-as-client. the adapters are kept thin on purpose, they only deal with thread dispatch and platform-specific API calls. shared logic stays in the parent module.
2861

29-
<p align="right">(<a href="#top">back to top</a>)</p>
62+
`api` is the public developer API for other plugins. channels, events, platform info. more on that below.
3063

31-
## Built With
64+
`dist` handles shadow JAR packaging and publishing to Modrinth and Hangar.
3265

33-
[![Java][Java]][Java-url]
34-
[![Undertow][Undertow]][Undertow-url]
35-
[![Jackson][Jackson]][Jackson-url]
36-
[![Velocity][Velocity]][Velocity-url]
37-
[![Paper][Paper]][Paper-url]
38-
[![Gradle][Gradle]][Gradle-url]
66+
---
3967

40-
<p align="right">(<a href="#top">back to top</a>)</p>
68+
## building from source
4169

42-
## Building from Source
70+
requires JDK 21 (Temurin recommended).
4371

4472
```sh
4573
git clone https://github.com/objz/CommandBridge.git
4674
cd CommandBridge
47-
4875
git checkout v3
49-
5076
./gradlew shadowJar
77+
# output: dist/build/libs/CommandBridge-<version>-all.jar
78+
```
79+
80+
other useful commands:
81+
82+
```sh
83+
# full build (compile + shadow JAR)
84+
./gradlew build
5185

52-
# Output: dist/build/libs/CommandBridge-all.jar
86+
# run checkstyle (this is what CI runs)
87+
./gradlew check
88+
89+
# checkstyle for a specific module
90+
./gradlew :core:checkstyleMain
91+
./gradlew :velocity:checkstyleMain
92+
93+
# clean
94+
./gradlew clean
5395
```
54-
<p align="right">(<a href="#top">back to top</a>)</p>
5596

56-
## Roadmap
97+
---
98+
99+
## developer API
100+
101+
CB has a public API module for other plugins to interact with the bridge network. source is at [`api/`](https://github.com/objz/CommandBridge/tree/v3/api/src/main/java/dev/objz/commandbridge/api), full documentation will be on [cb.objz.dev](https://cb.objz.dev).
102+
103+
```java
104+
CommandBridgeAPI api = CommandBridgeProvider.get();
57105

58-
### Current Status: Beta (v3.0)
106+
// send a command as console to a backend
107+
CommandChannel commands = api.channel(Channels.COMMAND);
108+
commands.console(Platform.BACKEND.target("survival-1"), "say hello");
59109

60-
- [x] **Backend Platform Support**
110+
// listen for incoming messages
111+
Subscription sub = commands.listen((ctx, payload) -> { /* ... */ });
112+
113+
// server events
114+
api.onServerConnected(server -> { /* ... */ });
115+
api.onServerDisconnected(server -> { /* ... */ });
116+
117+
// find a player across the network
118+
api.playerLocator().ifPresent(locator -> locator.locate(playerUuid));
119+
120+
// broadcast to all servers
121+
api.broadcast(commands, CommandPayload.console("say maintenance in 5 minutes"));
122+
```
123+
124+
---
125+
126+
## dependencies
127+
128+
### shaded (bundled in the jar)
129+
130+
| Library | What it does |
131+
|---|---|
132+
| [Undertow](https://undertow.io/) | WebSocket server |
133+
| [Jackson](https://github.com/FasterXML/jackson) | JSON serialization |
134+
| [Jedis](https://github.com/redis/jedis) | Redis client |
135+
| [OkHttp](https://github.com/square/okhttp) | HTTP client on backends |
136+
| [Configurate](https://github.com/SpongePowered/Configurate) | YAML config loading |
137+
| [SnakeYAML](https://bitbucket.org/snakeyaml/snakeyaml) | YAML parsing |
138+
| [Adventure MiniMessage](https://docs.advntr.dev/minimessage/) | chat formatting |
139+
| [BouncyCastle](https://www.bouncycastle.org/) | TLS and crypto |
140+
| [bStats](https://bstats.org/) | anonymous usage metrics |
141+
142+
### runtime (you install these)
143+
144+
| Library | Required | What it does |
145+
|---|---|---|
146+
| [CommandAPI](https://modrinth.com/plugin/commandapi) | yes | argument parsing and tab completion on all servers |
147+
| [PacketEvents](https://modrinth.com/plugin/packetevents) | no | enables extra argument types (like `PLAYERS` and `TIME`) on Velocity |
148+
| [PlaceholderAPI](https://modrinth.com/plugin/placeholderapi) | no | external placeholder data (stats, economy, etc.) |
149+
| [PapiProxyBridge](https://modrinth.com/plugin/papiproxybridge) | no | bridges PlaceholderAPI to the proxy side |
150+
151+
---
152+
153+
## roadmap
154+
155+
### current: v3.3.0
156+
157+
- [x] **backend platform support**
61158
- [x] Bukkit support
62159
- [x] Paper support
63160
- [x] Folia support
64-
- [x] Velocity(as client) support
65-
- [x] Automatic platform detection
161+
- [x] Velocity-as-client support (for multi-proxy)
162+
- [x] automatic platform detection
66163

67-
- [x] **WebSocket Communication**
164+
- [x] **WebSocket transport**
68165
- [x] WebSocket server on Velocity
69166
- [x] WebSocket client on backends
70-
- [x] Session and client management
71-
- [x] Rate limiting
72-
- [x] Automatic reconnection on disconnect(configurable)
167+
- [x] session and client management
168+
- [x] rate limiting
169+
- [x] automatic reconnection on disconnect (configurable)
73170

74-
- [x] **Alternative Redis Communication**
75-
- [x] Extended config for Redis
171+
- [x] **Redis transport**
172+
- [x] Redis config and connection management
76173
- [x] Redis implementation in core (SendOperation)
77-
- [x] Channel mapping alternative on velocity
78-
- [x] Sending/Receiving support on all Platforms
174+
- [x] channel mapping on Velocity
175+
- [x] sending/receiving on all platforms
79176

80-
- [x] **Security**
81-
- [x] Mutual authentication (HMAC-SHA256)
177+
- [x] **security**
178+
- [x] mutual authentication (HMAC-SHA256)
82179
- [x] TLS SPKI key pinning
83180
- [x] TLS 1.3 encryption
84-
- [x] Multiple TLS modes (PLAIN, TOFU, STRICT)
85-
86-
- [x] **YAML Scripting**
87-
- [x] YAML command definitions
88-
- [x] Strict validation
89-
- [x] Aliases, permissions, and cooldowns
90-
- [x] Argument types (strings, numbers, players, locations, items, etc.)
91-
- [x] Custom argument types via PacketEvents
92-
- [ ] Duplicate script name detection
93-
- [ ] More custom argument types
94-
95-
- [x] **Cross-Server Command Execution**
96-
- [x] Remote and local command execution
97-
- [x] Automatic command registration sync to backends
98-
- [x] Placeholder and PlaceholderAPI support
99-
- [x] Console, player, and operator execution modes
100-
- [x] Offline command queue
101-
- [ ] Database backend for task queue (currently JSON file) | maybe?
102-
103-
- [x] **Admin Commands (`/cb`)**
104-
- [x] `/cb help`
105-
- [x] `/cb info`
106-
- [x] `/cb scripts`
107-
- [x] `/cb reload`
108-
- [x] `/cb list`
109-
- [x] `/cb ping`
110-
- [x] `/cb debug`
111-
- [x] `/cb dump`
112-
- [x] `/cb migrate`
113-
- [x] Dual-mode output (chat and console)
114-
- [x] Automatic update checker
115-
- [x] Dump export to file or paste service
116-
- [x] Migration implementation for scripts
117-
- [x] bstats
118-
119-
- [ ] **Web Interface**
120-
- [ ] ...
121-
122-
- [ ] **Admin GUI**
181+
- [x] multiple TLS modes (PLAIN, TOFU, STRICT)
182+
183+
- [ ] **YAML scripting**
184+
- [x] YAML command definitions with strict validation
185+
- [x] aliases, permissions, and cooldowns
186+
- [x] 22 argument types (strings, numbers, players, locations, items, entities, etc.)
187+
- [x] custom argument types via PacketEvents
188+
- [x] script migration tooling (`/cb migrate`)
189+
- [x] schema versioning (currently `version: 4`)
190+
- [ ] duplicate script name detection
191+
- [ ] more custom argument types
192+
193+
- [x] **cross-server command execution**
194+
- [x] remote and local command dispatch
195+
- [x] automatic command registration sync to backends
196+
- [x] placeholder and PlaceholderAPI support
197+
- [x] console, player, and operator execution modes
198+
- [x] offline command queue (persists across restarts)
199+
- [x] network-wide player tracking and UUID resolution
200+
201+
- [x] **admin CLI (`/cb`)**
202+
- [x] `/cb help`, `/cb info`, `/cb scripts`
203+
- [x] `/cb reload`, `/cb list`, `/cb ping`
204+
- [x] `/cb debug`, `/cb dump`, `/cb migrate`
205+
- [x] dual-mode output (chat + console)
206+
- [x] dump export to file or paste service
207+
- [x] automatic update checker
208+
- [x] bStats integration
209+
210+
- [ ] **developer API**
211+
- [x] public API module (`api/`)
212+
- [x] typed message channels with send, request, and listen
213+
- [x] command channel with console/player/operator dispatch
214+
- [x] server connect/disconnect event subscriptions
215+
- [x] connection state tracking
216+
- [x] player locator service
217+
- [x] broadcast to all connected servers
218+
- [ ] more channel types and lifecycle hooks
219+
220+
- [ ] **web interface**
123221
- [ ] ...
124222

125-
- [ ] **Developer API**
223+
- [ ] **admin GUI**
126224
- [ ] ...
127225

128-
See the [open issues](https://github.com/objz/CommandBridge/issues) for features and bugs.
226+
see the [open issues](https://github.com/objz/CommandBridge/issues) for bugs and feature requests.
129227

130-
<p align="right">(<a href="#top">back to top</a>)</p>
131-
132-
## Contributing
133-
134-
Contributions are welcome.
228+
---
135229

136-
- Update documentation
137-
- Ensure builds pass: `./gradlew shadowJar`
230+
## requirements
138231

139-
<p align="right">(<a href="#top">back to top</a>)</p>
232+
| | Version |
233+
|---|---|
234+
| Java | 21+ |
235+
| Velocity | 3.4 - 3.5 |
236+
| Minecraft | 1.20 - 1.21.x |
140237

141-
## License
238+
---
142239

143-
Distributed under the GPL-3.0 License. See `LICENSE`.
240+
## contributing
144241

145-
<p align="right">(<a href="#top">back to top</a>)</p>
242+
contributions are welcome. fork it, branch it, PR it. make sure `./gradlew check` and `./gradlew build` both pass before opening a PR.
146243

147-
## Acknowledgments
244+
---
148245

149-
* [Undertow](https://undertow.io/)
150-
* [Jackson](https://github.com/FasterXML/jackson)
151-
* [CommandAPI](https://github.com/JorelAli/CommandAPI)
152-
* [SnakeYAML](https://bitbucket.org/snakeyaml/snakeyaml)
153-
* [Velocity](https://papermc.io/software/velocity)
154-
* [Paper](https://papermc.io/software/paper)
246+
## license
155247

156-
<p align="right">(<a href="#top">back to top</a>)</p>
248+
GPL-3.0. see [LICENSE](LICENSE).
157249

158250
---
159251

@@ -168,15 +260,3 @@ Distributed under the GPL-3.0 License. See `LICENSE`.
168260
[license-shield]: https://img.shields.io/github/license/objz/CommandBridge.svg?style=for-the-badge
169261
[license-url]: https://github.com/objz/CommandBridge/blob/v3/LICENSE
170262

171-
[Java]: https://img.shields.io/badge/Java-21-ED8B00?style=for-the-badge&logo=openjdk&logoColor=white
172-
[Java-url]: https://openjdk.org/projects/jdk/21/
173-
[Undertow]: https://img.shields.io/badge/Undertow-2.3-red?style=for-the-badge
174-
[Undertow-url]: https://undertow.io/
175-
[Jackson]: https://img.shields.io/badge/Jackson-2.18-blue?style=for-the-badge
176-
[Jackson-url]: https://github.com/FasterXML/jackson
177-
[Velocity]: https://img.shields.io/badge/Velocity-3.x-00ADD8?style=for-the-badge
178-
[Velocity-url]: https://papermc.io/software/velocity
179-
[Paper]: https://img.shields.io/badge/Paper-1.20--1.21-00ADD8?style=for-the-badge
180-
[Paper-url]: https://papermc.io/software/paper
181-
[Gradle]: https://img.shields.io/badge/Gradle-8.x-02303A?style=for-the-badge&logo=gradle
182-
[Gradle-url]: https://gradle.org/

0 commit comments

Comments
 (0)