# csc301-2026-f/20-amd-schola architecture

> Architecture diagram of the GitHub repository csc301-2026-f/20-amd-schola, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/csc301-2026-f/20-amd-schola
- Repository: https://github.com/csc301-2026-f/20-amd-schola

## Overview

Schola is an Unreal Engine toolkit for defining agent environments, exchanging observations and actions with Python reinforcement-learning frameworks, and running trained policies in games. The principal loop runs from Unreal environment and agent definitions through Gym/gRPC communication to Python training or evaluation, then returns actions to advance the environment. Separate branches support in-game inference and imitation-data collection. README and tree establish these product capabilities; sampled implementation detail is limited, so the graph omits unverified internal call links.

Main entry points: [`Resources/python/schola/gym/env.py`](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/gym/env.py) (Gym Environment API), [`Source/ScholaTraining/Public/Environment/EnvironmentInterface.h`](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaTraining/Public/Environment/EnvironmentInterface.h) (Environment Interfaces), [`Source/Schola/Public/Agent/AgentInterface.h`](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/Schola/Public/Agent/AgentInterface.h) (Agent Interface), [`Source/ScholaProtobuf/Private/GymConnectors/gRPC/gRPCGymConnector.cpp`](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaProtobuf/Private/GymConnectors/gRPC/gRPCGymConnector.cpp) (gRPC Connectors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_unreal["Unreal Environments"]
  node_environment["Environment Interfaces"]
  node_agent["Agent Interface<br/>[AgentInterface.h]"]
  node_interactors["Sensors and Actuators"]
  node_spaces["Spaces and Points"]
  node_gymconnector["Gym Connector<br/>[IGymConnector.h]"]
end

subgraph group_protocol["Protocol Layer"]
  node_grpc["gRPC Connectors"]
  node_schemas["Protocol Schemas<br/>[State.proto]"]
  node_serializer["Protobuf Conversion"]
end

subgraph group_python["Python RL"]
  node_gymapi["Gym Environment API<br/>[env.py]"]
  node_baseprotocol["Python Protocols<br/>[base_protocol.py]"]
  node_sb3["SB3 Integration<br/>[env.py]"]
  node_rllib["RLlib Integration<br/>[env.py]"]
  node_training["Training Commands<br/>[train.py]"]
  node_datasets["Minari Collection<br/>[datacollector.py]"]
end

subgraph group_inference["In-Game Inference"]
  node_policy["Policy Interface<br/>[PolicyInterface.h]"]
  node_nne["NNE Policy<br/>[NNEPolicy.h]"]
  node_stepper["Inference Stepper<br/>[PipelinedStepper.h]"]
  node_statetree["StateTree NPCs"]
end

subgraph group_imitation["Imitation Learning"]
  node_imit_env["Imitation Environment"]
  node_imit_connector["Imitation Connector"]
  node_imit_python["Imitation Protocol<br/>[grpc_protocol.py]"]
end

node_developer(("Environment Author"))
node_runtime(("Unreal Game"))
node_human(("Demonstrator"))

node_developer -->|"defines"| node_environment
node_environment -->|"hosts"| node_agent
node_agent -->|"observes and acts"| node_interactors
node_environment -->|"defines spaces"| node_spaces
node_gymconnector -->|"exposes"| node_environment
node_gymconnector -->|"dispatches"| node_grpc
node_grpc -->|"converts messages"| node_serializer
node_serializer -->|"encodes"| node_schemas
node_grpc -->|"exchanges state"| node_baseprotocol
node_baseprotocol -->|"serves environment API"| node_gymapi
node_gymapi -->|"adapts environment"| node_sb3
node_gymapi -->|"adapts environment"| node_rllib
node_training -->|"trains with"| node_sb3
node_training -->|"trains with"| node_rllib
node_sb3 -->|"steps environment"| node_gymapi
node_rllib -->|"steps environment"| node_gymapi
node_gymapi -->|"provides episode data"| node_datasets
node_agent -->|"receives actions"| node_policy
node_stepper -->|"collects observations"| node_agent
node_stepper -->|"dispatches inference"| node_policy
node_nne -->|"implements"| node_policy
node_statetree -->|"steps inference"| node_stepper
node_human -->|"provides demonstrations"| node_imit_env
node_imit_env -->|"supplies imitation state"| node_imit_connector
node_imit_connector -->|"exchanges data"| node_imit_python

click node_environment "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaTraining/Public/Environment/EnvironmentInterface.h"
click node_agent "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/Schola/Public/Agent/AgentInterface.h"
click node_interactors "https://github.com/csc301-2026-f/20-amd-schola/tree/main/Source/ScholaInteractors/Public"
click node_spaces "https://github.com/csc301-2026-f/20-amd-schola/tree/main/Source/Schola/Public/Spaces"
click node_gymconnector "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaTraining/Public/GymConnectors/IGymConnector.h"
click node_grpc "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaProtobuf/Private/GymConnectors/gRPC/gRPCGymConnector.cpp"
click node_schemas "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Proto/State.proto"
click node_serializer "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaProtobuf/Private/ProtobufUtils/ProtobufSerializer.cpp"
click node_gymapi "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/gym/env.py"
click node_baseprotocol "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/core/protocols/base_protocol.py"
click node_sb3 "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/sb3/env.py"
click node_rllib "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/rllib/env.py"
click node_training "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/scripts/sb3/train/train.py"
click node_datasets "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/minari/datacollector.py"
click node_policy "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/Schola/Public/Policies/PolicyInterface.h"
click node_nne "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaNNE/Public/Policies/NNEPolicy.h"
click node_stepper "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaInferenceUtils/Public/Steppers/PipelinedStepper.h"
click node_statetree "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaStateTree/Public/Environment/StateTreeTrainingEnvironment.h"
click node_imit_env "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaImitation/Public/Environment/ImitationPlayerController.h"
click node_imit_connector "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaProtobuf/Private/ImitationConnectors/gRPC/gRPCImitationConnector.cpp"
click node_imit_python "https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/core/protocols/protobuf/grpc_protocol.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_environment,node_agent,node_interactors,node_spaces,node_gymconnector toneBlue
class node_grpc,node_schemas,node_serializer toneAmber
class node_gymapi,node_baseprotocol,node_sb3,node_rllib,node_training,node_datasets toneMint
class node_policy,node_nne,node_stepper,node_statetree toneRose
class node_imit_env,node_imit_connector,node_imit_python,node_developer,node_runtime,node_human toneIndigo
```

## Components

### Unreal Environments

- [Environment Interfaces](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaTraining/Public/Environment/EnvironmentInterface.h): `Source/ScholaTraining/Public/Environment/EnvironmentInterface.h`
- [Agent Interface](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/Schola/Public/Agent/AgentInterface.h): `Source/Schola/Public/Agent/AgentInterface.h`
- [Sensors and Actuators](https://github.com/csc301-2026-f/20-amd-schola/tree/main/Source/ScholaInteractors/Public): `Source/ScholaInteractors/Public`
- [Spaces and Points](https://github.com/csc301-2026-f/20-amd-schola/tree/main/Source/Schola/Public/Spaces): `Source/Schola/Public/Spaces`
- [Gym Connector](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaTraining/Public/GymConnectors/IGymConnector.h): `Source/ScholaTraining/Public/GymConnectors/IGymConnector.h`

### Protocol Layer

- [gRPC Connectors](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaProtobuf/Private/GymConnectors/gRPC/gRPCGymConnector.cpp): `Source/ScholaProtobuf/Private/GymConnectors/gRPC/gRPCGymConnector.cpp`
- [Protocol Schemas](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Proto/State.proto): `Proto/State.proto`
- [Protobuf Conversion](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaProtobuf/Private/ProtobufUtils/ProtobufSerializer.cpp): `Source/ScholaProtobuf/Private/ProtobufUtils/ProtobufSerializer.cpp`

### Python RL

- [Gym Environment API](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/gym/env.py): `Resources/python/schola/gym/env.py`
- [Python Protocols](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/core/protocols/base_protocol.py): `Resources/python/schola/core/protocols/base_protocol.py`
- [SB3 Integration](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/sb3/env.py): `Resources/python/schola/sb3/env.py`
- [RLlib Integration](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/rllib/env.py): `Resources/python/schola/rllib/env.py`
- [Training Commands](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/scripts/sb3/train/train.py): `Resources/python/schola/scripts/sb3/train/train.py`
- [Minari Collection](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/minari/datacollector.py): `Resources/python/schola/minari/datacollector.py`

### In-Game Inference

- [Policy Interface](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/Schola/Public/Policies/PolicyInterface.h): `Source/Schola/Public/Policies/PolicyInterface.h`
- [NNE Policy](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaNNE/Public/Policies/NNEPolicy.h): `Source/ScholaNNE/Public/Policies/NNEPolicy.h`
- [Inference Stepper](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaInferenceUtils/Public/Steppers/PipelinedStepper.h): `Source/ScholaInferenceUtils/Public/Steppers/PipelinedStepper.h`
- [StateTree NPCs](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaStateTree/Public/Environment/StateTreeTrainingEnvironment.h): `Source/ScholaStateTree/Public/Environment/StateTreeTrainingEnvironment.h`

### Imitation Learning

- [Imitation Environment](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaImitation/Public/Environment/ImitationPlayerController.h): `Source/ScholaImitation/Public/Environment/ImitationPlayerController.h`
- [Imitation Connector](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Source/ScholaProtobuf/Private/ImitationConnectors/gRPC/gRPCImitationConnector.cpp): `Source/ScholaProtobuf/Private/ImitationConnectors/gRPC/gRPCImitationConnector.cpp`
- [Imitation Protocol](https://github.com/csc301-2026-f/20-amd-schola/blob/main/Resources/python/schola/core/protocols/protobuf/grpc_protocol.py): `Resources/python/schola/core/protocols/protobuf/grpc_protocol.py`

### Other components

- **Environment Author**
- **Unreal Game**
- **Demonstrator**

## Connections

- Environment Author → Environment Interfaces: defines
- Environment Interfaces → Agent Interface: hosts
- Agent Interface → Sensors and Actuators: observes and acts
- Environment Interfaces → Spaces and Points: defines spaces
- Gym Connector → Environment Interfaces: exposes
- Gym Connector → gRPC Connectors: dispatches
- gRPC Connectors → Protobuf Conversion: converts messages
- Protobuf Conversion → Protocol Schemas: encodes
- gRPC Connectors → Python Protocols: exchanges state
- Python Protocols → Gym Environment API: serves environment API
- Gym Environment API → SB3 Integration: adapts environment
- Gym Environment API → RLlib Integration: adapts environment
- Training Commands → SB3 Integration: trains with
- Training Commands → RLlib Integration: trains with
- SB3 Integration → Gym Environment API: steps environment
- RLlib Integration → Gym Environment API: steps environment
- Gym Environment API → Minari Collection: provides episode data
- Agent Interface → Policy Interface: receives actions
- Inference Stepper → Agent Interface: collects observations
- Inference Stepper → Policy Interface: dispatches inference
- NNE Policy → Policy Interface: implements
- StateTree NPCs → Inference Stepper: steps inference
- Demonstrator → Imitation Environment: provides demonstrations
- Imitation Environment → Imitation Connector: supplies imitation state
- Imitation Connector → Imitation Protocol: exchanges data