Running Schola

Schola V2 uses a protocol-simulator architecture to interact with Unreal Engine. It supports both creating a standalone instance of Unreal Engine running as a child process of your Python script, or connecting to a running Unreal Engine process. The architecture separates:

Protocols (BaseRLProtocol) - Handle communication with Unreal Engine
Simulators (BaseSimulator) - Manage the Unreal Engine process lifecycle

Launch An Unreal Environment From Python

Schola supports running environments entirely from Python using the UnrealExecutable simulator combined with a communication protocol like gRPCProtocol.

from schola.core.protocols.protobuf.gRPC import gRPCProtocol
from schola.core.simulators.unreal import UnrealExecutable

# Define the communication protocol
protocol = gRPCProtocol(
    url="localhost",  # Connect to the engine over localhost
    port=50051,  # Port for gRPC communication (default: 50051)
)

# Define the simulator to manage the Unreal Engine executable
simulator = UnrealExecutable(
    executable_path="Path/To/Your/Game.exe",  # Path to your packaged game binary
    headless_mode=True,  # Skip rendering (faster training)
    display_logs=True,  # Show Unreal Engine logs in terminal
    map=None,  # Use default map, or specify "/Game/&lt;MapName&gt;"
    set_fps=60,  # Fixed framerate for deterministic training
    disable_script=True,  # Ignore RunScriptOnLaunch setting
)

Initialize the Standalone Environment

from schola.core.protocols.protobuf.gRPC import gRPCProtocol
from schola.core.simulators.unreal import UnrealExecutable
from schola.gym import GymVectorEnv

# Setup protocol and simulator
protocol = gRPCProtocol(url="localhost", port=50051)
simulator = UnrealExecutable(
    executable_path="Path/To/Your/Game.exe",
    headless_mode=True
)

# Create vectorized Gymnasium environment
env = GymVectorEnv(simulator=simulator, protocol=protocol)

# Use the environment
obs, info = env.reset()
actions = env.action_space.sample()
obs, rewards, terminated, truncated, info = env.step(actions)

from schola.core.protocols.protobuf.gRPC import gRPCProtocol
from schola.core.simulators.unreal import UnrealExecutable
from schola.rllib import RayEnv, RayVecEnv

# Setup protocol and simulator
protocol = gRPCProtocol(url="localhost", port=50051)
simulator = UnrealExecutable(
    executable_path="Path/To/Your/Game.exe",
    headless_mode=True
)

# For single environment (local runner)
env = RayEnv(protocol=protocol, simulator=simulator)

# For multiple parallel environments (distributed training)
# env = RayVecEnv(protocol=protocol, simulator=simulator)

# Use the environment
obs, info = env.reset()
actions = {agent_id: env.action_space.sample() for agent_id in env.get_agent_ids()}
obs, rewards, terminated, truncated, info = env.step(actions)

from schola.core.protocols.protobuf.gRPC import gRPCProtocol
from schola.core.simulators.unreal import UnrealExecutable
from schola.sb3 import VecEnv

# Setup protocol and simulator
protocol = gRPCProtocol(url="localhost", port=50051)
simulator = UnrealExecutable(
    executable_path="Path/To/Your/Game.exe",
    headless_mode=True
)

# Create vectorized environment for SB3
env = VecEnv(simulator=simulator, protocol=protocol)

# Use with SB3 algorithms
from stable_baselines3 import PPO
model = PPO("MultiInputPolicy", env, verbose=1)
model.learn(total_timesteps=10000)

Connect To a Running Unreal Environment

Schola supports connecting to an already running Editor or Game, for debugging and Unreal Engine driven workflows using the UnrealEditor simulator.

from schola.core.protocols.protobuf.gRPC import gRPCProtocol
from schola.core.simulators.unreal import UnrealEditor

# Define the communication protocol
protocol = gRPCProtocol(
    url="localhost",  # Connect to the engine over localhost
    port=50051,  # Must match the port in your Unreal Engine Schola Plugin Settings
)

# Define the simulator (no process management needed for editor)
simulator = UnrealEditor()

Initialize the Editor Environment

from schola.core.protocols.protobuf.gRPC import gRPCProtocol
from schola.core.simulators.unreal import UnrealEditor
from schola.gym import GymVectorEnv

# Setup protocol and simulator
protocol = gRPCProtocol(url="localhost", port=50051)
simulator = UnrealEditor()

# Create vectorized Gymnasium environment
env = GymVectorEnv(simulator=simulator, protocol=protocol)

# Use the environment
obs, info = env.reset()
actions = env.action_space.sample()
obs, rewards, terminated, truncated, info = env.step(actions)

from schola.core.protocols.protobuf.gRPC import gRPCProtocol
from schola.core.simulators.unreal import UnrealEditor
from schola.rllib import RayEnv

# Setup protocol and simulator
protocol = gRPCProtocol(url="localhost", port=50051)
simulator = UnrealEditor()

# Create Ray environment
env = RayEnv(protocol=protocol, simulator=simulator)

# Use the environment
obs, info = env.reset()
actions = {agent_id: env.action_space.sample() for agent_id in env.get_agent_ids()}
obs, rewards, terminated, truncated, info = env.step(actions)

from schola.core.protocols.protobuf.gRPC import gRPCProtocol
from schola.core.simulators.unreal import UnrealEditor
from schola.sb3 import VecEnv

# Setup protocol and simulator
protocol = gRPCProtocol(url="localhost", port=50051)
simulator = UnrealEditor()

# Create vectorized environment for SB3
env = VecEnv(simulator=simulator, protocol=protocol)

# Use with SB3 algorithms
from stable_baselines3 import PPO
model = PPO("MultiInputPolicy", env, verbose=1)
model.learn(total_timesteps=10000)