Class DrawBuilder

java.lang.Object
com.botwithus.bot.api.draw.DrawBuilder
public final class DrawBuilder extends Object
Fluent presentation chain for one draw command. 
draw.rect("target-box", x, y, w, h).color(Colors.GREEN).thickness(2).ttl(1200).submit();

Mutable and single-use by convention — submit() may be called more than once, and each call re-sends the same key, which the producer treats as a replace. Nothing is put on the wire until submit().

Obtained from a DrawTarget: either Draw (each submit is its own round-trip) or DrawFrame (submits accumulate and leave as one batch). The chain reads identically either way, which is the point.

  • Method Details

    • color

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

    • alpha

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

    • thickness

      public DrawBuilder thickness(int pixels)
      Stroke width, DrawLimits.MIN_THICKNESS to DrawLimits.MAX_THICKNESS.

    • filled

      public DrawBuilder filled()
      Fill rather than stroke. Meaningful for rect, ellipse and poly.

    • filled

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

    • closed

      public DrawBuilder closed()
      Close a polyline back to its first point. Meaningful for poly only.

    • z

      public DrawBuilder z(int order)
      Draw order; higher is drawn in front.

    • ttl

      public DrawBuilder ttl(long milliseconds)
      Lifetime in milliseconds. The default is DrawLimits.DEFAULT_TTL_MS and it is always sent explicitly, so Draw.list() reports the lifetime this command actually got.

    • ttl

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

    • untilCleared

      public DrawBuilder untilCleared()
      Keep this command until it is replaced, cleared, or the script's connection closes. It is 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.

    • screen

      public DrawBuilder screen()
      Client-area pixels, origin top-left. The default.

    • world

      public DrawBuilder world()
      Game-world coordinates, projected to the screen by the producer. Bounded by DrawLimits.MAX_WORLD_COORDINATE rather than the screen bound, and refused for a DrawKind.POLY. See DrawSpace.WORLD.

    • build

      public DrawCommand.Primitive build()
      The command as configured, without sending it.

      The return type narrowed from DrawCommand to DrawCommand.Primitive. Source-compatible — a Primitive is a DrawCommand, so every existing use still compiles — but not binary compatible, so a script compiled against an older bot-api needs a rebuild. The narrowing is what lets drawSetBatch take List<Primitive> and so refuse a highlight at compile time; this builder never built anything else.

    • submit

      public String submit()
      Send the command, and answer the key it is stored under — which is also how you clear it later. Inside a DrawFrame this only queues; the wire traffic happens when the frame is flushed or closed.

      A command the producer refuses propagates the transport's own unchecked RPC error when submitted through Draw, and is counted into DrawBatchResult.dropped() when submitted through a DrawFrame. The two failure shapes differ because the wire's do — see DrawFrame.flush().