Understanding the Engine

The Altruist Engine is a game loop that provides frame-based execution for physics simulations, AI updates, and other real-time operations that require consistent tick rates.

Enabling the Engine

Configure the engine in config.yml:

altruist:
  game:
    engine:
      diagnostics: true    # Enable performance logging
      framerateHz: 30       # 30 ticks per second
      unit: "hz"
      gravity: { x: 0, y: -9.81 }

Note:

When the engine is enabled, server-side game logic runs at a consistent rate regardless of client activity.

Scheduling Tasks with [Cycle]

The [Cycle] attribute allows methods to execute on the engine loop:

Run at Engine Frame Rate

[Cycle]
public async Task UpdateGameState()
{
    // Runs every engine tick (e.g., 30 times per second at 30Hz)
}

Run at a Custom Frequency

[Cycle(120, CycleUnit.Seconds)]
public async Task RegenerateHealth()
{
    // Runs 120 times per second
}

Run on a Cron Schedule

[Cycle("*/1 * * * *")]
public async Task SaveGameState()
{
    // Runs every 1 minute
}

Programmatic Task Scheduling

You can also schedule tasks programmatically via IAltruistEngine:

engine.ScheduleTask(MyUpdateMethod, new CycleRate(60, CycleUnit.Seconds));
engine.RegisterCronJob(MySaveMethod, "0 * * * *"); // Every hour

Cron Expressions

ExpressionFrequency
"*/1 * * * *"Every 1 minute
"0 * * * *"Every hour
"0 0 * * *"Once per day
"0 0 * * 0"Once per week

World Configuration

The engine manages game worlds defined in config:

altruist:
  environment:
    mode: "3D"          # or "2D"

  game:
    worlds:
      partitioner: { width: 256, height: 256, depth: 256 }
      items:
        - index: 0
          id: "main-world"
          size: { x: 1000, y: 1000, z: 1000 }
          gravity: { x: 0, y: -9.81, z: 0 }
          data-path: "Resources/world.json"

Each world is spatially partitioned for efficient broadcasting and collision detection.

Engine + Resilient Services

The engine will not start until all IConnectable services report healthy. If a service goes down, the engine pauses automatically and resumes when all services recover.

Note:

Higher frame rates improve responsiveness but increase CPU usage. Choose a rate that balances performance and smoothness for your game.