ActorDispatcher.cpp

Go to the documentation of this file.

// Copyright (c) 2026 Computer Vision Center (CVC) at the Universitat Autonoma
// de Barcelona (UAB).
//
// This work is licensed under the terms of the MIT license.
// For a copy, see <https://opensource.org/licenses/MIT>.
 
#include "Carla/Actor/ActorDispatcher.h"
#include "Carla.h"
#include "Carla/Actor/ActorBlueprintFunctionLibrary.h"
#include "Carla/Actor/ActorROS2Handler.h"
#include "Carla/Actor/CarlaActorFactory.h"
#include "Carla/Game/CarlaEpisode.h"
#include "Carla/Game/Tagger.h"
#include "Carla/Vehicle/VehicleControl.h"
 
#include <util/ue-header-guard-begin.h>
#include "GameFramework/Controller.h"
#ifdef WITH_ROS2
  #include <util/disable-ue4-macros.h>
  #include "carla/ros2/ROS2.h"
  #include <util/enable-ue4-macros.h>
  #include <variant>
#endif
#include <util/ue-header-guard-end.h>
 
void UActorDispatcher::Bind(FActorDefinition Definition, SpawnFunctionType Functor)
{
  if (UActorBlueprintFunctionLibrary::CheckActorDefinition(Definition))
  {
    Definition.UId = static_cast<uint32>(SpawnFunctions.Num()) + 1u;
    Definitions.Emplace(Definition);
    SpawnFunctions.Emplace(Functor);
    Classes.Add(Definition.Id, Definition.Class);
  }
  else
  {
    UE_LOG(LogCarla, Warning, TEXT("Invalid definition '%s' ignored"), *Definition.Id);
  }
}
 
void UActorDispatcher::ReleaseContentPack(const FString &MountPoint)
{
  // Drop the definitions outright instead of only clearing their class: the
  // blueprint library the client asks for is built from Definitions, so a
  // definition left behind keeps advertising a blueprint whose content is no
  // longer mounted until the next world load rebuilds the list.
  Definitions.RemoveAll([&MountPoint](const FActorDefinition &Definition)
  {
    return ACarlaActorFactory::DefinitionReferencesPath(Definition, MountPoint);
  });
  for (auto It = Classes.CreateIterator(); It; ++It)
  {
    const bool bStillDefined = Definitions.ContainsByPredicate(
        [&It](const FActorDefinition &Definition) { return Definition.Id == It.Key(); });
    if (!bStillDefined)
    {
      It.RemoveCurrent();
    }
  }
}
 
void UActorDispatcher::BindNewDefinitions(ACarlaActorFactory &ActorFactory)
{
  for (const auto &Definition : ActorFactory.GetDefinitions())
  {
    const bool bAlreadyBound = Definitions.ContainsByPredicate(
        [&Definition](const FActorDefinition &Existing) { return Existing.Id == Definition.Id; });
    if (bAlreadyBound)
    {
      continue;
    }
    Bind(Definition, [&](const FTransform &Transform, const FActorDescription &Description) {
      return ActorFactory.SpawnActor(Transform, Description);
    });
  }
}
 
void UActorDispatcher::Bind(ACarlaActorFactory &ActorFactory)
{
  for (const auto &Definition : ActorFactory.GetDefinitions())
  {
    Bind(Definition, [&](const FTransform &Transform, const FActorDescription &Description) {
      return ActorFactory.SpawnActor(Transform, Description);
    });
  }
}
 
TPair<EActorSpawnResultStatus, FCarlaActor*> UActorDispatcher::SpawnActor(
    const FTransform &Transform,
    FActorDescription Description,
    FCarlaActor::IdType DesiredId)
{
  if ((Description.UId == 0u) || (Description.UId > static_cast<uint32>(SpawnFunctions.Num())))
  {
    UE_LOG(LogCarla, Error, TEXT("Invalid ActorDescription '%s' (UId=%d)"), *Description.Id, Description.UId);
    return MakeTuple(EActorSpawnResultStatus::InvalidDescription, nullptr);
  }
 
  UE_LOG(LogCarla, Log, TEXT("Spawning actor '%s'"), *Description.Id);
 
  auto Class = Classes.Find(Description.Id);
  if (Class == nullptr)
  {
    UE_LOG(LogCarla, Error, TEXT("Invalid ActorDescription '%s' (UId=%d)"), *Description.Id, Description.UId);
    return MakeTuple(EActorSpawnResultStatus::InvalidDescription, nullptr);
  }
 
  Description.Class = *Class;
  FActorSpawnResult Result = SpawnFunctions[Description.UId - 1](Transform, Description);
 
  if ((Result.Status == EActorSpawnResultStatus::Success) && (Result.Actor == nullptr))
  {
    UE_LOG(LogCarla, Warning, TEXT("ActorSpawnResult: Trying to spawn '%s'"), *Description.Id);
    UE_LOG(LogCarla, Warning, TEXT("ActorSpawnResult: Reported success but did not return an actor"));
    Result.Status = EActorSpawnResultStatus::UnknownError;
  }
 
  if (Result.IsValid())
  {
    // Tag before registering: FActorRegistry::MakeCarlaActor snapshots the
    // semantic tags into the actor info that spawn_actor/get_actors return,
    // and the OnActorSpawned tagger delegate already ran before the factory
    // assigned the mesh (props were tagged "None" there).
    ATagger::TagActor(*Result.Actor, true);
  }
 
  FCarlaActor* View = Result.IsValid() ?
      RegisterActor(*Result.Actor, std::move(Description), DesiredId) : nullptr;
  if (!View)
  {
    UE_LOG(LogCarla, Warning, TEXT("Failed to spawn actor '%s'"), *Description.Id);
    check(Result.Status != EActorSpawnResultStatus::Success);
  }
 
  return MakeTuple(Result.Status, View);
}
 
AActor* UActorDispatcher::ReSpawnActor(
    const FTransform &Transform,
    FActorDescription Description)
{
  if ((Description.UId == 0u) || (Description.UId > static_cast<uint32>(SpawnFunctions.Num())))
  {
    UE_LOG(LogCarla, Error, TEXT("Invalid ActorDescription '%s' (UId=%d)"), *Description.Id, Description.UId);
    return nullptr;
  }
 
  UE_LOG(LogCarla, Log, TEXT("Spawning actor '%s'"), *Description.Id);
 
  auto Class = Classes.Find(Description.Id);
  if (Class == nullptr)
  {
    UE_LOG(LogCarla, Error, TEXT("Invalid ActorDescription '%s' (UId=%d)"), *Description.Id, Description.UId);
    return nullptr;
  }
 
  Description.Class = *Class;
  FActorSpawnResult Result = SpawnFunctions[Description.UId - 1](Transform, Description);
 
  if ((Result.Status == EActorSpawnResultStatus::Success) && (Result.Actor == nullptr))
  {
    UE_LOG(LogCarla, Warning, TEXT("ActorSpawnResult: Trying to spawn '%s'"), *Description.Id);
    UE_LOG(LogCarla, Warning, TEXT("ActorSpawnResult: Reported success but did not return an actor"));
    Result.Status = EActorSpawnResultStatus::UnknownError;
    return nullptr;
  }
 
  if (Result.Status == EActorSpawnResultStatus::Success)
  {
    return Result.Actor;
  }
 
  return nullptr;
}
 
bool UActorDispatcher::DestroyActor(FCarlaActor::IdType ActorId)
{
  // Check if the actor is in the registry.
  FCarlaActor* View = Registry.FindCarlaActor(ActorId);
 
  // Invalid destruction if is not marked to PendingKill (except is dormant, dormant actors can be destroyed)
  if (!View)
  {
    UE_LOG(LogCarla, Warning, TEXT("Trying to destroy actor that is not in the registry"));
    return false;
  }
 
  const FString &Id = View->GetActorInfo()->Description.Id;
 
  // Destroy its controller if present.
  AActor* Actor = View->GetActor();
  if(Actor)
  {
    APawn* Pawn = Cast<APawn>(Actor);
    AController* Controller = (Pawn != nullptr ? Pawn->GetController() : nullptr);
    if (Controller != nullptr)
    {
      UE_LOG(LogCarla, Log, TEXT("Destroying actor's controller: '%s'"), *Id);
      bool Success = Controller->Destroy();
      if (!Success)
      {
        UE_LOG(LogCarla, Error, TEXT("Failed to destroy actor's controller: '%s'"), *Id);
      }
    }
 
    // Destroy the actor.
    UE_LOG(LogCarla, Log, TEXT("UActorDispatcher::Destroying actor: '%s' %x"), *Id, Actor);
    UE_LOG(LogCarla, Log, TEXT("            %s"), Actor?*Actor->GetName():*FString("None"));
    if (!Actor || !Actor->Destroy())
    {
      UE_LOG(LogCarla, Error, TEXT("Failed to destroy actor: '%s'"), *Id);
      return false;
    }
  }
 
  Registry.Deregister(ActorId);
 
  return true;
}
 
FCarlaActor* UActorDispatcher::RegisterActor(
    AActor &Actor, FActorDescription Description,
    FActorRegistry::IdType DesiredId)
{
  FCarlaActor* View = Registry.Register(Actor, Description, DesiredId);
  if (View)
  {
    // TODO: support external actor destruction
    Actor.OnDestroyed.AddDynamic(this, &UActorDispatcher::OnActorDestroyed);
 
    // ROS2 mapping of actor->ros_name
    #ifdef WITH_ROS2
    auto ROS2 = carla::ros2::ROS2::GetInstance();
    if (ROS2->IsEnabled())
    {
      // actor ros_name
      std::string RosName;
      std::string RosTopicName;
      for (auto &&Attr : Description.Variations)
      {
        if (Attr.Key == "ros_name")
        {
          RosName = std::string(TCHAR_TO_UTF8(*Attr.Value.Value));
        }
        if (Attr.Key == "ros_topic_name")
        {
          RosTopicName = std::string(TCHAR_TO_UTF8(*Attr.Value.Value));
        }
      }
      const std::string id = std::string(TCHAR_TO_UTF8(*Description.Id));
      std::string ResolvedRosName;
      if (RosName == id) {
        if(RosName.find("vehicle") != std::string::npos)
        {
          ResolvedRosName = "vehicle" + std::to_string(View->GetActorId());
        }
        else
        {
          size_t pos = RosName.find_last_of('.');
          if (pos != std::string::npos) {
            ResolvedRosName = RosName.substr(pos + 1) + "__";
          }
        }
      } else {
        ResolvedRosName = RosName;
      }
      if (!ResolvedRosName.empty())
      {
        ROS2->RegisterSensor(static_cast<void*>(&Actor), ResolvedRosName, ResolvedRosName, true);
      }
      // exact-topic override (empty when the attribute is unset or equals the
      // blueprint id: signal to generate the default topic name)
      ROS2->AddActorRosTopicName(static_cast<void*>(&Actor), RosTopicName == id ? "" : RosTopicName);
 
      // vehicle controller for hero. Scan the variations once for the hero role and the
      // opt-in Ackermann/Autoware control flags; the control topics are mutually
      // exclusive on the ROS 2 side, so only request them when an attribute asks for it.
      bool bIsHero = false;
      bool bEnableAckermannControl = false;
      bool bEnableAutowareControl = false;
      for (auto &&Attr : Description.Variations)
      {
        if (Attr.Key == "role_name" && (Attr.Value.Value == "hero" || Attr.Value.Value == "ego"))
        {
          bIsHero = true;
        }
        else if (Attr.Key == "ros2_ackermann_control")
        {
          bEnableAckermannControl = Attr.Value.Value.ToBool();
        }
        else if (Attr.Key == "ros2_autoware_control")
        {
          bEnableAutowareControl = Attr.Value.Value.ToBool();
        }
      }
      if (bIsHero)
      {
        if (bEnableAutowareControl)
        {
          // Autoware maps steering 1:1 to wheel angle; a speed-dependent
          // steering curve would silently rescale the command (tier4 port).
          ActorROS2Handler::FlattenSteeringCurve(&Actor);
        }
        ROS2->RegisterVehicle(static_cast<void*>(&Actor), ResolvedRosName, ResolvedRosName, [ResolvedRosName](void *Actor, carla::ros2::ROS2CallbackData Data) -> void
        {
          AActor *UEActor = reinterpret_cast<AActor *>(Actor);
          ActorROS2Handler Handler(UEActor, ResolvedRosName);
          std::visit(Handler, Data);
        }, bEnableAckermannControl, bEnableAutowareControl);
        #if defined(WITH_ROS2_DEMO)
        ROS2->AddBasicSubscriberCallback(static_cast<void*>(&Actor), ResolvedRosName, [ResolvedRosName](void *Actor, carla::ros2::ROS2MessageCallbackData Data) -> void
        {
          AActor *UEActor = reinterpret_cast<AActor *>(Actor);
          ActorROS2Handler Handler(UEActor, ResolvedRosName);
          std::visit(Handler, Data);
        });
        #endif
      }
    }
    #endif
  }
  return View;
}
 
void UActorDispatcher::PutActorToSleep(FCarlaActor::IdType Id, UCarlaEpisode* CarlaEpisode)
{
  Registry.PutActorToSleep(Id, CarlaEpisode);
}
 
void UActorDispatcher::WakeActorUp(FCarlaActor::IdType Id, UCarlaEpisode* CarlaEpisode)
{
  Registry.WakeActorUp(Id, CarlaEpisode);
}
 
void UActorDispatcher::OnActorDestroyed(AActor *Actor)
{
  FCarlaActor* CarlaActor = Registry.FindCarlaActor(Actor);
 
  #ifdef WITH_ROS2
  auto ROS2 = carla::ros2::ROS2::GetInstance();
  if (ROS2->IsEnabled())
  {
    void *ActorKey = reinterpret_cast<void *>(Actor);
    // UnregisterVehicle clears the per-actor subscribers, the actor-callback
    // map, and the ros_name maps in a single step. The call is idempotent on
    // a missing key, so it works for both vehicles and sensors that never
    // registered a callback.
    ROS2->UnregisterVehicle(ActorKey);
    ROS2->RemoveActorRosTopicName(ActorKey);
    #if defined(WITH_ROS2_DEMO)
    ROS2->RemoveBasicSubscriberCallback(ActorKey);
    #endif
  }
  #endif
 
  if (CarlaActor && CarlaActor->IsActive())
  {
    // An actor can also go without the episode destroying it (a life span
    // that ran out, falling out of the world): Multi-GPU secondaries mirror it
    // and must drop it too. FFrameData ignores a second report of the same id.
    UCarlaEpisode *Episode = Cast<UCarlaEpisode>(GetOuter());
    if (Episode && Episode->bIsPrimaryServer)
    {
      Episode->GetFrameData().AddEvent(CarlaRecorderEventDel{CarlaActor->GetActorId()});
    }
    Registry.Deregister(CarlaActor->GetActorId());
  }
}