Package games.pixscape.runtime.api

Interface EntitiesAPI

public interface EntitiesAPI
High-level entity identity access.

Use stableId as the preferred persistent/public identity. entityId is runtime/ECS-oriented and may be short-lived or recycled.

  • Method Details

    • ofEntityId

      EntityRef ofEntityId(int entityId)
      Returns a tolerant reference bound to the current incarnation of the provided runtime entityId. An absent or later-stale reference is inert.

    • ofStableId

      EntityRef ofStableId(int stableId)
      Returns a tolerant reference bound to the entity currently resolved from a persistent/public stableId. It does not follow later reuse or replacement.

    • requireEntityId

      EntityRef requireEntityId(int entityId)
      Same as ofEntityId(int) but throws when the entity does not exist at acquisition time. The returned reference can later become stale and inert.

    • requireStableId

      EntityRef requireStableId(int stableId)
      Same as ofStableId(int) but throws when not found at acquisition time. The returned reference can later become stale and inert.

    • requireTag

      EntityRef requireTag(String tag)
      Strictly resolves the entity currently indexed by tag. The returned reference can later become stale and inert.

    • requireName

      EntityRef requireName(String name)
      Strictly resolves the entity currently indexed by name. The returned reference can later become stale and inert.

    • entityIdOf

      int entityIdOf(int stableId)
      Resolves runtime entityId from stableId, or -1 when missing.

    • findEntityId

      int findEntityId(int stableId, int defaultValue)

    • stableIdOf

      int stableIdOf(int entityId)
      Resolves persistent/public stableId from runtime entityId.

    • ensureStableId

      int ensureStableId(int entityId)
      Ensures and returns a stableId for the runtime entityId.

    • existsEntityId

      boolean existsEntityId(int entityId)

    • existsStableId

      boolean existsStableId(int stableId)

    • destroy

      void destroy(EntityRef ref)
      Schedules entity destruction through ECS deletion.

      Effects become fully visible after the next normal world processing step (for example the next engine render() call that processes the world).

    • destroyEntityId

      void destroyEntityId(int entityId)
      Same semantics as destroy(EntityRef) for a runtime entityId.

    • destroyStableId

      void destroyStableId(int stableId)
      Same semantics as destroy(EntityRef) for a stableId lookup.