aegis-game 2.9.9

AEGIS

AEGIS is a survivor simulation game. This repo contains:

• Server/engine (Python package) that runs simulations and exposes a WebSocket for the client
• Client (Electron, React, TypeScript, Tailwind CSS) for visualizing and controlling simulations
• Documentation found here

Repo Layout

Codebase

• client: Electron desktop client (builds for macOS, Windows, Linux)
• schema: Shared Protocol Buffer/TypeScript types
• src: Python server/engine, CLI entrypoint, public API
• tests: Tests

Additional

• agents: Example/reference agents (e.g., agent_path, agent_mas, agent_prediction)
• config: Example/reference configurations (e.g., pathfinding-assignment.yaml, multi-agent-assignment.yaml)
• prediction-data: Example/reference prediction data
• scripts: Utility scripts
• worlds: Example/reference worlds for running simulations

Prerequisites

• Python 3.13+
• Node.js 20+

Package name (PyPI)

• The Python package is published as aegis-game.

Download for usage in assignments or competitions

0. Verify Python version accessible from shell (Should be 3.13+)

python --version
# OR if you have Python 2 installed (often the case on Mac/Linux)
python3 --version

1. Create a folder and install the aegis-game package

# Initialize project
mkdir my-new-project
cd my-new-project

2. Activate the virtual environment

python -m venv .venv

On macOS/Linux:

source .venv/bin/activate

On Windows (CMD):

.\.venv\Scripts\Activate

On Windows (PowerShell):

.\.venv\Scripts\Activate.ps1

This creates a virtual project environment under .venv/

3. Install aegis-game with:

pip install aegis-game

The CLI entrypoint is aegis (e.g., aegis launch).

Download for usage in assignments or competitions

3. Create folder scaffold

aegis init

Alternately, for multi-agent config use

aegis init --type mas

This creates all necessary files/folders in your project that an aegis simulation needs to run

Notes:

• Agent code under agents/
• Config code under config/
• Client GUI code under client/
• Worlds under worlds/

4. Configure features (Optional)

If default aegis init is not desired edit config/config.yaml to enable/disable features (e.g., messages, dynamic spawning, abilities). If you change features, regenerate stubs so the API your agent recongizes matches the config:

aegis forge

5a. Use the client UI

The client is in the \client folder You can run it by interacting with it through your OS folder system or

On Linux

client/aegis-client.AppImage

On Windows (CMD/PowerShell):

client\aegis-client.exe

On Mac:

open client/Aegis.app

5b. Launch a game (through the console)

# One agent
aegis launch --world example --agent agent_path

# Five agents with max rounds of 500 (requires config of ALLOW_CUSTOM_AGENT_COUNT=true)
aegis launch --world example --agent agent_path --amount 5 --rounds 500

Run aegis launch -h to see all ways you can run an aegis simulation

6. Deactivate (venv) Close your terminal/shell or run command

deactivate

&. Reactivate (venv) Open terminal shell within project folder or change directory into it and run

On macOS/Linux:

source .venv/bin/activate

On Windows (CMD):

.\.venv\Scripts\Activate

On Windows (PowerShell):

.\.venv\Scripts\Activate.ps1

Download for Development

Before you start, please read our Contributing Guidelines to understand the full contribution process, coding standards, and PR requirements.

1. Clone the repository and set up the Python environment

• uv (for Python env/build) — pip install uv or see https://docs.astral.sh/uv/

git clone https://github.com/AEGIS-GAME/aegis.git
cd aegis
uv sync --group dev

2. Activate the virtual environment

On macOS/Linux:

source .venv/bin/activate

On Windows (CMD):

.\.venv\Scripts\Activate

On Windows (PowerShell):

.\.venv\Scripts\Activate.ps1

3. Run locally

aegis launch --world ExampleWorld --agent agent_path

Client

For instructions on local development and setup of the client application, please see the client README

Documentation

The documentation can be found here.

Troubleshooting

• "Config Error Failed to load config.yaml. Please check your config file and ensure it's valid."
  • Use Settings 'Gear' icon to open settings and set 'Aegis Path' to the base folder of your project
    • The folder 'config' within that base folder should have the missing 'config.yaml' in it
• Windows PowerShell execution policy may block script activation; if needed, run PowerShell as Administrator and execute:
  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
• Ensure Node.js 20+ and Python 3.13+ are on your PATH
• If the client cannot connect, verify the server was started with --client and that no firewall is blocking the port
• If you aren't using a virtual environment (.venv) and see "Defaulting to user installation because normal site-packages is not writeable" during pip
  • You will likely get ": command not found" (Linux) or "'' is not recognized as an internal or external command, operable program or batch file." (Windows) when using commands
  • This can be rectfied by adding the local location of '' to your PATH. A local installation for python package installed via pip is generally able to be added to path with
    • Linux

      • PATH=$PATH:~/.local/bin```
        

    • Windows

      • PATH=%PATH%;%appdata%\Python\Python313\Scripts```