FV Embodied Agent

A generic, un-opinionated 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.

Overview

fv_embodied_agent is a core framework that enables programmatic control of character entities in Factorio. It provides a complete agent lifecycle, action system, and remote interface for external control via RCON or other remote interfaces. The mod is designed to be generic and reusable—it makes no assumptions about snapshot systems, file I/O, or external databases.

Core Features

Agent Class & Lifecycle

• Agent Creation & Management: Create, destroy, 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 metatable registration
• Custom Events: Raises events for agent creation, removal, and chunk charting

Action System

The mod provides a comprehensive action system organized into categories:

Async Actions (Return immediately, completion via UDP)

• Movement: walk_to() - Pathfinding-based movement with obstacle avoidance
• Mining: mine_resource() - Mine resources (ores, trees, rocks) with incremental or deplete modes
• Crafting: craft_enqueue() - Queue hand-crafting recipes

Synchronous Actions (Complete immediately)

• Entity Operations:
• place_entity() - Place entities in the world
• set_entity_recipe() - Configure machine recipes
• set_entity_filter() - Set inventory filters
• set_inventory_limit() - Configure inventory limits
• get_inventory_item() / set_inventory_item() - Manage entity inventories
• pickup_entity() - Pick up entities from the world
• Research: enqueue_research(), cancel_current_research()
• Charting: chart_view() - Chart chunks within agent's view

Query Methods

• inspect() - Get agent state and position
• get_reachable_entities() - Find entities within reach
• get_placement_cues() - Get placement hints for entities
• get_recipes() - Query available recipes
• get_technologies() - Query research technologies

State Machines

Built-in state machines track agent activities:

• Walking State Machine: Tracks pathfinding progress, waypoint completion, and arrival
• Mining State Machine: Tracks mining progress, entity depletion, and item collection
• Crafting State Machine: Tracks queued recipes and completion status

All state machines run on every tick and send UDP notifications for action lifecycle events (queued, progress, completed, cancelled).

Remote Interface System

• Per-Agent Interfaces: Each agent gets its own remote interface (agent_1, agent_2, etc.)
• Admin Interface: Global agent interface for agent lifecycle management
• Schema Export: Full method schemas with parameter validation for Python bindings and LLM documentation
• Parameter Validation: Automatic parameter normalization and validation using ParamSpec

Event System

• Custom Events: on_agent_created, on_agent_removed, on_chunk_charted
• UDP Notifications: Action lifecycle events sent via UDP for external systems
• 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
• mining.lua - Resource mining
• crafting.lua - Hand-crafting
• placement.lua - Entity placement
• entity_ops.lua - Entity manipulation
• charting.lua - Map charting
• researching.lua - Technology research
• reachability.lua - Entity reachability queries
• RemoteInterface.lua - Remote interface registration

Use Cases

• AI Agents: Control AI agents that interact with the Factorio world
• Automation Scripts: Programmatic automation of game actions
• Research & Development: Framework for testing agent behaviors
• Multi-Agent Systems: Coordinate multiple agents working together
• External Control: Control agents from external systems via RCON

Integration

• Standalone: Can be used independently for agent control
• Extensible: Designed to work with snapshot/sync mods (see fv_snapshot)
• No Dependencies: Only requires base Factorio (no other mods required)

Technical Details

• Factorio Version: 2.0+
• Language: Lua
• UDP Port: 34202 (for action lifecycle notifications)
• State Persistence: Uses Factorio's metatable registration system
• Hot Reload Support: Agent instances persist across mod reloads

Example Usage

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

-- Control agent_1
remote.call("agent_1", "walk_to", {x = 100, y = 200})
remote.call("agent_1", "mine_resource", "iron-ore", 50)
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")

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.