Interface DrawCommand.Highlight

All Superinterfaces:
DrawCommand
All Known Implementing Classes:
DrawCommand.Area, DrawCommand.Entity, DrawCommand.Tile
Enclosing interface:
DrawCommand
public static sealed interface DrawCommand.Highlight extends DrawCommand permits DrawCommand.Entity, DrawCommand.Tile, DrawCommand.Area
A command only a highlight_* call can carry, because what it marks is a thing rather than a place.

A DrawCommand.Primitive stores the coordinates it was sent. A highlight stores a reference — an entity's list slot, or a tile footprint on a named plane — and the producer re-resolves it on the game thread every tick. That is the difference that matters at the call site: a world-space DrawCommand.Rect at an NPC's tile and a highlight of that NPC look identical on the first frame and diverge the moment the NPC walks.

Neither kind nor space is a caller choice here. The handler forces both, so this API does not send either: space() is always DrawSpace.WORLD because there is no screen-space meaning for "the npc with index 42", and DrawCommand.kind() reports what the producer will store — which is what debug_draw_list reads back — rather than something that could be put in a kind field. Both of those kinds are deliberately unspellable on a set; see DrawKind.isSpellable().

Not batchable, structurally. debug_draw_set_batch applies debug_draw_set items and nothing else — its ApplyBatchItem runs the ordinary BuildSetRequest path, which has no way to name a semantic kind. So each highlight is its own round-trip. DrawFrame still accepts them and still works; see DrawFrame.flush() for what that costs and what it means when a flush fails part-way.

Every one of them takes an optional caption, for the same reason a component highlight does: the caller never learns where the marker landed, so with six on screen a label is the only way to tell them apart. The producer spells it label — text is refused — and DrawCaption is what makes the wrong spelling unrepresentable rather than merely refused.

  • Method Details

    • caption

      DrawCaption caption()
      The words drawn against the resolved marker, or DrawCaption.NONE.

    • space

      default DrawSpace space()
      Always DrawSpace.WORLD. Not a default the caller may override — the handler forces it before validating anything, and the store refuses the screen-space combination.
      Specified by:
      space in interface DrawCommand

    • requireTile

      static int requireTile(int tile, String name)
      A tile coordinate or tile extent, validated against DrawLimits.MAX_WORLD_TILE.

      Rejected at the call site rather than on the wire, and the bound is the one the producer's TileToWire applies before it multiplies by DrawLimits.SUBTILE_SCALE — so this refuses exactly what the producer would, one round-trip earlier.

    • requireExtentTiles

      static int requireExtentTiles(int tiles, String name)
      A footprint side, in tiles: positive and inside the world.

      Unlike requireTile(int, String), this is stricter than the producer rather than identical to it, and only the direction is guaranteed safe — this host never accepts an extent the producer would refuse. The producer's own extent check is kind-dependent: IsGeometryInRange waves an Entity footprint through unconditionally, while Tile and Area bound the far corner (a + c) rather than the extent alone. Reproducing that split here would mean duplicating a producer-side rule per variant to buy nothing: a footprint wide enough to matter is a caller mistake either way.

    • requirePlane

      static int requirePlane(int plane)
      A plane, DrawLimits.MIN_PLANE to DrawLimits.MAX_PLANE.

    • requireCaption

      static DrawCaption requireCaption(DrawCaption caption)
      The caption, validated. DrawCaption.NONE for no caption.