EldritchLink

EldritchLink is a robust network protocol designed for secure communication between AI agents and games. It provides a framework for remote function execution, secure data transfer, and real-time communication with advanced packet handling capabilities.

Overview

EldritchLink enables:

Remote execution of Flayer functions by AI agents
Encrypted communication with SSL/TLS support
Bi-directional file transfer through SpeedLane
Real-time message logging and error reporting
Thread-safe packet handling in game engines

Connection String

Connection strings use a URI-based format for flexible configuration:


{protocol}://{host}:{port}/{connection_id}

Protocol Types

el:// - Unencrypted connection (development only)
elx:// - SSL/TLS encryption without certificate validation
els:// - SSL/TLS encryption with certificate validation

Connection Examples:


// Secure connection with certificate validation
"els://game.example.com:5000/run-abc123"
 
// SSL without certificate validation (testing)
"elx://game.example.com:5000/run-abc123"
 
// Unencrypted connection (local development)
"el://localhost:5000/run-abc123"

The connection_id (e.g., run-abc123) uniquely identifies the associated test agent/game session.

Dynamic Packets

Dynamic packets enable flexible command-response communication between the AI and game:


public class DynamicPacket : Packet
{
    public string CommandName { get; }  // e.g., "flayer_funcs", "speedlane"
    public DynamicParam[] Params { get; } // Flexible parameter array
}

Dynamic packets support various parameter types:


public enum ParamType
{
    Boolean,    // bool
    Uint8,      // byte
    Int8,       // sbyte
    Uint16,     // ushort
    Int16,      // short
    Uint32,     // uint
    Int32,      // int
    Uint64,     // ulong
    Int64,      // long
    Float32,    // float
    Float64,    // double
    String,     // string
    Binary      // byte[]
}

Flayer Function Integration

Flayer functions are automatically registered as packet handlers during runtime:

AI Agent wants to run a Flayer function

Sends DynamicPacket with function name and parameters using the EldritchLink protocol.

Game Processing

Game receives the packet, validates the function name and parameters, and executes the corresponding function handler. In case for dynamic packets, the handler is the Flayer function itself.

In the case of the Flayer function, the handler is executed on the main game thread.

Result Handling

The result of the function execution is sent back to the AI agent as a response packet. The AI agent can then process the result and take further actions based on it.

When the function throws an error, instead of a result packet, an exception packet is sent back to the AI agent. This packet contains the error message and the stack trace of the exception. The AI agent can then log this error and take appropriate actions.

Packet Logger

The Packet Logger is a powerful tool for logging messages and errors from the game to the AI agent. It provides a simple interface for sending messages back to the AI agent, giving feedback on the execution of Flayer functions and other game events.


public abstract class PacketLogger
{
    // Log with optional network transmission
    public void Log(string message, LogLevel level = LogLevel.Info,
        LogSource source = LogSource.Sdk, bool sendToAI = false)
    {
        // Local logging
        // Optional network transmission
    }
}