Tutorial How to write a Game Plugin for SimTools 2.0 - API documentation

Big thank
I just think if plugin can collect data, it also can bring it to other file or sent to Matlab. (not sure if I'm right ?)
But setup interface plugin is also interesting. I'll try that.

sorry about pictures

I guess at "GameManager to Patch a Game". It can pass the condition about "hardware_setting_config.xml" and "cfg.BAK" but at the detail of "MyFileEditor", may be something isn't match.

Good luck to all my friends. Tell me what I'm doing wrong, I'm trying to write a plugin for F1 2020 UDP, telemetry data is intercepted, at the start of the game, GameEnginer issues an application error and closes. What am I doing wrong?

The recorded telemetry is intercepted through the All.telemetria program, but when the game starts, the Game Engine issues an application error and closes.

Greetings to all my friends. I still haven't solved my problem. I just found out that if I comment out this line

'System.Runtime.InteropServices.Marshal.Copy(ByteArray, 0, AddofLongValue, ByteArray.Length)

then the GameEnginer does not close when the game starts, but there is no data. If you uncomment it, it immediately closes when you start the game F1_22, before closing the Game engine, you can see that bytes are displayed, not half. I keep trying to figure it out, but I've already broken my head. If anyone helps, I will be grateful.

Option Explicit On
Option Strict On

Imports Game_PluginAPI
Imports System.IO

Public Class GamePlugin
Implements IPlugin_Game
'//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'/// SimTools Plugin - Edit the Setting below to provide support for your favorite game! ///
'//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
'////////////////////////////////////////////////
'/// Per Game Settings - Change for Each Game ///
'////////////////////////////////////////////////
Private Const _PluginAuthorsName As String = "yobuddy"
Private Const _GameName As String = "F1 22" 'GameName (Must Be Unique!) - the displayed Name.
Private Const _ProcessName As String = "F1_22" 'Process_Name without the (".exe") for this game
Private Const _Port As String = "20777" 'Your Sending/Recieving UDP Port for this game
Private Const _RequiresPatchingPath As Boolean = True 'do we need the game exe path for patching? (must be True if _RequiresSecondCheck = True)
Private Const _RequiresSecondCheck As Boolean = False 'Used when games have the same _ProcessName. (all plugins with the same _ProcessName must use this!)
Private Const _PluginOptions As String = "" 'Reserved For Future Use - No Change Needed
'////////////////////////////////////////////////
'/// Memory Map Variables ///
'////////////////////////////////////////////////
Private Const _Enable_MemoryMap As Boolean = False 'Is a MemoryMap file Required for this game?
Private Const _MMF_Name As String = "NULL" 'Set if using a Memory Map File - EXAMPLE("$gtr2$")
'////////////////////////////////////////////////
'/// MemoryHook Variables ///
'////////////////////////////////////////////////
Private Const _Enable_MemoryHook As Boolean = False 'Is a Memory Hook Required for this game?
Private Const _MemHook_Roll As UInteger = 0 'Not Used = 0
Private Const _MemHook_Pitch As UInteger = 0
Private Const _MemHook_Heave As UInteger = 0
Private Const _MemHook_Yaw As UInteger = 0
Private Const _MemHook_Sway As UInteger = 0
Private Const _MemHook_Surge As UInteger = 0
Private Const _MemHook_Extra1 As UInteger = 0
Private Const _MemHook_Extra2 As UInteger = 0
Private Const _MemHook_Extra3 As UInteger = 0
'////////////////////////////////////////////////
'/// DOFs Used for Output for this Game ///
'////////////////////////////////////////////////
Private Const _DOF_Support_Roll As Boolean = True
Private Const _DOF_Support_Pitch As Boolean = True
Private Const _DOF_Support_Heave As Boolean = True
Private Const _DOF_Support_Yaw As Boolean = True
Private Const _DOF_Support_Sway As Boolean = True
Private Const _DOF_Support_Surge As Boolean = True
Private Const _DOF_Support_Extra1 As String = "Traction Loss" 'Blank = False
Private Const _DOF_Support_Extra2 As String = "" '"" = Not Used
Private Const _DOF_Support_Extra3 As String = "" 'ADD THE FORCE NAME HERE
'/////////////////////////////////////////////////
'/// GameDash - Dash Board Support ///
'/////////////////////////////////////////////////
Private Const _Enable_DashBoard As Boolean = False 'Enable the DashBoard Output System?
'EXAMPLES OF DASH OUTPUT (all variables are strings) - 20 DASH OUTPUTS MAX!!!
'Use the Variables with either Process_PacketRecieved, Process_MemoryHook or Process_MemoryMap.
'Variable = (*Action, Value) as String - (The *Action variable can be anything)
'Basic Dash Support should include at the minimum - SPEED, RPM and GEAR
'Dash_1_Output = "Speed," & OUTPUT_VALUE_HERE.ToString
'Dash_2_Output = "Rpm," & OUTPUT_VALUE_HERE.ToString
'Dash_2_Output = "Gear," & OUTPUT_VALUE_HERE.ToString
'...
'Dash_20_Output = "Engine Temp," & OUTPUT_VALUE_HERE.ToString
'/////////////////////////////////////////////////
'/// GameVibe Support ///
'/////////////////////////////////////////////////
Private Const _Enable_GameVibe As Boolean = False 'Enable the GameVibe Output System?
'EXAMPLES OF GameVibe OUTPUT (all variables are strings) - 9 GameVibe OUTPUTS MAX!!!
'Use the Variables with either Process_PacketRecieved, Process_MemoryHook or Process_MemoryMap.
'Variable = (*Action, Value) as String - (The *Action" variable can ONLY be: Rpm, Heave, Sway, Surge, FR, FL, RR, RL, Turbo)
'Basic GameVibe Support should include at the minimum - Rpm
'Vibe_1_Output = "Rpm," & OUTPUT_VALUE_HERE.ToString
'Vibe_2_Output = "Heave," & OUTPUT_VALUE_HERE.ToString
'Vibe_3_Output = "Sway," & OUTPUT_VALUE_HERE.ToString
'Vibe_4_Output = "Surge," & OUTPUT_VALUE_HERE.ToString
'...
'Vibe_9_Output = "Gear Shift," & OUTPUT_VALUE_HERE.ToString
'/////////////////////////////////////////////////

'Used by GameManager when the Game Starts.
Public Sub GameStart() Implements IPlugin_Game.GameStart
'DO SOMETHING HERE AT GAME START!
End Sub

'Used by GameManager when the Game Stops.
Public Sub GameStop() Implements IPlugin_Game.GameEnd
'DO SOMETHING HERE AT GAME STOP!
End Sub

'Used by GameManager to Process a MemoryHook.
Public Sub Process_MemoryHook() Implements IPlugin_Game.Process_MemoryHook
'DO SOMETHING HERE AT GAME START!
End Sub

'Used by GameManager to Process a MemoryMap.
Public Sub Process_MemoryMap() Implements IPlugin_Game.Process_MemoryMap
'DO SOMETHING HERE AT GAME START!
End Sub

'Used by GameEngine to Process Incoming UDP Packets.
Public Sub Process_PacketRecieved(Text As String) Implements IPlugin_Game.Process_PacketRecieved

'Convert string to byte and copy to byte array
Dim ByteArray() As Byte = System.Text.Encoding.Default.GetBytes(Text)

'Create Gchandle instance and pin variable required
Dim MyGC As System.Runtime.InteropServices.GCHandle = System.Runtime.InteropServices.GCHandle.Alloc(MyOutsim_Internal, System.Runtime.InteropServices.GCHandleType.Pinned)

'get address of variable in pointer variable
Dim AddofLongValue As IntPtr = MyGC.AddrOfPinnedObject()

'Скопируйте пространство памяти в мой GCHandle
System.Runtime.InteropServices.Marshal.Copy(ByteArray, 0, AddofLongValue, ByteArray.Length)

'Direct Cast myGC to my Outsim Object
MyOutsim_Internal = DirectCast(MyGC.Target, OutSim)

'Free GChandle to avoid memory leaks
MyGC.Free()

'Get Proper Data out of UDP Packet
With MyOutsim_Internal
Roll_Output = ((.sngOrientation2 * 180 / 3.14159) - 90)
Pitch_Output = (.sngOrientation1 * 180 / 3.14159) * -1
Heave_Output = (System.Math.Cos(.sngOrientation2) * .sngAcceleration2)
Yaw_Output = (.sngOrientation0 * 180 / 3.14159)
Sway_Output = ((System.Math.Cos(.sngOrientation0) * .sngAcceleration0) + (System.Math.Sin(.sngOrientation0) * .sngAcceleration1))
Surge_Output = ((-System.Math.Sin(.sngOrientation0) * .sngAcceleration0) + (System.Math.Cos(.sngOrientation0) * .sngAcceleration1))
Extra1_Output = (((System.Math.Sin(.sngOrientation0) * .sngAcceleration0) + (System.Math.Sin(.sngOrientation0) * .sngAcceleration1)) * -1)
End With
End Sub

'Used by GameManager to Patch a Game.
Public Function PatchGame(ByVal MyPath As String, ByVal MyIp As String) As Boolean Implements IPlugin_Game.PatchGame
'Change as Needed
'If game is already patched - Unpatch first
UnPatch(MyPath)
If System.IO.File.Exists(MyPath & "\F1_22.exe") = True Then
Try
System.IO.File.Copy(MyPath & "\system\hardware_settings_config.xml", MyPath & "\system\cfg.BAK")
SetAttr(MyPath & "\system\hardware_settings_config.xml", GetAttr(MyPath & "\system\hardware_settings_config.xml") And (Not vbReadOnly))
MyFileEditor(MyPath & "\system\hardware_settings_config.xml", "<motion enabled=", "<motion enabled=" & Chr(34) & "true" & Chr(34) & " ip=" & Chr(34) & MyIp & Chr(34) & " port=" & Chr(34) & "4123" & Chr(34) & " delay=" & Chr(34) & "1" & Chr(34) & " extradata=" & Chr(34) & "0" & Chr(34) & " />")
MsgBox("Patch Installed!")
Return True
Catch ex As Exception
MsgBox("You Must first Install and Run the Game Once Prior to Patching" + vbCrLf + "You may also add Custom Game Installation Directories below!")
Return False
End Try
Else
Try
System.IO.File.Copy(MyPath & "\hardwaresettings\hardware_settings_config.xml", MyPath & "\hardwaresettings\cfg.BAK")
SetAttr(MyPath & "\hardwaresettings\hardware_settings_config.xml", GetAttr(MyPath & "\hardwaresettings\hardware_settings_config.xml") And (Not vbReadOnly))
MyFileEditor(MyPath & "\hardwaresettings\hardware_settings_config.xml", "<motion enabled=", "<motion enabled=" & Chr(34) & "true" & Chr(34) & " ip=" & Chr(34) & MyIp & Chr(34) & " port=" & Chr(34) & "4123" & Chr(34) & " delay=" & Chr(34) & "1" & Chr(34) & " extradata=" & Chr(34) & "0" & Chr(34) & " />")
MsgBox("Patch Installed!")
Return True
Catch ex As Exception
MsgBox("You Must first Install and Run the Game Once Prior to Patching" & vbCrLf & "You may also add Custom Game Installation Directories below!")
Return False
End Try
End If
End Function

'Used by GameManager to UnPatch a Game.
Public Sub UnPatchGame(MyPath As String) Implements IPlugin_Game.UnPatchGame
'Change as Needed
UnPatch(MyPath)
MsgBox("Patch Uninstalled!", MsgBoxStyle.OkOnly, "Patching info")
End Sub

'Used by GameManager to UnPatch a Game.
Private Sub UnPatch(MyPath As String)
If System.IO.File.Exists(MyPath & "\dirt2_game.exe") = True Then
If File.Exists(MyPath & "\system\cfg.BAK") Then 'Restore backup File
If File.Exists(MyPath & "\system\hardware_settings_config.xml") Then
System.IO.File.Delete(MyPath & "\system\hardware_settings_config.xml")
End If
Rename(MyPath & "\system\cfg.BAK", MyPath & "\system\hardware_settings_config.xml")
End If
Else
If File.Exists(MyPath & "\hardwaresettings\cfg.BAK") Then 'Restore backup File
If File.Exists(MyPath & "\hardwaresettings\hardware_settings_config.xml") Then
System.IO.File.Delete(MyPath & "\hardwaresettings\hardware_settings_config.xml")
End If
Rename(MyPath & "\hardwaresettings\cfg.BAK", MyPath & "\hardwaresettings\hardware_settings_config.xml")
End If
End If
End Sub

'Tells the User where to patch the game
Public Sub PatchPathInfo() Implements IPlugin_Game.PatchPathInfo
'Tell the User where to patch the game
MsgBox("32bit PC's - Please Select F1 22's Installation Directory." & vbCrLf & "64bit PC's - Please Select F1 22's Game Save Directory" & vbCrLf & "(64bit's default location is Documents\MyGames\F1 22).", MsgBoxStyle.OkOnly, "Patching info")
End Sub

'Used by GameManager to Validate a Path befors Patching.
Public Function ValidatePatchPath(MyPath As String) As Boolean Implements IPlugin_Game.ValidatePatchPath
'insert a simple validation of the patching path - let the user know he got it right
If System.IO.File.Exists(MyPath & "\F1_22.exe") = True Or System.IO.File.Exists(MyPath & "\hardwaresettings\hardware_settings_config.xml") = True Then
Return True
Else
Return False
End If
End Function

The code is incomplete so as not to clog up the chat

Dirt Rally this code works without problems, the game engine does not close and the data is coming. On F1 22, I tried to change UDP protocols in different 2018, 2019, 2020, 2022, nothing helps.

Hello guys!
I'm new in the world of simulators and SimTools and would like to ask you for some guidance.
I have a software that launches a "driving simulation", this simulation shares out values through an UDP socket. I wanted to create a Plugin in SimTools to then take this values and execute the actions (SimTools already works with other games).
When my driving simulation starts, a new process starts and this process I wrote under " _ProcessName". However, when trying to patch this Plugin, there is no cfg.bak or hardware_settings_config.xml file, as this is just an executable with location in System32. I tried then to select RequiredPatch to False, but when I run the simulation (after installing the Plugin using the Updater), SimTools doesnt detect execution (GameEngine doesnt turn blue).
For the configuration of my simulation, there is a config file where I manually placed port, IP, etc. (location different than System32, so executable is in another place).

Is this approach correct? Should I instead make an interface? What would be the difference? I don't know if King @yobuddy can assist me on this one?

I would really appreciate your help

Hi @yobuddy !
Thank you so much for the response.

I am still a bit unsure on why do I need to create a patching routine if I can manually place the port and IP in my UDP socket configuration. Which changes should the Patch routine execute (my file is not a XML but an INC, differently written in comparison to for example: <motion enabled="true" ip="192.168.0.10" port="20777" delay="1" extradata="0" />)?

Im starting to do the test file as you suggested!
Thanks in advance

Hi, I'm trying to write a game plugin for a game called VTOL VR (military flight sim built with VR in mind).
The game runs a mod called "FlyPT Mover telemetry" that makes it send telemetry via UDP, so I thought the Dirt 2 example project would be a good start.

Unfortunately, I am not able to even make dummy data from the plugin appear in TuningCenter.

This is what I did:

• I downloaded the Dirt 2 example project and opened it in Visual Studio 2022.
• I was told that the project was made for .Net v4.0 and I need to update to v4.8 - OK
• In "Project" I changed Assemblyname and Namespace to "VTOLVR_GamePlugin" (the exe of the Game is VTOLVR.exe). See attached Pic01.
• I updated PluginAuthorsName and entered VTOLVR for GameName and ProcessName. See attached Pic02.
• In Sub Process_PacketRecieved I removed the original code for parsing the data and calculating the outputs. Instead I entered constant dummy values for all the outputs. See attacht Pic03. The Idea is to do a first check and see if these dummy values appear in TuningCenter. If this works I can start working on parsing the data and doing calculations. I tried this method with Dirt 2 and it worked.
• I removed the code within all those subs that are associated with patching. See attached Pic04.
• Then I built the project, validated the dll and copied it into c:\Users\<Username>\AppData\Local\SimTools\GamePlugins\
• I started GameEngine and GameManager and VTOLVR showed up in the lists of games
• I start VTOLVR, activate the telemetry mod, start to flyy and then check GameManager and see that it recocgnizes that VTOLVR is running (blue banner). However, TuningCenter does not show any output coming from the plugin. I was expecting to see the dummy data. System locale is english. See attached Pic05.

My project including the compiled DLL can be found here:
https://drive.google.com/file/d/1U1RJrf131VZtWuuY41baRASxpV-UEn6M/view?usp=sharing

To make things more odd, I have two versions of a VTOL VR plugin that forum member Map63Vette kindly send me. The first one works for me in principle, but is missing roll rate, which is important to me. I asked him if he could add roll rate, to which he replied that the source code used to create the first plugin got lost in the sands of time. But lo and behold, he took the Dirt 2 example project, recreated his old plugin and added roll rate. How nice is that? There's just one catch: this new plugin does not work for me (no data in TuningCenter), but it works for him. Seems like there is something wrong on my side...

I am successfully using SimTools with Dirt 2, MSFS2020 and DCS (both, the normal and the experimental plugin).

Can anbody help me with this?

Thanks for the quick reply.

I added "Return True" for the functions in Pic04, see attached Pic04mod.

The edited project files including the compiled dll can be found here:

https://drive.google.com/file/d/1U2e7_-bmun0Uf-V9ivnC-Jq_v64xRVKf/view?usp=sharing

It still does not work.

GameManager shows that VTOLVR is recognized but TuningCenter is still all zeroes while in flight. While the game is still running and paused, I can close GameEngine and GameManager, switch out the DLL I made with the one I got from Map63Vette (the one without roll rate, the one that works for me, the one where the source code is lost), and start GameEngine and GameManager again. Then TuningCenter is populated with values that make sense. This shows that VTOLVR is outputting data and it is possible to concieve a Plugin that communicates successfully with SimTools. I just fail to replicate that.

I assume the two functions I edited are only called when I try to patch the game, so it makes sense to me that Return True does not make a difference. The game doesn't need a patch to output telemetry (this is done by the mod).

I also tried nebrivs plugin. That is, I downloaded his source code and tried to build it, but that failed. I get dozens of error messages saying something about type "IPlugin_Game" is undefined (i'm translating from german here, so the wording might be a little off).
I tried contacting nebriv about that a coulple of days ago, but he didn't reply yet. Can anyone here help me with that? Does this project compile for you?

https://github.com/nebriv/VTOLVR-SimTools/tree/master