download Installation

OculusAI is a Paper plugin.

Requirements

• Paper (or a Paper fork) on Minecraft 1.16+.
• ProtocolLib — the plugin depends on it.
• A running OculusAI service and an API key.

Setup

1. Download the plugin jar from the releases page.
2. Drop it into plugins/ along with ProtocolLib.
3. Start the server once, then open plugins/OculusAI/config.yml.
4. Set api.url in the config.
5. Run /oai connect on the server and open the link it prints while signed in here. The key and your server’s IP are written for you.
6. Doing it by hand instead: paste the key into api.key and set the server IP on the panel’s Settings tab. Without an address the key is refused and nothing is analysed.
7. Run /oai reload, then /oai guide in game.

Service health, past outages included, is public at Stats.

tune Configuration

Everything lives in plugins/OculusAI/config.yml. The important parts:

api

api:
  url: ""        # service address, e.g. https://yoursite.example
  key: ""        # your server's API key
  timeout-ms: 1500

analysis

How combat windows are cut and scored.

analysis:
  window-ticks: 20
  min-attacks: 1
  combat-ticks: 40
  min-rotation: 5.0

buffer

Suspicion accumulates into a buffer; thresholds decide alert vs punish.

buffer:
  suspicion: 0.5
  gain: 1.5
  decay: 1.4
  max: 10.0
  alert-at: 1.7
  punish-at: 5.0

punishment

punishment:
  enabled: true
  command: ""   # empty = an ordinary kick with the reason below

Leave enabled: false while you watch the model on your own server.

terminal Commands

The command is /oai (aliases /oculusai, /ai). Run /oai help for the full list.

Start here

Command	What it does
/oai connect	Bind this server to your account with one link.
/oai guide	How to use the anticheat, in one screen.
/oai monitor	Live list of who looks suspicious. A red dot is past the punish mark.
/oai npc	Spawn a sparring dummy and try it on yourself.
/oai diag [player]	Why a player’s windows are, or are not, being analysed.

Watching and acting

Command	What it does
/oai prob <player>	Watch a player’s live aim reading.
/oai history <player>	Past readings, kept on disk across restarts.
/oai player <player>	View a player’s buffer and history.
/oai journal	Open the live suspicion journal.
/oai forget <player>	Clear a player’s suspicion.
/oai vanish	Enter spectator observation.

Training data

Command	What it does
/oai data add cheater|legit <player>	Sign a player up to be recorded.
/oai data train	Start recording (windows are taken while they fight).
/oai data stop	Stop and send captures to the service.
/oai data list	Show the current roster.

Record both labels, then train the model in /oai dashboard.

key Permissions

Grant with LuckPerms or any other permissions plugin.

Permission	Purpose
oculusai.command	Use /oai.
oculusai.alerts	Receive detection alerts and watch readings.
oculusai.journal	Open the suspicion journal.
oculusai.vanish	Use vanish observation.
oculusai.data	Record and label training data.
oculusai.npc	Spawn sparring dummies.
oculusai.connect	Run /oai connect (operator by default).
oculusai.diag	Run /oai diag (operator by default).
oculusai.bypass	Never analysed. Watch out for wildcards: a staff group with * gets this too, and those players are then skipped entirely.

sell Pricing and quotas

Every plan is sized by a daily request quota, counted over a rolling 24 hours. Pro can be tried free for three days, once per account - the button is on the Pro card.

Plan	Requests / day	Pin model
Free	400	—
Starter	5,000	—
Pro	60,000	yes
Unlimited	unlimited	yes

You bind your server’s IP to your key from the dashboard’s Settings tab. A key with no address set is refused everywhere, so this is a required step rather than a hardening option. The port is ignored — the service always checks the bare server IP — and the address can be changed once per 2 hours.

badge Your key and dashboard

An account holds one API key. The key is what the plugin sends; it carries your plan, your allowed server address, and the switches that control what the plugin may do.

• Usage — your daily quota and when it resets.
• Keys — pause predict, pin a model version.
• Settings — set the one server IP this key is allowed from.
• AI exclusions — worlds or WorldGuard regions the model should ignore.
• Settings — a Discord webhook: every kick, alert and report is mirrored into one channel.

What the service answers when something is wrong

Code	Meaning
001	The request came from an address this key does not allow.
002	No server IP is set for this key yet.
008	The plan’s daily quota is spent; the plugin backs off and retries.
009	The account is banned.
010	The address is blocked by the operator.

The key string never changes when you upgrade a plan, so nothing in config.yml needs editing.