World

Stage simulates a 'world' composed of `models', defined in a `world file'.

API: Stg::World

Worldfile properties

Summary and default values

	 name                     <worldfile name>
	 interval_sim            100
	 quit_time                 0
    resolution                0.02
	 show_clock                0
	 show_clock_interval     100
    threads                   0

    

Details

• name <string>
  An identifying name for the world, used e.g. in the title bar of the GUI.

• interval_sim <float>
  The amount of simulation time run for each call of World::Update(). Each model has its own configurable update interval, which can be greater or less than this, but intervals shorter than this are not visible in the GUI or in World update callbacks. You are not likely to need to change the default of 100 msec: this is used internally by clients such as Player and WebSim.

• quit_time <float>
  Stop the simulation after this many simulated seconds have elapsed. In libstage, World::Update() returns true. In Stage with a GUI, the simulation is paused.wo In Stage without a GUI, Stage quits.

• resolution <float>
  The resolution (in meters) of the underlying bitmap model. Larger values speed up raytracing at the expense of fidelity in collision detection and sensing. The default is often a reasonable choice.

• show_clock <int>
  If non-zero, print the simulation time on stdout every $show_clock_interval updates. Useful to watch the progress of non-GUI simulations.

• show_clock_interval <int>
  Sets the number of updates between printing the time on stdoutm, if $show_clock is enabled. The default is once every 10 simulated seconds. Smaller values slow the simulation down a little.

• threads <int>
  The number of worker threads to spawn. Some models can be updated in parallel (e.g. laser, ranger), and running 2 or more threads here may make the simulation run faster, depending on the number of CPU cores available and the worldfile. As a guideline, use one thread per core if you have parallel-enabled high-resolution models, e.g. a laser with hundreds or thousands of samples, or lots of models.

More examples

The Stage source distribution contains several example world files in (stage src)/worlds along with the worldfile properties described on the manual page for each model type.