Clone wiki

WatchFox / use

How to use WatchFox

Using a tool

The easiest way to use WatchFox is with a tool. Use /wf tool (see below) to define your tool and simply left-click any block to get the history of that location. If your tool is a block, you can place it to search the location.

Crouching (or as probably more familiar, holding down 'shift') will add a location to your current search, thus making it easy to build up a history.

Note: Using the tool will restrict your search (if it isn't already) to the world you are in. Trying to span multiple worlds will result in an error.

Note: If you searched using a command, all your previous arguments will still apply. Thus, you can search (see below) with /wf search -l 342,72,66 -e container_transaction -p bad_player and then shift-click additional chests to build up a total transaction history. (Of course, this could also easily be done with a WorldEdit selection!)

Note: All WatchFox events are duplicated across multi-block... blocks, EXCEPT container_transaction. That is, if you smack a door, regardless of top or bottom, you will get its interaction history. However, double chests do not exhibit this and will default to a particular side. If it started out as a single chest, events may span both blocks. (If you're wondering why, it's to prevent spanned searches from building essentially a double transaction history. Other events aren't as sensitive to being duplicated)

Using commands

WatchFox supports an array of commands all stemming from a base command: /watchfox or /wf. There is a special command /wfsave which is described at the bottom.

The line after the command is the relevant permission node. Usage of /watchfox / /wf command *is restricted to players in-game*.

  • /wf help

    Brings up a simple list of all the commands and their use. It will display all WatchFox commands, not just the ones the player has access to.
  • /wf search ARGS

    Searches the database and dumps the search into your session for use. Multiple arguments are separated with a space. Any argument can be prefixed with a bang '!' to denote that it is a NOT argument. That is, no results will have this specified value. Note: everything is case insensitive. Note: Entries will be sorted by default by time, old entries first.

    The following arguments are valid:

    • -w [world_name...]

      Search in the listed world(s), must be exact
    • -l [x:z x,z x:y:z x,y,z we worldedit...]

      Search the following coordinates. Specified as either a whole x,z column or as a specifc block x,y,z. A colon or a comma must be used to separate coordinate values. "we" or "worldedit" can be specified to include all blocks in your WorldEdit selection (any and all shapes are supported, not just cuboids). Warning: Massive selections can take a long time to search. Search time scales linearly with number of blocks selected. Obviously, WorldEdit must be installed for 'we'/'worldedit' to work.
    • -e [event_name...]

      Search for the following events. Don't forget to use _'s as necessary.
    • -x [plugin_name...]

      Search for the following plugins' events. This will match any event of the specified plugin(s).
    • -p [#explicit_player_name player_name...]

      Search for the following players. Names prefixed with a # are literal and no name-matching will be attempted. Names without will attempt to be expanded to the name of an online player. Notes: To specify a NOT literal, use !#not_this_player. Multiple matches of a playername (say you search for "bob" and "bob1" and "bob2" are online) will result in searching for the literal "bob". There is no warning in that circumstance.
    • -t [time_interval...]

      Search in the following time intervals. A time interval is a slightly complicated construction, the method to construct one follows.

      First, 'time_span' will be defined. Simply, it is a list of non-negative floating point numbers (you do not need to include the period) each followed by a character indicating the time unit. Characters s, m, h, d, w represent Second, Minute, Hour, Day and Week respectively. However, you can exclude the last character and it will default to Minute.

      For example, "30s" represents 30 seconds. "4.5m" represents 270 seconds, or 4 and a half minutes.
      "2d40m" is 2 days + 40 minutes. "25" is 25 minutes. "4h30" is 4 hours + 30 minutes.

      Now, a time interval consists of two time_span's, separated by a colon ':'. At least one of these time_span's must be "absolute". That is, it must be a point in time. You do this by prefixing the time_span with a hyphen '-'. An "absolute" time is relative to _now_. A non-absolute time, or relative time, is then relative to your absolute time.

      For example, "1h:-1d" represents the time span 25 hours ago to 24 hours ago.
      "-1w:2d" represents the time span 1 week ago to 5 days ago.
      "-1w:-2d" represents the time span 1 week ago to 2 days ago.

      Now, to make things even more complicated (or simpler! stay with me!), you can exclude the second time_span and specify only one. The second will be added implicitly and represent now. This addition counts as an absolute time.

      For example, (these are time_intervals) "-4h" represents the time span 4 hours ago to now.
      "4h" represents the time span 4 hours ago to now.

      So every time_span is a valid time_interval, and it functions as you would expect, "4 hours ago to now".

      In practice, specifying the time is often done as trivially as "-t 30", which is valid, and searches the last 30 minutes. Whew. (Believe it or not, this was easier to program than document)

      Note: An astute mathematician will quickly realize it's possible to search the future. While you are free to do so, it is marginally faster to let the interpreter add the implicit "to now", and it will actually get every so slightly more updated results as well.
    • -i [name name:byte int int:byte...]

      Search for the following blocks/items. Names are the literals specified by Bukkit (they will be auto uppercased). In many cases, it's probably easier to just look up the ID. Metadata can be specified as a byte (as a number) with a colon. Note: You *can* search for an item with a damage value as long as your specified value is less than 128. This will check the lowest 8 bits of the item's damage value. For example, you can search for specific potion effects, but this will match the potion regardless of whether it's a splash potion)

      If anyone knows a simple library to turn names into int:byte values, let me know...
    • -n [event_id...]

      Search for the following events as specified by their IDs. Basically just pulls up the listed ids, though it is still a full argument so you can apply other filters if you wanted. Possibly more useful to exclude certain events from your search.
    • -r [rollback_id...] NO -a FLAG

      Search for the events that were rolled back with the following IDs. Events that were undone are NOT included.
    • -r [rollback_id...] -a

      Search for the events that were rolled back with the following IDs. Events that were undone ARE included.
    • -a

      Include rolled back events in your search (they're not by default).
    • Warning: -r and -a mean different things depending on the other's presence.
    • -s [string...]

      Search for the specified string. '+'s are converted to ' 's (plusses are converted to spaces) however this can be escaped with a backslash. So "\+" -> "+" and "+" -> " ". This is only useful for logged events that log some kind of text (as noted in the list of event types with (text)). Since this text field is occasionally used for other purposes, searching for single characters may result in unexpected matches.
  • /wf searchn NUM ARGS

    Just like a normal search, except you specify the max number of most recent results to return. An 'N' of 1 will search only for the most recent match. An 'N' of 5 will only search for the 5 most recent matches.
  • /wf sort ARGS

    Sorts your session (your search results in most cases) according by the value(s) specified. You can stack ARGs to perform chained sorts. Note: The sorts are stable, that is, equal values will not change the ordering the previous sort established. For example, the location sort works by sorting by coord first, then world, so entries will be completely separated if they span worlds, but the general clustering from the coord sort will be maintained.

    The following args are valid:
    • id - Sort by event ID
    • world - Sort by world
    • coord - Sort by x:z coords. This will attempt to group clusters of events so that they are close to each other in the list.
    • eventtype - Sort by event type (ignores plugin)
    • plugin - Sort by plugin
    • player - Sort by player
    • time - Sort by time (old first)
    • rtime - Sort by time (recent first)
    • itemtype - Sort by itemtype
    • itemmeta - Sort by itemmeta (the byte value of blocks and lowest 8 bits of an item's damage code)
    • rollback - Sort by rollback code
    • misc / string - Sort by text/string data

      Default chained sorts, these will run two sorts successively:
    • item - Sort by itemmeta, then itemtype
    • loc / location - Sort by coord, then world
    • event / action - Sort by event type (groups by plugin)
  • /wf NUM

    View a page from your search. All entries will have the event ID, the world name, the coordinates, and the time displayed. Entries that cannot fit on one line are truncated. To view the full entry, use /wf lookup.
  • /wf lookup NUM

    Look up the details on a specific event by event ID. This will not truncate entries if they are long. (Used for things like player chat, commands, signs, etc)
  • /wf preview

    "Previews" a rollback of your session (most recent search). All rollbackable events from WatchFox will preview except for sign_change. Liquids from buckets will not flow either. This functions by sending your client block change packets without actually performing a change in the world. Interacting with the previewed region can be unstable.
  • /wf cancel

    Essentially cancels a preview. In reality, it just refreshes whatever blocks were changed (for you) from performing /wf preview. As such, for it to work properly, you cannot perform another search in between using /wf preview and /wf cancel.
  • /wf rollback

    Rolls-back whatever events can be rolledback in your session. More specifically, this will only rollback events that can be (see event list) and it will only do so if the block hasn't been changed by a non-searched party. For example, if PlayerA destroys a Gold Block and PlayerB replaces it with a Diamond Block, attempting to rollback PlayerA actions will not change the Diamond Block back to a Gold Block. However, attempting to rollback PlayerA and PlayerB will restore the Gold Block. This function will return a rollback ID that can be used to identify this rollback in the future and optionally undo it.

    Upon success, WatchFox will report how many events were successfully rolled back, how many were skipped (if your search included events that are not rollback-able), and how many events were superseded, that is, were skipped from the effect detailed above.

    Liquids that have been restored will not flow and should be updated to restore original flow. This was done to match the behavior set by /wf preview.
  • /wf undo NUM

    Will undo a rollback by replaying the events.
  • /wf replay

    Will indiscriminately replay rollbackable events in your session. If performing a rollback is too difficult or impossible, you can use a tool like WorldEdit to reset the region and replay a player's actions.
  • /wf chest

    Without an argument, will notify you if you have pending chest rollback data.

    Used with a number, it will display paginated results from your chest rollback data. (Similar to /wf num)

    Used with argument "chest", you will enter a chest-place interactive mode. As you place chests, data in your chest rollback data will be drained and the chests filled.

  • /wf share USER
    watchfox.share, USER must have

    Will attempt to share your session with another user. This user must have the permission. If the user accepts, your session (essentially just your last search and its contents) will be replicated for this user for him to use. The offer will expire after 30 seconds. A user can only have one pending offer at a time.

    This function can be useful in training mods, having them search, preview, and finally share sample searches to a mentor who can supervise their early work.
  • /wf tool [item]

    Used without an argument, this fuction will return what item is your WatchFox tool.

    Used with an [item] of "hand", this function will set the item in your hand as your WatchFox tool.

    Used with an [item] of "off" or "disable", this function will disable your WatchFox tool.

    Used with an item's Bukkit name OR an item's ID, this function will set the specified item as your WatchFox tool.
  • /wf stats

    Will display some statistics about the currently running WatchFox database.

    Logged events is the number of total logged events.
    Datastore chunks is the number of data blobs in RAM.
    Coordinate index chunks is the number of world map chunks in RAM.
    Player index chunks is the number of player data chunks in RAM.
    Time index chunks is the number of time data chunks in RAM.
    EPS is the Events Per Second in the past 1, 5 and 15 minutes.
    Load is the estimated DB load in the past 1, 5 and 15 minutes.
    Current system throughput is the most recent snapshot of how many EPS the server was recording.
    Effective system throughput is an estimate of what the system's stable EPS recording ability is.
  • /wf save

    Will cause WatchFox to attempt to save. While this will almost certainly succeed, getting the confirmation message does not mean it actually did succeed. If it didn't, an error message will shortly follow.
  • /wfsave

    Just like /wf save, however it avoids the /wf command which is player only. This command be run by anyone (including terminals, console, etc).
  • /wf update

    Will manually invoke the updater (regardless of auto-update setting). If used with argument "check", will only perform a check for an update without downloading.
    This command will honor the update-notifications setting.

WatchFox @ BukkitDev