1. Do not share user accounts! Any account that is shared by another person will be blocked and closed. This means: we will close not only the account that is shared, but also the main account of the user who uses another person's account. We have the ability to detect account sharing, so please do not try to cheat the system. This action will take place on 04/18/2023. Read all forum rules.
    Dismiss Notice
  2. 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 Now a Download Plan!
  3. 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
  4. 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. Do not follow these rules can lead to permanent exclusion from this website: Read the forum rules.
    Are you a company? Read our company rules

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

Discussion in 'SimTools Plugins' started by yobuddy, Aug 6, 2013.

  1. yobuddy

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

    Joined:
    Feb 9, 2007
    Messages:
    5,133
    Occupation:
    Computer Technician
    Location:
    Portland, Oregon - USA
    Balance:
    47,911Coins
    Ratings:
    +5,027 / 16 / -0
    There are 3 sections of any new plugin that need to be completed in order to produce a compatible plugin for SimTools.
    1) Game Plugin Settings – All of the settings for the new 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.
    Below are 4 plugin examples that all use different ways to collect data from a game.
    Select the one that is closest to what you are trying to accomplish as a starting point for your plugin.

    1) Live for Speed – Example Plugin – 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, NSR Stage 1)
    LFS_V3_Source_Dash.zip
    2) GTR2 – Example Plugin - 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. (Some games in this category are: all SimBin Games)
    GTR2_V3_Source.zip
    3) NoLimitsCoasters – Example Plugin - 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: NoLimitsCoasters, Need for Speed Shift)
    NoLimits_V3_Source_v1.8.zip
    Memory Hooks Examples:
    Example 1
    Example 2
    Example 3

    4) rFactor – Example Plugin - 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: all rFactor, PCars)
    - When you create your custom game DLL, There are 2 main ways to have SimTools collect the data.
    1) The custom DLL collects the data needed and sets it in a Memory Map file. From here your Game DLL will install this DLL and treat it as any other memory mapped game. (use example two files above)
    2) The custom DLL directly broadcasts the 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...
    rFactor_V3_Source.zip

    Let’s get started!!
    The following steps apply to all plugins, no matter which one you start with. The first thing to do is to set all of the setting for the plugin.
    1) Open the selected plugin by unzipping and clicking on “PluginExample.sln”.
    2) Then click on “Plugin.vb” in the editor.
    Plugin_0.jpg
    1) Game Plugin Settings
    This is what you should be looking at; refer to this picture for the settings below.
    (To Be Posted)
    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 games available.
    _ProcessName – the name that SimTools looks for in windows processes list in order to tell if the game has started or stopped.
    _Port – the Port used for sending and receiving information, all plugins use 4123 as of this posting.

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

    Memory Hook Variables
    _Is_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 control the red dots on the Profiles Page. See below.
    They tell the user what DOF outputs are supported by the plugin.
    _DOF_Supported_Roll – set to true of false accordingly.
    _DOF_Supported_Pitch – set to true of false accordingly.
    _DOF_Supported_Heave – set to true of false accordingly.
    _DOF_Supported_Yaw – set to true of false accordingly.
    _DOF_Supported_Sway – set to true of false accordingly.
    _DOF_Supported_Surge – set to true of false accordingly.
    _DOF_Supported_Extra1 – = not used.
    _DOF_Supported_Extra2 – = not used.
    _DOF_Supported_Extra3 – = not used.

    Plugin_2.2.jpg
    GameDash - Dash Board Support
    _Is_DashBoard = False - Set to True to enable the Dashboard Output System?
    Once enabled you may assign up to 20 dash output variables.
    You may the Variables anywhere within the plugin, but often used with either Process_PacketRecieved, Process_MemoryHook or Process_MemoryMap.
    Assign the dash output variable as follows:
    Dash_1_Output = Speed, & OUTPUT_VALUE_HERE.
    Dash_2_Output = Rpm, & OUTPUT_VALUE_HERE
    ...


    2) Game Data Collection
    Startup and Shutdown Commands
    if your game needs any extra commands to start or stop the collection of data, it can be entered here.
    Plugin_2.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.
    Plugin_11.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.
    Plugin_10.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)
    Plugin_4.jpg

    3) Patching the Game
    This section will show you how to construct a patching routing for the game section of SimTools
    Plugin_5.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.


    How to Compile the Plugin
    Click on “My Project”
    Plugin_7.jpg
    Make sure the “application” tab is selected. Now name the game DLL as follows: _GameName (without spaces) + _Plugin.
    So for “Live for Speed” we get ‘LiveforSpeed_Plugin’. Use this name for both the ‘Assembly Name’ and the ‘Root Namespace’ as in the picture below
    Plugin_8.jpg
    Click the green play button at the top of the screen and it will compile you game dll and verify it as a plugin for SimTools.
    Once verified - it reads back the _GameName from within the dll itself.
    Plugin_9.jpg
    Your new game plugin can now be found in the folder:
    Example Plugin Folder\AdditionPlugin\bin\Release\MyPlugin_Plugin.dll
    • Like Like x 19
    • Informative Informative x 8
    Last edited: Mar 9, 2016
  2. value1

    value1 Nerd SimAxe Beta Tester SimTools Developer Gold Contributor

    Joined:
    Jan 9, 2011
    Messages:
    2,184
    Location:
    Zug, Switzerland
    Balance:
    14,463Coins
    Ratings:
    +3,318 / 11 / -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.
    • Informative Informative x 8
    • Like Like x 4
    Last edited: Sep 14, 2013
  3. shannonb1

    shannonb1 Well-Known Member

    Joined:
    Mar 12, 2008
    Messages:
    1,107
    Occupation:
    Sales Intelligence
    Location:
    Virginia
    Balance:
    8,909Coins
    Ratings:
    +598 / 5 / -0
    My Motion Simulator:
    2DOF, AC motor, Arduino, JRK, 4DOF
    I love the print outs that you show so folks can understand movement. This is especially helpful when making sure your actuators are going in the right direction.
    • Like Like x 1
  4. Raulmerlos

    Raulmerlos Member

    Joined:
    Jan 11, 2014
    Messages:
    83
    Occupation:
    Mecanico maquinaria calzado
    Location:
    Monóvar (Alicante) España
    Balance:
    146Coins
    Ratings:
    +71 / 0 / -0
    My Motion Simulator:
    3DOF, Arduino
    I do want to know how this game as the plugin Telemetry
  5. value1

    value1 Nerd SimAxe Beta Tester SimTools Developer Gold Contributor

    Joined:
    Jan 9, 2011
    Messages:
    2,184
    Location:
    Zug, Switzerland
    Balance:
    14,463Coins
    Ratings:
    +3,318 / 11 / -1
    My Motion Simulator:
    2DOF, DC motor, JRK, Joyrider
    What game are you refering to? :confused:
  6. Raulmerlos

    Raulmerlos Member

    Joined:
    Jan 11, 2014
    Messages:
    83
    Occupation:
    Mecanico maquinaria calzado
    Location:
    Monóvar (Alicante) España
    Balance:
    146Coins
    Ratings:
    +71 / 0 / -0
    My Motion Simulator:
    3DOF, Arduino
    By colin mcrae rally 2.0, I'm doing a test
  7. XORExploit

    XORExploit

    Balance:
    Coins
    Ratings:
    +0 / 0 / -0
    Thansk for the tutorial how to write plugin ...good job :)
  8. benj

    benj Member

    Joined:
    Oct 22, 2014
    Messages:
    51
    Location:
    UK
    Balance:
    44Coins
    Ratings:
    +42 / 1 / -1
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    Wow, this is awesome stuff Yobuddy - thanks. I am a pretty experienced coder, but this is a different area for me.

    I had a cool thought away from simulator games, I'd love to try and make a plugin for Doom, or Quake, or other first person games. Being open source, these games might be easier to patch than a more modern title...

    I'd love to get the new Alien Isolation game working, but that's the huge dream! I play with Oculus, so would be so fun to be thrown around a bit :)

    My problem is, I have no idea where to start and your examples give me the option of Memory Hooks or a custom DLL...or I suppose I could modify the actual Doom source code...

    Have you seen anyone trying anything like this?

    Cheers,
    Ben
    • Like Like x 1
  9. value1

    value1 Nerd SimAxe Beta Tester SimTools Developer Gold Contributor

    Joined:
    Jan 9, 2011
    Messages:
    2,184
    Location:
    Zug, Switzerland
    Balance:
    14,463Coins
    Ratings:
    +3,318 / 11 / -1
    My Motion Simulator:
    2DOF, DC motor, JRK, Joyrider
    Yes! @yobuddy has done a great job with the possibility to add new games via a plugin. This opens such a wide field!
    There have been several requests for motion for FPS games. Yet none is supported so far. When trying to build such a plugin, one issue I faced was, that I don't know what data I’m looking for. With a racing game, you can at least search for speed in [m/s]. In a FPS speed could have any fancy unit of measure.

    By studying the source code, you could at least identify, how the coordinate system is implemented and how movements are coded in the game.
    • Like Like x 1
  10. benj

    benj Member

    Joined:
    Oct 22, 2014
    Messages:
    51
    Location:
    UK
    Balance:
    44Coins
    Ratings:
    +42 / 1 / -1
    My Motion Simulator:
    2DOF, DC motor, Arduino, Motion platform
    Hey there @value1 !

    Indeed, we need to know what to look for. I might dig through some Doom or Quake source code...or I might play around in Unity and try my own thing...not sure yet but time is always limited so nothing will happen too quickly!

    I would guess that a lot of modern games using an engine like the Unreal engine would all use the same physics engine for movement so once you cracked one you should be able to get a few games done easily.
    • Like Like x 1
    • Agree Agree x 1
  11. boboghost1

    boboghost1

    Balance:
    Coins
    Ratings:
    +0 / 0 / -0
    OH,I find the"PluginExample.sln"!,it's in plugin zip,but I don't know how to open it....
  12. boboghost1

    boboghost1

    Balance:
    Coins
    Ratings:
    +0 / 0 / -0
  13. value1

    value1 Nerd SimAxe Beta Tester SimTools Developer Gold Contributor

    Joined:
    Jan 9, 2011
    Messages:
    2,184
    Location:
    Zug, Switzerland
    Balance:
    14,463Coins
    Ratings:
    +3,318 / 11 / -1
    My Motion Simulator:
    2DOF, DC motor, JRK, Joyrider
    Yes. Download and install Microsoft Visual Basic 2010 Express. You can download for free.
    • Like Like x 2
  14. boboghost1

    boboghost1

    Balance:
    Coins
    Ratings:
    +0 / 0 / -0
    thank you very much!
  15. zigzag49

    zigzag49 Active Member

    Joined:
    May 27, 2014
    Messages:
    251
    Balance:
    704Coins
    Ratings:
    +220 / 3 / -0
    My Motion Simulator:
    2DOF, Arduino
    Tuto et merci pour le très interessant, dommage Que fait la traduction de Google Parfois defaut.
    Lorsqu'il y a une mise à jour de jeu faut il obligatoirement un nouveau plugin?

    Tuto and thank you for the very interesting, too bad What does Google translation sometimes lacking. When there is a game update there must be a new plugin?
  16. hooshang

    hooshang Active Member

    Joined:
    Jul 6, 2011
    Messages:
    272
    Balance:
    289Coins
    Ratings:
    +157 / 3 / -0
    My Motion Simulator:
    2DOF, DC motor, AC motor, Arduino, 6DOF
    Hi friends
    how to find which type a special game is?and that game is belong to which 4 categories @yobuddy mentioned in first post?
    thx
    Hooshang
    Last edited: May 6, 2015
  17. lioxacydak1

    lioxacydak1 Member

    Joined:
    Feb 28, 2015
    Messages:
    52
    Occupation:
    rescuer
    Balance:
    - 249Coins
    Ratings:
    +16 / 0 / -0
    My Motion Simulator:
    2DOF, 3DOF, DC motor, Arduino, Motion platform, 4DOF, 6DOF
    Hello colleagues.how to find out in the game telemetry port?
  18. noorbeast

    noorbeast VR Tassie Devil Staff Member Moderator Race Director

    Joined:
    Jul 13, 2014
    Messages:
    20,463
    Occupation:
    Innovative tech specialist for NGOs
    Location:
    St Helens, Tasmania, Australia
    Balance:
    144,614Coins
    Ratings:
    +10,741 / 52 / -2
    My Motion Simulator:
    3DOF, DC motor, JRK
    Have a look at the LFS example in @yobuddy's original post. I am unclear if yours is a general question @lioxacydak1, if not what game are you specifically referring to?
  19. sebastien

    sebastien New Member

    Joined:
    Mar 12, 2014
    Messages:
    12
    Balance:
    183Coins
    Ratings:
    +4 / 0 / -0
    My Motion Simulator:
    2DOF, Arduino
    salut a tous écrire un plugin pour moi relève du domaine e la science fiction
    dommage pour moi et bravo à vous.
  20. lioxacydak1

    lioxacydak1 Member

    Joined:
    Feb 28, 2015
    Messages:
    52
    Occupation:
    rescuer
    Balance:
    - 249Coins
    Ratings:
    +16 / 0 / -0
    My Motion Simulator:
    2DOF, 3DOF, DC motor, Arduino, Motion platform, 4DOF, 6DOF
    More of a question in General for all games.