Plugin documentation
VeloFlame quick start
Velocity proxy fork adding antibot, rate limiting, firewall, whitelist, and maintenance commands, built with a Java 25 toolchain.
Documentation and contents
VeloFlame is a Velocity proxy fork. It adds antibot checks, connection rate limits, a firewall module, and whitelist and maintenance commands for admins. Internally the project is velocity-ctd. Its README is upstream Velocity-CTD text, not VeloFlame documentation.
Requirements
- Root or
CAP_NET_ADMINon Linux whenfirewall.ipsetstaystrue, the default. The config notes thatipsetandiptablesare required. If setup fails, the Java-side cache still works. - No plugin dependency descriptor. VeloFlame replaces the proxy.
- Java 25 build toolchain.
The protocol API declares MINIMUM_VERSION = MINECRAFT_1_7_2 and a maximum at MINECRAFT_26_3. The declared range is 1.7.2 through 26.3.
Two version strings disagree. Gradle reports 4.2.1-SNAPSHOT, while VeloFlame.java reports internal version 1.4.9.
Install
- Build with the Gradle wrapper:
./gradlew build. - Take the shaded proxy jar from
proxy/build/libs. The produced file isVeloFlame-Lite.jar, hard-coded inproxy/build.gradle.kts. - Run it. A default
veloflame.tomlis generated alongside the corevelocity.toml. - If
firewall.ipsetremainstrue, installipsetandiptablesand run with root orCAP_NET_ADMIN.
Artifact-name drift: the README says -all. This build emits VeloFlame-Lite.jar.
Configure
Real defaults from default-veloflame.toml:
config-version = "0.0.8"
[firewall]
enabled = true
duration = 60
ipset = true
[ratelimit]
connections = 3
connections-period = 5
[packet-guard]
serverbound-unknown-play-max-packet-size = 204800
Core proxy settings such as bind address, servers, and forwarding stay in velocity.toml. The [limbo] section is marked VeloFlame PRO only and defaults to enabled = true. Its default global whitelist includes localhost and private addresses. Remove those entries on a test instance, or the limbo check never sees your connection. [advanced] seamless-server-switching defaults to false. The config warns to enable it only when backends use compatible registries and data packs.
Commands
Root is /veloflame, alias /velo. /bungeecord and /bungee aliases are added for non-PRO builds, or when PRO controls allow them.
| Command | Purpose |
|---|---|
/veloflame |
Version, edition, and command list |
/veloflame reload |
Reload configuration |
/veloflame whitelist |
Usage and entry count |
/veloflame whitelist add <entry> |
Add a single-word entry |
/veloflame whitelist remove <entry> |
Remove an entry |
/veloflame whitelist list / clear |
List or clear entries |
/veloflame firewall |
Usage: add, remove, list |
/veloflame firewall add <ip> |
Add an IP |
/veloflame maintenance |
Status |
/veloflame maintenance on|off [backend] [target] |
Global or per-backend toggle |
Whitelist and maintenance arguments use Velocity’s single-word string argument, so entries cannot contain spaces.
The README also documents inherited upstream commands. This page does not reproduce them, because they are upstream docs rather than VeloFlame-specific behavior verified here.
Permissions
These four nodes are checked in source:
| Node | Where enforced |
|---|---|
veloflame.reload |
VeloFlameCommand |
veloflame.whitelist |
WhitelistSubcommand |
veloflame.firewall |
FirewallSubcommand |
veloflame.maintenance |
MaintenanceSubcommand |
No descriptor declares these nodes, so there are no default values. Assign them through your permission plugin. Do not assume operator grants. Upstream velocity.command.* nodes appear only in the inherited README. velocity.command.gkick is the one code-confirmed sample.
Troubleshooting
VeloFlame has no troubleshooting document or section. Only inline config comments cover failure behavior. Firewall setup failure falls back to the Java-side cache. Seamless switching carries a registry compatibility warning. Limbo testing requires removing localhost and private entries from the global whitelist. Do not treat those comments as a diagnostic guide.