Flayer Function Attribute

The Flayer Function attribute system provides a clean, declarative way to expose game functionality to AI agents. It handles the registration, validation, and execution of functions that can be called remotely by AI agents.

How it works

Any function marked with the [FlayerFunction] attribute that is part of the global assembly gets automatically registered as a command handler in the network client. When the SDK receives a dynamic packet, it matches it with these registered handlers and calls the appropriate flayer function with the received arguments.

The function signature must follow specific requirements to avoid validation errors. All flayer functions must include a PacketLogger as their final parameter, which enables sending logs back to the AI. For other parameters and return types, only primitive types are supported to ensure reliable serialization and deserialization across the network boundary.

The flayer attribute includes metadata that helps AI agents better understand and utilize the functions. This metadata includes essential information like the function’s description and optional elements such as the hint key, which controls when the function becomes available to AI agents. This metadata-driven approach enables AI agents to make more informed decisions about when and how to use each function.

Attribute Parameters

The attribute takes two parameters:

1. name (required): The name the function will be registered under
2. description (required): A description of what the function does for the AI
3. hintKey (optional): The hint key decides WHEN the function is exposed to the AI
4. exposed (optional, default=true): Indicates if the function is exposed to the AI (only if hint key matches)
5. yieldReturnType (required for IEnumerator): Shows what is expected to get yielded from a coroutine
6. volatileFunction (optional): Boolean indicating if the function can be overridden
   • true: Function can be overridden by non-volatile implementations
   • false (default): Function cannot be overridden

Key Features

• Automatic Registration: Functions are discovered and registered at runtime
• Thread Safety: Always executed on Unity’s main thread
• Signature Validation: Ensures functions have the correct parameter types and return values
• Volatile Support: Allows for overriding default implementations
• Error Handling: Built-in error catching and propagation
• Timeout Protection: Automatic timeout after 120 seconds

Best Practices

• Always Validate Arguments: Check argument count and types before processing
• Use the Logger: Send meaningful messages to the AI!
• Use Coroutines for Long Operations: Anything that takes multiple frames

Examples

Simple Action (Single Frame)

[FlayerFunction("open_inventory", "opens the character's inventory")]
public static bool HandleOpenInventory(PacketLogger logger)
{
    if (!inventory.CanOpen)
    {
        logger.Log("Cannot open inventory right now", sendToAI: true);
        return false;
    }
 
    // Do short actions that complete in 1 frame
    inventory.Open();
    return true;
}

Complex Action (Multiple Frames)

[FlayerFunction("move_to", "moves to the specified location", yieldReturnType: typeof(bool))]
public static IEnumerator HandleMoveTo(float x, float y, float z, PacketLogger logger)
{
    Vector3 targetPos = new Vector3(args[0], args[1], args[2]);
 
    // Log the action
    logger.Log($"Moving to position {targetPos}", sendToAI: true);
 
    // Run multi-frame operations
    yield return MovementSystem.NavigateTo(targetPos);
 
    // Can yield to other coroutines
    yield return WaitForAnimation();
 
    // Return success
    yield return true;
}

Overriding Core Functions

// Override the default screenshot function
[FlayerFunction("screenshot", "returns a screenshot", volatileFunction: false)]
public static bytes HandleCustomScreenshot(PacketLogger logger)
{
    // Your custom screenshot implementation
    var bytes = CustomScreenshotTool.Capture();
 
    var modifiedBytes = ...
 
    return modifiedBytes;
}