Class Capture

java.lang.Object
privbot.hooks.Capture

public final class Capture extends Object
Passive recording for a plugin: ctx.capture. Rows go to ~/.privbot/captures/<serverId>/<pluginId>/<run>/<stream>.jsonl, which ships with the client logs so a fight can be reviewed afterwards. It is the same recorder the flagship plugins use.

A stopped plugin costs nothing. Nothing is created on disk until start(java.lang.String, java.lang.Class<?>); record(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>) and event(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>) before it (or after stop()) do nothing at all. Call start from your Start button or runner start, never from startUp, so a plugin that is installed but not running leaves no files.

What it proves. start returning true means a run directory is reserved and rows are accepted. It does not mean a row reached the disk: writes are queued to a background writer, and a full queue drops rows (the capture's own health counters report that). record and event never throw and never block on the disk.

Unreadable. The tick on each row is client.getTickCount(); if that cannot be read the row is recorded with tick -1 instead of being lost. Row values must be JSON-friendly (numbers, strings, booleans, lists, maps).

Thread. Any thread. Nothing here marshals onto the client thread or waits; the tick read is one cheap field read.

  • Method Details

    • start

      public boolean start(String pluginId, Class<?> owner)
      Starts a recording run for this plugin under the current server id.
      Parameters:
      pluginId - a short stable name, used as the folder name: lower-case letters, digits and dashes, starting with a letter or digit, at most 64 characters ([a-z0-9][a-z0-9-]{0,63})
      owner - your plugin's main class: the capture session belongs to its class loader
      Returns:
      true when the run started, or was already started (idempotent: a second call begins no second run); false, writing nothing, for an id that does not match or a null owner
    • record

      public void record(String stream, Map<String,Object> row)
      Appends one row to a stream. A no-op while not started.
      Parameters:
      stream - a file-name-safe stream name (letters, digits, _, -); anything else is dropped
      row - the fields of the row; null is an empty row
    • event

      public void event(String name, Map<String,Object> row)
      Appends one named event to the events stream. A no-op while not started.
      Parameters:
      name - what happened
      row - details; null is empty
    • stop

      public void stop()
      Ends the run: its manifest is finalised. Later rows are no-ops until start(java.lang.String, java.lang.Class<?>) again.
    • isStarted

      public boolean isStarted()
      Returns:
      whether start(java.lang.String, java.lang.Class<?>) has run and stop() has not