How Hooks Work
A data hook is a bridge between another plugin and the engine. It reads what happens in that plugin and turns it into the same kind of record the auction house produces, then hands it to the engine.
Three kinds of information
| Kind | Where it comes from | What the engine does with it |
|---|---|---|
| Sale prices | Player shops and player trades, where one player sells to another | Learns real market prices from them, like auction sales. They are weighted by trust and feed the next round of training. |
| Price limits | Server shops, sell plugins and NPC traders, where the server buys from or sells to a player | What the server pays becomes a price floor and what it charges a price ceiling. Suggestions stay between the two, and a player sale far under the floor is flagged for your staff. These do not train the engine, because the server sets them, not the market. |
| Money between players | /pay, coinflips, duel bets, and money handed over in a trade | Checked for alt rings by fraud detection. Never used for prices. |
What happens to a hooked trade
- The hook sees a completed trade in the other plugin, a shop buy or sell, a trade between players, or a payment.
- It reads the item, the total price for the amount traded, the currency, and who was involved.
- The record joins the engine's own stream of auction sales and is used for what its kind allows, as in the table above.
Hooked trades are gathered in a buffer and written in batches, so a busy shop does not hammer your database, and the engine never blocks or slows the other plugin.
Plugins without events
Some plugins announce nothing when a trade happens, but keep a fixed price list. For those, the engine reads the price list itself: the EssentialsX and CMI worth lists, and the shop prices of GUIShop, dtlTraders, X-Prison's autosell and Shop by Conjurate. These lists are read again every five minutes and on /ahadmin reload, so a price you change shows up without a restart.
Turning hooks on and off
Each hook has a switch under economyEngine.hooks in config.yml, and a hook only starts when both its switch is on and the plugin it reads is installed. A switch for a plugin you do not run simply does nothing.
After changing a switch, run /ahadmin reload. A hook switched off stops at once, and a hook switched on starts, with no restart needed.
Checking which hooks work
/ahadmin hooks lists every hook and its current state.
| What it says | What it means |
|---|---|
| working, sales learned since the server started: N | Connected and learning. N counts what it has learned since the last start, with the time of the most recent one. |
| turned off in config | Its switch under economyEngine.hooks is off. |
| not installed | The plugin is not on the server. |
| installed, connects after a restart | The plugin is there, but the hook has not connected yet, usually because the plugin started after ProtonAuctions did. /ahadmin reload or a restart connects it. |
| can't connect | The hook could not attach, usually because a new version of the plugin changed what it offers. One warning goes to the console. |
| connected, but can't read its sales | The hook attached, but reading a trade failed. One warning goes to the console. |
| the economy engine is off | economyEngine.enabled is false, so no hook runs. |
Price-list readers report what they read instead, for example how many shop prices are used as ceilings and as floors. When a reader cannot use a plugin's prices, the line says why, for example because that shop is paid in a currency other than the Vault economy. The same list also shows how many banned players are left out of prices, and whether the combat block is following CombatLogX.