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 an Axis Assignments (Math) Plugin for SimTools 2.0 - API documentation

Discussion in 'Tutorials and Tips by the Developer' started by yobuddy, Mar 9, 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...

    There are 4 sections of any new Axis Assignment (math) Plugin that needs to be completed in order to produce a compatible Axis Assignment Plugin for SimTools 2.0.

    1) Axis Assignment Settings – Basic settings for the new AxisAssignments Plugin.
    2) The Form – Form Creation and Structure variables.
    3) Engine Control – 5 subroutines to control the engine
    4) Engine Math – The Math Itself.

    Let’s get started!
    Download this Example Plugin:
    Generic2D_Example_AxisAssignmentsPlugin.zip

    1) Open the plugin by unzipping and clicking on “AxisAssignmentsPlugin.sln”.
    2) Then double click on “AxisAssignmentsPlugin.vb” in solution explorer.
    AA0_Select.jpg

    Step 1) Axis Assignment Settings
    AA1_BasicSettings.jpg

    _PluginAuthorsName - The name, or names, of people that have worked on the plugin. If someone sends you a plugin to edit/add-on too, please just add your name with a coma like this “Original Author, Your Name”.
    _AxisAssignmentsName - This is name displayed in Game Engines list of AxisAssignments available.
    _PerGameSettings – Do all games use the same settings? Or separate settings depending on the game selected?
    _Enable_AxisAssignments1 – should this plugin be enabled for Axis Assignments ( a )
    _Enable_AxisAssignments2 – should this plugin be enabled for Axis Assignments ( b )

    Step 2) The Form
    A) Then double click on “UserControl_Settings.vb” in solution explorer.
    AA0_Select.jpg

    We are now going to build our form for this Axis Assignment plugin.
    Here is a pic of the Example plugins GUI.
    (Should look fairly familiar to most of you)
    AA0.5_GUI.jpg

    Notice this example plugin allows for mixing 3 DOF’s per Axis and has no filters for the easy of explaining how the api works.

    B) Now let’s setup our Structure for this form.
    We need to add ‘1’ variable to the structure for each control on the form.
    Notice there are ‘9’ controls per Axis (3 per DOF). And we have ‘6’ axes available to the user. This should give us a total of ‘54’ variables to add to the structure.

    This is what I did.
    AA2_Structure.jpg
    And so on for all 6 Axis…

    C) Now let’s teach the form a few tricks!
    FM2_Subs.jpg

    LoadFormFromStructure()
    Teach the Form how to fill itself from the Structure data.
    (See example plugin for more detail)
    Example
    btn_Axis1_B1.Checked = _AxisAssignments._Axis1DIR1
    And so on for all controls on the form…

    LoadStrutureFromForm()
    Teach the Structure how to fill itself from the Form data.
    (Just the opposite from the sub above) (See example plugin for more detail)
    Example
    _AxisAssignments._Axis1DIR1 = btn_Axis1_B1.Checked
    And so on for all variables in the Structure…

    Clear_AxisAssignments()
    Teach the Form how to reset itself.
    (Resetting the structure is not needed – just the form)
    Example
    btn_Axis1_B1.Checked = False
    And so on for all controls on the form…

    CheckSaveButton()
    This is an optional subroutine. (Not used in this example)
    //////////////////////// MORE ON THIS LATER ////////////////////////

    Step 3) 5 subroutines to control the engine.
    (Double click on “AxisAssignmentsPlugin.vb”)
    AA3_5Subs.jpg
    StartUp()
    If your plugin needs to do anything as it gets loaded, you can do so here.

    ShutDown()
    If your plugin needs to do anything as it gets unloaded, you can do so here.
    (For this Example plugin, I added Output_Calculations_Running to False just to be sure all threads are stopped)

    GameStart()
    Start your engine here when a game starts.
    In my example plugin I use “StartupSelected()” to only start up the math calculations for the axis that the user is actually using. (2 of the 6 axis shown below)
    (See the example Plugin for more detailed info)
    AA3_2Startup.jpg

    You could just start them all up, but I wanted to show you that you can create a faster engine by only starting what is actually needed.
    Notice that “StartupSelected()” starts the axis calculations in background threads for the needed axis. These threads will continue to loop until Output_Calculations_Running = False.

    GameStop()
    Stop your engine here when a game ends.
    (For this Example plugin, you can end all your threads by setting Output_Calculations_Running to False. Easy!)

    ResetValues()
    You can reset any extra needed variables here.
    (SimTools automatically resets its internal DOF inputs and Axis Output variables)
    (You only need to reset any added variables need for your engine)
    (Btw, this example did not have anything extra to reset.)

    Step 4) The Math Itself
    Here are all of your input DOF variables:
    _Roll_Input
    _Pitch_Input
    _Heave_Input
    _Yaw_Input
    _Sway_Input
    _Surge_Input
    _Extra1_Input
    _Extra2_Input
    _Extra3_Input

    After you do your calculations, you apply your outputs to these AXIS variables:
    _Axis1Output
    _Axis2Output
    _Axis3Output
    _Axis4Output
    _Axis5Output
    _Axis6Output

    (All 15 of the variables above get automatically reset after the game. You do not need to worry about resetting any of these 15 variables when the game ends)

    Now a bit about how it works.
    All math that is done in an axis assignment plugin, is a calculation of percent used.

    ~ Inputs ~
    The values of all of the ‘_Input’ variables above are always delivered to you as a whole number between -1 and 1. This means that 0 is the center of the axis and -1 and 1 are both the ends of the axis. Remember that 0 (center) is really just 50% of the axis used. So a -0.5 would mean that 25% of the axis is used. While a 0.5 would mean that 75% of the axis is used. Take a second to think it over if you’re confused, it’s really not too hard once you get the hang of it

    ~ Outputs ~
    Outputs work the same way as inputs. Once you have applied your math calculations and you are happy with your results, you assign your result to any of the 6 output variables listed above. The value of the outputs should be between -1 and 1.

    (SimTools will automatically clip the numbers to be between these values if needed. Trying to pass back a 1.5 to SimTools will result in SimTools receiving a value of 1. Same goes for negative numbers, trying to pass back a -1.5 to SimTools will result in SimTools receiving a value of -1.)

    Let’s take a look at ‘Axis Calculations’ for Axis 1
    (All calculations should be done using the structure; accessing any form controls in the loop will destroy the speed of your plugins engine)
    AA3_1Calculate.jpg

    You will see that all I am doing is simply looping and building the output the user has selected. Remember that each Axis has 3 Force’s that can be used in the mixing of the axis output (for this example plugin). So what we need to do, is figure out the value of each of the 3 Force’s that can be part of the particular Axis output. And then add them together for the final output for that Axis.

    First we look to see what the force is for ._Axis1DOF1.
    Let’s say it’s Roll, we then get the ‘_Roll_Input’ and multiply it by the ‘Percentage’ the user wants to use for DOF1. (Roll at 50% for example)
    We then flip the output if the user has ‘DIR’ checked for DOF1.
    We then do the same for DOF2 and DOF3.
    The final output for this Axis is the combination of DOF1 + DOF2 + DOF3
    (This is all the 6 Axis Calculation Sub’s are doing)

    Take a look at the example, as it will really help in the understanding of how this works.

    You do not need to edit sections that look like this:
    Doing so will probably only make things not work as they should
    AA5_NoEdit.jpg

    That’s it!
    Let’s compile your new plugin!​

    How to Compile the Plugin
    Click on “My Project”
    Compile1.jpg

    Make sure the “application” tab is selected. Now name the AxisAssignments DLL as follows: _AxisAssignmentsName (without spaces) + _AxisAssignmentsPlugin.
    So for this example we get ‘Generic2DExample_AxisAssignmentsPlugin. Use this name for both the ‘Assembly Name’ and the ‘Root Namespace’ as in the picture below
    Compile2.jpg

    Right click on AxisAssignmentPlugin in the solution explorer and select Build!
    Compile3.jpg

    Your new AxisAssignments plugin can now be found in the folder;
    ExamplePluginFolder\ AxisAssignmentsPlugin\AxisAssignmentsPlugin\bin\Release\MyPlugin_AxisAssignmentsPlugin.dll
    Run ‘PluginValidator.exe’ in the same folder to validate your new plugin.
    Validate1.jpg


    Congratulations!!
    Your new AxisAssignment Plugin is complete!
    Now install it into SimTools 2.0 and test out your work!​
    • Winner x 6
    • Like x 5
    • Informative x 1
    • Useful x 1
    • Creative x 1
    Last edited: Jul 5, 2018
  2. 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
    Now that is a great SimTools 2.0 foundation resource right out of the gate @yobuddy :thumbs
    • Like Like x 3
    • Agree Agree x 2
  3. eaorobbie

    eaorobbie Well-Known Member Staff Member SimTools Developer Gold Contributor SimTools 2.0 Beta Tester

    Joined:
    May 26, 2009
    Messages:
    2,593
    Occupation:
    CAD Detailer
    Location:
    Ellenbrook, Western Australia
    Balance:
    19,462Coins
    Ratings:
    +1,626 / 22 / -2
    My Motion Simulator:
    2DOF, DC motor, JRK, SimforceGT, 6DOF
    Very cool indeed , I will be able to incorporate my 6Dof Maths into this nicely.
    • Like Like x 2
  4. eightbit

    eightbit Active Member SimTools 2.0 Beta Tester

    Joined:
    May 20, 2013
    Messages:
    108
    Occupation:
    Fish Farmer
    Location:
    Trentham Cliffs
    Balance:
    301Coins
    Ratings:
    +45 / 0 / -0
    My Motion Simulator:
    3DOF, DC motor, Arduino
    Very nice! Very very nice :) thank you yobuddy! And that's why I love being here.
    • Like Like x 1
  5. 86530766

    86530766 New Member

    Joined:
    Dec 23, 2016
    Messages:
    6
    Location:
    japan
    Balance:
    27Coins
    Ratings:
    +2 / 0 / -0
    My Motion Simulator:
    3DOF, Arduino
    Very cool indeed , I will be able to incorporate.
    • Like Like x 1
  6. 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
    Hi @yobuddy , any plans on releasing an example of a Axis assignment (math) plugin ?
  7. 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
    Yes, as soon as I feel its a perfect API to be built on, I will release it.
    The Interface release will be first thou, but it's on the list of things to do asap.
    Thx guy's!
    yobuddy
  8. Z FOX

    Z FOX New Member

    Joined:
    May 8, 2018
    Messages:
    6
    Location:
    USA
    Balance:
    39Coins
    Ratings:
    +2 / 0 / -0
    My Motion Simulator:
    2DOF, Arduino
    Sorry to pester but I just wanted to check the status @yobuddy!

    How's the API coming along? Thank you for all you've done. I've been lurking here for a bit and have seen you and @noorbeast answer every single question I've come across!
  9. 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
    • Like Like x 1
  10. 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
    @Painit_Budder
    I believe the api is done.
    But as there is not a lot of stuff built on it yet, there may be reasons to change it still.
    But if you want a early copy, I could probably do that.
    yobuddy
    • Informative Informative x 1
  11. Z FOX

    Z FOX New Member

    Joined:
    May 8, 2018
    Messages:
    6
    Location:
    USA
    Balance:
    39Coins
    Ratings:
    +2 / 0 / -0
    My Motion Simulator:
    2DOF, Arduino
    @yobuddy What I'm mainly after right now is the example for the axis assignments (math) plugin! Is that available?
  12. 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
    @Painit_Budder,
    Please give me the weekend to clean up the example to be able to post it.
    yobuddy
    • Winner Winner x 2
  13. 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
    This would be great - always wanted to try and build a log filter (especial for heave), so that only the higher values are flattened while leaving the smaller details alone.
    • Agree Agree x 2
  14. 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
    I will have an example ready tomorrow, sorry for the delay.
    yobuddy
    • Like Like x 4
  15. 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 Axis Assignment Plugin Posted!
    yobuddy
    • Like Like x 2
  16. 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
    Great work @yobuddy :thumbs, just had a quick look and its seems pretty straight forward.
  17. 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
    Will I need to modify this to access the 12 axises that Simtools now has? 1a, 2a etc.
  18. 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
    The plugin loads for both the ( a ) axis assignments and also the ( b ) axis assignments.
    So it will work for all 12 axis as needed buddy.

    I'll add the background change ( a or b axes) this weekend to the example.
    (Since I see that is not in there right now.)

    Take care!
    yobuddy
  19. 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
    Oh, I see it now

    'Enable_AxisAssignments1 – should this plugin be enabled for Axis Assignments ( a )
    _Enable_AxisAssignments2 – should this plugin be enabled for Axis Assignments ( b )'

    Obviously need to play with this a bit :) Edit : just missed your post while I was typing this.
  20. 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
    I'll fix the background labels to reflect the (a) vs (b) axis assignments.
    (And make sure I didn't leave anything else out that should be in there.) lol

    Really trying to show an easy to use example that's fully using multithreading.
    (As it makes things so much better)

    Anyway, I'm always around for any questions buddy!
    Take care,
    yobuddy
    • Winner Winner x 1