Creating Cutom Panels

kristopher-allison-249993-unsplash.jpg
 
 

GETTING STARTED WITH CUSTOM PANELS…

So we all have our favorite games and we want to build a great panel for it. Or perhaps you’d like to modify one of the existing panels to better meet your play style. So how do you get started. Well it’s easy, and in the next few moments I’ll try and provide the foundation you need to create/edit and test your own panels for StarKeys-vMFD

First you’ll want to download a sample template to get started. We provide a zip of each panel hosted on the community portal. For access visit the panel games page, then choose the zip for your favorite panel to use as a baseline. Here are shortcuts to the Star Citizen and Elite Dangerous packages:

https://games.starkeys-vmfd.com/gamepanels/starcitizen/starcitizen.zip

and

https://games.starkeys-vmfd.com/gamepanels/elitedangerous/elitedangerous.zip

Download either one and unzip it to a working folder to get started.

Now that you’ve downloaded the files, you’ll want to make changes. So let me explain a few of the pieces:

  1. The main html file starcitizen-alpha.html (for example) is a simple panel using very basic css to help with formatting.

  2. In the Head section you’ll see two required scripts, DON’T change these. When you resubmit your new panel for upload, these are required and must be unchanged:

    • <script type="text/javascript" src="./js/ga.js"></script>

    • <script type="text/javascript" src="./js/starkeys-vmfd.js"></script>

  3. Next in the <BODY> you’ll find two forms:

    <form name="GetHostIP" id="GetHostIP" onsubmit="event.preventDefault();">
    <font color="yellow">Host IP: </font><input type="text" name="hostip">
    </form>
    <form name="GetFileID" id="GetFileID" onsubmit="event.preventDefault();">
    <font color="yellow">File ID: </font><input type="text" name="fileid">
    </form>

    These are basically required. The “hostip” is the private IP address of the game pc. This will eventually be sync’d and passed in from the community portal when you open it, but for now you’ll need to enter it into a form.

    The “fileid” is also a required field that designates which macro file is specific to this panel. When you’re editing it yourself you can set the fileid to whatever you want, as long as the value entered and the value stored in the macro file itself match. However, once you upload your panel we’ll override any value in the macro file to ensure its unique within the community portal.

    Both the “hostip” and the “fileid” are displayed within the PC StarKeys-vMFD app and can be used to know the right values to enter into these fields.

The rest of the html file is pretty simple.

You’ll see all the “<a href = “java…(‘macro:#’)”… then <img src=”images/button1.jpg”>….Flight Ready….

  • each of these lines can be changed the same way

  • Change the macro # to align to a macro in the macro file loaded on the game PC. Chances are you can leave these numbered 1-25 without too much to change. Just make sure we edit the macro file on the PC to execute the expected key presses

  • Change the image to a new graphic if you like. Copy the new graphic into the images folder and use relative pathing. This is important, as any absolute pathing will be rejected if you submit it to share on the community portal

  • Finally Change the text from “Flight Ready” to whatever you want to new button functionality to be

If you want to change the backgound, edit the css/sc-style.css and change the referenced file to the new background file

On the PC edit the starcitizen-macros.json file and change the macros “value” to the appropriate key combinations for the action you desire

    1. The text file Macros-keys-mapping-readme.txt, included with the game pc server download, explains all the different keys available and how to map and group them.

    2. For example use [] when you need to press several keys together such as Control-F or Control-Alt-Z.

    3. Use {} for most special characters such as {CONTROL} or {F1}.

    4. Most letters and numbers keys can just be entered directly. So for example to execute just H it’s “H”, to do control H you need control in braces, and the whole thing in brackets such as [{CONTROL}H].

Beyond this, feel free to completely rewrite the HTML and CSS to meet your needs. The only requirements are:

  1. Everything except the things whitelisted in the sample (mentioned above in section 2) must use relative pathing: either “./images/{some image}” or “images/{some image}” but don’t specify a leading “/” as all these panels when uploaded to the community portal, will be running virtually under a parent root folder, so /images will reference the system images folder, not the images folder to accompany your panel.

  2. Don’t use any references to http:…. anything. For security reasons, we don’t want any unknown sites being referenced.

  3. The following java script references are required on all panels:

<script type="text/javascript" src="js/ga.js"></script>

<script type="text/javascript" src="js/starkeys-vmfd.js"></script>

Note: These will be changed automatically during the upload process, to absolute pathing, to use our approved versions. Any issues attempting to map these to the absolute path will result in your panel being rejected.

TESTING ON A PC

Once you make the changes to either the main .html file, or supporting images, css and js files you’ll want to test your changes. To test on a PC, just use the local file explorer; navigate to the html file and double click to open in your favorite browser. You should see the changes.

Note:

When referencing files such as images, css or js, you can reference them 3 ways:

  1. with the full FQDN : “./sdk.amazonaws.com/js/aws-sdk-2.5.0.min.js”

  2. absolute : “/images/starkeys-logo.jpg”

  3. relative : “./images/edcockpit1.png”

The requirement for all panels is that all references are performed as relative path only. This is to provide better security, as well as the ability to run each panel from its own relative root, not conflicting with other panels. When you submit a panel for upload/review to the community portal site, it’ll be scanned and any infractions will be cause for immediate rejection of the upload.

TESTING ON A TABLET, OR SMART PHONE

To test on a non-pc device such as a tablet or smartphone, you’ll need to host the panel on a web server. So you don’t have to create a complex environment for this we’ve built it in to the community portal. Follow the directions below to properly package your panel and upload it to the portal for testing.

UPLOADING TO THE COMMUNITY PORTAL

Before uploading to the community portal there’s a few things that are required:

  • You can have many html for different pages/tabs but one will be the main html which must reside in the root level. The others (if you have them) can reside in the root or in a sub folder, but when linking/referencing them they must be referenced using relative pathing and should include the hostip and fileid as link parameters such as:

./page2.html or
./pages/page2.html

  • You must include in the head section of each page the following references:

<script type="text/javascript" src="./js/ga.js"></script>

<script type="text/javascript" src="./js/starkeys-vmfd.js"></script>

  • You must have no external reference to other files, so no links or scripts or images referenced using http:// etc…

  • You must include all required elements such as java script, css and images in folders beneath the projects root level

For example c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen would have within it

c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen\mypanel.html

c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen\mypanel-macro.json

c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen\mypanel.conf

c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen\readme.txt

c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen\images\some-background_image.jpg

c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen\images\some-button-images.jpg

c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen\css\mypanel.css

c:\Users\dave\devel\starkeys-vmfd\panels\starcitizen\js\some-js-to-perform-cool-animations.js

  • All access to files within the html, js, or css must use relative pathing, meaning DON’T use /images/xxx.jpg or http://…/xxx.jpg to access an image, instead use ./images/xxx.jpg or ../images/xxx.jpg (two dots if you’re in a subfolder and need to get back to your root folder. If you’re two sub folders deep it would be ./../images/xxx.jpg)

  • {mypanel-macro}.json is required and provides all the mappings from the html button presses to the game PC keyboard presses. For example when “landing gear” is pressed, the html file maps the button to macro:9 and the macro file maps macro:9 to the letter “N” which is the default key in Star Citizen to raise/lower the landing gear. If you have multiple pages/tabs then all the macros across them share the one macro file. Therefore be sure that each page uses different numbering.

    • If you’re creating a panel that has several separate pages/tabs/html files then it’s suggested you using a single macro file and combine all macros for all the pages. Aside from simplifying loading a single macro for the user, it also allows the single fileid of the shared macro file to be shared across all these pages. Therefore, you can pass it using the ?fileid=xxxx instead of having to enter it on each page

    • To help with running multi page panels, we’re providing the javascript macro OpenPanel to be used when calling other pages. This will automatically provide the fileid and hostip to the subsequent pages. Use the following style of method call:
      <a href="javascript:OpenPanel('./starcitizen-page2.html')">

  • {starcitizen}.conf file is required for properly categorizing any new panel that’s submitted to the portal. It must have the same name as the parent folder that is zipped, and it must reside in this root folder. It must contain the following information:

{

    “username” : “wolfman99”,

    “panelname” : “starcitizen-normal-flight-1”,

    “paneldesc”' : “starcitizen normal flight, good for takeoff, landing, navigation and exploration”,

    “gamename” : “starcitizen”,

    “gameversion” : “1.0”,

    “htmlname” : “starcitizen-alpha.html”,

    “macroname” : “starcitizen-macros.json”,

    “thumbnail” : “images/starkeys-starcitizen-logo.jpg”

}

Note part of the file, just description of the fields:

    “username” : this must match the name you’ve logged in with

    “panelname” : give your panel a name, this must match the name entered in the input prompt when attempting to upload. If it doesn’t match the upload will be rejected

    “paneldesc” : give your panel a description

    “gamename” : provide the name of the game this panel is designed for (auto downshifted to simplify searching)

    “gameversion” : provide the game version this panel is designed for

    “htmlname” : provide the name of the html file for this panel, must match the html file on the root folder

    “macroname” : provide the name of the macro file for this panel, must match the  file on the root folder

    “thumbnail” : provide the relative path and name to an image to be used to represent this panel. A screen shot of the panel is usually best for this

  • readme.txt file should explain all the buttons available but most importantly also provide the key mappings from the macro file to the game, explaining how to map any keys in game that either aren’t mapped by default of are mapped with a value other than the default value

  • Once all the files are in place, you’ll want to zip the root folder “starcitizen” in the above example to create a file “starcitizen.zip”

  • Now proceed to the Panel Upload Tab off the Game Panels tab to begin the upload

If the file meets all the requirements and passes the scan for viruses/trogans/spyware, etc… it’ll be staged to a private staging area where only you can access it. An email will be sent to the registered email address containing additional information on how to access the panel

Once you feel the panel is working as expected, you’ll be able to promote the panel to an approval/review process, where the community will test it and vote it with a thumbs up/down. Once enough up votes are received it’ll be moved to the general availability area for panels on the site.

For now a panel will be in the private section for 7 days and then it’ll be removed and you’ll need to upload it again.  This is only temporary until we add the ability for the community to upvote/approve a panel, coming in a few weeks.

That’s it. If you did it correctly you’ll receive an email within a few minutes with a link to access your new panel.

Please keep us updated on your experience at our Discord Channel.

Good Luck!