Defining Agent Functions

Agent Functions can be specified as CUDA functions, built at compile time when using the C++ API, or they can be specified as Run-Time Compiled (RTC) function strings when using the both the C++ and Python APIs.

An agent function is defined using the FLAMEGPU_AGENT_FUNCTION macro. This takes three arguments: a unique name identifying the function, an input message communication strategy, and an output message communication strategy. We will discuss messages in more detail later, so for now don’t worry about the second and third parameters. flamegpu::MessageNone is specified when not requiring message input or output, so this is used. Similarly, agent functions should return flamegpu::ALIVE by default, agent death is explained in a later section of this chapter.

For Non-RTC functions, when using the C++ API, the FLAMEGPU_AGENT_FUNCTION macro can be used to declare and define the agent function, which can then be associated with the AgentDescription object using the newFunction() method.

// Define an agent function called agent_fn1 - specified ahead of main function
FLAMEGPU_AGENT_FUNCTION(agent_fn1, flamegpu::MessageNone, flamegpu::MessageNone) {
    // Behaviour goes here
    return flamegpu::ALIVE;
}

int main() {
    // ...

    // Attach a function called agent_fn1, defined by the symbol agent_fn1 to the AgentDescription object agent.
    flamegpu::AgentFunctionDescription &agent_fn1_description = agent.newFunction("agent_fn1", agent_fn1);

    // ...
}

When using the Run-Time Compiled (RTC) functions, optionally in the C++ API or required by the Python API, the function must be defined in a string and associated with the AgentDescription using the newRTCFunction() method.

const char* agent_fn1_source = R"###(
// Define an agent function called agent_fn1 - specified ahead of main function
FLAMEGPU_AGENT_FUNCTION(agent_fn1, flamegpu::MessageNone, flamegpu::MessageNone) {
    // Behaviour goes here
}
)###";

int main() {
    ...

    // Attach a function called agent_fn1, defined in the string variable agent_fn1_source to the AgentDescription object agent.
    flamegpu::AgentFunctionDescription& agent_fn1_description = agent.newRTCFunction("agent_fn1", agent_fn1_source);

    ...
}

FLAME GPU Device Functions

If you wish to define regular functions which can be called from agent functions, you can use the FLAMEGPU_DEVICE_FUNCTION macro:

// Define a function for adding two integers which can be called inside agent functions.
FLAMEGPU_DEVICE_FUNCTION int add(int a, int b) {
    return a + b;
}

FLAME GPU Host Device Functions

If you wish to define regular functions which can be called from within agent and host functions, you can use the FLAMEGPU_HOST_DEVICE_FUNCTION macro:

// Define a function for subtracting two integers which can be called inside agent functions, or in host code
FLAMEGPU_HOST_DEVICE_FUNCTION int subtract(int a, int b) {
    return a - b;
}