Project Overview

A project is the top-level container for an Astra application - it defines the engine configuration, resource directory, window layout, and system manifest. Everything the engine loads at startup is derived from the project descriptor.

Structure

my-game/
├── project.astra          # Project descriptor
└── assets/                # Conventionally used as resources.directory
    ├── shaders/
    ├── textures/
    ├── models/
    └── fonts/

The subdirectory layout above is a common convention. Astra does not enforce any particular folder structure beyond what is declared in the descriptor.

Project Descriptor

project.astra is a serialized descriptor that the engine reads on startup. The top-level keys are name, directory, manifest, windows, systems, resources, and serialization.

{
  "name": "My Game",
  "directory": "/path/to/my-game",
  "manifest": "/path/to/my-game/project.astra",
  "resources": {
    "directory": "assets/"
  },
  "serialization": {
    "format": "json"
  },
  "windows": [
    {
      "id": "main",
      "title": "My Game",
      "width": 1280,
      "height": 720,
      "headless": false
    }
  ],
  "systems": [
    {
      "name": "render",
      "content": {
        "backend": "opengl",
        "window_id": "main",
        "headless": false,
        "msaa": {
          "samples": 4,
          "is_enabled": true
        }
      }
    },
    {
      "name": "physics",
      "content": {
        "backend": "physx",
        "pvd_host": "127.0.0.1",
        "pvd_port": 5425,
        "pvd_timeout": 5,
        "gravity": { "x": 0.0, "y": -9.81, "z": 0.0 }
      }
    }
  ],
  "resources": []
}

Systems Manifest

The systems array controls which engine systems are activated and in what initialization order. Systems not listed are not constructed, keeping startup cost proportional to what the project actually uses.

Each entry is an object with two keys:

• name - lowercase system identifier. Recognised values are "render" and "physics".
• content - a backend-specific configuration sub-object whose fields differ per system type (see the example above).

Path Resolution

Astra distinguishes two path bases, exposed as C++ user-defined literal (UDL) operators:

_engine suffix

auto path = "shaders/default.vert"_engine;

Resolves the relative path against ASTRALIX_ASSETS_DIR, a compile-time constant baked into the engine binary pointing at the engine's own asset directory. This base is independent of any project descriptor field.

_project suffix

auto path = "textures/diffuse.png"_project;

Resolves the relative path against the active project's directory joined with resources.directory. In the example descriptor above that expands to /path/to/my-game/assets/textures/diffuse.png.

Both operators return a Ref<Path> (shared_ptr<Path>). The PathManager::resolve() method converts a Ref<Path> to an absolute std::filesystem::path at runtime.

Path aliases in the descriptor

Resource paths inside the descriptor can be prefixed with @engine/ or @project/ to override the default base directory:

{ "path": "@engine/shaders/default.vert" }
{ "path": "@project/textures/diffuse.png" }

An unprefixed string defaults to BaseDirectory::Project.

Subsystems

Subsystem	Responsibility
ProjectManager	Singleton that owns and tracks all loaded Project instances; provides get_active_project() and add_project(). Accessible via the project_manager() inline helper.
PathManager	Singleton that resolves Ref<Path> objects to absolute filesystem paths using the engine or project base directories. Accessible via the path_manager() inline helper.