[Release] LH_DataViewer (v1.03)

[Triscopic]

(You must be logged in to view these screen shots and download the plugin)

LH_DataViewer
Latest Version: 1.03

This plugin makes gaming layouts a reality. However it is not for the faint of heart. It is important to understand that this plugin is not designed to allow someone to add a little bit of game data to an existing layout (although you could), but rather it is meant to have an entire layout built around it, something that you load specially when you want to play a particular game.

What does it do?
Perhaps it's better to being with what it does not do. This plugin does not extract data from a game. Rather it imports data from a text file and formats it according to a set of custom rules. If a game is able to export stats and information to a text file (e.g. via the use of an in-game script) then this plugin can pull that onto your LCD display.

If data is available to the plugin then it can display text, perform calculations, use regular expressions, look-up values in lists, display images based on customizable conditions, and format data into bars whose max and min values can also be dynamically set from the data. And of course since this is LCDHost you also have access to all the other other items that LCDHost can display allowing you to incorporate FPS, CPU usage, memory footprint, etc in your gaming layout as well.

Example Screenshots:
The following two screen shots show examples of the sort of thing that can be created for the game X3 Terran Conflict. The game has a powerful scripting engine so it is possible to create a script that exports all manor of stats.
These screen shots show the dynamic bars, here showing shielding, health and (for your ship at least) weapon energy. The distance will actually correct itself to use meters or kilometers just as the game itself does. In addition to displaying basic text data there are also a number of calculations and list look-ups - the rankings only export a number between -1,000,000 ("gouge his eyes out with a spoon") and 1,000,000 ("have my babies") and the plugin has to convert those into the more useful rank levels, names and percentages. You can also see an example of a dynamic image - there are almost 100 ship icons. It just so happens here that I've managed to be looking at an enemy ship of the same type when taking the screen shot.

The layout above also makes use of the LH_Cursor plugin to allow the user to use the G19's lcd control keys to move between pages, indicated by the icons across the bottom of the screen.

How to use the plugin
Full Guide:
A full guide is available here: LCDHost Gaming Layout Builder.pdf

Quick Guide:
In order to create a layout I would suggest taking the following steps:

• Begin by establishing whether it's possible either by scripting something in game, using a mod, or through some other means, to export data from the game to a text file
• If it is, design the layout paying particular attention to the data you would want; if you intend to create pages using LH_Cursor, work out what data should go on each page.
• The tricky bit. Either write a script/create a mod/perform dark magic to extract the data from the game. Again, neither this plugin nor I can help you here. Your best bet is to hang out in the forums of the game in question and see if you can work it all out there.
• The next most tricky bit. You now need to create a datamap file that defines the data. The data map defines what data value sits where in the file. It can use regular expressions to pull data out, and defines any lists required as well has explaining how they get used. The plugin uses this file to tell it how to interpret the file generated by the game. For a clearer example, download the X3TC layout and examine the datamap.txt file, comparing it with the example data file included.
• The easy but time-consuming and fiddly bit. Once the datamap is complete and the game is exporting data successfully, you can open up LCDHost and begin creating your layout.
  
  • Start by adding a "Data Connector" (under Dynamic\DataViewer) and add the data map file (which you should really save inside the layout's directory) and selecting the datasource.
  • Now you can add a "Data Text" object. Entering {0} into the Data Template will make the box display the first item in the datamap. You can also add any custom text you want or indeed add several references, e.g. if the first three items were player name, level and class then the template "{0} (Lvl {1} {2})" might display "Gandalf (Lvl 20 Wizard)"
  • Adding a bar operates in a similar way. Template values are used to set the min and max values so that you can either use a reference or enter a fixed value, so for a percentage based stat you would usually want to set the max to "100"; however if, as with ship energy above, the maximum is determined by another variable you can add a reference to this instead in the same way as above, e.g. "{12}". Other than this they work in the same way as usual bars with all the same options.
  • It is worth noting that templates can combine numerical values using simple mathematics ( +, -, *, / and brackets only), and c++'s sprintf format codes e.g.: "{=({10}-{11})/({12}-{11})*100:%.2f}%" displays as a percentage to 2 decimal places the progress made from a starting value (entry #11, e.g. experience required for the player's current level) to another target value (item #12, e.g. the experience required to level up) where value #10 is the current "value" of the attribute in question (e.g. the players current experience)
  • You can also create Data Image objects. These use an image map file as well as a "lookup code" (another template like the text file). The image map file contains a list of conditions and the image that matches that condition. The lookup code as well as using the same format as above also allows you to embed a single comma in the template which will split the result into a row name and a column name which are then used to look up the corresponding image in the imagemap file (basically a tab separated spreadsheet). For example in the X3TC layout the shipicon image map contains 34 different ship codes and three columns - one for neutral ships (blue) one for enemy ships (red) and one for allied ships (green) the lookup code {15},{16} then translates to a ship code and an a relationship code which can then be looked up in the image map.
  • the last remaining data object is the simplest. The Expired Image displays a picture only when the game data has expired (a setting in the image map defines how many seconds data is valid for; a file older than this value will not be read), which is designed to allow a layout to display only a splash screen whilst waiting for data to be created (e.g. if the game is not running or a new level is loading).

As mentioned, the plugin is not trivial to use. Perhaps the best way to begin is to examine the X3TC layout closely (available shortly after the A13 release) and see how that works.

Again, there is a full guide for using this plugin to build your own layouts, located here.

[Triscopic]

(reserved)

[SirReal]

This is going to melt some brains, I'm sure.

[Triscopic]

Unlocked this thread now A13 is out.

[Triscopic]

I'm pleased to say I've finally got the documentation finished:
LCDHost Gaming Layout Builder.pdf

[SirReal]

That's impressive, that is.

[Sepa]

Nice. It has some really useful features.

One suggestion though:

Instead of reading X number of lines if data file is set to 'not-all-at-once' mode, wouldn't it be easier to read until [mark] ?
That would allow to re-draw only new values. Then you can set a switch, so empty fields are either filled using default values (from separate file maybe), or left alone with their previous values. Could be useful in some games, when the data gathering process is time consuming or callback triggered.

EDIT:

I see that a data map is made statically, column/row, so above idea would not work. In my old X:TC plugin I was looking for the 1st column and then run appropriate parsing code (in a nasty if block - that was evil, you don't wanna do that).
In Perl I often use similar technique, were I make hashes with code refs - I just didn't know how to do that in C.
However, that do not apply very well to X:TC case, where it could be better to re-arrange the game data file to achieve your desired grouping (as player data is in several rows)

Anyhow, if you replace the ROW with KEYWORD (where it's regexed like /^KEYWORD:/) your data map could work like this:

Code: [Select]

[Definitions]
Player: Name    1,Pilot
Player: Money    1,Account
Player: Time Played 1,Time seconds>time
Player: Insurance 1,Insurance

Instead of:

Code: [Select]

[Definitions]
Player: Name    1,0
Player: Money    1,3
Player: Time Played 1,4 seconds>time
Player: Insurance 1,24

given the data source file like:

Code: [Select]

Pilot: Erin Iovis
Ships: 2
Stations: 0
Account: 878,596
Time: 22186
Argon: Argon Federation Associate:52
Boron: Boron Suspected Foe:-11
Split: Split Suspected Foe:-15
Paranid: Paranid Suspected Foe:-12
Teladi: Teladi Federation Associate:65
Goner: Goner Citizen:5
Terran: Terran Confirmed Friend:120
ATF: ATF Confirmed Friend:100
Pirates: Pirates Confirmed Insurgent:-10000
Yaki: Yaki Confirmed Insurgent:-10000
ShipClass: 0:0:0:1:1:0:0:0:0:0:0:0
Bars: 100:100:3000:3000
ShipName: Your Sabre:M4:YM4XJ-17:0
ShipEnv: Shipyard(Mars)
Target:
Combat: Veteran:389
Trade: Opportunist:0
Missiles: 0
Enemies: 0
Insurance: 0

I can see several uses of that Implementation is fairly simple:

Init:
parse -> map to line numbers, cache

each read:
if (LineCount != previousLineCount) rebuild line mapping

What do you think? Will be very useful for the things like the wingman stuff, so wingman data can be stored in such a way in data file:

Code: [Select]

Wingman: 1:0:0:0:1:1:0:0:0:0:0:0:0
Wingman: 2:0:0:0:2:1:0:0:0:0:0:0:0
Wingman: 3:0:0:0:1:1:3:0:0:0:0:0:0

This line is similar to ShipClass line, with just wingman index in front. With line numbers as they are now, adding flexible wingman info is probably not possible.

END EDIT

I got some doubts as for this XML data type - do you really need to put it in such variable? Is it not easier to check if the first line is [xxx] or <?xml...> ?

Sorry for being a d..k though, too many code reviews done today, I'm still in a zone I guess

Keep in mind I speak from Perl perspective, I don't know how hard would such a regex be in C

Btw, I would like to use this occasion to say big Thank Your for the LCDHost to SirReal.

[MPD]

Hi

I'm new to scripting on the G19 - so fell free to slap me and point me in a different direction or area to post

I've got a script made up for LoTRo for my G19 which is working well, but I need output to the LCD.  Before I tackle the game data from the status files I want to crack outputing messages directly from the LUA script.  I can use OutputLCDMessage but it looks real ugly.

I'd love to start playing with LCDHost but am a bit beweldered  where to start - can I use the write to the LH_DataText object from my LUA script in the Logitech Profiler?  If someone could point me at similar code I'd be very grateful.

Again - apologies if I'm out of bounds on this one   

M

[general_joe]

OK, now to see if I can make iRacing export to MoTEC and get that to export to a text file.  Don't hold your breath.  Good work that man!

[Triscopic]

MPD,

This plugin will allow you to convert data output to a text file at regular intervals into a customisable layout on LCDHost. It's not trivial, I'll give you that, but the documentation (see the main post for a link to the pdf) should be sufficient.

Using LUA... you'd have to ask lethys about that.

[SirReal]

MPD, I don't think you need to script at all to use the LH_DataViewer. Just read Triscopics instructions in the first post.

[MPD]

MPD, I don't think you need to script at all to use the LH_DataViewer. Just read Triscopics instructions in the first post.

Hi-ya

Thanks for the reply.  I undestood the link between game stat files and LH_DataViewer which I'll be trying later.  The bit I'm struggling to see how to do - is display information from the output of my scripts.  Information that isn't in any game stat file

This is stuff like - press button G1, do a defined set of actions but display infomation about the sequence in case the game interrupts and I have to manually pickup  (if anyone is familiar - this is for controlling Warden Gambits in LoTRo)

Unless I'm missing something obvious (I am a noob  )?

thanks

[SirReal]

I think you're missing the big picture. LCDHost itself renders layouts containing layout class instances. Right now, a layout is static inasmuch you can't programatically add or remove class instances. You can resize an instance though, or you can hide it by simply not rendering anything.

[MPD]

I think you're missing the big picture. LCDHost itself renders layouts containing layout class instances. Right now, a layout is static inasmuch you can't programatically add or remove class instances. You can resize an instance though, or you can hide it by simply not rendering anything.

Hehe - I might very well be missing quite a lot 

What I'm after is static object that I can programatically change its properties.  Thinking bakc to my windows programming days - a label object or a listbox where I'm trying to change the text property.  I don't want to dynamically create move or hide this object - just change the contents (or text property)

Thanks for your ongoing efforts to help!

[SirReal]

You can't alter the output of another instance from your own instance. There is functionality planned that will allow plugins and instances to use data from each other, but that's in the future.