FV Embodied Agent

A framework for programmatic control of embodied character agents in Factorio. Provides a complete agent system with actions, state machines, and remote interfaces for external control via RCON.

Overview

fv_embodied_agent enables programmatic control of character entities in Factorio. It provides agent lifecycle management, an action system, and a remote interface for external control. The mod is generic and reusable—it makes no assumptions about snapshot systems, file I/O, or external databases.

Core Features

Agent Lifecycle

• Multi-Agent Support: Create and manage multiple agents with unique IDs
• Force Management: Each agent can have its own force or share a common force
• Persistent State: Agent instances persist across saves using Factorio's metatable registration
• Hot Reload Support: Agents survive mod reloads without losing state
• Custom Events: Raises events for agent creation, removal, and chunk charting

Action System

The mod provides a comprehensive action system organized into async and sync operations:

Async Actions (Return immediately, completion via UDP)

• Movement: walk_to(goal, strict_goal?, options?) - Pathfinding-based movement with obstacle avoidance. Automatically adjusts goals if target position is inside an entity.
• Mining: mine_resource(resource_name, max_count?) - Mine resources (ores, trees, rocks). Use max_count for incremental mining, or omit to deplete the resource completely.
• Crafting: craft_enqueue(recipe_name, count?) - Queue hand-crafting recipes. Agent crafts automatically when ingredients are available.

Synchronous Actions (Complete immediately)

• Entity Placement: place_entity(entity_name, position, options?) - Place entities in the world with automatic placement validation
• Machine Configuration:
• set_entity_recipe(entity_name, position?, recipe_name?) - Configure machine recipes (assemblers, furnaces, chemical plants)
• set_entity_filter(entity_name, position?, inventory_type, filter_index?, filter_item?) - Set inventory filters on inserters and containers
• set_inventory_limit(entity_name, position?, inventory_type, limit) - Configure inventory slot limits
• Inventory Management:
• get_inventory_item(entity_name, position?, inventory_type, item_name, count) - Extract items from entity inventories
• set_inventory_item(entity_name, position?, inventory_type, item_name, count) - Insert items into entity inventories
• Entity Pickup: pickup_entity(entity_name, position?) - Pick up entities from the world into agent inventory
• Research: enqueue_research(technology_name), cancel_current_research() - Manage technology research
• Charting: chart_view(rechart?) - Chart chunks within agent's view for map exploration

Query Methods

• inspect(attach_state?) - Get agent state, position, and optionally detailed activity state (walking, mining, crafting)
• get_reachable() - Find all entities and resources within reach, with full entity data (recipes, inventory contents, fuel, etc.)
• get_placement_cues(entity_name) - Get placement hints and requirements for entities
• get_recipes() - Query available recipes for the agent's force
• get_technologies(only_available?) - Query research technologies

State Machines

Built-in state machines track agent activities and run on every tick:

• Walking State Machine: Tracks pathfinding progress, waypoint completion, and arrival. Sends UDP notifications for pathfinding start, progress updates, and completion.
• Mining State Machine: Tracks mining progress, entity depletion, and item collection. Handles both incremental and deplete modes, with special handling for stochastic resources (like huge-rock).
• Crafting State Machine: Tracks queued recipes and completion status. Monitors agent's crafting queue and sends completion notifications.

All state machines send UDP notifications for action lifecycle events (queued, progress, completed, cancelled) to enable external systems to track agent activities.

Remote Interface System

• Per-Agent Interfaces: Each agent gets its own remote interface (agent_1, agent_2, etc.) for direct control
• Admin Interface: Global agent interface for agent lifecycle management (create, destroy, list agents)
• Schema Export: Full method schemas with parameter validation for external bindings and documentation
• Parameter Validation: Automatic parameter normalization and validation using ParamSpec system
• Type Safety: Position, entity name, recipe, and inventory type validation

Event System

• Custom Events: on_agent_created, on_agent_removed, on_chunk_charted - Subscribe to agent lifecycle events
• UDP Notifications: Action lifecycle events sent via UDP for external systems (action queued, progress, completed, cancelled)
• Message Queue: Agents enqueue messages that are processed by game state on each tick

Architecture

The mod is organized into modular action categories:

• walking.lua - Movement and pathfinding with obstacle avoidance
• mining.lua - Resource mining with incremental and deplete modes
• crafting.lua - Hand-crafting queue management
• placement.lua - Entity placement with validation
• entity_ops.lua - Entity manipulation (recipes, filters, inventory)
• charting.lua - Map charting and exploration
• researching.lua - Technology research management
• reachability.lua - Entity reachability queries with rich data serialization
• RemoteInterface.lua - Remote interface registration and schema export

Use Cases

• AI Agents: Control AI agents that interact with the Factorio world programmatically
• Automation Scripts: Write scripts to automate complex game actions
• Research & Development: Framework for testing agent behaviors and game mechanics
• Multi-Agent Systems: Coordinate multiple agents working together on complex tasks
• External Control: Control agents from external systems via RCON (any language that supports RCON)
• LLM Integration: Use with language models to create intelligent agents that can play Factorio

Integration

• Standalone: Can be used independently for agent control without any dependencies
• Extensible: Designed to work with snapshot/sync mods (see companion mod fv_snapshot for game state synchronization)
• No Dependencies: Only requires base Factorio (no other mods required)
• RCON Compatible: Works with any RCON client to control agents remotely

Technical Details

• Factorio Version: 2.0+
• Language: Lua
• UDP Port: 34202 (default, configurable per-agent for action lifecycle notifications)
• State Persistence: Uses Factorio's metatable registration system for save/load
• Hot Reload Support: Agent instances persist across mod reloads

Example Usage

Basic Agent Control (Lua/RCON)

-- Create an agent
remote.call("agent", "create_agents", 1)

-- Control agent_1 via remote interface
local result = remote.call("agent_1", "walk_to", {x = 100, y = 200})
-- Returns: {queued = true, action_id = "walk_abc123"}
-- Completion sent via UDP when agent arrives

-- Mine resources (incremental: mine 50 iron ore)
remote.call("agent_1", "mine_resource", "iron-ore", 50)

-- Place and configure a machine
remote.call("agent_1", "place_entity", "assembling-machine-1", {x = 105, y = 205})
remote.call("agent_1", "set_entity_recipe", "assembling-machine-1", {x = 105, y = 205}, "iron-gear-wheel")

-- Query reachable entities
local reachable = remote.call("agent_1", "get_reachable")
-- Returns: {entities = {...}, resources = {...}} with full entity data

-- Inspect agent state
local state = remote.call("agent_1", "inspect", true)
-- Returns: {agent_id = 1, position = {x, y}, state = {walking = {...}, mining = {...}, crafting = {...}}}

Multi-Agent Coordination

-- Create multiple agents
remote.call("agent", "create_agents", 3)

-- Agent 1: Mine iron ore
remote.call("agent_1", "walk_to", {x = 50, y = 50})
remote.call("agent_1", "mine_resource", "iron-ore", 100)

-- Agent 2: Mine copper ore
remote.call("agent_2", "walk_to", {x = -50, y = 50})
remote.call("agent_2", "mine_resource", "copper-ore", 100)

-- Agent 3: Craft items from collected resources
remote.call("agent_3", "craft_enqueue", "iron-gear-wheel", 20)

Advanced Entity Management

-- Set up an assembly line
remote.call("agent_1", "place_entity", "assembling-machine-1", {x = 10, y = 10})
remote.call("agent_1", "set_entity_recipe", "assembling-machine-1", {x = 10, y = 10}, "iron-gear-wheel")

-- Configure inserter filters
remote.call("agent_1", "set_entity_filter", "fast-inserter", {x = 12, y = 10}, "inserter_stack_filter", 1, "iron-plate")

-- Manage inventory
remote.call("agent_1", "set_inventory_item", "assembling-machine-1", {x = 10, y = 10}, "assembling_machine_input", "iron-plate", 100)
local items = remote.call("agent_1", "get_inventory_item", "assembling-machine-1", {x = 10, y = 10}, "assembling_machine_output", "iron-gear-wheel", 50)

License

See repository for license information.

Note: This mod provides the core agent framework. For game state synchronization, file I/O, and database integration, see the companion mod fv_snapshot.