Class Projectile

java.lang.Object
com.botwithus.bot.api.entities.Projectile
All Implemented Interfaces:
EntityContext
public final class Projectile extends Object implements EntityContext
Rich wrapper around a snapshot Projectile record — one in-flight projectile at the producer's current tick (v17+).

Obtained via Projectiles.query().

This is a read-only entity. Unlike Npc, SceneObject and GroundItem, a projectile is not clickable — there is no menu action against a graphic in flight, and correspondingly no ActionTypes entry for one. The absence of interact() here is deliberate, not an oversight.

Position semantics. A projectile has two positions: where it was launched and where it lands. EntityContext exposes exactly one, and this wrapper anchors it on the target (end) tile — so nearest() and withinDistance() answer "what is about to land near me", which is the question combat scripts actually ask. The launch point remains available as startTileX() / startTileY().

Name collision note: the snapshot type com.botwithus.bot.api.snapshot.Projectile shares the simple name Projectile with this wrapper, so the snapshot type is fully qualified at the field declaration below and reflected mechanically on the constructor parameter and raw() accessor (Java has no import aliasing, and the enclosing class shadows any import of the snapshot type).

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    cyclesRemaining(int currentCycle)
    Cycles remaining until impact, floored at 0.
    int
    endCycle()
    Game cycle it lands.
    int
    endTileX()
    Absolute world tile X of the impact point.
    int
    endTileY()
    Absolute world tile Y of the impact point.
    double
    flightProgress(int currentCycle)
    Flight progress, 0.0 at launch through 1.0 at impact, clamped to that range.
    boolean
    isSourceTile()
    true when the source end is a fixed tile rather than an entity.
    boolean
    isTargetTile()
    true when the target end is a fixed tile rather than an entity.
    int
    plane()
    Plane / height level (0-3).
    int
    projectileId()
    Graphic (spot-anim) id of the projectile.
    Projectile
    raw()
    The underlying snapshot record.
    int
    sourceIndex()
    Server index of the source entity, or -1 when the projectile originates from a fixed tile rather than an entity.
    Npc
    sourceNpc()
    Resolve the source endpoint to a live NPC, or null if no NPC in this tick's snapshot carries that server index.
    Player
    sourcePlayer()
    Resolve the source endpoint to a live player.
    int
    sourceType()
    Raw engine entity-type tag for the source endpoint, surfaced unmodified.
    int
    startCycle()
    Game cycle the projectile was launched.
    int
    startTileX()
    Absolute world tile X of the launch point.
    int
    startTileY()
    Absolute world tile Y of the launch point.
    int
    targetIndex()
    Server index of the target entity, or -1 when the projectile is aimed at a fixed tile.
    Npc
    targetNpc()
    Resolve the target endpoint to a live NPC.
    Player
    targetPlayer()
    Resolve the target endpoint to a live player.
    boolean
    targetsLocalPlayer()
    true when this projectile is aimed at the local player — the "is this incoming at me" predicate.
    int
    targetType()
    Raw engine entity-type tag for the target endpoint.
    int
    tileX()
    Impact tile X — see the position-semantics note on the class.
    int
    tileY()
    Impact tile Y — see the position-semantics note on the class.
    String
    toString()
     

    Methods inherited from class Object

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

    Methods inherited from interface EntityContext

    distanceTo, distanceTo

  • Method Details

    • raw

      public Projectile raw()
      The underlying snapshot record.

    • projectileId

      public int projectileId()
      Graphic (spot-anim) id of the projectile.

      There is no name for this id: the API has no SpotAnimType and NXTCacheLibrary carries no spot-anim decoder, so EntityQuery.named(String) never matches on projectiles. Filter with EntityQuery.withId(int) instead.

    • startCycle

      public int startCycle()
      Game cycle the projectile was launched.

    • endCycle

      public int endCycle()
      Game cycle it lands.

    • flightProgress

      public double flightProgress(int currentCycle)
      Flight progress, 0.0 at launch through 1.0 at impact, clamped to that range.

      The cycle is a parameter by design. The snapshot does not carry the live game cycle, so the only source is GameAPI.getGameCycle() — an RPC round-trip. Hiding that inside a no-arg progress() would put a pipe call in the middle of what reads like a cheap field access, and a script iterating projectiles would pay it once per element. Fetch the cycle once per tick and pass it in.

      Returns 1.0 for a degenerate zero-length flight.

    • cyclesRemaining

      public int cyclesRemaining(int currentCycle)
      Cycles remaining until impact, floored at 0. Same cycle-as-a- parameter rationale as flightProgress(int).

    • sourceIndex

      public int sourceIndex()
      Server index of the source entity, or -1 when the projectile originates from a fixed tile rather than an entity.

    • targetIndex

      public int targetIndex()
      Server index of the target entity, or -1 when the projectile is aimed at a fixed tile.

    • sourceType

      public int sourceType()
      Raw engine entity-type tag for the source endpoint, surfaced unmodified.

      The concrete values are not decoded yet — the producer passes the engine's tag straight through. Treat it as an opaque discriminator to compare between projectiles, not as a value to switch on.

    • targetType

      public int targetType()
      Raw engine entity-type tag for the target endpoint. See sourceType().

    • isSourceTile

      public boolean isSourceTile()
      true when the source end is a fixed tile rather than an entity.

    • isTargetTile

      public boolean isTargetTile()
      true when the target end is a fixed tile rather than an entity.

    • sourceNpc

      public Npc sourceNpc()
      Resolve the source endpoint to a live NPC, or null if no NPC in this tick's snapshot carries that server index.

      Caveat: NPC and player server indices are separate index spaces, so an index alone cannot tell you which kind of entity the endpoint is — that is what sourceType() is for, and its values are not decoded yet. Until they are, a non-null result here does not by itself prove the source was an NPC; it may be a same-numbered NPC coinciding with a player endpoint. Cross-check sourceType() against a projectile whose origin you already know.

    • targetNpc

      public Npc targetNpc()
      Resolve the target endpoint to a live NPC. Same caveat as sourceNpc().

    • sourcePlayer

      public Player sourcePlayer()
      Resolve the source endpoint to a live player. Same caveat as sourceNpc().

    • targetPlayer

      public Player targetPlayer()
      Resolve the target endpoint to a live player. Same caveat as sourceNpc().

    • targetsLocalPlayer

      public boolean targetsLocalPlayer()
      true when this projectile is aimed at the local player — the "is this incoming at me" predicate.

      Carries the same index-space caveat as sourceNpc(): it compares targetIndex() against the snapshot's ownIndex, which is a player index, so an NPC target that happens to share the local player's index would read as a false positive. This becomes exact once targetType()'s values are decoded.

    • startTileX

      public int startTileX()
      Absolute world tile X of the launch point.

    • startTileY

      public int startTileY()
      Absolute world tile Y of the launch point.

    • endTileX

      public int endTileX()
      Absolute world tile X of the impact point. Same as tileX().

    • endTileY

      public int endTileY()
      Absolute world tile Y of the impact point. Same as tileY().

    • tileX

      public int tileX()
      Impact tile X — see the position-semantics note on the class.
      Specified by:
      tileX in interface EntityContext

    • tileY

      public int tileY()
      Impact tile Y — see the position-semantics note on the class.
      Specified by:
      tileY in interface EntityContext

    • plane

      public int plane()
      Description copied from interface: EntityContext
      Plane / height level (0-3).
      Specified by:
      plane in interface EntityContext

    • toString

      public String toString()
      Overrides:
      toString in class Object