Project Structure

This page provides an overview of the FLE codebase organization.

Directory Layout

factorio-learning-environment/
├── .github/                        # GitHub workflows and CI/CD
├── .fle/                           # Runtime data (saves, scenarios, trajectory logs)
├── docs/                           # Documentation and website
├── examples/                       # Example agent implementations
├── fle/                            # Main codebase
│   ├── agents/                     # Agent implementations
│   ├── cluster/                    # Docker orchestration and scenarios
│   ├── commons/                    # Shared utilities and models
│   ├── configs/                    # Configuration files
│   ├── data/                       # Data files and replays
│   ├── env/                        # Core environment
│   ├── eval/                       # Evaluation framework
│   ├── run.py                      # CLI entry point
│   └── server.py                   # RCON server
├── tests/                          # Test suite
├── .example.env                    # Environment variables template
├── BUILD.md                        # Build instructions
├── CONTRIBUTING.md                 # Contribution guidelines
├── pyproject.toml                  # Python project config
└── uv.lock                         # Dependency lock file

Core Directories

fle/agents/

Agent implementations including:

  • BasicAgent: Simple text-based agent

  • VisualAgent: Vision-enabled agent

  • MultiAgent: Multi-agent coordination

  • Base classes and interfaces

Key Files:

  • agent_abc.py: Abstract base class for agents

  • models.py: Agent configuration models

fle/cluster/

Docker orchestration and scenario management:

  • Factorio server containers

  • Docker Compose configurations

  • Scenario definitions

  • Server management utilities

Key Files:

  • docker-compose.yml: Container orchestration

  • scenarios/: Pre-built game scenarios

fle/commons/

Shared utilities and models used across the codebase:

  • Data models (Position, Entity, Inventory, etc.)

  • Utility functions

  • Constants and enumerations

  • Database client interface

Key Files:

  • models.py: Core data models

  • db_client.py: Database abstraction layer

  • utils.py: Helper functions

fle/env/

Core environment implementation:

env/
├── gym_env/                # OpenAI Gym interface
│   ├── action.py           # Action definitions
│   ├── observation.py      # Observation space
│   ├── registry.py         # Environment registry
│   └── gym_env.py          # Main gym environment
├── tools/                  # Agent-accessible tools
│   ├── agent/              # Agent tools
│   └── admin/              # Admin tools
├── protocols/              # Communication protocols
│   ├── _mcp/               # Model Context Protocol
│   └── a2a/                # Agent-to-Agent protocol
├── exceptions/             # Custom exceptions
├── entities.py             # Entity definitions
├── instance.py             # Game instance management
└── namespace.py            # Python namespace management

Key Components:

  • gym_env/: Standard gym interface for RL frameworks

  • tools/: All agent-callable functions

  • protocols/: Communication layer implementations

  • exceptions/: Typed exceptions for error handling

fle/eval/

Evaluation framework for running experiments:

eval/
├── algorithms/             # Search algorithms
│   ├── beam_search.py      # Beam search implementation
│   ├── mcts.py             # Monte Carlo Tree Search
│   └── independent.py      # Independent evaluation
├── analysis/               # Analysis tools
├── tasks/                  # Task definitions
│   └── task_definitions/   # JSON task configs
│       ├── lab_play/       # Structured tasks
│       └── open_play/      # Open-ended tasks
├── infra/                  # Infrastructure
│   ├── setup_api_keys.py   # API key configuration
│   └── cluster_manager.py  # Cluster management
└── evaluator.py            # Main evaluation logic

Key Files:

  • evaluator.py: Runs agent evaluations

  • tasks/task_definitions/: Task configurations

  • algorithms/: Search and optimization algorithms

tests/

Comprehensive test suite:

tests/
├── actions/                # Tool tests
├── benchmarks/             # Performance benchmarks
├── functional/             # End-to-end tests
├── gym_env/                # Gym interface tests
└── integration/            # Integration tests

Configuration Files

pyproject.toml

Python project configuration:

  • Package metadata

  • Dependencies

  • Optional feature groups ([eval], [mcp], [psql])

  • Build system configuration

.env

Environment variables (created from .example.env):

  • API keys (OpenAI, Anthropic, etc.)

  • Database configuration

  • Cluster settings

  • Feature flags

Key Modules

fle/run.py

CLI entry point providing commands:

  • fle cluster start: Start Factorio cluster

  • fle eval: Run evaluations

  • fle sprites: Manage sprites

  • fle init: Initialize configuration

fle/server.py

RCON server for communicating with Factorio instances:

  • Handles tool invocations

  • Manages game state

  • Executes Lua commands

fle/env/instance.py

Manages individual Factorio game instances:

  • Instance lifecycle

  • State management

  • Connection handling

  • Resource cleanup

fle/env/namespace.py

Python namespace management for agent code:

  • Variable storage

  • Function definitions

  • Class definitions

  • Namespace isolation

Data Flow

Agent
  │
  ├─> Synthesizes Python Code
  │
  ▼
Environment (gym_env)
  │
  ├─> Interprets Code
  │
  ├─> Executes Tools (client.py)
  │       │
  │       ├─> Calls server.py (RCON)
  │       │       │
  │       │       ├─> Executes server.lua
  │       │       │       │
  │       │       │       └─> Factorio Engine
  │       │       │
  │       │       └─> Returns Results
  │       │
  │       └─> Returns Typed Objects
  │
  ├─> Updates Namespace
  │
  └─> Returns Observation
        │
        └─> Agent

Important Files

Core Environment

  • fle/env/gym_env/gym_env.py: Main gym environment

  • fle/env/instance.py: Game instance management

  • fle/env/namespace.py: Python namespace handling

Tools System

  • fle/env/tools/tool.py: Base tool class

  • fle/env/tools/agent/**/client.py: Tool implementations

  • fle/server.py: Server-side execution

Registry & Tasks

  • fle/env/gym_env/registry.py: Environment registry

  • fle/eval/tasks/task_definitions/: Task JSON files

  • fle/eval/evaluator.py: Evaluation orchestration

Development Workflow

Adding a New Tool

  1. Create directory: fle/env/tools/agent/my_tool/

  2. Add client.py, server.lua, agent.md

  3. Create test: tests/actions/test_my_tool.py

  4. Tool is automatically discovered

Adding a New Task

  1. Create JSON file: fle/eval/tasks/task_definitions/my_task.json

  2. Task is automatically registered

  3. Access via: gym.make("my_task")

Running Tests

# Run all tests
pytest tests/

# Run specific test file
pytest tests/actions/test_place_entity.py

# Run with coverage
pytest --cov=fle tests/

Building Documentation

cd docs/sphinx && python -m sphinx -b html source build/html