Repository files navigation

This project contains Example Environments for Schola. These can be used as a resource to see how to structure environments built with Schola or reused to train similar agents

As Schola examples is an Unreal Engine Project, you will need to first install Unreal Engine. Refer to the below table to identify the correct version of Unreal Engine for each version of Schola Examples.

NoteVersions of Schola/ScholaExamples may be compatible with other Unreal Versions beyond the ones listed here, however these are the version(s) tested for each release.

Visual Studio 2022 is available for download fromMicrosoft. Additionally, details (and an additional plugin) for setting up Visual Studio with Unreal Engine are available in theUE Docs.

Note
Only MSVC v143 Build Tools should be selected during install including other build tools will cause linking errors. Specifically, useMSVC14.X whereX>34 from Visual Studio 2022, andWindows 10.0.22621.0 SDK to avoid linking errors

As Visual Studio is not supported on Linux, we recommend installing Visual Studio Code following the official guide forSetting Up Visual Studio Code for Unreal Engine.

This installs the ScholaExamples environments as a standalone package

pip install -e<path to ./python>

# OpenAI Gymnasium environmentsfromschola_examples.gymimportBallShooter,BallShooterVec# Both environments are subclasses of gymnasium.vector.VectorEnvenv=BallShooter()# Single environment instance for sequential trainingenv=BallShooterVec(headless_mode=True)# Vectorized environment for parallel training# Stable-Baselines3 environmentsfromschola_examples.sb3importBallShooter,BallShooterVec# Both environments are subclasses of stable_baselines3.common.vec_env.VecEnvenv=BallShooter()# Single environment instanceenv=BallShooterVec(headless_mode=True)# Vectorized environment for parallel training# RLlib environmentsfromschola_examples.rayimportBallShooter,BallShooterVec# Both environments are subclasses of ray.rllib.env.base_env.BaseEnvenv=BallShooter()# Single environment instanceenv=BallShooterVec(headless_mode=True)# Vectorized environment for parallel training

importschola_examplesimportgymnasium# Creates a vectorized environment of class gymnasium.vector.VectorEnv using Gymnasium's make_vec factoryenv=gymnasium.make_vec("Schola/Basic-v0")

importschola_examplesfromray.rllib.algorithmsimportppo# Creates environment of class ray.rllib.env.base_env.BaseEnv from RLlib's built-in registryalgo=ppo.PPO(env="Basic-V0")

When adding new examples to ScholaExamples please follow the below naming scheme for your files and folders.

Content/└── Examples/    ├── ExampleOne/    |   ├── Maps/    |   |   ├── ExampleOneInference.umap    |   |   ├── ExampleOneTrain.umap    |   |   └── ExampleOneVecTrain.umap    |   ├── Blueprints/    |   |   ├── ExampleOneEnvironment.uasset    |   |   ├── ExampleOneTrainer.uasset    |   |   ├── CustomActuator.uasset    |   |   ├── CustomObserver.uasset    |   |   └── ExampleOneAgent.uasset    |   └── Models/    |       └── ExampleOneOnnx.uasset    └── ExampleTwo/        └── Blueprints/            ├── FirstAgentNameAgent.uasset            ├── FirstAgentTrainer.uasset            └── SecondAgentNameAgent.uasset

1. All umap files go under the Maps folder
2. All code and blueprints goes under the blueprints folder. Prefer blueprints for implementing examples.
3. For Each Example add one map that runs inference, using the trained model, one map that trains a single environment at a time, and one map that trains multiple copies of the environment.
4. If the example is single agent the environment should be named after the name of the example (e.g.3DBallAgent.uasset), for multiagent environments use the name of the agents (e.g.RunnerAgent.uasset andTaggerAgent.uasset) instead of the example for Trainers and Agents.
5. Models should be saved as the name of the example followed byOnnx and be stored in the Models folder.

All unreal code with be styled following the Unreal Style Guide in theUnreal Documentation.

One potential auto-formatter is theClang Formatter which has visual studio support.

Comments are based on doxygen /** style to match closely with javadoc (which Unreal uses) but support handy visual studio features such as comment previews.To enable autogenerated doxygen stubs go to Tools -> Options -> Text Editor -> C/C++ -> Code Style -> General and change the option from XML to Doxygen (/**).This will enable autogeneration of stubs with ctrl + /, or whenever you type /** in visual studio.

Testing is implemented through pytests in Schola inResources/python/tests. These tests build a fresh copy of both this project and Schola before running unit tests on Python + Unreal. This tests whether all examples run with each framework and are functional based on the API.