esmini: a small OpenSCENARIO XML player with a real API

esmini plays scenarios rather than authoring them

The description on the project page is a short phrase: a basic OpenSCENARIO player. That phrase sets the scope better than any marketing sentence could, and it is worth taking the project at its word before you build anything around it.

The problem esmini addresses is playback. A simulation scenario in the ASAM OpenSCENARIO XML format plus a road network in OpenDRIVE is a portable, text based description of what a vehicle should do and where the road goes. Large simulation tool chains can consume those files, but many teams want something small enough to embed in a test rig, a CI job or a co-simulation setup. esmini was started in 2018 to explore that format and to be easy to integrate, with portability across Windows, Mac, Linux and Android named as a high priority from the beginning, along with use from native C++ and from frameworks such as Unity3D in C# and MATLAB/Simulink.

The origin story matters for judging the current state. The code began as the outcome of a Swedish collaborative research project called Simulation Scenarios, and the README says the initial focus was more on features than quality. It also states plainly that there is currently no plan to support OpenSCENARIO DSL, so if your scenario pipeline emits DSL rather than XML, this is not your player.

Two libraries, with RoadManager underneath ScenarioEngine

The engine is split into two main libraries, and the split matters if you plan to embed the project.

RoadManager ships as esminiRMLib and provides an interface to road networks described in the OpenDRIVE format. It is the piece that knows about lanes, road geometry and the reference line. ScenarioEngine ships as esminiLib and is described as the main library, providing a viewer and an API interface to traffic scenarios described in the OpenSCENARIO XML format. The README states that this library includes RoadManager.

That inclusion is the important architectural detail. If you want to read a road network without running a scenario, you take RoadManager on its own. If you want to drive a scenario, you take esminiLib and it brings the road layer with it. A player built on top of a separate road model and a separate scenario model would force every integrator to write glue code; folding RoadManager into esminiLib removes that step, at the cost of a slightly less granular dependency.

The repository layout backs this up. There is an EnvironmentSimulator/ directory, an OSMP_FMU/ directory, a Hello-World_coding-example/ directory, a run/ directory for the shipped examples, and separate osc_coverage.txt and odr_coverage.txt files that record how much of each standard the implementation covers.

Six applications share the same core

The repository also ships sample applications, described in the README as usable as is or as a starting point for customised solutions.

The main one is esmini, the scenario player application, which links the esmini modules statically. esmini-dyn is a minimalistic example that uses esminiLib to play OpenSCENARIO XML files, and it exists to show the library route rather than the static application. odrplot produces a data file from an OpenDRIVE road network so it can be plotted in Python, which is a quick way to check a map before running a scenario against it. odrviewer visualises an OpenDRIVE road network with populated dummy traffic, useful when the question is whether the map looks right. replayer re-plays previously executed scenarios, so a recorded run can be reproduced without re-simulating. osireceiver is a simple application that receives OSI messages from esmini over UDP.

Six small programs covering a different question each. That is a design choice, not filler. Each one isolates a use case so that an integrator can copy the smallest piece that solves the problem, and replayer and odrplot in particular suggest the project was built by people who debug scenarios against recorded runs and plotted maps.

OSI ground truth through three doors

esmini also speaks the Open Simulation Interface, and this is the part that turns it from a player into a component.

Beyond the internal API for querying the running simulation, for example the road width and the position of a road user, esmini collects everything into an OSI groundtruth structure. The README lists three ways to get at that data: storing it in an OSI trace file, retrieving it over UDP, and retrieving it directly through the API. The trace file path reuses the replayer application for inspection. The UDP path is what osireceiver exists for, and it is how a co-simulated tool picks up the state without linking the library. The API path is the cheapest option for a custom application that already links the shared library.

There is a caveat stated in bold in the README: only parts of the OSI groundtruth is populated. So an OSI consumer must not assume a fully populated frame. If your integration depends on a specific OSI field, check the coverage documentation before wiring it up, because the gap is in the data, not in the transport.

The shared library is called ScenarioEngineDLL, and despite the name it is available on Linux and Mac as well. The project points to a shared library programming page and a Hello World tutorial for building a minimalistic application on top of it, and to a separate example for fetching OSI groundtruth.

Running your first scenario from the demo packages

The fastest way to see esmini work is the pre-built route. The README states that pre-built demo packages are available from the releases page, that you unzip the package, navigate to the run directory inside it and run any of the example scripts. The demo packages also contain pre-created 3D models, which are also offered as a separate download and should be unpacked into the resources directory, where they work on all platforms. The environment models used for roads, terrain and buildings were created with the VIRES Road Network Editor, which tells you what to expect visually.

So the first run looks like this: fetch the latest release package, unpack it, and run one of the example scripts from the esmini run directory that ships inside it.

esmini\run\esmini

At the repository level, the directories you will work with are these.

EnvironmentSimulator/
Hello-World_coding-example/
OSMP_FMU/
run/
scripts/

The Hello-World_coding-example directory is where the embedding route starts, and OSMP_FMU/ is the functional mock-up interface directory, which is worth a look if your toolchain speaks FMU rather than C++.

Releases are frequent: v3.10.0 (build 6442) on 2026-10-14, v3.9.0 (build 6434) on 2026-10-06 and v3.8.2 (build 6400) on 2026-09-22. The last push was on 2026-10-19, so the tree is current.

One shared library, three integration routes

The README calls the all inclusive shared library ScenarioEngineDLL the easiest way of integrating esmini into a custom application, and it points out that despite the DLL name it is available on Linux and Mac too. The same engine is then exposed through three integration surfaces.

The first is native C++. The Hello World tutorial walks through creating a minimalistic application on the shared library, including an example of how to fetch the state of scenario objects. The second is Unity, where the shared library works as a plugin on Windows, Linux and Mac, with a documented example in the user guide. The third is Python, covered in the Python binding section of the Hello World tutorial.

That the same binary serves all three is the point. A team can prototype in Python, hand a scenario to a C++ application, and drop the same library into a Unity scene without maintaining three separate interpretations of the scenario format.

Two supporting mechanisms make that workable. A build guide section on external dependency details covers OSI build information and version handling, which matters when your tool links against a specific OSI version. A pre-commit-config.yaml, a .clang-tidy configuration and a .clang-format file at the repository root show that formatting and static analysis are enforced in the tree, and a CODEOWNERS file plus a CONTRIBUTING.md indicate how outside patches are handled.

Coverage is the limit, and the project says so

The honest limitation is stated in the README rather than buried. esmini supports OpenSCENARIO XML v1.0 to v1.3, but the README adds that feature coverage is limited and that functionality grows slowly but steadily, based on need and contributions. The repository keeps the detail in two plain text files, osc_coverage.txt for OpenSCENARIO and odr_coverage.txt for OpenDRIVE, and they are the first thing to read.

The second limitation is the DSL gap. There is currently no plan to support OpenSCENARIO DSL, so a scenario authored in the DSL form is out of reach regardless of how complete the XML support is.

The third is the scope of the OSI output. Only parts of the groundtruth structure are populated, which means a consumer must be written against what is actually filled in rather than against the full structure.

The fourth is that the tool is basic by design. It plays scenarios and moves entities along a road network; it is not a traffic simulation with behavioural models. Anyone needing driver models, traffic flow realism or a perception stack will need a different engine, and treating esmini as a reference for those is a category error.

How esmini differs from scenario generators and scenario collections

The project itself points at three related efforts, and the differences in approach are clear enough to make adoption decisions easier.

scenariogeneration is a Python based scenario creation framework. The idea is to write scenarios in a high-level script format and automatically generate and run linked OpenDRIVE and OpenSCENARIO XML counterparts, and it supports parameter sweeps to create multiple variants of a parameterized scenario. esmini sits on the other side of that pipeline: it consumes the XML that a generator produces and executes it. The two are complementary rather than competing, and a common arrangement is generation in Python, playback in esmini, with the XML as the handoff.

The scenario collections are test assets rather than tools. OSC-ALKS-scenarios is a collection of scenarios for Automated Lane Keeping System testing, and the project page quotes the description that BMW took on implementing the test scenarios from the ALKS regulation using OpenSCENARIO and OpenDRIVE, resulting in a bundle of XML files executable with standard compliant simulators. OSC-NCAP-scenarios is a collection based on Euro NCAP test protocols, contributed by Vector as an implementation of those scenarios using the ASAM standards. Both assume a player exists, which is exactly the slot esmini fills.

For licensed terms, the repository carries the MPL-2.0 licence, with the file-level copyleft and the file-level exception structure that implies for anyone modifying library files. A separate 3rd_party_terms_and_licenses/ directory at the root signals that bundled external components carry their own terms, and the OSI library used for the groundtruth output is one of those externals. That is a licensing review to run before shipping, not advice, and the third party directory is where to start it.

Editorial conclusion

esmini fits teams that already own OpenSCENARIO XML scenarios and OpenDRIVE maps and need a portable, scriptable player for CI, regression or tool integration, and it fits Unity, MATLAB and Python users because the shared library exposes the same engine. It does not fit authors of scenarios, since the project only plays them, and it does not fit work requiring the full OpenSCENARIO feature set, since the project states that coverage is limited and that there is no plan to support OpenSCENARIO DSL. Before adopting it, open osc_coverage.txt and odr_coverage.txt to see whether your own scenario elements are supported, run one of the pre-built demo packages, and read the release notes for the version you intend to pin.

Frequently asked questions

Official sources

1. esmini/esmini on GitHub
2. Issues
3. License: MPL-2.0
4. README
5. Releases