SimControl API

The scrimmage executable is a light-weight wrapper around the primary C++ class used to manage the simulation engine: SimControl. The SimControl class can be used in three contexts: executing SimControl in its own thread, executing SimControl in the current thread, and executing SimControl in the current thread with manual stepping of the simulation.

Note

The return values of the SimControl API call should be checked in production code (often just a boolean check). The checks are left out of the following code samples to improve readability.

Threaded Execution of SimControl

The following code sample demonstrates how to use the SimControl class in non-blocking threaded execution. This is how the simulation is executed when running with the scrimmage visualization engine because the VTK window needs to be executed in the primary thread.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
  // Create an instance of the SimControl class.
  SimControl simcontrol;

  // Initialize the simulation with the straight.xml mission file.
  // SimControl will search on the SCRIMMAGE_MISSION_PATH environment
  // variable for the mission file.
  simcontrol.init("straight");

  // Run the simulation in its own thread. The run_threaded() function  is
  // non-blocking.
  simcontrol.run_threaded();

  // ... Do other work in the current thread ...

  // Tell the simulation to end execution.
  simcontrol.force_exit();

  // Wait for the simulation to stop running internal threads.
  simcontrol.join();

  // Clean up any resources allocated during the simulation.
  simcontrol.shutdown();

Non-Threaded Execution of SimControl

The following code sample demonstrates how to use the SimControl class in blocking non-threaded execution. This is how the simulation is executed when the scrimmage GUI is not enabled.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
  // Create an instance of the SimControl class.
  SimControl simcontrol;

  // Initialize the simulation with the straight.xml mission file.
  simcontrol.init("straight");

  // Run the simulation in the current thread. The run() function is
  // blocking.
  simcontrol.run();

  // Clean up any resources allocated during the simulation.
  simcontrol.shutdown();

Manual Stepping of SimControl

The following code sample demonstrates how to use the SimControl class in a manual simulation stepping context. This context is helpful for writing unit tests that need to check the state of the simulation at each time step.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
  // Create an instance of the SimControl class.
  SimControl simcontrol;

  // Initialize the simulation with the straight.xml mission file.
  simcontrol.init("straight");

  // Start the simulation timers, setup log directories, etc. The start()
  // function has to be manually called in this case. In the previous
  // examples, the run() function automatically called the start()
  // function.
  simcontrol.start();

  // Step the simulation 100 times.
  for (int i = 0; i < 100; i++) {
      simcontrol.run_single_step(i);
  }

  // Clean up any resources allocated during the simulation.
  simcontrol.shutdown();