Module Components

AIAgent (Class)

Location: AIAgentModule/AIAgent.lua Represents the core AI agent class, responsible for binding AI functionality to an NPC model.

Constructor

AIAgent.new(getGameState: () -> table, npcModel: Model, personalityId: string, executableCommands: table)

Creates a new instance of an AI agent with the specified parameters.

Parameters

• getGameState: A function that returns the current game state as a table. The actual AiAgent will use the data that this provides in order to make its decisions.

• npcModel: The in-game NPC model the AI agent is attached to, turning it into a "smart NPC".

• personalityId: The identifier for the AI agent, and by extension its personality.

• executableCommands: A table containing available commands the AI agent can execute in-game, including contextual rules, such as needed parameters, for each command.

Internal Properties

• agentId (string): A unique in-game identifier for the AIAgent object instance, generated using HttpService:GenerateGUID().

• npcModel (Model): The reference to the NPC model associated with this AI agent object.

• getGameState (function): Stores the game state function for internal use.

• personalityId (string): Stores the personality ID used to contextualize the agent’s behavior.

• isRunningBehavior (boolean): Tracks whether the agent is currently running a continuous behavior loop.

Functions

• StartContinuousBehavior(behaviorModule: ModuleScript, frequency: number) Starts a custom behavior loop using a ModuleScript provided by the developer, executed at intervals using the specified frequency (in seconds).

• SendApiRequest(method: string, endpoint: string, body: table, headers: table?) Sends an HTTP request to an external API. Acts as a wrapper for HTTP communication.

• SendChatMessageToAgent(player: Player, message: string, extraBodyData: table?) Sends a chat message from a player to the API for generating a contextual response.

• SendQueryToAgent(requestBody: table) Sends a custom query payload directly to the API. This may return a message or a command.

---

AIAgentManager (Manager)

Location: AIAgentModule/AIAgentManager.lua Handles the creation, management, and retrieval of AI agent instances.

Fields

• aiAgents: A list containing all active AI agents.

• agentToNpcTable: A mapping between NPC models and their associated AI agents.

Functions

• AIAgentManager:CreateAgent(getGameState, npcModel, personalityId, executableCommands, continuousBehaviorScripts, frequency) Creates and initializes a new AI agent, optionally assigning continuous behavior scripts.

• AIAgentManager:GetAiAgentFromNpc(npcModel: Model) Returns the AI agent associated with the specified NPC model.

• AIAgentManager:GetAiAgentFromNpcName(npcName: string) Returns an AI agent by its NPC’s model name.

• AIAgentManager:GetAiAgentFromId(id: string) Returns an AI agent using its unique agent ID.

---

AICommandMap (Commands)

Location: AIAgentModule/AICommandMap.lua Defines a set of commands that can be executed by the AI agent upon receiving a specific instruction.

Built-in Commands

• MoveTo: Moves the NPC to a specific position.

• MoveToPosition: Uses pathfinding to move the NPC to a target position.

• MoveToTarget: Moves the NPC to the location of a specified model or object.

• FollowTarget: Causes the NPC to continuously follow a designated target (e.g., a player).

Each command performs parameter validation and utilizes core components of the NPC model, such as Humanoid and HumanoidRootPart, to execute actions effectively.

---

AIConfigurations (Config)

Location: AIAgentModule/AIConfigurations.lua

Defines the list of configurable data for the AI Agent Module

Sample Content:

local Config = {} Config.URL = "https://api.ready-gamer.sovrun.org" return Config