Class HighlightBuilder

java.lang.Object
com.botwithus.bot.api.draw.HighlightBuilder
public final class HighlightBuilder extends Object
Fluent chain for a highlight — the four calls that mark a thing rather than a place. 
draw.npc(npc).color(Colors.RED).label(name).submit();        // tracks the NPC
draw.self().color(Colors.CYAN).untilCleared().submit();
draw.tile("flag", x, y, plane).filled().alpha(80).submit();
draw.area("zone", x, y, 5, 5, plane).label("safe").submit();

Why this is a separate type from DrawBuilder and DrawCaptionBuilder. Two of the knobs those offer are meaningless here, and this codebase's standing answer to a meaningless knob is to make it unspellable rather than ignored — the same reason draw.rect(...).font(...) does not compile:

  • No screen() / world(). There is no screen-space meaning for "the npc with index 42". The producer forces world on every highlight before it validates anything, so offering the choice would be offering one the caller does not have.
  • No closed(). That is a polyline's flag and a highlight is never a polyline.

The geometry is not here either — which entity, which tile, how many tiles of footprint, which plane — because each of those is specific to one of the four calls and a wrong one has to be reportable by name. They are named parameters of the DrawTarget method that opens the chain, so highlight_tile's refusal of a w is a thing this API cannot express rather than a thing it has to defend against.

The styling half is delegated to a DrawBuilder rather than copied, so there is one implementation of what color or ttl mean across all three chains. Only the return types differ, which is what keeps them typed.

  • Method Details

    • label

      public HighlightBuilder label(String text)
      Draw this text against the marker the producer resolved.

      The only way to tell two highlights apart, and it has to travel with the command precisely because the caller never learns where the marker landed. Replaces any caption already set — the wire allows exactly one per command, so these are alternatives rather than additions.

      The producer spells it label; sending text to a highlight is refused with entity names its caption "label", not "text". That spelling is chosen by the encoder from the command's own kind, so it is not a mistake reachable from here.

    • value

      public HighlightBuilder value(long value, int decimals)
      Caption with a scaled number: value(1234, 2) renders "12.34". Replaces any caption already set.

      There is no float on this wire, deliberately. Send a scaled integer and say what you scaled it by; the producer does the formatting.

    • value

      public HighlightBuilder value(long value)
      Caption with a whole number.

    • font

      public HighlightBuilder font(DrawFont font)
      Draw the caption in a named style. A style name, not a size — the producer owns the size table.

      Order-independent: the style is remembered and applied to whatever caption the chain ends up with, as well as to one already set. A font on a highlight that never gains a caption draws nothing and sends nothing, which is deliberately not an error — setting the style up front and the caption conditionally is a reasonable thing to write.

      Throws:
      IllegalArgumentException - if font is null

    • caption

      public DrawCaption caption()
      The caption as configured.

    • color

      public HighlightBuilder color(int argb)
      Packed 0xAARRGGBB. See Colors.

    • alpha

      public HighlightBuilder alpha(int alpha)
      The current colour at a different 0..255 alpha.

    • thickness

      public HighlightBuilder thickness(int pixels)
      Stroke width for the box drawn around the resolved marker.

    • filled

      public HighlightBuilder filled()
      Fill the marker rather than stroking it.

    • filled

      public HighlightBuilder filled(boolean fill)
      Fill or stroke explicitly.

    • z

      public HighlightBuilder z(int order)
      Draw order; higher is drawn in front. The only way to control which of several overlapping highlights is visible where they cross, which is exactly the case labels exist to serve.

    • ttl

      public HighlightBuilder ttl(long milliseconds)
      Lifetime in milliseconds. Defaults to DrawLimits.DEFAULT_TTL_MS.

    • ttl

      public HighlightBuilder ttl(Duration duration)
      Lifetime as a Duration, truncated to whole milliseconds.

    • untilCleared

      public HighlightBuilder untilCleared()
      Keep this highlight until it is replaced, cleared, or the script's connection closes. Not a way to leave something on screen after the script stops: ownership is connection-scoped and the producer drops everything a connection drew when its pipe closes.

    • build

      public DrawCommand.Highlight build()
      The highlight as configured, without sending it.

    • submit

      public String submit()
      Send the highlight, and answer the key it is stored under — which is also how you clear it later.

      Off Draw this is one highlight_* round-trip. Inside a DrawFrame it only queues; a highlight cannot ride debug_draw_set_batch, so the frame sends it as its own call when it flushes. See DrawFrame.flush() for what that means for a frame that fails part-way.