19. Open Rails Software Platform

19.1. Architecture

To better understand how the Open Rails game operates, performs, and functions, the architecture diagram below lays out how the software code is organized. The architecture of the Open Rails software allows for modular extension and development, while providing standardized methods to customize the simulation experience.

Note

Please note that this diagram includes many capabilities and functions that are yet to be implemented.

19.2. Open Rails Game Engine

The Open Rails software is built on the MonoGame platform. MonoGame is an open source implementation of the Microsoft XNA 4 Framework and provides:

• Game framework
• 2D and 3D rendering
• Sound effect and music playback
• Keyboard, mouse, touch, and controller inputs
• Content building and optimization
• Math library optimized for games

19.3. Frames per Second (FPS) Performance

FPS rate is as default not linked to the sync rate of the monitor. However, with this option FPS rate may be set at the value of the monitor refresh rate.

19.4. Game Clock and Internal Clock

Like other simulation software, Open Rails software uses two internal clocks; a game clock and an internal clock. The game clock is required to synchronize the movement of trains, signal status, and present the correct game environment. The internal clock is used synchronize the software process for optimal efficiency and correct display of the game environment.

The Open Rails team is dedicated to ensuring the game clock properly manages time in the simulation, so that a train will cover the proper distance in the correct time. The development team considers this vital aspect for an accurate simulation by ensuring activities run consistently across community members’ computer systems.

19.5. Resource Utilization

Because Open Rails software is designed for the MonoGame framework, it natively exploits today’s graphics cards’ ability to offload much of the display rendering workload from the computer’s CPU.

19.6. Multi-Threaded Coding

The Open Rails software is designed from the ground up to support up to 4 CPUs, either as virtual or physical units. Instead of a single thread looping and updating all the elements of the simulation, the software uses four threads for the main functions of the software.

• Thread 1 – Main Render Loop (RenderProcess)
• Thread 2 – Physics and Animation (UpdaterProcess)
• Thread 3 – Shape and Texture Loading/Unloading (LoaderProcess)
• Thread 4 – Sound

There are other threads used by the multiplayer code as each opened communication is handled by a thread.

The RenderProcess runs in the main game thread. During its initialization, it starts two subsidiary threads, one of which runs the UpdaterProcess and the other the LoaderProcess. It is important that the UpdaterProcess stays a frame ahead of RenderProcess, preparing any updates to camera, sky, terrain, trains, etc. required before the scene can be properly rendered. If there are not sufficient compute resources for the UpdaterProcess to prepare the next frame for the RenderProcess, the software reduces the frame rate until it can catch up.

Initial testing indicates that stutters are significantly reduced because the process (LoaderProcess) associated with loading shapes and textures when crossing tile boundaries do not compete with the main rendering loop (RenderProcess) for the same CPU cycles. Thread safety issues are handled primarily through data partitioning rather than locks or semaphores to maximise performance.

Ongoing testing by the Open Rails team and the community will determine what and where the practical limits of the software lie. As the development team receives feedback from the community, improvements and better optimization of the software will contribute to better overall performance – potentially allowing high polygon models with densely populated routes at acceptable frame rates.

19.7. Web Server

19.7.1. Sample Web Pages

These pages give examples of what can be done with the APIs.

Some of these sample pages repeat data from the in-game panels to provide a more convenient display.

• The HUD web page repeats the F5 overlay.

• The Track Monitor page repeats the F4 panel and is also available with a dark background for night-time use.
• The Train Driving page offers a panel which is not yet available in the official version of Open Rails.
• Another page offers both of these and the panels can be dragged around for the best arrangement.

• The time page shows the simulation time as a digital clock and links to 3 versions of an analogue clock.

The sample pages can be found in the Content\Web subfolder of the OR program folder and the web server defaults to Content\Web\index.html.

If you choose to develop your own pages, please consider sharing them with the Open Rails community.

19.7.2. Application Programming Interfaces (APIs)

The web server features a simple API to obtain data from the simulator. Responses are OR data structures serialized in JSON format.

You can see the JSON data just by browsing. E.g.: for APISample, browse to http://localhost:2150/API/APISAMPLE

Note: The API portion of this address is case-sensitive.

Note: To avoid overloading the simulator, please keep API calls to once or twice a second.

Method	API call	Description	Response type
GET	/API/HUD/<n>	Retrieves the information rendered on the <F5> HUD, row by row, page by page, where <n> is the HUD page number 0 to 7.	Orts.Viewer3D.WebServices .WebServer.ORTSApiController .HudApiArray
GET	/API/TRAINMONITOR or /API/TRAININFO	Retrieves information rendered on the Track Monitor, such as speed, acceleration, grade, and upcoming hazards.	Orts.Simulation.Physics .Train.TrainInfo
GET	/API/TIME	Retrieves just the simulation time in seconds since midnight.	Orts.Viewer3D.WebServices .WebServer.ORTSApiController .ApiTime
GET	/API/CABCONTROLS	Retrieves an array of the cab controls for the player localhost TypeName, MinValue, MaxValue, RangeFraction.	Orts.Viewer3D.WebServices .WebServer.ORTSApiController .ApiCabControls
GET	/API/APISAMPLE	A test object that demonstrates the JSON serialization of various data types.	Orts.Viewer3D.WebServices .WebServer.ORTSApiController .ApiSampleData