1. For downloading SimTools plugins you need a Download Package. Get it with virtual coins that you receive for forum activity or Buy Download Package - We have a zero Spam tolerance so read our forum rules first.

    Buy Download Package Now!
  2. Do not try to cheat our system and do not post an unnecessary amount of useless posts only to earn credits here. We have a zero spam tolerance policy and this will cause a ban of your user account. Otherwise we wish you a pleasant stay here! Read the forum rules
  3. We have a few rules which you need to read and accept before posting anything here! Following these rules will keep the forum clean and your stay pleasant here. Do not following these rules will lead to permanent exclusion from this website: Read the forum rules.

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

Discussion in 'Tutorials and Tips by the Developer' started by yobuddy, Sep 23, 2016.

  1. yobuddy

    yobuddy Well-Known Member Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Feb 9, 2007
    Messages:
    3,062
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    32,377Coins
    Ratings:
    +3,142 / 10 / -0
    Work In Progress, (I need to better explain the new additions from 1.0) …
    - Added Example GamePlugin Downloads
    - Added GameVibe RPM example


    There are 3 sections of any new Game Plugin that needs to be completed in order to produce a compatible Game Plugin for SimTools 2.0.
    1) Game Plugin Settings – Basic settings for the new Game Plugin.
    2) Game Data Collection – Collecting and deciphering the data sent to SimTools.
    3) Game Patching – Patching/Un-Patching the game for output.

    The first thing you need to do is to figure out how you are going to get telemetry data out of the game.
    There is not always an obvious answer to the question, but often times looking up what engine the game is built on can provide some cues. Other times you can find information on Google about how to get telemetry data, and other times the games website provides an API to collect the data. And sometime there is not provided way to get data. (But it’s still possible to get the data need!)

    Below are some Game Plugin Examples that all use the 4 different ways to collect data from a game.
    Select the example below that is closest to what you are trying to accomplish, as a starting point for your plugin new game plugin.

    Example 1) UDP Output – (Example – Dirt2)
    These types of games export telemetry data via UDP packets.
    If your game uses UDP packets to export telemetry data, start with this example.
    (Some games in this category are: LFS, CodeMaster Games and NSR Stage 1)

    Dirt 2 - Example Game Plugin.zip

    Example 2) Memory Mapped File – (Example - Race 07)
    These types of games export telemetry data via Memory Mapped Files.
    If your game uses Memory Mapped Files to export telemetry data, start with this example.
    (Games in this category are: all SimBin Games)

    Race 07 - Example Game Plugin.zip

    Example 3) Memory Hooks – (Example - No Limits Coasters)
    These types of games will export telemetry data via Memory Hooks because no real form of telemetry exportation is available.
    If your game has no telemetry output supported, using Memory Hooks to export data may be your only option.
    If that is the case, start with this example.
    (Some games in this category are: No Limits Coasters and Need for Speed Shift)

    NoLimits Rollercoaster 1.8 - Example Game Plugin.zip

    Memory Hooks Examples:
    Example 1
    Example 2
    Example 3


    Example 4) Custom built DLL – (Example - rFactor)
    These types of games install a custom built DLL to export telemetry data. You usually download a SDK from the games website to compile this DLL. (Some games in this category are: rFactor and PCars)

    - When you create your custom game DLL, There are 2 main ways to send the data to SimTools.
    Way 1) The custom DLL collects the data needed from the game and sets it in a Memory Map file. From here your Game Plugin will install this DLL and treat the Game Plugin as any other memory mapped game.
    (In this case, use example 2 files above - Memory Mapped Files)

    Way 2) The custom DLL collects the data needed from the game and sends UDP packets with the data needed to the ‘_Port’ address assigned in the plugin. You then catch the UDP packets with the ‘Process_PacketReceived’ sub routine and assign values to Roll_Output, Pitch_Output etc...
    (In this case, use example 1 files above – UDP Output)

    Once you have created the custom DLL file for the game, Use one of the examples above to create the Game plugin.

    Let’s get started!!
    The following steps apply to all of the game plugins posted above, no matter which one you start with. The first thing to do is to set all of the basic settings for the game plugin.
    1) Open the selected plugin by unzipping the file and click on “PluginExample.sln”.
    2) Then double click on “GamePlugin.vb” in the editor.

    P1.jpg
    Section 1) Game Plugin Settings
    This is what you should be looking at: refer to this picture for the settings below.

    P2.jpg
    Per Game Settings
    _PluginAuthorsName - The name, or names, of people that have worked on the plugin.
    _GameName - This is name displayed in Game Managers list of available games.
    _ProcessName – The name that SimTools looks for in the windows processes list in order to tell if the game has started or stopped. You can have multiple comma delimited exe names if needed. Like this (dirt2_game, drt_fungame), you do not need to add the “.exe” to the name. This name is also not case sensitive.
    _Port – The Port used for sending and receiving information, plugins default to 4123 if the game does not otherwise state a port to use.
    _RequiresPatchingPath – Do we need to make any alterations to the game files? (If False, ValidatePathPath, PatchGame and UnpatchGame never get called, but the game is still marked as Patched.) (Must be True if _RequiresSecondCheck = True). Memory hook games don’t require file patching for example.
    _RequiresSecondCheck – 'Used when games have the same _ProcessName. (All plugins with the same _ProcessName must use this for it to work correctly!)
    _PluginOptions – Reserved for Future Use - No Change Needed

    Memory Map Variables
    _Enable_MemoryMap – if your plugin is a memory map game, set this to true. (See example plugin)
    _MMF_Name - if your plugin is a memory map game, enter the memory map file name here

    Memory Hook Variables
    _Enable_MemoryHook – if it is a memory hook game set to true. (See example plugin)
    _MemoryHook_Roll – if it is a memory hook game; enter the memory location for roll.
    _MemoryHook_Pitch – if it is a memory hook game; enter the memory location for pitch.
    _MemoryHook_Heave – if it is a memory hook game; enter the memory location for heave.
    _MemoryHook_Yaw – if it is a memory hook game; enter the memory location for yaw.
    _MemoryHook_Sway – if it is a memory hook game; enter the memory location for sway.
    _MemoryHook_Surge – if it is a memory hook game; enter the memory location for surge.
    _MemoryHook_Extra1 – if it is a memory hook game; enter the memory location for surge.
    _MemoryHook_Extra2 – if it is a memory hook game; enter the memory location for surge.
    _MemoryHook_Extra3 – if it is a memory hook game; enter the memory location for surge.

    DOF’s used for this game
    These values are used to control the red dots on the Profiles Page. (See pic below).
    They tell the user what DOF outputs are supported by the plugin.
    _DOF_Supported_Roll – set to true or false accordingly.
    _DOF_Supported_Pitch – set to true or false accordingly.
    _DOF_Supported_Heave – set to true or false accordingly.
    _DOF_Supported_Yaw – set to true or false accordingly.
    _DOF_Supported_Sway – set to true or false accordingly.
    _DOF_Supported_Surge – set to true or false accordingly.
    _DOF_Supported_Extra1 – “Traction Loss" Add a Force name here to set it to true.
    _DOF_Supported_Extra2 – "" Not Used set to blank.
    _DOF_Supported_Extra3 – "" Blank equals False.

    P3.jpg


    GameDash - Dash Board Support
    _Enable_DashBoard = False - Set to ‘True’ to enable the Dashboard Output System.
    (Basic Dash Support should include - SPEED, RPM and GEAR)
    Once enabled, you may assign up to 20 Dash output variables.


    ~ Examples~
    Assign the dash output variable as follows:
    Dash_1_Output = "Speed," & OUTPUT_VALUE_HERE.
    Dash_2_Output = "Rpm," & OUTPUT_VALUE_HERE
    ...

    GameVibe - Buttkicker Support

    _Enable_GameVibe = False - Set to ‘True’ to enable the GameVibe Output System.
    (Basic GameVibe Support should include – RPM)

    Once enabled, you may assign up to 9 Vibe output variables.
    The Names of the input is very important, as it tells GameVibe how to make sound out of the data.
    Here is the list of Names we can use in a Game Plugin.

    Name (What to output from the game)
    ~~~~~~~~~~~~~~~~~~~~~~~~
    Rpm (Rpm)
    Turbo (Turbo)
    Afterburners (Afterburners)
    Gear Shift (Current Gear)
    Road Detail (Heave)
    Turbulence (Speed)
    Collision L/R (Sway)
    Collision F/B (Surge)
    Chassis (FL, FR, RL, RR)

    ~ Examples~
    Assign the 3D Chassis variable like this:
    Vibe_6_Output = "Chassis," & SuspensionPositionFrontLeft_Var & ":" & SuspensionPositionFrontRight_Var & ":" & SuspensionPositionRearLeft_Var & ":" & SuspensionPositionRearRight_Var
    Assign all other vibe output variables as follows:
    (Please set RPM to Vibe_1_Output)
    Vibe_1_Output = "Rpm," & OUTPUT_VALUE_HERE
    Vibe_2_Output = "Gear Shift," & OUTPUT_VALUE_HERE
    ...


    Section 2) Game Data Collection
    Game Start and Game Stop
    If your game plugin requires any extra commands to start or stop the collection of data, it can be entered here.

    P4.jpg
    Process a Memory Hook
    Place your end results in the output variables, Roll_MemHook, Pitch_MemHook, Etc...
    NoLimitsCoasters – Example shown - Roll, Pitch etc... Memory readings are strait forward.
    No need to alter the Process_PacketsReceived subroutine when using a memory hooked game.

    P5.jpg
    Process a Memory Map
    Place your end results in the output variables, Roll_MemMap, Pitch_MemMap, Etc...
    GTR2 – Example Plugin - The data structure is copied from memory and then outputs are assigned to the MemMap variables.
    No need to alter the Process_PacketsReceived subroutine when using a memory mapped game.

    P6.jpg
    Process the Packets Received
    Decipher the incoming UDP packets from the Game or Game Manager into Game Engine. The following is an example of deciphering the outsim udp packet captured directly from the game. See the Live for Speed example plugin for more info. Simply place the end results in the output variables, Roll_Output, Pitch_Output, etc... (There is no need to alter this subroutine if you are using a memory mapped or memory hooked game) (Used by GameEngine)

    P7.jpg

    Section 3) Patching the Game
    This section will show you how to construct a patching routing for the game section of SimTools

    P8.jpg
    PatchPathInfo
    This is used to tell the user the location they should patch there game at. It is presented to the user when they press the “Edit Path” button in GameManager.

    ValidatePatchPath
    Used to enable or disable the “Patch Game” button in GameManager. In the picture above, we see that the user has a valid path, when the path has the file “LFS.exe” present. (In other words, it makes the user select Live for Speeds installation folder)

    PatchGame
    Used to install a DLL (rFactor plugin example) or edit a .txt or .cfg file (Live for Speed plugin example) to achieve telemetry output from the game. With most games, I made a backup of the file I’m going to edit and save it to cfg.BAK.

    UnPatchGame
    Used to remove whatever alterations were made to the game during the PatchGame procedure.
    You do not need to edit sections that look like this:
    Doing so will probably only make things not work as they should

    P9_NoEdit.jpg

    That’s it!
    Let’s compile your new plugin!
    How to Compile the Plugin
    Click on “My Project”

    P10_Compile.jpg
    Make sure the “application” tab is selected. Now name the Game Plugin DLL as follows: GameName (without spaces) + _GamePlugin.
    So for this example we get ‘LiveForSpeed_GamePlugin’. Use this name for both the ‘Assembly Name’ and the ‘Root Namespace’ as in the picture below

    P11_Compile.jpg
    Right click on GamePlugin in the solution explorer and select Build!
    P12_Compile.jpg
    Your new Game plugin can now be found in the folder;
    ExamplePluginFolder\ GamePlugin\GamePlugin\bin\Release\MyPlugin_GamePlugin.dll
    Run ‘PluginValidator.exe’ in the same folder to validate your new plugin.

    P13_Compile.jpg

    Congratulations!!
    Your new Game Plugin is complete!

    Now install it into SimTools 2.0 and test out your work!
    • Like Like x 3
    Last edited: Mar 30, 2018
  2. value1

    value1 Nerd Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Jan 9, 2011
    Messages:
    2,044
    Location:
    Zug, Switzerland
    Balance:
    4,534Coins
    Ratings:
    +2,882 / 10 / -1
    My Motion Simulator:
    2DOF, DC motor, JRK, Joyrider
    Conventions for plugins

    Nomenclature of movements in SimTools
    Pitch is the tilt of the car forwards or backwards in [°]
    Roll is how much the car is dipped to the left or right in [°]
    Yaw is the heading of the car (north, east, south, west) in [°]

    Surge means the acceleration of the car in longitudinal direction [g]
    Sway means the acceleration of the car in lateral direction [g]
    Heave means the acceleration up and down [g]
    Axes.gif
    Direction of movements in SimTools
    Acceleration → pitch slider moves to left, surge slider moves to right
    Deceleration (braking) → pitch slider moves to right, surge slider moves to left
    Right turn → roll slider moves to left, sway slider moves to right, yaw slider moves to left
    Turn right.jpg
    Left turn → roll slider moves to right, sway slider moves to left, yaw slider moves to right
    Turn left.jpg
    Driving downhill → pitch slider moves to right
    Downhill Slider Pitch.jpg
    Driving uphill → pitch slider moves to left
    Uphill Slider Pitch.jpg
    Tilted to the left → roll slider moves to left
    Tilted left Slider Roll.jpg
    Tilted to the right → roll slider moves to right
    Tilted right Slider Roll.jpg
    Where available a plugin shall also issue Speed, RPM and Gear as a minimum for dashboard applications.
    Extra1 data is Traction Loss per default. However this is not mandatory.

    See also this thread for a graphical representation and explanation.
    • Winner Winner x 2
    • Informative Informative x 2
  3. vthinsel

    vthinsel Active Member

    Joined:
    Feb 20, 2015
    Messages:
    343
    Location:
    FRANCE
    Balance:
    4,226Coins
    Ratings:
    +434 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino
    Great. Will the examples be posted soon ? I cant wait to port my pCars UDP plugin to the simtools 2.0 :)
    • Like Like x 1
  4. Daguru

    Daguru Rally drivers do it in the mud

    Joined:
    Sep 4, 2013
    Messages:
    520
    Occupation:
    window cleaner
    Location:
    Wales uk
    Balance:
    951Coins
    Ratings:
    +494 / 0 / -0
    My Motion Simulator:
    2DOF
    I too would like to see the examples @yobuddy :thumbs
  5. yobuddy

    yobuddy Well-Known Member Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Feb 9, 2007
    Messages:
    3,062
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    32,377Coins
    Ratings:
    +3,142 / 10 / -0
    Working on them guy's!
    Will be posted sometime after the weekend.
    • Like Like x 2
    • Winner Winner x 1
  6. Blame73

    Blame73 Yet it moves!

    Joined:
    Nov 6, 2014
    Messages:
    1,136
    Location:
    Italy
    Balance:
    8,047Coins
    Ratings:
    +988 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    Any news @yobuddy?
  7. Daguru

    Daguru Rally drivers do it in the mud

    Joined:
    Sep 4, 2013
    Messages:
    520
    Occupation:
    window cleaner
    Location:
    Wales uk
    Balance:
    951Coins
    Ratings:
    +494 / 0 / -0
    My Motion Simulator:
    2DOF
    To be fair he didn't say which weekend lol:grin
    • Funny Funny x 2
  8. yobuddy

    yobuddy Well-Known Member Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Feb 9, 2007
    Messages:
    3,062
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    32,377Coins
    Ratings:
    +3,142 / 10 / -0
    Hi Guy's,
    We have selected some good example game plugin files.
    I need to go thru them and check if I need to add notes anywhere.
    And then I will get to posting them.
    Almost there... lol
    yobuddy
    • Like Like x 2
    • Winner Winner x 2
  9. SeatTime

    SeatTime Well-Known Member SimTools 2.0 Beta Tester

    Joined:
    Dec 27, 2013
    Messages:
    2,034
    Location:
    Newcastle Australia
    Balance:
    25,397Coins
    Ratings:
    +2,343 / 20 / -0
    My Motion Simulator:
    DC motor, Motion platform, 6DOF
    Excellent, I've been waiting for this. - pulls programming hat out of the cupboard and brushes off dust :).
    • Like Like x 1
    • Agree Agree x 1
  10. vthinsel

    vthinsel Active Member

    Joined:
    Feb 20, 2015
    Messages:
    343
    Location:
    FRANCE
    Balance:
    4,226Coins
    Ratings:
    +434 / 1 / -0
    My Motion Simulator:
    2DOF, DC motor, Arduino
    I'll be on holidays this week, and the weather is not likely to be brilliant.... luckily, I have my laptop with Visual Studio and Project Cars. If the sample UDP plugin could arrive, I could probably port my previous work to simtools v2 :p
    Especially as GameDash 2.0 is now available. :thumbs
    • Like Like x 3
  11. DVThomas

    DVThomas New Member Gold Contributor

    Joined:
    Jan 26, 2017
    Messages:
    1
    Location:
    France
    Balance:
    2Coins
    Ratings:
    +0 / 0 / -0
    My Motion Simulator:
    3DOF
    Hey everyone,

    I recently purchased a 3DOF motion simulator and a license of Simtools 2.0 expecting to be able to get to work on a plugin, but I'm struggling to find how to get started without the examples for the new API. Is there any other resource I could use to get started while the examples are still being worked on?
  12. noorbeast

    noorbeast VR - The Next Generation Staff Member Moderator SimTools 2.0 Beta Tester

    Joined:
    Jul 13, 2014
    Messages:
    11,763
    Occupation:
    Innovative tech specialist for NGOs
    Location:
    St Helens, Tasmania, Australia
    Balance:
    91,407Coins
    Ratings:
    +7,686 / 37 / -2
    My Motion Simulator:
    3DOF, DC motor, JRK
    @yobuddy is currently preparing examples on how to create plugins for SimTools 2.0, they will be released soon.
  13. yobuddy

    yobuddy Well-Known Member Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Feb 9, 2007
    Messages:
    3,062
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    32,377Coins
    Ratings:
    +3,142 / 10 / -0
    Example Game Plugins posted :thumbs
    • Winner Winner x 4
    • Like Like x 1
  14. noorbeast

    noorbeast VR - The Next Generation Staff Member Moderator SimTools 2.0 Beta Tester

    Joined:
    Jul 13, 2014
    Messages:
    11,763
    Occupation:
    Innovative tech specialist for NGOs
    Location:
    St Helens, Tasmania, Australia
    Balance:
    91,407Coins
    Ratings:
    +7,686 / 37 / -2
    My Motion Simulator:
    3DOF, DC motor, JRK
    Whoohoo...tapping @Ville Pesonen on the shoulder so hopefully the War Thunder plugin can be updated for 2.0!
    • Like Like x 2
  15. Ville Pesonen

    Ville Pesonen Active Member

    Joined:
    Jan 13, 2015
    Messages:
    131
    Balance:
    839Coins
    Ratings:
    +189 / 0 / -0
    My Motion Simulator:
    2DOF
    Thanks for the heads up. I'll give it a go.
    • Like Like x 1
    • Winner Winner x 1
  16. Ville Pesonen

    Ville Pesonen Active Member

    Joined:
    Jan 13, 2015
    Messages:
    131
    Balance:
    839Coins
    Ratings:
    +189 / 0 / -0
    My Motion Simulator:
    2DOF
    I am having some problems writing a plugin for War Thunder. I am using the Example 3 for memory hooks as a basis for the plugin.

    I only get motion data out to Simtools in the Public Sub Process_MemoryHook() by assigning values to these:
    Heave_MemHook
    Surge_MemHook
    Sway_MemHook
    When I add values to the other variables (Roll_MemHook,Pitch_MemHook,Yaw_MemHook,Extra1/2_MemHook), they output 0 to the Simtools.
    I've enabled the DOFS in the beginning of the plugin code:
    prolems1.PNG
    the memory locations are not valid as the plugin gets the values via TCP from the game.

    I've tried to put the values that I use for Roll/Pitch/Yaw/extra1/extra2 through the Heave, Surge and Sway Memhook variables and they work.

    Here's an example of the problem. I assign variable "Elevator" to the Pitch_Memhook and Heave_Memhook and Tuning manager only shows the value in Heave, not in pitch. The same problem happens with Surge_Memhook and Yaw_Memhook with the variable Rudder. and then with Sway_Memhook/Extra1_Memhook with the variable aviahorizon_roll
    problems3.PNG


    EDIT:
    got it to work... the problem was in the Public Sub Process_PacketRecieved
    It had some 0 in it so I fixed it. Took me a while to find the problem.
    Public Sub Process_PacketRecieved(Text As String) Implements IPlugin_Game.Process_PacketRecieved
    'DO SOMETHING HERE TO RECIEVED UDP PACKETS
    Input_Data = CType(DeSerializeString(Text), GenericOutput)
    With Input_Data
    Roll_Output = 0
    Pitch_Output = ._Pitch
    Heave_Output = ._Heave
    Yaw_Output = ._Yaw
    Sway_Output = ._Sway
    Surge_Output = ._Surge
    Extra1_Output = ._Extra1
    Extra2_Output = ._Extra2
    End With
    End Sub
    • Informative Informative x 1
    • Useful Useful x 1
    Last edited: Feb 14, 2017
  17. yobuddy

    yobuddy Well-Known Member Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Feb 9, 2007
    Messages:
    3,062
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    32,377Coins
    Ratings:
    +3,142 / 10 / -0
    @Ville Pesonen,
    Is this error in the example itself buddy?
    I'd like to update it if it is.

    Also as we go along, if there is anything I need to add to any of the examples to make them easier, let me know guys.

    yobuddy
  18. Ville Pesonen

    Ville Pesonen Active Member

    Joined:
    Jan 13, 2015
    Messages:
    131
    Balance:
    839Coins
    Ratings:
    +189 / 0 / -0
    My Motion Simulator:
    2DOF
    I just checked and the error is in the example plugin itslef:
    exampleplugin.PNG
    It started to work when I modified it to look like this:
    exampleplugin2.PNG
  19. value1

    value1 Nerd Staff Member Moderator SimTools Developer SimAxe Beta Tester Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    Jan 9, 2011
    Messages:
    2,044
    Location:
    Zug, Switzerland
    Balance:
    4,534Coins
    Ratings:
    +2,882 / 10 / -1
    My Motion Simulator:
    2DOF, DC motor, JRK, Joyrider
    Sorry, but this is not an error in the plugin. If you read the source code of the plugin carefully, NoLimits V1.8 only provides surge, sway and heave. Therefore the other values must be 0.

    In your case – where you also provide other data – you must indeed add these values in the subroutine!
  20. noorbeast

    noorbeast VR - The Next Generation Staff Member Moderator SimTools 2.0 Beta Tester

    Joined:
    Jul 13, 2014
    Messages:
    11,763
    Occupation:
    Innovative tech specialist for NGOs
    Location:
    St Helens, Tasmania, Australia
    Balance:
    91,407Coins
    Ratings:
    +7,686 / 37 / -2
    My Motion Simulator:
    3DOF, DC motor, JRK
    Is SimTools in demo mode...it has to be licensed to load plugins other than LFS.
    • Agree Agree x 2
    • Like Like x 1