Record Class Orientation

java.lang.Object
java.lang.Record
com.botwithus.bot.api.snapshot.Orientation
Record Components:
raw - the client angle 0..16383, or UNKNOWN_RAW
public record Orientation(int raw) extends Record
Which way an entity is facing, as the client stores it (wire v21).

raw() is the client's own angle, 0..16383 per full turn. It is the entity's rendered facing, which the client interpolates while the entity turns, so for a few ticks after a turn starts it reads an in-between angle rather than the direction being turned towards. It is UNKNOWN_RAW when the producer could not read one.

For anything but an exact comparison, use degrees() (a compass bearing, clockwise from north) or compass() (the nearest of eight points). Both are empty when the facing is unknown. They never quietly answer "north" or "0 degrees" for a value that was not read.

Compare facings with isSameFacingAs(Orientation), not equals. The client's conversion truncates, so a facing the server set to angle j can read back as j - 1. Record equals is exact value identity and will call those two different; isSameFacingAs(Orientation) allows the READBACK_TOLERANCE of one unit. compass() is unaffected, because one unit is far inside a 45-degree sector.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    FULL_TURN
    Client angle units in one full turn.
    static final int
    NORTH_RAW
    The raw angle that faces north (+tileY).
    static final int
    READBACK_TOLERANCE
    How far, in raw units, a facing read back from the client may sit from the angle that set it: the client's conversion truncates, so angle j can read back as j - 1.
    static final int
    UNKNOWN_RAW
    raw() when the facing is not known.
    static final int
    WIRE_UNKNOWN
    What the producer publishes on the wire for "not known": an all-ones u16.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Orientation(int raw)
    Creates an instance of a Orientation record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<Direction>
    compass()
    The nearest of the eight compass points; empty when unknown.
    OptionalDouble
    degrees()
    Compass bearing in [0, 360), clockwise from north; empty when unknown.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    static Orientation
    fromWire(int wireValue, IntConsumer outOfContract)
    Decodes the producer's zero-extended u16, degrading rather than throwing.
    final int
    hashCode()
    Returns a hash code value for this object.
    boolean
    isKnown()
     
    boolean
    isSameFacingAs(Orientation other)
    True when both facings are known and lie within READBACK_TOLERANCE of each other around the circle, so 0 and 16383 count as one unit apart.
    int
    raw()
    Returns the value of the raw record component.
    final String
    toString()
    Returns a string representation of this record class.
    static Orientation
    unknown()
    An orientation that was not read.

    Methods inherited from class Object

    getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • FULL_TURN

      public static final int FULL_TURN
      Client angle units in one full turn.
      See Also:

    • NORTH_RAW

      public static final int NORTH_RAW
      The raw angle that faces north (+tileY). The raw angle grows clockwise seen from above: 0 south, 4096 west, 8192 north, 12288 east.

      This zero offset is inferred statically and not yet confirmed against a live client. If that check disagrees, this constant is the one line to change, and OrientationTest's cardinal pins say what the answers must become.

      See Also:

    • UNKNOWN_RAW

      public static final int UNKNOWN_RAW
      raw() when the facing is not known.
      See Also:

    • WIRE_UNKNOWN

      public static final int WIRE_UNKNOWN
      What the producer publishes on the wire for "not known": an all-ones u16.
      See Also:

    • READBACK_TOLERANCE

      public static final int READBACK_TOLERANCE
      How far, in raw units, a facing read back from the client may sit from the angle that set it: the client's conversion truncates, so angle j can read back as j - 1.
      See Also:

  • Constructor Details

    • Orientation

      public Orientation(int raw)
      Creates an instance of a Orientation record class.
      Parameters:
      raw - the value for the raw record component

  • Method Details

    • fromWire

      public static Orientation fromWire(int wireValue, IntConsumer outOfContract)
      Decodes the producer's zero-extended u16, degrading rather than throwing.

      WIRE_UNKNOWN is an unknown orientation and 0..16383 is the angle itself. Anything else (16384..65534) breaks the producer's contract; it is also decoded as unknown, never wrapped into a plausible wrong angle, and reported to outOfContract. This method never throws: it runs inside a snapshot decode, and one bad row must not take down every running script. Constructing an Orientation directly with an out-of-range value still throws, because that is a caller's mistake rather than the wire's.

      Parameters:
      wireValue - the zero-extended u16 read from shared memory
      outOfContract - told the offending value when it is neither an angle nor the sentinel; the decode layer rate-limits what it logs

    • unknown

      public static Orientation unknown()
      An orientation that was not read.

    • isKnown

      public boolean isKnown()

    • isSameFacingAs

      public boolean isSameFacingAs(Orientation other)
      True when both facings are known and lie within READBACK_TOLERANCE of each other around the circle, so 0 and 16383 count as one unit apart. Use this rather than equals, which is exact and so fooled by the client's truncation. An unknown facing matches nothing, including another unknown one.

    • degrees

      public OptionalDouble degrees()
      Compass bearing in [0, 360), clockwise from north; empty when unknown.

    • compass

      public Optional<Direction> compass()
      The nearest of the eight compass points; empty when unknown. A bearing exactly on a sector boundary (22.5, 67.5, ...) rounds clockwise.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • raw

      public int raw()
      Returns the value of the raw record component.
      Returns:
      the value of the raw record component