flecs_adapter.h

#pragma once
 
#include <tess/ecs/adapter.h>
 
#if defined(TESS_ENABLE_FLECS)
 
#ifndef FLECS_H
#error "Include <flecs.h> before <tess/ecs/flecs/flecs_adapter.h>"
#endif
 
#if FLECS_VERSION_MAJOR < 4 ||                               \
    (FLECS_VERSION_MAJOR == 4 && FLECS_VERSION_MINOR < 1) || \
    (FLECS_VERSION_MAJOR == 4 && FLECS_VERSION_MINOR == 1 && \
     FLECS_VERSION_PATCH < 5)
#error "The tess Flecs adapter requires Flecs 4.1.5 or newer"
#endif
 
#include <algorithm>
#include <cstddef>
#include <cstdint>
#include <type_traits>
#include <vector>
 
// The Flecs adapter: concrete PathAgentSource/PathAgentSink types
// over a flecs::world, explicit lifecycle intents (spawn / despawn /
// teleport / park / place -- raw entity destruction on an on-board agent
// leaks a permanently impassable tile, so the intents are the only
// sanctioned mutation paths), and tick_flecs_* drivers that are thin
// instantiations of the generic tick_ecs_* pipeline. Compiled only when
// the consumer defines TESS_ENABLE_FLECS and includes
// <flecs.h> first; tess core never provides Flecs.
namespace tess {

struct FlecsHandleAdapter {
  using entity_type = flecs::entity_t;
 
  [[nodiscard]] static auto to_handle(flecs::entity_t entity) noexcept
      -> EntityHandle {
    if (entity == 0u) {
      return kNullEntityHandle;
    }
    TESS_ASSERT_MSG(entity != kNullEntityHandle.value,
                    "the all-ones Flecs ID is reserved for tess null");
    return EntityHandle{entity};
  }
 
  [[nodiscard]] static auto to_entity(EntityHandle handle) noexcept
      -> flecs::entity_t {
    return handle.is_null() ? 0u : handle.value;
  }
};
static_assert(EntityHandleAdapter<FlecsHandleAdapter>);

class FlecsTilePositionAdapter {
 public:
  explicit FlecsTilePositionAdapter(flecs::world& world) noexcept
      : world_(&world) {}
 
  [[nodiscard]] auto position(flecs::entity_t entity) const -> Coord3 {
    return world_->entity(entity).get<TilePosition>().coord;
  }
 
  void set_position(flecs::entity_t entity, Coord3 coord) {
    world_->entity(entity).set<TilePosition>(TilePosition{coord});
  }
 
 private:
  flecs::world* world_;
};
static_assert(PositionAdapter<FlecsTilePositionAdapter, flecs::entity_t>);

struct FlecsAgentEntry {
  std::uint64_t agent_id = 0;
  flecs::entity_t entity = 0u;
  // Cached during query iteration. Flecs component addresses remain stable
  // because collection performs no structural mutation before fill ends.
  PathState* state = nullptr;
};

struct FlecsPathAgentContext {
  // Flecs copies each temporary term into builder-owned storage, but the
  // analyzer follows its address through the upstream fluent builder and
  // reports an escape at downstream constructor call sites.
  // NOLINTBEGIN(clang-analyzer-core.StackAddressEscape)
  explicit FlecsPathAgentContext(flecs::world& world)
      : world_identity(world.c_ptr()),
        agent_query(
            world.query_builder<PathState, const TilePosition, const AgentId>()
                .build()) {}
  // NOLINTEND(clang-analyzer-core.StackAddressEscape)
 
  PathAgentTickState tick_state{};
  PathAgentBatch batch{};
  std::vector<FlecsAgentEntry> entries{};
  std::uint64_t next_agent_id = 0;
  // The query is owned by this exact world; equal component registrations in
  // another world do not make its entity IDs or table storage interchangeable.
  flecs::world_t* world_identity = nullptr;
  flecs::query<PathState, const TilePosition, const AgentId> agent_query;
 
  void reserve(std::size_t agent_capacity) {
    batch.reserve(agent_capacity);
    entries.reserve(agent_capacity);
  }
};
 
namespace detail {
 
template <typename World>
[[nodiscard]] auto flecs_tile_resolves(const World& world, Coord3 tile) noexcept
    -> bool {
  const auto resolved = world.try_resolve(tile);
  if (!resolved.has_value()) {
    return false;
  }
  if constexpr (std::is_same_v<typename World::residency_type,
                               SparseResident>) {
    if (!world.is_resident(resolved->chunk_key)) {
      return false;
    }
  }
  return true;
}
 
template <typename World>
void flecs_mark_tile_dirty(World& world, Coord3 tile, DirtyMask mask) {
  if (mask) {
    world.mark_dirty(world.resolve(tile).chunk_key, mask,
                     Box3{tile, Extent3{1, 1, 1}});
  }
}
 
inline void flecs_assert_immediate_lifecycle(
    [[maybe_unused]] const flecs::world& world) noexcept {
  // Flecs would queue structural commands inside a deferred scope while tess
  // changes occupancy immediately. Refuse that split commit boundary.
  TESS_ASSERT_MSG(!world.is_deferred() && !world.is_readonly(),
                  "Flecs lifecycle intents require immediate mode");
}
 
inline void flecs_assert_context_world(
    [[maybe_unused]] const flecs::world& world,
    [[maybe_unused]] const FlecsPathAgentContext& context) noexcept {
  TESS_ASSERT_MSG(context.world_identity == world.c_ptr(),
                  "FlecsPathAgentContext must use the same Flecs world");
}
 
}  // namespace detail

class FlecsPathAgentSource {
 public:
  FlecsPathAgentSource(flecs::world& world,
                       FlecsPathAgentContext& context) noexcept
      : world_(&world), context_(&context) {}
 
  auto collect(PathAgentBatch& batch) -> PathAgentCollectInfo {
    detail::flecs_assert_immediate_lifecycle(*world_);
    detail::flecs_assert_context_world(*world_, *context_);
    auto& entries = context_->entries;
    entries.clear();
    batch.clear();
 
    context_->agent_query.each([&](flecs::entity entity, PathState& state,
                                   const TilePosition&,
                                   const AgentId& agent_id) {
      // A negated builder term would avoid this check, but Flecs 4.1.5's
      // fluent `without<T>()` produces StackAddressEscape false positives at
      // every downstream constructor call under the required Clang analyzer
      // gate. Keep the non-mutating filter inside the safe query phase until
      // that upstream builder is analyzer-clean.
      if (!entity.has<OffBoard>()) {
        entries.push_back(FlecsAgentEntry{agent_id.value, entity.id(), &state});
      }
    });
    std::sort(entries.begin(), entries.end(),
              [](const FlecsAgentEntry& lhs, const FlecsAgentEntry& rhs) {
                return lhs.agent_id < rhs.agent_id;
              });
 
    PathAgentCollectInfo info;
    info.count = entries.size();
    // Fill the batch strictly in sorted-entry order so batch index i and
    // entries[i] stay one agent for the sink's write-back.
    for (const auto& entry : entries) {
      auto& state = *entry.state;
      if (const auto* goal = world_->entity(entry.entity).try_get<PathGoal>()) {
        if (!state.agent.has_goal || state.agent.goal != goal->coord) {
          set_path_agent_goal(state.agent, goal->coord);
          info.pathing_dirty = true;
        }
      } else if (state.agent.has_goal) {
        clear_path_agent_goal(state.agent);
      }
      batch.push(FlecsHandleAdapter::to_handle(entry.entity), state.agent);
    }
    return info;
  }
 
 private:
  flecs::world* world_;
  FlecsPathAgentContext* context_;
};
static_assert(PathAgentSource<FlecsPathAgentSource>);
 
template <typename Position = FlecsTilePositionAdapter>
  requires PositionAdapter<Position, flecs::entity_t>
class FlecsPathAgentSink {
 public:
  FlecsPathAgentSink(flecs::world& world, FlecsPathAgentContext& context,
                     Position position) noexcept
      : world_(&world),
        context_(&context),
        position_(static_cast<Position&&>(position)) {}
 
  FlecsPathAgentSink(flecs::world& world,
                     FlecsPathAgentContext& context) noexcept
    requires std::constructible_from<Position, flecs::world&>
      : FlecsPathAgentSink(world, context, Position(world)) {}
 
  void apply(const PathAgentBatch& batch) {
    detail::flecs_assert_immediate_lifecycle(*world_);
    detail::flecs_assert_context_world(*world_, *context_);
    const auto agents = batch.agents();
    const auto& entries = context_->entries;
    TESS_ASSERT(agents.size() == entries.size());
    for (std::size_t i = 0; i < entries.size(); ++i) {
      const auto entity = entries[i].entity;
      const auto& agent = agents[i];
      auto flecs_entity = world_->entity(entity);
      flecs_entity.set<PathState>(PathState{agent});
      position_.set_position(entity, agent.position);
      if (const auto* goal = flecs_entity.try_get<PathGoal>();
          goal != nullptr && !agent.has_goal && agent.position == goal->coord) {
        flecs_entity.remove<PathGoal>();
      }
    }
  }
 
 private:
  flecs::world* world_;
  FlecsPathAgentContext* context_;
  Position position_;
};
static_assert(PathAgentSink<FlecsPathAgentSink<>>);

template <typename World, typename OccupancyTag>
[[nodiscard]] auto spawn_flecs_path_agent(
    flecs::world& ecs, FlecsPathAgentContext& context, World& world,
    TileOccupancyIndex& index, Coord3 position, DirtyMask dirty_mask = {},
    DeltaCollector* render_deltas = nullptr) -> flecs::entity_t {
  detail::flecs_assert_immediate_lifecycle(ecs);
  detail::flecs_assert_context_world(ecs, context);
  if (!detail::flecs_tile_resolves(world, position) ||
      static_cast<bool>(world.template field<OccupancyTag>(position)) ||
      !index.entity_at(position).is_null()) {
    return 0u;
  }
  // Grow the only tess-owned allocating structure before creating an entity,
  // advancing AgentId, or claiming the world tile. insert() cannot allocate
  // after this preflight, so allocation failure is a semantic no-op.
  index.reserve(index.size() + 1);
  auto state = PathAgentState{};
  state.position = position;
  const auto flecs_entity = ecs.entity()
                                .set<AgentId>(AgentId{context.next_agent_id++})
                                .set<TilePosition>(TilePosition{position})
                                .set<PathState>(PathState{state});
  const auto entity = flecs_entity.id();
  world.template field<OccupancyTag>(position) = true;
  const auto inserted =
      index.insert(position, FlecsHandleAdapter::to_handle(entity));
  TESS_ASSERT(inserted);
  static_cast<void>(inserted);
  detail::flecs_mark_tile_dirty(world, position, dirty_mask);
  if (render_deltas != nullptr) {
    render_deltas->record_spawn(FlecsHandleAdapter::to_handle(entity),
                                position);
  }
  return entity;
}

[[nodiscard]] inline auto spawn_flecs_path_agent_off_board(
    flecs::world& world, FlecsPathAgentContext& context) -> flecs::entity_t {
  detail::flecs_assert_immediate_lifecycle(world);
  detail::flecs_assert_context_world(world, context);
  return world.entity()
      .set<AgentId>(AgentId{context.next_agent_id++})
      .set<TilePosition>(TilePosition{})
      .set<PathState>(PathState{})
      .add<OffBoard>()
      .id();
}

template <typename World, typename OccupancyTag>
auto despawn_flecs_path_agent(flecs::world& ecs, World& world,
                              TileOccupancyIndex& index, flecs::entity_t entity,
                              DirtyMask dirty_mask = {},
                              DeltaCollector* render_deltas = nullptr) -> bool {
  detail::flecs_assert_immediate_lifecycle(ecs);
  if (!ecs.is_alive(entity)) {
    return false;
  }
  auto flecs_entity = ecs.entity(entity);
  const auto* state = flecs_entity.try_get<PathState>();
  if (state == nullptr) {
    return false;
  }
  if (!flecs_entity.has<OffBoard>()) {
    const auto position = state->agent.position;
    world.template field<OccupancyTag>(position) = false;
    const auto erased = index.erase(position);
    TESS_ASSERT(erased == FlecsHandleAdapter::to_handle(entity));
    static_cast<void>(erased);
    detail::flecs_mark_tile_dirty(world, position, dirty_mask);
    if (render_deltas != nullptr) {
      // This branch is on-board, so despawn must emit the release now.
      // Parked entities skip the whole block because parking already emitted
      // the release.
      render_deltas->record_despawn(FlecsHandleAdapter::to_handle(entity),
                                    position);
    }
  }
  flecs_entity.destruct();
  return true;
}

template <typename World, typename OccupancyTag>
auto teleport_flecs_path_agent(flecs::world& ecs, World& world,
                               TileOccupancyIndex& index,
                               flecs::entity_t entity, Coord3 to,
                               DirtyMask dirty_mask = {},
                               DeltaCollector* render_deltas = nullptr)
    -> bool {
  detail::flecs_assert_immediate_lifecycle(ecs);
  if (!ecs.is_alive(entity)) {
    return false;
  }
  auto flecs_entity = ecs.entity(entity);
  auto* state = flecs_entity.try_get_mut<PathState>();
  if (state == nullptr || flecs_entity.has<OffBoard>()) {
    return false;
  }
  if (!detail::flecs_tile_resolves(world, to) ||
      static_cast<bool>(world.template field<OccupancyTag>(to)) ||
      !index.entity_at(to).is_null()) {
    return false;
  }
  const auto from = state->agent.position;
  world.template field<OccupancyTag>(from) = false;
  world.template field<OccupancyTag>(to) = true;
  index.move(from, to, FlecsHandleAdapter::to_handle(entity));
  auto fresh = PathAgentState{};
  fresh.position = to;
  flecs_entity.set<PathState>(PathState{fresh});
  flecs_entity.set<TilePosition>(TilePosition{to});
  detail::flecs_mark_tile_dirty(world, from, dirty_mask);
  detail::flecs_mark_tile_dirty(world, to, dirty_mask);
  if (render_deltas != nullptr) {
    render_deltas->record_teleport(FlecsHandleAdapter::to_handle(entity), from,
                                   to);
  }
  return true;
}

template <typename World, typename OccupancyTag>
auto park_flecs_path_agent(flecs::world& ecs, World& world,
                           TileOccupancyIndex& index, flecs::entity_t entity,
                           DirtyMask dirty_mask = {},
                           DeltaCollector* render_deltas = nullptr) -> bool {
  detail::flecs_assert_immediate_lifecycle(ecs);
  if (!ecs.is_alive(entity)) {
    return false;
  }
  auto flecs_entity = ecs.entity(entity);
  auto* state = flecs_entity.try_get_mut<PathState>();
  if (state == nullptr || flecs_entity.has<OffBoard>()) {
    return false;
  }
  const auto position = state->agent.position;
  world.template field<OccupancyTag>(position) = false;
  const auto erased = index.erase(position);
  TESS_ASSERT(erased == FlecsHandleAdapter::to_handle(entity));
  static_cast<void>(erased);
  clear_path_agent_goal(state->agent);
  flecs_entity.modified<PathState>();
  flecs_entity.add<OffBoard>();
  detail::flecs_mark_tile_dirty(world, position, dirty_mask);
  if (render_deltas != nullptr) {
    render_deltas->record_park(FlecsHandleAdapter::to_handle(entity), position);
  }
  return true;
}

template <typename World, typename OccupancyTag>
auto place_flecs_path_agent(flecs::world& ecs, World& world,
                            TileOccupancyIndex& index, flecs::entity_t entity,
                            Coord3 position, DirtyMask dirty_mask = {},
                            DeltaCollector* render_deltas = nullptr) -> bool {
  detail::flecs_assert_immediate_lifecycle(ecs);
  if (!ecs.is_alive(entity)) {
    return false;
  }
  auto flecs_entity = ecs.entity(entity);
  auto* state = flecs_entity.try_get_mut<PathState>();
  if (state == nullptr || !flecs_entity.has<OffBoard>()) {
    return false;
  }
  if (!detail::flecs_tile_resolves(world, position) ||
      static_cast<bool>(world.template field<OccupancyTag>(position)) ||
      !index.entity_at(position).is_null()) {
    return false;
  }
  // Preflight index growth while the entity is still parked and the world
  // tile is still free. The remaining index insertion is non-allocating.
  index.reserve(index.size() + 1);
  world.template field<OccupancyTag>(position) = true;
  const auto inserted =
      index.insert(position, FlecsHandleAdapter::to_handle(entity));
  TESS_ASSERT(inserted);
  static_cast<void>(inserted);
  auto fresh = PathAgentState{};
  fresh.position = position;
  flecs_entity.set<PathState>(PathState{fresh});
  flecs_entity.set<TilePosition>(TilePosition{position});
  flecs_entity.remove<OffBoard>();
  detail::flecs_mark_tile_dirty(world, position, dirty_mask);
  if (render_deltas != nullptr) {
    render_deltas->record_place(FlecsHandleAdapter::to_handle(entity),
                                position);
  }
  return true;
}

inline void set_flecs_path_agent_goal(flecs::world& world,
                                      flecs::entity_t entity, Coord3 goal) {
  world.entity(entity).set<PathGoal>(PathGoal{goal});
}

inline void clear_flecs_path_agent_goal(flecs::world& world,
                                        flecs::entity_t entity) {
  world.entity(entity).remove<PathGoal>();
}
 
template <typename World, typename ClassOrTag, typename OccupancyTag,
          typename ReservationTag, typename Position = FlecsTilePositionAdapter>
[[nodiscard]] auto tick_flecs_unit_path_agents(
    flecs::world& ecs, FlecsPathAgentContext& context, World& world,
    PathRequestRuntime& runtime, TileOccupancyIndex& index,
    PathAgentTickOptions options = {},
    const RegionGraphT<typename World::residency_type>* graph = nullptr,
    DeltaCollector* render_deltas = nullptr) -> PathAgentTickStats {
  detail::flecs_assert_immediate_lifecycle(ecs);
  detail::flecs_assert_context_world(ecs, context);
  FlecsPathAgentSource source(ecs, context);
  FlecsPathAgentSink<Position> sink(ecs, context);
  return tick_ecs_unit_path_agents<World, ClassOrTag, OccupancyTag,
                                   ReservationTag>(
      context.tick_state, world, source, sink, context.batch, runtime, index,
      options, graph, render_deltas);
}
 
template <typename World, typename Class, std::uint32_t MaxCost,
          typename OccupancyTag, typename ReservationTag,
          typename Position = FlecsTilePositionAdapter>
[[nodiscard]] auto tick_flecs_path_agents(
    flecs::world& ecs, FlecsPathAgentContext& context, World& world,
    PathRequestRuntime& runtime, TileOccupancyIndex& index,
    PathAgentTickOptions options = {},
    const RegionGraphT<typename World::residency_type>* graph = nullptr,
    DeltaCollector* render_deltas = nullptr) -> PathAgentTickStats {
  detail::flecs_assert_immediate_lifecycle(ecs);
  detail::flecs_assert_context_world(ecs, context);
  FlecsPathAgentSource source(ecs, context);
  FlecsPathAgentSink<Position> sink(ecs, context);
  return tick_ecs_path_agents<World, Class, MaxCost, OccupancyTag,
                              ReservationTag>(
      context.tick_state, world, source, sink, context.batch, runtime, index,
      options, graph, render_deltas);
}
 
}  // namespace tess
 
#endif  // TESS_ENABLE_FLECS