Maneuver Data

[ihinckle]

The maneuver data is confusing just from a look. It took pulling up the reference card to figure out what was referencing what. Is there something that could be added to the documentation to assist with understanding each ships maneuver data.

My other question is that the data seems inconsistent. For a lot of ships the first array in the maneuver array represents the 5 movement. Then they go bottom to top after that. It becomes inconsistent for example on the lambda shuttle which only has enough arrays as there are movement rows and represents bottom to top. Is there a reason under the organization decision? I figured out what it meant now. It is to represent the zero row even though it doesn't exist on the reference card. The Tie Fighter helped me figure this out. Documentation would be helpful here. Is it something that you would like help with?

[lvisintini]

The ship's maneuver property is structured as an array of arrays.

Each array in the top level array contains a representation of the maneuvers available to the ship at a particular speed, determined by its index in the top level array.

For example:

• ship.maneuvers[1] will provide all maneuvers available to said ship at speed 1.
• LambdaShuttle.maneuvers[0] will provide all maneuvers available to the lambda shuttle at speed 0, though this only makes sense for the Stationary maneuver, which is represented as a Straight 0 maneuver.

This array may be as short as required to provide accurate data, meaning that a missing speed 'index' indicates that the ship is is not capable of such speed.

In the "speed" arrays, each value references a different maneuver depending on its index in the array, which maps according to the following list.

00 = Left Turn 01 = Left Bank 02 = Straight 03 = Right Bank 04 = Right Turn 05 = Koiogran Turn 06 = Segnor\'s Loop Left 07 = Segnor\'s Loop Right 08 = Tallon Roll Left 09 = Tallon Roll Right 10 = Backwards Left Bank 11 = Backwards Straight 12 = Backwards Right Bank

Possible values in this array range from 0 to 3 and mean the following:

0 = Maneuver unavailable 1 = White maneuver 2 = Green maneuver 3 = Red maneuver

Speed arrays may be as short as required to provide accurate data, meaning that a missing value for a particular maneuver type indicates that said maneuver is not available to that particular ship at that particular speed.

[lvisintini]

We have considered ways to make the maneuvers more readable and easy to understand at a glance:

• The idea of displaying all "speed" arrays in a single line has been considered.
• Making sure that all "speed" arrays contain the same number of element.

That way, the X-Wing maneuver property would look like

    ...
    "maneuvers": [
      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      [0, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      [1, 1, 2, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0],
      [1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0],
      [0, 0, 1, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0],
      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    ],
    ...

This would make the data more consistent and easy to read it also means that:

• We are using a non-standard way to indent a JSON structure, which would discourage contributions to this repo or make it more dificult at least.
• We would need to add a bunch of zeros at the end of every "speed" array for all ships every time a new maneuver type is introduced into the game.

Having it the way it is now means that once the data is added, it does not need additional updating

[guidokessels]

Thanks @lvisintini, you covered it well.

The maneuvers array format was copied from YASB when I initially created these files. As @lvisintini said it is an array of arrays in which each value represents a maneuver and its difficulty.

The reason for the 'weird' formatting is that I build an editor that I use to update the files. The way it saves JSON output causes the maneuver arrays to look like this:

"maneuvers": [
      [
        0,
        0,
        0,
        0,
        0,
        0
      ],
      [
        0,
        2,
        2,
        ...

instead of the more compact:

"maneuvers": [
  [0,0,0,0,0,0],
  [0,2,2,2,0,0],
  [1,1,2,1,1,0],
  [1,1,1,1,1,0],
  [0,0,1,0,0,3]
]

But as the data is only read by code and the editor saves me a lot of time (I used to type the JSON manually) I can live with it.

[ihinckle]

Thanks a lot for the reply. It did finally make sense once I dug into it more in that the array index represents which movement row (0=0, 1=1). Would you like me to create some sort of edit of your response to the documentation? Or somehow pin this closed thread so that there is a location for people to read up on it?

[guidokessels]

Some of this is already in the JSON schemas description (https://github.com/guidokessels/xwing-data/blob/master/schemas/ships.json#L172)

But I think it's time we add some documentation to the repo or start a wiki. It'd be good to document all the fields.

[ihinckle]

Oh! Well that explains a lot. I guess I have a lot to get used to in terms of project organization. I did not realize this data existed in that format. Thanks for pointing that out.

[lvisintini]

I have it in my TO DO list to make a script to auto-generate some documentation based on the schemas, but I may never get to it this lifetime.