Carriers Extended! SDK

From SWS Wiki
Jump to: navigation, search

Introduction

Carriers Extended! SDK (CEX SDK) is aimed at enhancing the functionality of your naval vessels. While the focus of CEX is mostly aircraft carriers, most of its features can be used to enhance other naval vessels as well through the addition of user controlled animations and properties.

The purpose of this page is to help you take full advantage of CEX SDK's capabilities by detailing every step of the process. Each step listed below will follow the following format:

  • Introduction
  • Necessary software
  • Samples
  • Installation
  • Description page

While we will try to keep things unchanged, the will be constantly updated as new features are making their way in. We recommend that you keep track of the changelogs for any new features or changes.

We would also like to start with some definitions that will keep the SDK consistent and understandable:

  • SimObject: any airplane, boat, rotorcraft, ground vehicle or other simulated entity that exists in FSX/P3D. SimObjects have aircraft.cfg or sim.cfg files.
  • Class: does not refer to ship classes. A class is formed by simobjects that have identical properties. These properties are specific and defined in the class description.
  • Header: a section enclosed by brackets. Example: [SECTION_0]
  • Title: The title string as referenced in aircraft.cfg or sim.cfg

Available features

Version 1.0.0

  • Animated arrestor cables
  • User controlled ship animations
  • Drivable tow truck
  • Custom FLOLS
  • Custom LSO
  • Custom catapult launch speeds
  • vLSO integration
  • Features work on CEX-enhanced drivable carriers

Version 1.2.7 (in testing)

  • General changes
    • Added Ship Placer
    • Moved CEX files from Appdata\Local to Appdata\Roaming
    • Added class-based folder structure
    • Updated SDK interface to support for any combination of features, including carriers with multiple OLSs
  • Carriers Extended! updates
    • Added keyboard acceleration for all menus
    • Restructured SimConnect menu tree for ease of use
    • Added TACAN interface
    • Adder NAVAIDs menu entry, showing currently loaded facilities/frequencies
    • Added catapult launch sequence. Launch key command now serves as a salute to the shooter. Launch will occur a couple of seconds later, after the shooter touches deck.
    • Increased visibility limit of OLS datum lights
    • Improved interfacing with vLSO
    • Fixed bug causing very slight "high" indication from FLOLS
  • Ship placer
    • Ability to spawn ship formations
    • Basic manouevering & speed control
      • Standard turn - Ships turn independently. Example: in a diamond formation the lead ship will be on the left side of the formation after a 90 degree right turn
      • Corpen turn - Ships turn as a group. This turn takes a long time to complete because the inside ship is going slowly and the outside ship is going at flank speed, to keep the formation.
      • Carrier recovery corpen - The formation does a corpen turn into the wind so that the wind-over-deck is optimal for carrier landings.
    • Shortcuts:
      • Ctrl+Shift+S: Main menu
      • Ctrl+Shift+P: Position display
    • Warp-to-deck functionality: allows you to directly move onto a ship's deck.
    • Save flight on carrier: when loading a flight saved on an AI carrier, you will now start on deck. The carrier loads normally and you are placed where you were when you saved the flight.
    • Ability to save parking spots on the deck. Position and orientation are stored.
    • Station keeping AI: ships manage their speed and heading to maintain formation based on commands.

Documentation

CEX features depend on the following components. Click the list items to move to the respective section

  1. CarrierExtensions.dll - Contains the necessary logic for operation of all features. Currently available with SWS' Midway Battlegroup and F-4B/N Phantom II. It will not be covered in this documentation.
  2. CEX configuration files - Contain the description of the simobject's features, such as number of arrestor cables, meatball position, animation variables and more. This is file is created and supplied by you.
  3. User interface - this can be in the form of a 2D gauge in the simulator and the accompanying .ini files which will allow the end-user to control the various animations. This is developed and distributed by you.
  4. 3D model - The model file of the simobject, containing the geometry, animations and visibility conditions. For certain parts interacting with CEX such as arrestor cables, certain restrictions apply. See the relative section.
  5. CEX API - For the convenience of aircraft & carrier developers, certain read-only Lvars are provided when CEX is running.

Changes

  • January 8th, 2018: initial version recovered and updated

CEX Configuration files

Introduction

CEX Configuration files describe the class of the vehicle. A class consists of certain infrastructural features that are identical among similar vehicle. Note however that due to variations and modifications, ships in the same real-world class may still be different enough to require separate CEX configuration files.

Example: Our Midway & Coral Sea are handled as different classes. One of the reasons is that Midway has three arrestor cables, while Coral Sea has four. As the number of arrestor cables is hardcoded in the beginning of the file.

Configuration files are in the familiar INI format used by FSX's cfg files. Each vehicle's CEX CFG file contains one or more [TITLE_X] entries for identification, one [GENERAL] section for data used by all ships, ground vehicles, or aircraft, and zero or more special headers which vary depending on the specific role of the vehicle (for example carrier, deck tractor, tanker, etc.)

The description page should help you understand the structure and function of a CEX configuration file.

Necessary software

Notepad

Installation

CEX configuration files need to go into the correct folder for the vehicle you are modeling. The general path structure is: %appdata%\CarrierExtensions\SimobjectType\SimObjectClass\ClassName.cfg

 %appdata%\CarrierExtensions\SimObjectType\ClassFolder\ClassName.cfg Path structure
 %appdata% CEX files are located in Appdata\Roaming. This way they are accessible to any user account.
SimObjectType Subfolder. Ships and GroundVehicles are the only ones currently supported. More will be added in the future.
ClassFolder Subfolder. For clarity, we suggest that you use your company's prefix, followed by the ship class. I.e. SWS_Carriers
ClassName.cfg CEX configuration file. Can be named anything you want.
EXAMPLES
Appdata\Roaming\CarrierExtensions\Ships\Carriers\SWS_CV41.cfg CEX configuration file for the Midway carrier created by SWS.
Appdata\Roaming\CarrierExtensions\Ships\Carriers\SWS_CV43.cfg CEX configuration file for the Coral Sea carriers (1965 & 1973 models) created by SWS.
Appdata\Roaming\CarrierExtensions\Ships\Auxiliary\SWS_Mispillion.cfg CEX configuration file for the Mispillion class of oilers, created by SWS

Samples

  • Located under SWS CEX SDK\Carrier Configuration files. Requires Dropbox - [Contact us]
  • SWS_CV43.cfg provided as an example ship config file
  • MD3_Deck_Tractor.cfg provided as an example ground vehicle config file

Description page

User Interface

Introduction

The user interface consists of the ship control gauge and the panel.cfg entry. The ship control gauge can be an XML or C++ gauge that allows the end-user to interact with the enhanced simobjects. An example deck gauge can be seen in the samples.

The panel.cfg template is the entry for that window, which is added to panel.cfg through the CEX Aircraft Configuration App.

Necessary software

  • PSD2XML from FSX or P3D SDK
  • Notepad

Installation

  • The ship control gauge should preferably be installed in the Gauges folder of the simulator. Its location will be referenced in the panel.cfg so its placement is up to the developer.
  • The .ini file should be placed under %appdata%\CarrierExtensions\ConfigApp. The naming convention should be NAME_panel.ini

Samples

2D gauge in the simulator

SWS_CV_43_73_Panel.ini

Description page

Click here to go to the Panel.ini file description

3D Model

Introduction

The 3D model elements that can be used for CEX operation are:

Each of these elements is be covered in its own page. Please click the links to be taken to the relevant page.

Samples

Model samples are included in the relevant Dropbox folder. Please [contact us through e-mail] to get access.

CEX API

Variable naming

All variables used for CEX animations need to follow the format prefix_variablename. The prefix should be an identifier unique for the simobject you are creating. It can be anything you want, but should be at the start of every Lvar that you intend to use in a CEX-controlled animation.

Examples:

  • SWS Midway uses the prefix cv_41. Example variable: cv41_wire1_pull
  • SWS Coral Sea (both '65 and '73 versions) use the prefix cv_43. Example variable: cv43_park10

Reserved variables

For the convenience and miscellaneous use of carrier and aircraft developers, the following general "read-only" Lvars are created and updated by CEX when it is running. These are not prefixed by carrier.

Variable name Unit Description
CEX_Wire_Engaged enum Integer. If zero (0), then no wire is engaged by the tailhook. Numbers other than zero indicate the cable caught by the tailhook. Cables can be as many as needed.
CEX_Catapult_Engaged enum 1: catapult holdback engaged

2: catapult firing (0-100%) 0: all other times

CEX_in_groove bool 1: lined up on final and less than 1nm from the carrier.

0: not lined up on final or more than 1nm from the carrier.

Two more sets of reserved variables pertain to the FLOLS and cables. These are all using the prefix_varname format.

The tables below use the "cv41_" prefix from our Midway carrier as an example. All variables are read-only and can be used to create modeldef animations for your balls and cables.

Variable name Units Description
cv41_ball_obstructed bool 1 if the ball is obstructed due to a foul deck. 0 if the ball is available to use.
cv41_BALL_VISIBLE bool 1 if the ball is on
cv41_Carrier_distance number Distance from the carrier, returned in Nautical Miles
cv41_GS_on bool 1 if the amber glideslope light is on. 0 if not
cv41_glideslope number Animation for the amber glideslope light. Range is 0-100
cv41_GS_red bool 1 if the red glideslope light (too low) is on. 0 if not
cv41_Ball_datum bool 1 if the datum lights are on. 0 if not.
cv41_Cut_Lights bool 1 if the cut lights are on. 0 if not.
cv41_Ball_WO bool 1 if the waveoff lights are on. 0 if not.
Variable name Units Animation length Description 3ds max keyframes (start-end)
cv41_wire1_pull number Preferably 0-100, but can be changed. Needs to be be set through CEX configuration file. Denotes the longitudinal pull of the cable.

0 is the cable in its,neutral pose, while 100 is the cable pulled at the tip of the landing,deck.

wire1 indicates the wire number.

0-100
cv41_wire1_height number Preferably 0-100, but can be changed. Needs to be be set through CEX configuration file. Denotes the vertical pull of the cable (above the deck).

0 is the cable,in its neutral pose, while 100 is the cable pulled at the tip of the,landing deck.

wire1 indicates the wire number.

110-210
cv41_wire1_side number Preferably 0-100, but can be changed. Needs to be be set through CEX configuration file. Denotes the lateral pull of the cable (above the deck).

0 is the cable pulled fully left, 50 is centered and 100 is right.

wire1 indicates the wire number.

240-340


TACAN

TACAN is supported on radio line of sight out to 150 nautical miles. It can be tuned through A:NAV ACTIVE FREQUENCY:1, A:NAV ACTIVE FREQUENCY:2, or through a dedicated L:var - (L:CEX_TACAN_frequency,mHz). For shipboard transmitter implementation, see CEX configuration file. The set and read L:vars used by the aircraft's tacan receiver system are shown below:

Variable name Read or Set Description
(L:CEX_use_TACAN,bool) Set Set this to 1, otherwise CEX's Navaids menu page will notify the user that TACAN is unusable due to lack of aircraft support
(L:CEX_TACAN_frequency,mHz) Set CEX TACAN will normally be tuned through the Sim's native NAV1 and NAV2 frequency A:vars, however, it may also be tuned through this L:var
(L:CEX_nav1_has_TACAN,bool) Read Non-zero if the NAV1 active frequency A:var is tuned to a valid, in-range CEX TACAN
(L:CEX_nav1_TACAN_bearing,degrees) Read TACAN radial. That is, the magnetic bearing from station to aircraft (using the magnetic variation at the station)
(L:CEX_nav1_TACAN_distance,nautical miles) Read Slant range from station to aircraft, in nautical miles
(L:CEX_nav2_has_TACAN,bool) Read Non-zero if the NAV2 active frequency A:var is tuned to a valid, in-range CEX TACAN
(L:CEX_nav2_TACAN_bearing,degrees) Read TACAN radial. That is, the magnetic bearing from station to aircraft (using the magnetic variation at the station)
(L:CEX_nav2_TACAN_distance,nautical miles) Read Slant range from station to aircraft, in nautical miles
(L:CEX_lv_has_TACAN,bool) Read Non-zero if (L:CEX_TACAN_frequency,mHz) is tuned to a valid, in-range CEX TACAN
(L:CEX_lv_TACAN_bearing,degrees) Read TACAN radial. That is, the magnetic bearing from station to aircraft (using the magnetic variation at the station)
(L:CEX_lv_TACAN_distance,nautical miles) Read Slant range from station to aircraft, in nautical miles

ICLS

ICLS (carrier-based ILS) is supported in the form of a faithful implementation of the AN/SPN-41 equipment which has been standard on US carriers since the 1960s. For shipboard transmitter implementation, see CEX configuration file. The set and read L:vars used by the aircraft's ICLS receiver system are shown below:

Variable name Read or Set Description
(L:CEX_use_ICLS,bool) Set Set this to 1, otherwise CEX's Navaids menu page will notify the user that ICLS is unusable due to lack of aircraft support
(L:CEX_ICLS_channel,enum) Set This variable should be set to a value between 1-20 inclusive, to tune the receiver
(L:CEX_ICLS_active,bool) Read Non-zero if the (L:CEX_ICLS_channel,enum) is tuned to a valid AN/SPN-41 which is in range and angular limits for reception.
(L:CEX_ICLS_lineup,degrees) Read Lineup error in degrees. If this is greater than zero, you are to the left of the centerline, if less than zero, you are right of the centerline. Used for your CDI animation.
(L:CEX_ICLS_glideslope,degrees) Read Glideslope error in degrees. If this is greater than zero, you are above the glideslope. If this is less than zero, you are below the glideslope. Used for the Glideslope needle animation.

The glideslope can be changed by the user through the CEX menu.

(L:CEX_ICLS_BIT,bool) Set AN/ARA-63 (airborne ICLS receiver) Built-In Test. While this variable is non-zero, then the needle variables (L:CEX_ICLS_lineup,degrees) and (L:CEX_ICLS_glideslope,degrees) will not be set to the current glideslope and lineup, but instead will be set according to the ARA-63 test pattern.

(L:CEX_ICLS_active,bool) will also be non-zero during the test.