Skip to content
OMXOMX Docs

Getting started

An OMX resource is a C# class library that OMX loads at startup. It has up to two halves:

  • a client half, which runs in the game for the player at that computer;
  • a server half, which runs on the authority: the dedicated server in multiplayer, or inside the game in single player.

Both halves use the same SDK, OMX.ModAPI, and a resource never references OMX’s engine, renderer or network code.

What you need

Section titled “What you need”
  • The .NET 10 SDK.
  • OMX installed, with your OMSI 2 content set up.

Create the project

Section titled “Create the project”
Terminal window
dotnet new classlib -n SpeedHUD -f net10.0
cd SpeedHUD
dotnet add package OMX.ModAPI --version 2.0.0

Your project file should look like this. The manifest, omx-resource.json, is copied next to the built DLL:

SpeedHUD.csproj
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="OMX.ModAPI" Version="2.0.0" />
    <None Include="omx-resource.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>
</Project>

Write the entry point

Section titled “Write the entry point”

A client resource is one public class derived from ClientResource. OMX finds it, starts it, and calls its overrides:

SpeedHudResource.cs
using System.Numerics;
using OMX.ModAPI;
using OMX.ModAPI.Client;


namespace SpeedHUD;


public sealed class SpeedHudResource : ClientResource
{
    protected override void OnTick(TimeSpan delta)
    {
        ILocalVehicle? bus = Vehicles.Local;
        if (bus is not { IsSpawned: true }) { Hud.Remove("speed"); return; }


        float kilometresPerHour = bus.Velocity.Length() * 3.6f;
        Hud.SetText("speed", $"{kilometresPerHour:0} km/h", new HudTextOptions
        {
            Anchor = HudAnchor.BottomRight,
            Offset = new Vector2(28f, 34f),
            Scale = 1.35f,
        });
    }


    protected override ValueTask OnStopAsync(CancellationToken cancellationToken)
    {
        Hud.Clear();
        return ValueTask.CompletedTask;
    }
}

Describe it in a manifest

Section titled “Describe it in a manifest”

Every resource has an omx-resource.json. The HUD needs the ui.hud permission:

omx-resource.json
{
  "id": "speed-hud",
  "name": "Speed HUD",
  "version": "1.0.0",
  "apiVersion": "2.0",
  "permissions": ["ui.hud"],
  "client": { "assembly": "SpeedHUD.dll" }
}

See The manifest for every field.

Build and install

Section titled “Build and install”
Terminal window
dotnet build -c Release

Copy the contents of bin/Release/net10.0 into a folder of its own under OMX’s resources folder, which is next to the OMX executable:

resources/
  speed-hud/
    omx-resource.json
    SpeedHUD.dll

Start OMX and drive a bus: the speed appears in the bottom-right corner. Resource load errors are printed to OMX’s log. To load resources from a different folder, start OMX with --resources <folder>; --no-resources turns them off.

A dedicated server loads its resources from the folder named by resourcesDirectory in its server.json.

Next steps

Section titled “Next steps”