ScholaExamples v1.2.0

Author: kurbeco

Config/DefaultEngine.ini

@@ -233,7 +233,7 @@ bUseManualIPAddress=False
 ManualIPAddress=
 
 [/Script/Schola.ScholaManagerSubsystemSettings]
-bRunScriptOnPlay=False
+bRunScriptOnPlay=True
 GymConnectorClass=/Script/CoreUObject.Class'/Script/Schola.PythonGymConnector'
 ScriptSettings=(ScriptType=Python,EnvType=Default,CondaEnvName="",CustomPythonPath=(FilePath=""),PythonScriptType=SB3,CustomPythonScriptSettings=(LaunchScript=(FilePath=""),Args=(),Flags=),CustomScriptSettings=(LaunchScript=(FilePath=""),Args=(),Flags=),SB3Settings=(Timesteps=8000,LoggingSettings=(EnvLoggingVerbosity=0,TrainerLoggingVerbosity=0,bSaveTBLogs=False,LogFreq=10,LogDir=(Path=""),CallbackVerbosity=1),CheckpointSettings=(bSaveCheckpoints=False,bSaveFinalModel=False,bSaveVecNormalize=False,bSaveReplayBuffer=False,CheckpointDir=(Path=""),SaveFreq=1000,NamePrefix="ppo"),ResumeSettings=(bLoadModel=False,ModelPath=(FilePath=""),bLoadReplayBuffer=False,ReplayBufferPath=(FilePath=""),bLoadVecNormalize=False,VecNormalizePath=(FilePath="")),NetworkArchitectureSettings=(ActivationFunction=ReLU,ValueFunctionParameters=(256,256),PolicyParameters=(256,256)),bDisplayProgressBar=True,Algorithm=PPO,PPOSettings=(LearningRate=0.000300,NSteps=2048,BatchSize=64,NEpochs=10,Gamma=0.990000,GAELambda=0.950000,ClipRange=0.200000,NormalizeAdvantage=True,EntCoef=0.000000,VFCoef=0.050000,MaxGradNorm=0.500000,UseSDE=False,SDESampleFreq=-1),SACSettings=(LearningRate=0.000300,BufferSize=1000000,LearningStarts=100,BatchSize=256,Tau=0.005000,Gamma=0.990000,TrainFreq=1,GradientSteps=1,OptimizeMemoryUsage=False,LearnEntCoef=True,InitialEntCoef=1.000000,TargetUpdateInterval=1,TargetEntropy="auto",UseSDE=False,SDESampleFreq=-1)),RLlibSettings=(Timesteps=8000,LoggingSettings=(EnvLoggingVerbosity=0,TrainerLoggingVerbosity=1),CheckpointSettings=(bSaveFinalModel=True,bExportToONNX=False,bEnableCheckpoints=False,SaveFreq=1000,CheckpointDir=(Path="")),ResumeSettings=(bLoadModel=False,ModelPath=(FilePath="")),NetworkArchitectureSettings=(ActivationFunction=ReLU,FCNetHiddens=(512,512),MinibatchSize=256),ResourceSettings=(NumCPUsPerWorker=1,NumGPUs=0,NumCPUs=1)))
 CommunicatorSettings=(Address="127.0.0.1",Port=8002)

Plugins/Schola

@@ -16,4 +16,5 @@ norecursedirs =
     __pycache__
 testpaths = 
     python/tests
-engine_path = C:/Program Files/Epic Games/UE_5.5
+engine_path = C:/Program Files/Epic Games/UE_5.5
+clean_build = false

pytest.ini

@@ -1,54 +1,6 @@
 # Copyright (c) 2025 Advanced Micro Devices, Inc. All Rights Reserved.
-import sys  
-import types  
-from gymnasium.envs.registration import register
-from ray.tune.registry import register_env
-from schola.gym.env import GymVectorEnv 
-from schola.sb3.env import VecEnv # todo: a bit slow, maybe figure out a way to delay the import upon first use
-from schola.ray.env import BaseEnv
-from .registry import envs
 
 
-# Register all environments with gym
-for env_id in envs.all():
-    register(
-        id = f"Schola/{env_id}-v0",
-        vector_entry_point = lambda env_id=env_id, **kwargs: GymVectorEnv(envs.make_unreal_connection(env_id, **kwargs)),
-        order_enforce = True,
-        disable_env_checker = False,
-        apply_api_compatibility = False
-    )
-
-
-# Register all environments with Ray
-for env_id in envs.all():
-    register_env(
-        name = f"Schola/{env_id}-v0",
-        env_creator = lambda env_id=env_id, **kwargs: BaseEnv(envs.make_unreal_connection(env_id, **kwargs)),)
-
-
-# Create a virtual module for 'gym'  
-gym = types.ModuleType('schola_examples.gym')
-# Dynamically create functions like `Basic`, `BasicVec`, `BallShooter`, etc.
-for env_id in envs.all():
-    func_name = env_id.replace('-', '')
-    setattr(gym, func_name, lambda env_id=env_id, **kwargs: GymVectorEnv(envs.make_unreal_connection(env_id, **kwargs))  )
-sys.modules['schola_examples.gym'] = gym # Add the virtual module to sys.modules
-
-
-# Create a virtual module for 'sb3'
-sb3 = types.ModuleType('schola_examples.sb3')
-# Dynamically create functions like `Basic`, `BasicVec`, `BallShooter`, etc.
-for env_id in envs.all():
-    func_name = env_id.replace('-', '')
-    setattr(sb3, func_name, lambda env_id=env_id, **kwargs: VecEnv(envs.make_unreal_connection(env_id, **kwargs))  )
-sys.modules['schola_examples.sb3'] = sb3 # Add the virtual module to sys.modules
-
-
-# Create a virtual module for 'ray'
-ray = types.ModuleType('schola_examples.ray')
-# Dynamically create functions like `Basic`, `BasicVec`, `BallShooter`, etc.
-for env_id in envs.all():
-    func_name = env_id.replace('-', '')
-    setattr(ray, func_name, lambda env_id=env_id, **kwargs: BaseEnv(envs.make_unreal_connection(env_id, **kwargs))  )
-sys.modules['schola_examples.ray'] = ray # Add the virtual module to sys.modules
+import schola_examples.gym
+import schola_examples.ray
+import schola_examples.sb3

python/schola_examples/__init__.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2025 Advanced Micro Devices, Inc. All Rights Reserved.
+
+from gymnasium import register
+from schola.gym.env import GymEnv, GymVectorEnv
+from schola_examples.registry import envs
+
+def make_gym_env(env_path):
+    class PartialGymEnv(GymEnv):
+        def __init__(self, **kwargs):
+            super().__init__(envs.make_unreal_connection(env_path, **kwargs))
+    return PartialGymEnv
+
+def make_gym_vector_env(env_path):
+    class PartialGymVectorEnv(GymVectorEnv):
+        def __init__(self, **kwargs):
+            super().__init__(envs.make_unreal_connection(env_path, **kwargs))
+    return PartialGymVectorEnv
+
+
+for env in filter(lambda x: x.gym_compat, envs.all()):
+    register(
+        id = f"Schola/{env.name}-v0",
+        entry_point= make_gym_env(env.path),
+        vector_entry_point = make_gym_vector_env(env.vec_path),
+        order_enforce = True,
+        disable_env_checker = False,
+        apply_api_compatibility = False
+    )
+
+for env in filter(lambda x: x.gym_compat, envs.all()):
+    func_name = env.name.replace('-', '')
+    globals()[func_name] = make_gym_env(env.path)
+    func_name = env.vec_name.replace('-', '')
+    globals()[func_name] = make_gym_vector_env(env.vec_path)

python/schola_examples/gym.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2025 Advanced Micro Devices, Inc. All Rights Reserved.
+
+from schola.ray.env import BaseEnv
+from .registry import envs
+from ray.tune.registry import register_env
+
+def make_ray_env(env_path):
+    class PartialRayEnv(BaseEnv):
+        def __init__(self, **kwargs):
+            super().__init__(envs.make_unreal_connection(env_path, **kwargs))
+    return PartialRayEnv
+
+for env in envs.all():
+    func_name = env.name.replace('-', '')
+    globals()[func_name] = make_ray_env(env.path)
+    func_name = env.vec_name.replace('-', '')
+    globals()[func_name] = make_ray_env(env.vec_path)
+
+# Register all environments with Ray
+for env in envs.all():
+    register_env(
+        name = f"Schola/{env.name}-v0",
+        env_creator = make_ray_env(env.path),
+        )
+    register_env(
+        name = f"Schola/{env.vec_name}-v0",
+        env_creator = make_ray_env(env.vec_path),
+        )

python/schola_examples/ray.py

@@ -1,41 +1,51 @@
 # Copyright (c) 2025 Advanced Micro Devices, Inc. All Rights Reserved.
+from typing import NamedTuple
 from schola.core.unreal_connections import StandaloneUnrealConnection
 import os  
 import platform
 
+class EnvRegistryEntry:
+    
+    def __init__(self,name,gym_compatible=True):
+        self.name = name
+        self.gym_compat = gym_compatible
+
+    @property
+    def path(self):
+        return f"/Game/Examples/{self.name}/Maps/{self.name}Train"
+
+    @property
+    def vec_path(self):
+        return f"/Game/Examples/{self.name}/Maps/{self.name}VecTrain"
+
+    @property
+    def vec_name(self):
+        return self.name + "-Vec"
+    
 class ScholaExamplesEnvRegistry:
     def __init__(self):
         self.registry = {
-            "Basic": "/Game/Examples/Basic/Maps/BasicTrain",
-            "Basic-Vec": "/Game/Examples/Basic/Maps/BasicVecTrain",
-            "3DBall": "/Game/Examples/3DBall/Maps/3DBallTrain",
-            "3DBall-Vec": "/Game/Examples/3DBall/Maps/3DBallVecTrain",
-            "BallShooter": "/Game/Examples/BallShooter/Maps/BallShooterTrain",
-            "BallShooter-Vec": "/Game/Examples/BallShooter/Maps/BallShooterVecTrain",
-            "BrickBreaker": "/Game/Examples/BrickBreaker/Maps/BrickBreakerTrain",
-            "BrickBreaker-Vec": "/Game/Examples/BrickBreaker/Maps/BrickBreakerVecTrain",
-            "MazeSolver": "/Game/Examples/MazeSolver/Maps/MazeSolverTrain",
-            "MazeSolver-Vec": "/Game/Examples/MazeSolver/Maps/MazeSolverVecTrain",
-            "Pong": "/Game/Examples/Pong/Maps/PongTrain",
-            "Pong-Vec": "/Game/Examples/Pong/Maps/PongVecTrain",
-            "RaceTrack": "/Game/Examples/RaceTrack/Maps/RaceTrackTrain",
-            "RaceTrack-Vec": "/Game/Examples/RaceTrack/Maps/RaceTrackVecTrain",
-            "Tag": "/Game/Examples/Tag/Maps/TagTrain",
-            "Tag-Vec": "/Game/Examples/Tag/Maps/TagVecTrain",
+            "Basic": EnvRegistryEntry("Basic"),
+            "3DBall": EnvRegistryEntry("3DBall"),
+            "BallShooter": EnvRegistryEntry("BallShooter"),
+            "MazeSolver": EnvRegistryEntry("MazeSolver"),
+            "Pong": EnvRegistryEntry("Pong",gym_compatible=False),
+            "RaceTrack": EnvRegistryEntry("RaceTrack"),
+            "Tag": EnvRegistryEntry("Tag",gym_compatible=False),
         }
         dir_path = os.path.dirname(os.path.realpath(__file__))
         os_name = "Windows" if platform.system() == "Windows" else "Linux"
         entry_point_filename = "ScholaExamples" + (".exe" if platform.system() == "Windows" else ".sh")
         self.built_game_path = os.path.join(dir_path, "bin", os_name, entry_point_filename)
 
-    def make_unreal_connection(self, env_id, port=None, headless_mode=False, set_fps=None, built_game_path=None, display_logs=False):  
+    def make_unreal_connection(self, path:str, port=None, headless_mode=False, set_fps=None, built_game_path=None, display_logs=False):  
         """
         Creates a new environment connection instance.
         
         Parameters
         ----------
-        env_id : str
-            The environment ID.
+        path : str
+            The Unreal Engine Path to the map to load.
         port : int, optional
             The port to connect to, if None, an open port will be found.
         headless_mode : bool, optional
@@ -57,15 +67,15 @@ def make_unreal_connection(self, env_id, port=None, headless_mode=False, set_fps
             executable_path=built_game_path if built_game_path else self.built_game_path,
             port=port,
             headless_mode=headless_mode, 
-            map=self.registry[env_id], 
+            map=path, 
             display_logs=display_logs,
             set_fps=set_fps,
             disable_script=True)
-        
-    def all(self):
+
+    def all(self) -> EnvRegistryEntry:
         """
         Returns a list of all environment IDs.
         """
-        return list(self.registry.keys())
+        return list(self.registry.values())
 
 envs = ScholaExamplesEnvRegistry()

python/schola_examples/registry.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2025 Advanced Micro Devices, Inc. All Rights Reserved.
+
+from schola.sb3.env import VecEnv
+from .registry import envs
+
+def make_sb3_env(env_path):
+    class PartialSB3Env(VecEnv):
+        def __init__(self, **kwargs):
+            super().__init__(envs.make_unreal_connection(env_path, **kwargs))
+    return PartialSB3Env
+
+# Dynamically create functions like `Basic`, `BasicVec`, `BallShooter`, etc.
+for env in envs.all():
+    func_name = env.name.replace('-', '')
+    # Add the class to this module
+    globals()[func_name] = make_sb3_env(env.path)
+    func_name = env.vec_name.replace('-', '')
+    globals()[func_name] = make_sb3_env(env.vec_path)
+

python/schola_examples/sb3.py

@@ -38,16 +38,12 @@
 # All environments that can be converted to vectorized environments, including single agent environments, or multiagent environments where all agents
 # have the same observation/action space
 # use this for SB3 and Gym as they can't handle agents with different obs/action spaces
-VEC_COMPATIBLE_EXAMPLES = list(
+GYM_VEC_COMPATIBLE_EXAMPLES = list(
     filter(lambda x: not x.has_different_agents, ALL_EXAMPLES)
 )
 
-VEC_COMPATIBLE_VEC_EXAMPLES = list(
-    filter(lambda x: not x.has_different_agents, VECTORIZED_EXAMPLES)
-)
-
-VEC_COMPATIBLE_SINGLE_ENV_EXAMPLES = list(
-    filter(lambda x: not x.has_different_agents, SINGLE_ENV_EXAMPLES)
+GYM_COMPATIBLE_EXAMPLES = list(
+    filter(lambda x: not x.has_different_agents and x.total_num_agents == 1, ALL_EXAMPLES)
 )
 
 # Can use this for testing whether asserts are triggered notifying the user that the env is unsuported

python/tests/Maps/Examples/__init__.py

@@ -1,7 +1,8 @@
-# Copyright (c) 2024 Advanced Micro Devices, Inc. All Rights Reserved.
+# Copyright (c) 2024-2025 Advanced Micro Devices, Inc. All Rights Reserved.
 
+from typing import Type, Union
 from schola.core.unreal_connections import StandaloneUnrealConnection
-from schola.gym.env import GymVectorEnv
+from schola.gym.env import GymEnv, GymVectorEnv
 import pytest
 from schola.core.spaces import DictSpace, BoxSpace, DiscreteSpace
 import numpy as np
@@ -11,14 +12,50 @@
 
 from .common import UnrealExample
 
+def make_env(build_path, example, target_class = GymEnv):
+    if isinstance(target_class,str):
+        if target_class == "GymEnv":
+            target_class = GymEnv
+        elif target_class == "GymVectorEnv":
+            target_class = GymVectorEnv
+        else:
+            raise ValueError(f"Unknown Gym Class: {target_class}. Must be a string of 'GymEnv' or 'GymVectorEnv' or the corresponding class object.")
+
+    if hasattr(schola_examples.gym, example.classname) and issubclass(getattr(schola_examples.gym, example.classname), target_class):
+        env = getattr(schola_examples.gym, example.classname)(built_game_path = build_path, headless_mode=not example.requires_rendering, display_logs=False)
+        return env
+    else:
+        unreal_connection = StandaloneUnrealConnection("localhost", build_path, headless_mode=not example.requires_rendering, display_logs=False, map = example.path)
+        env = target_class(unreal_connection=unreal_connection)
+        return env
+
 
 class AbstractTestGymExampleDefinition:
     example : UnrealExample = None # type : ignore
 
     #We use one env for the various tests here since none of them modify state
     @pytest.fixture(scope="class")
     def env(self, example_build_path_arg):
-        env = getattr(schola_examples.gym, self.example.classname)(built_game_path = example_build_path_arg, headless_mode=True, display_logs=False)
+        env = make_env(example_build_path_arg, self.example, GymEnv)
+        yield env
+        env.close()
+
+    def test_environment_action_space(self, env):
+        batched_action_space = self.example.single_action_space
+        assert env.action_space == batched_action_space, f"Action Space Mismatch. Got: {env.action_space} Expected:{batched_action_space}"
+
+    def test_environment_observation_space(self, env):
+        batched_observation_space = self.example.single_observation_space
+        assert env.observation_space == batched_observation_space, f"Observation Space Mismatch. Got: {env.observation_space} Expected:{batched_observation_space}"
+
+
+class AbstractTestVecGymExampleDefinition:
+    example : UnrealExample = None # type : ignore
+
+    #We use one env for the various tests here since none of them modify state
+    @pytest.fixture(scope="class")
+    def env(self, example_build_path_arg):
+        env = make_env(example_build_path_arg, self.example, GymVectorEnv)
         yield env
         env.close()
 
@@ -49,15 +86,17 @@ def env_sequencer(env: GymVectorEnv, episode_lengths):
             env.step(env.action_space.sample())
         env.reset()
 
+# works for both normal gym and vectorized environments
 class AbstractTestGymExample:
     example: UnrealExample = None
+    gym_class = "GymEnv"
 
     @pytest.fixture(scope="function")
     def make_env(self, example_build_path_arg):
         envs = []
 
         def factory(example : UnrealExample) -> GymVectorEnv:
-            env = getattr(schola_examples.gym, example.classname)(built_game_path = example_build_path_arg, headless_mode=not example.requires_rendering, display_logs=False)
+            env = make_env(example_build_path_arg, example, self.gym_class)
             envs.append(env)
             return env
 
@@ -66,7 +105,6 @@ def factory(example : UnrealExample) -> GymVectorEnv:
         for env in envs:
             env.close()
 
-
     @pytest.mark.parametrize("episode_sequence", [[1,1],[0,0],[10,10,10],[100,100]], ids=lambda x: f"Episode Lengths: {x}")
     def test_episode_stepping(self, make_env, episode_sequence):
         env = make_env(self.example)
@@ -80,13 +118,14 @@ def test_passes_gym_checker(self, make_env):
 
 class AbstractTestIncompatibleGymExample:
     example = None
+    gym_class = "GymEnv"
 
     @pytest.fixture(scope="function")
     def make_env(self, example_build_path_arg):
         envs = []
 
         def factory(example : UnrealExample) -> GymVectorEnv:
-            env = getattr(schola_examples.gym, example.classname)(built_game_path = example_build_path_arg, headless_mode=not example.requires_rendering, display_logs=False)
+            env = make_env(example_build_path_arg, example, self.gym_class)
             envs.append(env)
             return env