Class DrawLimits

java.lang.Object
com.botwithus.bot.api.draw.DrawLimits
public final class DrawLimits extends Object
The producer's hard limits on debug drawing, named once so no caller has to spell a bare number.

Wire lockstep. Every constant here mirrors one in NXTLibrary/src/overlay/DrawTypes.h (or kDrawBatchMax in src/rpc/Handlers.cpp). Changing a cap on the producer means changing it here in the same logical change; these are the producer's numbers, not this host's policy.

Every cap a single call can hit is an explicit producer-side error rather than a silent truncation — with one exception, documented on RESOLVED_COMPONENTS_PER_TICK.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_FOOTPRINT_TILES
    The footprint a highlighted entity or tile gets when the caller names none, in tiles.
    static final long
    DEFAULT_TTL_MS
    The TTL the producer applies when a command omits ttl_ms.
    static final int
    MAX_BATCH_ITEMS
    Most items one debug_draw_set_batch accepts.
    static final int
    MAX_COMMANDS
    Retained commands per producer, across every connected client.
    static final int
    MAX_DECIMALS
    Most decimal places a fixed-point caption may be scaled by.
    static final int
    MAX_EXTENT
    Largest width or height a rect or ellipse may have.
    static final int
    MAX_KEY_BYTES
    Longest key the producer stores, in UTF-8 bytes — its buffer is 48 bytes including the NUL.
    static final int
    MAX_PLANE
    Highest plane a world highlight may name.
    static final int
    MAX_POLY_COMMANDS
    Retained poly commands, across every connected client.
    static final int
    MAX_POLY_POINTS
    Most points a polyline may have.
    static final int
    MAX_SCREEN_COORDINATE
    Largest absolute value a screen coordinate may take.
    static final int
    MAX_TEXT_COMMANDS
    Retained text commands, across every connected client.
    static final int
    MAX_TEXT_LENGTH
    Longest text a text command may carry, in UTF-16 code units — the producer converts the UTF-8 payload into a 128-unit wide buffer and fails the command rather than truncating when it will not fit.
    static final int
    MAX_THICKNESS
    Thickest stroke.
    static final int
    MAX_WORLD_COORDINATE
    Largest absolute value a world coordinate may take, in wire sub-tiles.
    static final int
    MAX_WORLD_TILE
    Largest absolute value a tile coordinate or tile extent may take, for the highlight_* calls that speak whole tiles rather than sub-tiles.
    static final int
    MAX_Z
    Highest paint order.
    static final int
    MIN_PLANE
    Lowest plane a world highlight may name.
    static final int
    MIN_POLY_POINTS
    Fewest points a polyline may have.
    static final int
    MIN_THICKNESS
    Thinnest stroke.
    static final int
    MIN_Z
    Lowest paint order.
    static final int
    RESOLVED_COMPONENTS_PER_TICK
    Component highlights the producer re-resolves per tick.
    static final int
    SUBTILE_SCALE
    Fixed-point sub-tile divisions per tile, for DrawSpace.WORLD geometry.
    static final long
    TTL_UNTIL_CLEARED
    TTL meaning "until replaced, cleared, or my connection closes".

  • Method Summary

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • MAX_KEY_BYTES

      public static final int MAX_KEY_BYTES
      Longest key the producer stores, in UTF-8 bytes — its buffer is 48 bytes including the NUL.

      Two different counters are called dropped and an over-long key lands in one but not the other, so be specific about which you are reading: the producer rejects the key before its store is touched, so it never reaches DrawStats.dropped() (the store's process-lifetime counter), but inside a batch it does count into DrawBatchResult.dropped(), because the batch tallies every non-OK item whatever the reason.

      See Also:

    • MAX_TEXT_LENGTH

      public static final int MAX_TEXT_LENGTH
      Longest text a text command may carry, in UTF-16 code units — the producer converts the UTF-8 payload into a 128-unit wide buffer and fails the command rather than truncating when it will not fit. This counts Java String.length(), not UTF-8 bytes, and the two differ for any non-ASCII text.
      See Also:

    • MAX_BATCH_ITEMS

      public static final int MAX_BATCH_ITEMS
      Most items one debug_draw_set_batch accepts. Over this is a hard error.
      See Also:

    • MAX_COMMANDS

      public static final int MAX_COMMANDS
      Retained commands per producer, across every connected client.
      See Also:

    • MAX_TEXT_COMMANDS

      public static final int MAX_TEXT_COMMANDS
      Retained text commands, across every connected client.
      See Also:

    • MAX_POLY_COMMANDS

      public static final int MAX_POLY_COMMANDS
      Retained poly commands, across every connected client.
      See Also:

    • MAX_DECIMALS

      public static final int MAX_DECIMALS
      Most decimal places a fixed-point caption may be scaled by. The producer rejects more with "decimals" must be 0..9, and rejects decimals with no value at all.
      See Also:

    • MIN_POLY_POINTS

      public static final int MIN_POLY_POINTS
      Fewest points a polyline may have.
      See Also:

    • MAX_POLY_POINTS

      public static final int MAX_POLY_POINTS
      Most points a polyline may have.
      See Also:

    • MIN_THICKNESS

      public static final int MIN_THICKNESS
      Thinnest stroke.
      See Also:

    • MAX_THICKNESS

      public static final int MAX_THICKNESS
      Thickest stroke.
      See Also:

    • MIN_Z

      public static final int MIN_Z
      Lowest paint order. The producer stores z in an int16_t and refuses anything outside it with z must be -32768..32767.

      It did not always. Through phase 1 it was static_cast<int16_t>(ClampToI32(p.z)), so z(100000) arrived as -31072 and quietly painted behind everything instead of in front of it — nothing in the reply, nothing in DrawStats.dropped(), nothing in Draw.list() to show for it. The host check was written as the only thing standing between a caller and that silent reorder; the producer has since made it an explicit error, alongside the same treatment for color. So this now agrees with a producer-side refusal rather than substituting for a missing one, and what it buys is the failure arriving at the call site with a stack trace instead of after a round-trip. Same bound, same rejection, one tick earlier.

      See Also:

    • MAX_Z

      public static final int MAX_Z
      Highest paint order. See MIN_Z.
      See Also:

    • MIN_PLANE

      public static final int MIN_PLANE
      Lowest plane a world highlight may name.
      See Also:

    • MAX_PLANE

      public static final int MAX_PLANE
      Highest plane a world highlight may name.

      Mirrors overlay::kMaxPlane. A plane is accepted only in world space — on a screen command the producer refuses it with only world space takes a plane rather than ignoring it — and for anything but an entity it is honoured by refusal: see DrawCommand.Tile.

      See Also:

    • MAX_SCREEN_COORDINATE

      public static final int MAX_SCREEN_COORDINATE
      Largest absolute value a screen coordinate may take. Out of range is an error, not a clamp.

      This is also the bound a world command's projected coordinates must land inside, which the producer checks a tick later — so a world command can be accepted and still fail to draw, if what it projects to is off this scale. A point behind the camera projects to a saturated sentinel rather than being clamped, so you learn the point is not on screen instead of getting a line to nowhere.

      See Also:

    • MAX_WORLD_COORDINATE

      public static final int MAX_WORLD_COORDINATE
      Largest absolute value a world coordinate may take, in wire sub-tiles.

      Deliberately larger than MAX_SCREEN_COORDINATE, because the two gate different quantities: this one bounds what a caller sends, while the screen bound applies to what those coordinates project to. Reusing one number for both would have refused legal world positions — anything past tile 4096 — for failing a limit that is about pixels.

      Where the number comes from, because it is not round. Every absolute world tile the producer publishes in its snapshot — NPC, player, location, ground item, projectile — is an int16_t. So the widest tile magnitude any consumer can be holding is |Short.MIN_VALUE| = 32768, and at SUBTILE_SCALE sub-tiles per tile that is 2^23. A bound below this would refuse a coordinate the same producer published a tick earlier.

      The practical consequence: a tile taken from a snapshot can never exceed this, because the snapshot cannot express one that does. Underground content, which sits at y + 6400, is nowhere near it.

      See Also:

    • MAX_EXTENT

      public static final int MAX_EXTENT
      Largest width or height a rect or ellipse may have.
      See Also:

    • DEFAULT_TTL_MS

      public static final long DEFAULT_TTL_MS
      The TTL the producer applies when a command omits ttl_ms. This API never omits it — DrawStyle always puts a TTL on the wire so the lifetime a command actually got is visible in Draw.list() rather than being an invisible producer-side default.
      See Also:

    • TTL_UNTIL_CLEARED

      public static final long TTL_UNTIL_CLEARED
      TTL meaning "until replaced, cleared, or my connection closes". It is not a way to draw something that outlives the script: ownership is connection-scoped and the producer drops everything a connection drew when its pipe closes.
      See Also:

    • RESOLVED_COMPONENTS_PER_TICK

      public static final int RESOLVED_COMPONENTS_PER_TICK
      Component highlights the producer re-resolves per tick. This is the one cap that is not an error, because it is not reachable from a single call: past it the surplus resolves on a following tick and collection rotates, so nothing is starved permanently — but geometry beyond this many live highlights lags the game by a tick or more, and DrawStats.resolveOverflow() counts the ticks on which that happened.
      See Also:

    • SUBTILE_SCALE

      public static final int SUBTILE_SCALE
      Fixed-point sub-tile divisions per tile, for DrawSpace.WORLD geometry.
      See Also:

    • MAX_WORLD_TILE

      public static final int MAX_WORLD_TILE
      Largest absolute value a tile coordinate or tile extent may take, for the highlight_* calls that speak whole tiles rather than sub-tiles.

      Derived rather than written down, because it is MAX_WORLD_COORDINATE expressed in the other unit: the producer's TileToWire is the single place the two meet, and it refuses a tile outside this before multiplying. A separate literal here could disagree with the bound it is supposed to be the same number as.

      The tile helpers speak TILES; raw space: "world" primitives speak sub-tiles. draw.tile(key, 3200, 3200) sends 3200, while draw.rect(...).world() at the same place sends 3200 * SUBTILE_SCALE. That is the producer's split, not a host convention, and the handler is the one place they meet — so nothing downstream of it ever sees two units.

      See Also:

    • DEFAULT_FOOTPRINT_TILES

      public static final int DEFAULT_FOOTPRINT_TILES
      The footprint a highlighted entity or tile gets when the caller names none, in tiles. The producer's own default for w/h.
      See Also: