Skip to content

API.md

Latest commit

 

History

History
905 lines (750 loc) · 35.6 KB

API.md

File metadata and controls

905 lines (750 loc) · 35.6 KB
Raw

C++ Core API Reference

This document provides a detailed reference for the C++ core API, primarily focusing on functions exposed to the C# adapter layer via P/Invoke.

Table of Contents

  1. Data Structures and Enums
  2. General API Functions (AgentSimApi.h)
  3. C# Adapter API Reference (UnityAdapter.cs)

1. Data Structures and Enums

LogLevel

enum LogLevel {
    Trace = 0,
    Debug = 1,
    Info = 2,
    Warn = 3,
    Error = 4,
    Critical = 5,
    Off = 6
};
  • Description: Defines the severity levels for log messages originating from the C++ core. Used in conjunction with SetLogCallback to filter and categorize logs.

Vector3

struct Vector3 {
    float x, y, z;
};
  • Description: Represents a 3D vector or point in space. Used for positions, directions, and other spatial data.

Quaternion

struct Quaternion {
    float x, y, z, w;
};
  • Description: Represents a rotation in 3D space.

WorldObjectType

enum class WorldObjectType : int {
    NONE = 0,
    TREE,
    ROCK,
    WATER,
    FOOD,
    SHELTER,
    // Add more types as needed
};
  • Description: Categorizes different types of static or interactive objects in the simulated world.

WorldEventType

enum class WorldEventType : int {
    NONE = 0,
    SOUND,
    SMELL,
    SIGHT,
    TOUCH,
    // Add more types as needed
};
  • Description: Categorizes different types of events that can occur in the simulated world, influencing agent perception.

AgentState

enum class AgentState : int {
    IDLE = 0,
    WANDERING,
    MOVING_TO_GOAL,
    PERFORMING_ACTION,
    PURSUING_GOAL,
    // Add more states as needed
};
  • Description: Represents the high-level Finite State Machine (FSM) states an agent can be in.

WorldProperty

enum class WorldProperty : int {
    HAS_FOOD = 0,
    HAS_SHELTER,
    IS_THIRSTY,
    IS_HUNGRY,
    IS_TIRED,
    IS_SAFE,
    HAS_AXE,
    HAS_WOOD,
    // Add more world properties as needed
};
  • Description: Defines various boolean properties that describe the state of an agent's understanding of the world or its personal needs. Used in GOAP planning.

AgentWorldState

// Using a fixed-size bitset for agent world state conditions
// Max 64 properties for now to fit in a uint64_t
using AgentWorldState = std::bitset<64>;
  • Description: A bitset representing an agent's current perception of the world state and its internal needs based on WorldProperty values. Each bit corresponds to a WorldProperty.

WorldObject

struct WorldObject {
    int id;
    WorldObjectType type;
    Vector3 position;
    Quaternion rotation;
    // Add other relevant properties like health, interactable state, etc.
};
  • Description: Represents a single observable object in the world. Its data is typically managed by the C# engine and passed to the C++ core.

WorldEvent

struct WorldEvent {
    int id;
    WorldEventType type;
    Vector3 position;
    float severity; // e.g., loudness for sound, intensity for smell
    // Add other relevant properties like duration, source, etc.
};
  • Description: Represents a single event occurring in the world. Its data is typically managed by the C# engine and passed to the C++ core.

WorldSnapshot

struct WorldSnapshot {
    long long timestamp; // Time in milliseconds or simulation ticks
    WorldObject* worldObjects;
    int numWorldObjects;
    WorldEvent* worldEvents;
    int numWorldEvents;

    // Global world properties
    Vector3 sunDirection;
    float timeOfDay; // 0.0 to 24.0
    // Add other global properties like weather, global resource counts, etc.
};
  • Description: A comprehensive snapshot of the entire world state at a given time. This structure is typically populated by the C# layer and passed to the C++ core for processing during simulation updates. Memory for worldObjects and worldEvents is owned by the C# side.

IncrementalWorldSnapshot

struct IncrementalWorldSnapshot {
    long long timestamp;

    // World Objects
    WorldObject* addedObjects;
    int addedObjectCount;

    int* removedObjectIds;
    int removedObjectIdCount;

    WorldObject* modifiedObjects;
    int modifiedObjectCount;

    // World Events
    WorldEvent* addedEvents;
    int addedEventCount;

    int* removedEventIds;
    int removedEventIdCount;
};
  • Description: Represents changes to the world state incrementally, containing only objects and events that have been added, removed, or modified since the last snapshot. This is used for optimizing data transfer between C# and C++. Memory for all pointers is owned by the C# side.

AgentDebugData

struct AgentDebugData {
    int agentId;
    int lodTier; 
    int currentGoal;
    int fsmState;
    Vector3 targetPosition;
    const char* currentActionName;
};
  • Description: A structure used to retrieve detailed debug information about an individual agent from the C++ core. Populated by the C++ core and read by the C# layer for visualization or debugging.

Vector2Int

struct Vector2Int {
    int x, y;
};
  • Description: Represents a 2D integer vector, typically used for grid coordinates or similar integer-based spatial data.

SimulationStageTimings

struct SimulationStageTimings {
    long long worldQueryUpdateMs;
    long long totalAgentUpdateMs;
    long long perceptionMs;
    long long planningMs;
    long long executionMs;
    long long stateUpdateMs;
};
  • Description: Provides detailed timing information (in milliseconds) for various stages of the simulation update loop, useful for performance profiling and optimization.

AgentCommandType

enum class AgentCommandType {
    NONE,
    MOVE_TO,
    ARRIVED_AT_POSITION,
    INTERACT_WITH_OBJECT,
    PLAY_ANIMATION,
    CHANGE_STATE,
    PERFORM_ACTION
    // ... more command types
};
  • Description: Defines the types of commands an agent can issue to the game engine. These commands instruct the engine on how to visually or physically represent the agent's actions and states. This enum has a direct C# counterpart (AgentSimMiddleware.AgentCommandType) with slightly different enum member names (e.g., MOVE_TO in C++ is MOVE_TO_POSITION in C#).

AgentCommand

struct AgentCommand {
    int agentId;
    AgentCommandType commandType;
    Vector3 targetPosition;
    int targetObjectId;
    const char* animationName;
    int newState;
};
  • Description: Represents a single command generated by the C++ core for a specific agent, to be processed by the C# game engine. The fields used depend on the commandType. For animationName, the C++ side provides a const char*, which is marshaled to a IntPtr in the C# AgentCommand struct (AgentSimMiddleware.AgentCommand). The C# struct provides an AnimationName property to convert IntPtr to string.

LogLevel

enum LogLevel {
    Trace = 0,
    Debug = 1,
    Info = 2,
    Warn = 3,
    Error = 4,
    Critical = 5,
    Off = 6
};
  • Description: Defines the severity levels for log messages originating from the C++ core. This enum has a direct C# counterpart (AgentSimMiddleware.UnityAdapter.LogLevel) used for logging integration.

Vector3

struct Vector3 {
    float x, y, z;
};
  • Description: Represents a 3D vector or point in space. Used for positions, directions, and other spatial data. This struct has a direct C# counterpart (AgentSimMiddleware.Vector3).

Quaternion

struct Quaternion {
    float x, y, z, w;
};
  • Description: Represents a rotation in 3D space. This struct has a direct C# counterpart (AgentSimMiddleware.Quaternion).

WorldObjectType

enum class WorldObjectType : int {
    NONE = 0,
    TREE,
    ROCK,
    WATER,
    FOOD,
    SHELTER,
    // Add more types as needed
};
  • Description: Categorizes different types of static or interactive objects in the simulated world. This enum has a direct C# counterpart (AgentSimMiddleware.WorldObjectType). The C# version may contain additional types beyond what the C++ core is compiled to understand; the C++ core will only process types it explicitly knows.

WorldEventType

enum class WorldEventType : int {
    NONE = 0,
    SOUND,
    SMELL,
    SIGHT,
    TOUCH,
    // Add more types as needed
};
  • Description: Categorizes different types of events that can occur in the simulated world, influencing agent perception. This enum has a direct C# counterpart (AgentSimMiddleware.WorldEventType). Similar to WorldObjectType, the C# version may define more event types than the C++ core explicitly handles.

AgentState

enum class AgentState : int {
    IDLE = 0,
    WANDERING,
    MOVING_TO_GOAL,
    PERFORMING_ACTION,
    PURSUING_GOAL,
    // Add more states as needed
};
  • Description: Represents the high-level Finite State Machine (FSM) states an agent can be in. This enum has a direct C# counterpart (AgentSimMiddleware.AgentState).

WorldProperty

enum class WorldProperty : int {
    HAS_FOOD = 0,
    HAS_SHELTER,
    IS_THIRSTY,
    IS_HUNGRY,
    IS_TIRED,
    IS_SAFE,
    HAS_AXE,
    HAS_WOOD,
    // Add more world properties as needed
};
  • Description: Defines various boolean properties that describe the state of an agent's understanding of the world or its personal needs. Used in GOAP planning. This enum has a direct C# counterpart (AgentSimMiddleware.WorldProperty).

AgentWorldState

// Using a fixed-size bitset for agent world state conditions
// Max 64 properties for now to fit in a uint64_t
using AgentWorldState = std::bitset<64>;
  • Description: A bitset representing an agent's current perception of the world state and its internal needs based on WorldProperty values. Each bit corresponds to a WorldProperty. This type is marshaled as a ulong in C#.

WorldObject

struct WorldObject {
    int id;
    WorldObjectType type;
    Vector3 position;
    Quaternion rotation;
    // Add other relevant properties like health, interactable state, etc.
};
  • Description: Represents a single observable object in the world. Its data is typically managed by the C# engine and passed to the C++ core. This struct has a direct C# counterpart (AgentSimMiddleware.WorldObject).

WorldEvent

struct WorldEvent {
    int id;
    WorldEventType type;
    Vector3 position;
    float severity; // e.g., loudness for sound, intensity for smell
    // Add other relevant properties like duration, source, etc.
};
  • Description: Represents a single event occurring in the world. Its data is typically managed by the C# engine and passed to the C++ core. This struct has a direct C# counterpart (AgentSimMiddleware.WorldEvent).

WorldSnapshot

struct WorldSnapshot {
    long long timestamp; // Time in milliseconds or simulation ticks
    WorldObject* worldObjects;
    int numWorldObjects;
    WorldEvent* worldEvents;
    int numWorldEvents;

    // Global world properties
    Vector3 sunDirection;
    float timeOfDay; // 0.0 to 24.0
    // Add other global properties like weather, global resource counts, etc.
};
  • Description: A comprehensive snapshot of the entire world state at a given time. This structure is typically populated by the C# layer and passed to the C++ core for processing during simulation updates. Memory for worldObjects and worldEvents is owned by the C# side. This struct has a direct C# counterpart (AgentSimMiddleware.WorldSnapshot) which handles marshaling of pointers.

IncrementalWorldSnapshot

struct IncrementalWorldSnapshot {
    long long timestamp;

    // World Objects
    WorldObject* addedObjects;
    int addedObjectCount;

    int* removedObjectIds;
    int removedObjectIdCount;

    WorldObject* modifiedObjects;
    int modifiedObjectCount;

    // World Events
    WorldEvent* addedEvents;
    int addedEventCount;

    int* removedEventIds;
    int removedEventIdCount;
};
  • Description: Represents changes to the world state incrementally, containing only objects and events that have been added, removed, or modified since the last snapshot. This is used for optimizing data transfer between C# and C++. Memory for all pointers is owned by the C# side. This struct has a C# counterpart (AgentSimMiddleware.UnityAdapter.IncrementalWorldSnapshot) which uses IntPtr for arrays, requiring careful marshaling.

AgentDebugData

struct AgentDebugData {
    int agentId;
    int lodTier; 
    int currentGoal;
    int fsmState;
    Vector3 targetPosition;
    const char* currentActionName;
};
  • Description: A structure used to retrieve detailed debug information about an individual agent from the C++ core. Populated by the C++ core and read by the C# layer for visualization or debugging. The currentActionName field requires manual string marshaling in C#.

Vector2Int

struct Vector2Int {
    int x, y;
};
  • Description: Represents a 2D integer vector, typically used for grid coordinates or similar integer-based spatial data. This struct has a direct C# counterpart (AgentSimMiddleware.Vector2Int).

SimulationStageTimings

struct SimulationStageTimings {
    long long worldQueryUpdateMs;
    long long totalAgentUpdateMs;
    long long perceptionMs;
    long long planningMs;
    long long executionMs;
    long long stateUpdateMs;
};
  • Description: Provides detailed timing information (in milliseconds) for various stages of the simulation update loop, useful for performance profiling and optimization. This struct has a direct C# counterpart (AgentSimMiddleware.SimulationStageTimings).

AgentCommandType

enum class AgentCommandType {
    NONE,
    MOVE_TO,
    ARRIVED_AT_POSITION,
    INTERACT_WITH_OBJECT,
    PLAY_ANIMATION,
    CHANGE_STATE,
    PERFORM_ACTION
    // ... more command types
};
  • Description: Defines the types of commands an agent can issue to the game engine. These commands instruct the engine on how to visually or physically represent the agent's actions and states. This enum has a direct C# counterpart (AgentSimMiddleware.AgentCommandType).

AgentCommand

struct AgentCommand {
    int agentId;
    AgentCommandType commandType;
    Vector3 targetPosition;
    int targetObjectId;
    const char* animationName;
    int newState;
};
  • Description: Represents a single command generated by the C++ core for a specific agent, to be processed by the C# game engine. The fields used depend on the commandType. For animationName, the C# side must copy the string if it needs to persist beyond the current frame. This struct has a direct C# counterpart (AgentSimMiddleware.AgentCommand) which handles string marshaling.

Goal

enum class Goal {
    GATHER_WOOD,
    GET_FOOD,
    SATISFY_THIRST,
    REACH_TARGET,
    FIND_TREE,
    GO_TO_NEAREST_FOOD_SOURCE,
    COUNT
};
  • Description: Defines predefined goals that agents can pursue within the simulation. These goals are used in the GOAP planning system. This enum has a direct C# counterpart (AgentSimMiddleware.Goal).

AgentDisplayData

public struct AgentDisplayData {
    public int agentId;
    public int lodTier; 
    public int currentGoal;
    public int fsmState;
    public Vector3 targetPosition;
    public string currentActionName;
}
  • Description: A C# specific structure used to display agent debug information. It is a convenience wrapper around the raw C++ AgentDebugData with the currentActionName string already marshaled for easier consumption in C#.

GetLastSimulationTimings

AGENTSIM_API void GetLastSimulationTimings(AgentContainer* container, SimulationStageTimings* outTimings);
  • Description: Retrieves the performance timings for the various stages of the last simulation update.
  • Parameters:
    • container: A pointer to the AgentContainer instance.
    • outTimings: A pointer to a SimulationStageTimings struct that will be populated with the timing data.
  • Returns: void

3. C# Adapter API Reference (UnityAdapter.cs)

The AgentSimMiddleware.UnityAdapter class provides the primary interface for Unity to interact with the native C++ simulation core. It handles marshaling data between C# and C++, manages agent lifecycle, and facilitates world state synchronization.

UnityAdapter.Init

public static bool Init(int maxAgents, string goapJsonFilePath)
  • Description: Initializes the C++ simulation core and sets up the necessary communication channels. This must be called before any other simulation-related functions.
  • Parameters:
    • maxAgents: The maximum number of agents the simulation is configured to handle.
    • goapJsonFilePath: The path to the GOAP JSON file (e.g., "Data/actions_goals") within Unity's Resources folder, containing definitions for actions and goals.
  • Returns: true if the simulation was initialized successfully, false otherwise.

UnityAdapter.SetLODThresholds

public static void SetLODThresholds(float fullSimDistance, float liteSimDistance)
  • Description: Configures the Level-of-Detail (LOD) distance thresholds for the C++ simulation. Agents within fullSimDistance will be fully simulated, and those within liteSimDistance (but outside fullSimDistance) will be lightly simulated.
  • Parameters:
    • fullSimDistance: The distance from the camera within which agents receive full simulation updates.
    • liteSimDistance: The distance from the camera within which agents receive lighter simulation updates.
  • Returns: void

UnityAdapter.RegisterAgentBehaviour

public static void RegisterAgentBehaviour(int agentId, AgentBehaviour agentBehaviour)
  • Description: Registers an AgentBehaviour instance with the adapter, associating it with a specific agent ID from the C++ core. This allows the adapter to dispatch AgentCommands to the correct Unity GameObject.
  • Parameters:
    • agentId: The unique ID of the agent in the C++ simulation.
    • agentBehaviour: The AgentBehaviour component associated with the Unity representation of the agent.
  • Returns: void

UnityAdapter.UnregisterAgentBehaviour

public static void UnregisterAgentBehaviour(int agentId)
  • Description: Unregisters an AgentBehaviour instance, typically called when an agent is removed from the simulation or its corresponding Unity GameObject is destroyed.
  • Parameters:
    • agentId: The unique ID of the agent to unregister.
  • Returns: void

UnityAdapter.RegisterGameObject

public static void RegisterGameObject(int id, GameObject gameObject)
  • Description: Registers a GameObject with its instance ID, allowing the adapter to retrieve GameObjects by their ID for world snapshot generation or command processing.
  • Parameters:
    • id: The Unity Instance ID of the GameObject.
    • gameObject: The GameObject to register.
  • Returns: void

UnityAdapter.UnregisterGameObject

public static void UnregisterGameObject(int id)
  • Description: Unregisters a GameObject from the internal lookup, typically called when a GameObject is destroyed.
  • Parameters:
    • id: The Unity Instance ID of the GameObject to unregister.
  • Returns: void

UnityAdapter.GetGameObjectById

public static GameObject GetGameObjectById(int id)
  • Description: Retrieves a registered GameObject by its instance ID.
  • Parameters:
    • id: The Unity Instance ID of the GameObject.
  • Returns: The GameObject if found, otherwise null.

UnityAdapter.AddAgent

public static int AddAgent(Vector3 initialPos, Quaternion initialRot, int initialGoal, int initialState)
  • Description: Adds a new agent to the C++ simulation. This is a convenience wrapper around the native AddAgent function, automatically using the active AgentContainer handle.
  • Parameters:
    • initialPos: The initial position of the agent in world coordinates.
    • initialRot: The initial rotation of the agent.
    • initialGoal: The initial goal ID for the agent (from Goal enum).
    • initialState: The initial state ID for the agent (from AgentState enum).
  • Returns: The unique ID of the newly added agent, or -1 on failure.

UnityAdapter.RemoveAgent

public static void RemoveAgent(int agentId)
  • Description: Removes an agent from the C++ simulation. This is a convenience wrapper around the native RemoveAgent function.
  • Parameters:
    • agentId: The ID of the agent to be removed.
  • Returns: void

UnityAdapter.GetAgentCount

public static int GetAgentCount()
  • Description: Retrieves the current number of active agents in the C++ simulation. This is a convenience wrapper around the native GetAgentCount function.
  • Returns: The number of active agents.

UnityAdapter.GetAgentPositions

public static void GetAgentPositions([Out] Vector3[] positions, ref int count)
  • Description: Populates an array with the current positions of all active agents from the C++ simulation. This is a convenience wrapper around the native GetAgentPositions function.
  • Parameters:
    • positions: A pre-allocated array of Vector3 structs where agent positions will be written.
    • count: On input, specifies the maximum capacity of the positions array; on output, will be updated with the actual number of positions written.
  • Returns: void

UnityAdapter.GetAgentFSMStates

public static void GetAgentFSMStates([Out] int[] states, ref int count)
  • Description: Populates an array with the current FSM states of all active agents from the C++ simulation. This is a convenience wrapper around the native GetAgentFSMStates function.
  • Parameters:
    • states: A pre-allocated array of integers where agent FSM states will be written.
    • count: On input, specifies the maximum capacity of the states array; on output, will be updated with the actual number of states written.
  • Returns: void

UnityAdapter.GetAgentDataWrapper

public static AgentDisplayData[] GetAgentDataWrapper()
  • Description: Retrieves detailed debug data for all active agents, including ID, LOD tier, current goal, FSM state, target position, and current action name. It marshals the string data from C++ for easier consumption in C#.
  • Returns: An array of AgentDisplayData structs.

UnityAdapter.Shutdown

public static void Shutdown()
  • Description: Shuts down the C++ simulation and cleans up all associated resources. This should be called when the Unity application exits or the simulation is no longer needed.
  • Returns: void

UnityAdapter.PopulateWorldSnapshot

public static WorldSnapshot PopulateWorldSnapshot()
  • Description: Collects the current world state from the Unity scene (e.g., positions of tagged GameObjects) and populates a WorldSnapshot struct. This snapshot is then passed to the C++ core for perception and simulation updates.
  • Returns: A populated WorldSnapshot struct.

UnityAdapter.StepSimulationWrapper

public static void StepSimulationWrapper(float deltaTime, Vector3 cameraPosition)
  • Description: Advances the C++ agent simulation by one step using an incremental world snapshot. It collects changes from the Unity world, passes them to the C++ core, and then processes the AgentCommands received back from the core to update agent behaviors in Unity.
  • Parameters:
    • deltaTime: The time elapsed since the last simulation step, in seconds.
    • cameraPosition: The current position of the main camera, used for LOD calculations.
  • Returns: void

UnityAdapter.GenerateTestWorldSnapshot

public static WorldSnapshot GenerateTestWorldSnapshot()
  • Description: Generates a WorldSnapshot containing dummy data for testing purposes. This can be used to provide a simulated world state to the C++ core without requiring a fully populated Unity scene.
  • Returns: A WorldSnapshot struct populated with test data.

UnityAdapter.PopulateIncrementalWorldSnapshot

public static IncrementalWorldSnapshot PopulateIncrementalWorldSnapshot()
  • Description: Populates an IncrementalWorldSnapshot by comparing the current Unity world state with the state from the previous frame. This allows for efficient transfer of only changed world data to the C++ core.
  • Returns: An IncrementalWorldSnapshot struct containing only the changes. Note that the pointers within this struct must be explicitly freed after use to prevent memory leaks (handled internally by StepSimulationWrapper).

AgentBehaviour

public class AgentBehaviour : MonoBehaviour
  • Description: A Unity MonoBehaviour script that attaches to agent GameObjects in the scene. It acts as the visual and interactive representation of an agent, receiving commands from the C++ core and updating its Unity GameObject accordingly.
  • Properties:
    • AgentId: An integer representing the unique ID of the agent in the C++ simulation. This is typically set in the Unity Inspector.

AgentBehaviour.ApplyAgentCommand

public void ApplyAgentCommand(AgentCommand command)
  • Description: Processes a single AgentCommand received from the C++ simulation. This method updates the agent's GameObject in Unity based on the command type (e.g., moves the agent, triggers an animation, or changes its visual state).
  • Parameters:
    • command: The AgentCommand to be applied.
  • Returns: void

These functions are directly exposed from the C++ core DLL for interoperability with C# (e.g., Unity).

CreateAgentContainer

AGENTSIM_API AgentContainer* CreateAgentContainer(int maxAgents, const char* goapJsonContent);
  • Description: Initializes the core agent simulation and creates an AgentContainer instance. This function sets up necessary internal structures and loads initial GOAP data.
  • Parameters:
    • maxAgents: The maximum number of agents the simulation is configured to handle.
    • goapJsonContent: A null-terminated C-style string containing the JSON data for GOAP actions and goals.
  • Returns: A pointer to the initialized AgentContainer. This handle must be passed to subsequent API calls. Returns nullptr on failure.

DestroyAgentContainer

AGENTSIM_API void DestroyAgentContainer(AgentContainer* container);
  • Description: Shuts down the agent simulation and cleans up all allocated resources associated with the provided AgentContainer.
  • Parameters:
    • container: A pointer to the AgentContainer instance to be shut down.
  • Returns: void

SetLogCallback

AGENTSIM_API void SetLogCallback(LogCallbackFn callback);
  • Description: Sets a callback function in the C++ core that will be invoked for logging messages. This allows C# to receive and process log output from the native C++ simulation.
  • Parameters:
    • callback: A function pointer (LogCallbackFn) to a C# method that matches the signature void (*LogCallbackFn)(LogLevel level, const char* message). The LogLevel enum maps to corresponding Unity log types.
  • Returns: void

SetLODThresholds

AGENTSIM_API void SetLODThresholds(AgentContainer* container, float fullSimDistance, float liteSimDistance);
  • Description: Configures the Level-of-Detail (LOD) thresholds for agent simulation. Agents within fullSimDistance will be fully simulated, and those within liteSimDistance (but outside fullSimDistance) will be lightly simulated.
  • Parameters:
    • container: A pointer to the AgentContainer instance.
    • fullSimDistance: The distance from the camera within which agents receive full simulation updates.
    • liteSimDistance: The distance from the camera within which agents receive lighter simulation updates.
  • Returns: void

GetGoalIdByName

AGENTSIM_API int GetGoalIdByName(AgentContainer* container, const char* goalName);
  • Description: Retrieves the integer ID associated with a GOAP goal given its string name. This allows C# to reference goals by a stable ID.
  • Parameters:
    • container: A pointer to the AgentContainer instance.
    • goalName: A null-terminated C-style string representing the name of the goal.
  • Returns: The integer ID of the goal, or -1 if the goal name is not found.

SetVerboseMode

AGENTSIM_API void SetVerboseMode(bool enabled);
  • Description: Enables or disables verbose logging within the C++ core. When enabled, more detailed debug information will be output via the registered log callback.
  • Parameters:
    • enabled: A boolean value; true to enable verbose mode, false to disable.
  • Returns: void

AddAgent

AGENTSIM_API int AddAgent(AgentContainer* container, Vector3 initialPos, Quaternion initialRot, int initialGoal, int initialState);
  • Description: Adds a new agent to the simulation with specified initial properties.
  • Parameters:
    • container: A pointer to the AgentContainer instance.
    • initialPos: The initial position of the agent in world coordinates.
    • initialRot: The initial rotation of the agent.
    • initialGoal: The initial goal ID for the agent (mapped to Goal enum or its equivalent).
    • initialState: The initial state ID for the agent (mapped to AgentState enum).
  • Returns: The unique ID of the newly added agent, or -1 on failure.

Update

AGENTSIM_API void Update(AgentContainer* container, float deltaTime, const Vector3& cameraPosition, const WorldSnapshot* snapshot, AgentCommand* agentCommands, int* commandCount, int maxCommandCapacity);
  • Description: Advances the agent simulation by one step using a full WorldSnapshot. This is the main update function called each frame from the engine. It processes the current world state, updates agents, and generates commands for the engine.
  • Parameters:
    • container: A pointer to the AgentContainer instance.
    • deltaTime: The time elapsed since the last simulation step, in seconds.
    • cameraPosition: The current position of the main camera in the engine, used for Level-of-Detail (LOD) calculations.
    • snapshot: A pointer to a WorldSnapshot struct containing the current full state of the game world (objects, events, etc.).
    • agentCommands: An array of AgentCommand structs pre-allocated by C# to receive commands from the C++ core.
    • commandCount: A pointer to an integer that will be updated by the C++ core to indicate the number of AgentCommands written to the agentCommands array.
    • maxCommandCapacity: The maximum number of AgentCommands that the agentCommands array can hold.
  • Returns: void

StepSimulationIncremental

AGENTSIM_API void StepSimulationIncremental(AgentContainer* container, float deltaTime, const IncrementalWorldSnapshot* incrementalSnapshot, AgentCommand* agentCommands, int* commandCount, int maxCommandCapacity, const Vector3& cameraPosition);
  • Description: Advances the agent simulation by one step using an IncrementalWorldSnapshot. This function is an optimized alternative to Update when only a subset of world data has changed.
  • Parameters:
    • container: A pointer to the AgentContainer instance.
    • deltaTime: The time elapsed since the last simulation step, in seconds.
    • incrementalSnapshot: A pointer to an IncrementalWorldSnapshot struct containing only the changes to the world state.
    • agentCommands: An array of AgentCommand structs pre-allocated by C# to receive commands from the C++ core.
    • commandCount: A pointer to an integer that will be updated by the C++ core to indicate the number of AgentCommands written to the agentCommands array.
    • maxCommandCapacity: The maximum number of AgentCommands that the agentCommands array can hold.
    • cameraPosition: The current position of the main camera in the engine, used for Level-of-Detail (LOD) calculations.
  • Returns: void

GetLastSimulationTimings

AGENTSIM_API void GetLastSimulationTimings(AgentContainer* container, SimulationStageTimings* outTimings);
  • Description: Retrieves the performance timings for the various stages of the last simulation update.
  • Parameters:
    • container: A pointer to the AgentContainer instance.
    • outTimings: A pointer to a SimulationStageTimings struct that will be populated with the timing data.
  • Returns: void