{"id":51127550,"url":"https://github.com/owengregson/simpleboxer","last_synced_at":"2026-06-25T09:00:47.706Z","repository":{"id":364933386,"uuid":"1261198392","full_name":"owengregson/SimpleBoxer","owner":"owengregson","description":"A simple spigot plugin implementing Sumo/Boxing PvP bots that follow your server's exact configuration.","archived":false,"fork":false,"pushed_at":"2026-06-15T05:36:09.000Z","size":206,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T07:23:29.365Z","etag":null,"topics":["bot","bukkit-plugin","combat-testing","fake-players","knockback","knockback-minecraft","minecraft","minecraft-bot","minecraft-plugin","minecraft-pvp","nms","paper","paper-plugin","player-bots","pvp","pvp-bot","pvp-practice","sparring-bot","spigot-plugin","virtual-players"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/owengregson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-06T11:19:17.000Z","updated_at":"2026-06-15T05:36:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/owengregson/SimpleBoxer","commit_stats":null,"previous_names":["owengregson/simpleboxer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/owengregson/SimpleBoxer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owengregson%2FSimpleBoxer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owengregson%2FSimpleBoxer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owengregson%2FSimpleBoxer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owengregson%2FSimpleBoxer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/owengregson","download_url":"https://codeload.github.com/owengregson/SimpleBoxer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owengregson%2FSimpleBoxer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34767548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","bukkit-plugin","combat-testing","fake-players","knockback","knockback-minecraft","minecraft","minecraft-bot","minecraft-plugin","minecraft-pvp","nms","paper","paper-plugin","player-bots","pvp","pvp-bot","pvp-practice","sparring-bot","spigot-plugin","virtual-players"],"created_at":"2026-06-25T09:00:46.487Z","updated_at":"2026-06-25T09:00:47.698Z","avatar_url":"https://github.com/owengregson.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SimpleBoxer\n\n**Virtual sparring players for testing combat plugins.** Spawn a bot that is\na *real player* to your server — real player-list entry, real inventory, real\nmovement packets, real knockback — then tune its ping, aim, click speed,\nreach, and movement to spar against. Built for Paper **1.17.1 → 26.x**.\n\n[![Minecraft](https://img.shields.io/badge/Minecraft-1.17.1%20%E2%86%92%2026.x-brightgreen)](#requirements)\n[![Platform](https://img.shields.io/badge/platform-Paper-orange)](https://papermc.io)\n[![Release](https://img.shields.io/github/v/release/owengregson/SimpleBoxer?include_prereleases\u0026sort=semver)](https://github.com/owengregson/SimpleBoxer/releases/latest)\n\n---\n\n## Why SimpleBoxer?\n\nTesting a combat plugin (knockback tuning, anti-cheat, OldCombatMechanics\nmodesets, [Mental](https://github.com/owengregson/Mental) profiles) usually\nmeans rounding up real people. SimpleBoxer gives you opponents on demand.\n\nA boxer is **indistinguishable from a real player to the server**. Whatever\nshapes combat on your server shapes the boxer identically, because the boxer\nrides the same wire:\n\n- Knockback arrives as the same velocity packet a real client receives, and is\n  integrated through the vanilla client's motion math — so a boxer flies back\n  exactly like a player with the same ping would.\n- Movement, sprinting, attacks, and swings leave as genuine player packets —\n  same server validation, same Bukkit events (`PlayerMoveEvent`,\n  `PlayerToggleSprintEvent`, …).\n- Vanilla commands (`/tp`, `/effect`, `/give`) and other plugins target boxers\n  like any player. They're hidden from the tab list but stay tab-completable.\n\n\u003e **Use case:** arena-style flat/simple terrain. Boxers sprint, strafe, and\n\u003e jump single-block steps — they don't path through mazes.\n\n---\n\n## Features\n\n- 🥊 **Real-player bots** — no NPC shortcuts; the server sees a `ServerPlayer`.\n- 🎚️ **Difficulty ladder** — `dummy` → `easy` → `medium` → `hard` → `expert` →\n  `aimbot`, each a full behaviour bundle.\n- 🛰️ **Simulated ping** — symmetric RTT that delays both perception and action,\n  like a real laggy client.\n- 🎯 **Spring-damper aim** — presets `locked`/`sharp`/`smooth`/`sloppy`, or tune\n  stiffness, damping, and max turn speed by hand.\n- 🖱️ **Configurable clicking** — CPS with jitter, reach and aim-cone gating.\n- 🏃 **Movement styles** — `rush`, `strafe-circle`, `strafe-weave`, `stand`,\n  with w-tap rhythm and stop-distance rings.\n- ⚙️ **Live tuning** — change any knob at runtime with `/boxer set`.\n- 🧩 **Skins \u0026 targets** — wear any account's skin; pre-bind a follow target.\n- 🛡️ **Tireless fixtures** — invincible (full hit + restore) and well-fed by\n  default, so a test never ends because the bot starved or died.\n\n---\n\n## Requirements\n\n| | |\n| --- | --- |\n| **Server** | [Paper](https://papermc.io) (or a Paper fork) `1.17.1` through `26.x` |\n| **Java** | 17+ for MC 1.17–1.20.4 · 21+ for MC 1.20.5 and newer |\n\n\u003e SimpleBoxer reaches into server internals (NMS) to make boxers real players.\n\u003e It targets Paper; Spigot/CraftBukkit are untested. If your exact version is\n\u003e unsupported the plugin disables itself cleanly and logs why — it never\n\u003e half-loads.\n\n---\n\n## Installation\n\n1. **Download** the latest `SimpleBoxer-x.y.z.jar` from the\n   [**Releases**](https://github.com/owengregson/SimpleBoxer/releases/latest)\n   page.\n2. **Drop it** into your server's `plugins/` folder.\n3. **Restart** the server (a reload won't load a new plugin cleanly).\n4. **Verify** — you should see `SimpleBoxer x.y.z enabled` in the console, and\n   a `plugins/SimpleBoxer/config.yml` will be created.\n5. **Spawn one** in-game:\n   ```\n   /boxer spawn Rival hard target:YourName\n   ```\n\nThat's it. By default only operators can use the commands (see\n[Permissions](#permissions)).\n\n---\n\n## Quick start\n\n```\n/boxer spawn Bot                       # an unhandicapped partner at your feet\n/boxer spawn Bot hard                  # pick a difficulty from the ladder\n/boxer spawn Bot expert skin:Notch target:Steve\n/boxer target Bot Steve                # sic an existing boxer onto a player\n/boxer set Bot ping 150                # tune anything, live\n/boxer pause Bot                       # freeze its brain (it still takes hits)\n/boxer info Bot                        # inspect its current settings\n/boxer remove all                      # clean up\n```\n\nAlias: `/sb` works anywhere `/boxer` does.\n\n---\n\n## Commands\n\nAll commands are under `/boxer` (alias `/sb`).\n\n| Command | Description |\n| --- | --- |\n| `/boxer spawn \u003cname\u003e [preset] [skin:\u003cplayer\u003e] [target:\u003cplayer\u003e] [at \u003cx\u003e \u003cy\u003e \u003cz\u003e]` | Spawn a boxer. With no preset it uses your `defaults`. `at` is required from console. |\n| `/boxer remove \u003cname\\|all\u003e` | Remove one boxer, or every boxer. |\n| `/boxer list` | List live boxers with their target, ping, and CPS. |\n| `/boxer info \u003cname\u003e` | Full settings dump for one boxer. |\n| `/boxer target \u003cname\u003e \u003cplayer\\|none\u003e` | Set or clear a boxer's follow/attack target. |\n| `/boxer pause \u003cname\\|all\u003e` | Freeze a boxer's brain (it still receives knockback). |\n| `/boxer resume \u003cname\\|all\u003e` | Un-freeze. |\n| `/boxer set \u003cname\u003e \u003ckey\u003e \u003cvalue\u003e` | Tune one setting at runtime (see below). |\n| `/boxer reload` | Re-read `config.yml`. |\n\n### Tunable keys (`/boxer set`)\n\n| Key | Value | Example |\n| --- | --- | --- |\n| `ping` | whole number of ms (0–2000) | `/boxer set Bot ping 150` |\n| `cps` | clicks per second (0–50; 0 = never attacks) | `/boxer set Bot cps 12` |\n| `reach` | blocks (0.5–6) | `/boxer set Bot reach 3.2` |\n| `aim` | `locked` / `sharp` / `smooth` / `sloppy` | `/boxer set Bot aim smooth` |\n| `wtap` | `true` / `false` | `/boxer set Bot wtap true` |\n| `movement` | `rush` / `strafe-circle` / `strafe-weave` / `stand` | `/boxer set Bot movement strafe-circle` |\n| `preset` | any preset name | `/boxer set Bot preset expert` |\n| `invincible` | `true` / `false` | `/boxer set Bot invincible false` |\n\nInvalid input is answered in plain language — e.g. `set Bot ping abc` replies\n`ping expects a whole number, not 'abc'.` rather than throwing.\n\n---\n\n## Difficulty presets\n\nEach preset bundles ping, CPS, aim, reach discipline, w-tap, and movement into\na named tier. Every component stays individually overridable at spawn or with\n`/boxer set`.\n\n| Preset | Feel | Ping | CPS | Aim |\n| --- | --- | --- | --- | --- |\n| `dummy` | Stands still, never attacks — a punching bag | 0 | 0 | smooth |\n| `easy` | High ping, slow sloppy clicks, walks | 120 | 4 | sloppy |\n| `medium` | An ordinary player | 60 | 7 | smooth |\n| `hard` | A practiced PvPer, disciplined w-taps | 35 | 10 | sharp |\n| `expert` | Tournament-grade, circles its target | 15 | 13 | tight |\n| `aimbot` | The calibrator: zero ping, locked aim | 0 | 16 | locked |\n\nYou can also define your own presets in `config.yml` as sparse overlays — an\nentry there with a built-in's name overrides it.\n\n---\n\n## Permissions\n\nEverything defaults to **operators only**. Grant these nodes to delegate.\n\n| Node | Grants | Default |\n| --- | --- | --- |\n| `simpleboxer.command.use` | Run `/boxer`, plus `help`, `list`, `info` | op |\n| `simpleboxer.command.spawn` | `spawn` and `remove` | op |\n| `simpleboxer.command.control` | `target`, `pause`, `resume` | op |\n| `simpleboxer.command.tune` | `set` | op |\n| `simpleboxer.command.reload` | `reload` | op |\n| `simpleboxer.*` | All of the above | op |\n\n---\n\n## Configuration\n\nA documented `config.yml` is written to `plugins/SimpleBoxer/` on first start.\nThe two top-level blocks are `defaults` (applied to any spawn that names no\npreset, and the base every preset overlays) and `presets` (your own named\noverlays). Every key inherits a sensible default when omitted, and a malformed\nvalue warns in the console and keeps the inherited value — **a typo can never\nbreak a spawn.**\n\n```yaml\n# Keep boxers out of the tab list (still tab-completable in commands).\nhide-from-tab: true\n\ndefaults:\n  ping-ms: 0              # simulated RTT, 0–2000 (split: half perception, half action)\n  cps: 8.0               # clicks per second, 0–50 (0 = never attacks)\n  click-jitter: 0.3      # per-click interval wobble, 0–0.9\n  aim:\n    preset: sharp         # locked / sharp / smooth / sloppy\n    # stiffness: 0.55     # optional granular overrides on top of the preset\n    # damping: 0.30\n    # max-velocity: 60.0\n  reach: 3.0             # attack range in blocks, 0.5–6\n  aim-tolerance-degrees: 10.0   # a click only attacks within this cone\n  w-tap:\n    enabled: false\n    delay-ticks: 1        # ticks after a hit before forward releases (0–20)\n    release-ticks: 2      # ticks forward stays released (1–20)\n  movement:\n    style: rush           # rush / strafe-circle / strafe-weave / stand\n    stop-distance: 0.0    # 0 = hold W through the target (true rusher)\n    sprint: true\n  invincible: true        # take the full hit, then restore health\n  feed-hunger: true       # pin hunger full so sprint stays legal\n\n# Your own presets (sparse overlays over `defaults`):\npresets:\n  # laggy-spammer:\n  #   ping-ms: 180\n  #   cps: 14\n  #   aim:\n  #     preset: smooth\n```\n\nAfter editing, run `/boxer reload`.\n\n---\n\n## Developer API\n\nOther plugins can spawn and control boxers. The `api` module exposes\n`BoxerService`, obtainable from Bukkit's `ServicesManager`:\n\n```java\nBoxerService boxers = Bukkit.getServicesManager().load(BoxerService.class);\n\nboxers.spawn(new BoxerSpawnRequest(\n        \"Rival\",\n        player.getLocation(),\n        DifficultyPresets.HARD,\n        \"Notch\",        // skin owner, or null\n        player.getName() // target, or null\n)).thenAccept(boxer -\u003e boxer.setTarget(player));\n```\n\n`BoxerSpawnEvent` and `BoxerRemoveEvent` fire on the Bukkit event bus.\n\n---\n\n## Building from source\n\nRequires a JDK 21+ (the build provisions a Java 25 toolchain automatically).\n\n```bash\ngit clone https://github.com/owengregson/SimpleBoxer.git\ncd SimpleBoxer\n./gradlew build          # compiles + runs unit tests; jar in core/build/libs/\n```\n\nThe shaded plugin jar is `core/build/libs/SimpleBoxer-\u003cversion\u003e.jar`.\n\n### Tests\n\n```bash\n./gradlew build                  # unit tests (physics, aim, latency, settings)\n./gradlew integrationTest        # boots real Paper servers (floor + ceiling) and runs the in-server suite\n./gradlew integrationTestMatrix  # every version listed in gradle.properties\n```\n\nIntegration results land in\n`run/\u003cversion\u003e/plugins/SimpleBoxerTester/test-results.txt`.\n\nSee [`ARCHITECTURE.md`](ARCHITECTURE.md) for the module map, the\ncaptured-connection design, threading rules, and the honest boundaries\n(in-process packets are invisible to packet-sniffing plugins; Folia and\npathfinding are deferred).\n\n---\n\n## Honest boundaries\n\n- In-process boxers have no socket, so their outbound packets don't traverse\n  the netty pipeline — ProtocolLib/PacketEvents listeners won't see boxer\n  traffic. The interesting direction (a real player attacking a boxer) works\n  fully, because the attacker's own connection carries the packets.\n- **Folia** isn't supported yet (the scheduling seam is ready; placement and\n  cross-region brains aren't).\n- Boxers are **ephemeral** — they're never written to player data and are\n  despawned cleanly on shutdown.\n\n---\n\n## Credits\n\nBuilt by [owengregson](https://github.com/owengregson) to pair with\n[Mental](https://github.com/owengregson/Mental) and OldCombatMechanics.\nIssues and pull requests welcome on\n[GitHub](https://github.com/owengregson/SimpleBoxer).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowengregson%2Fsimpleboxer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowengregson%2Fsimpleboxer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowengregson%2Fsimpleboxer/lists"}