Windows

To install vice on Windows, download and launch the installer below. After installation, vice will be available in the Windows Start menu and a shortcut will be added to your desktop.

Macintosh

On a Mac, download the zip file below; it contains a universal binary that runs on both Intel and Apple CPUs. Note that MacOS Big Sur or a more recent version of OSX is required. After opening the zip file, drag Vice.app to your Applications folder to install it.

Linux

On Linux systems, it is necessary to install vice from source. See the directions on building vice on Linux in the source code distribution for details.

Reporting Bugs

If you encounter bugs in vice, apologies! It would be of great help if you would send in a report if vice crashes or if you see mistakes in how it simulates aircraft or the STARS interface.

The best way to report bugs is via the "bugs" channel on the vice discord. Alternatively, if you have a github account, you can file bugs directly in vice's issue tracker.

Release History

• 0.2.1: Initial release
• 0.3.1: Added KJFK approach scenarios, improved aircraft flight model, routes, and airlines.
• 0.4.0: Added KPHL scenarios, airspace warnings, and KFRG arrivals and intra-TRACON arrivals for KJFK.
• 0.4.1: Fixed bugs in datablock positioning, added "turn left/right X degrees" commands.
• 0.4.2: Fixed a crash at first launch, updated syntax for "turn left/right X degrees" commands.
• 0.4.3: Allow specifying JSON config on the command line, to make it easier to develop new scenarios.
• 0.5.0: Added new scenarios for EWR and LIB departure (thanks to Adam Bolek!)
• 0.5.1: Fixed bug with RNAV approaches not descending, improved JFK arrival spawn and route details.
• 0.6.0: Added scenarios in the F11 TRACON (KMCO, KSFB, KISM, KORL...). Thanks to Mike K!
• 0.6.1: Fixed a crash related to handed off aircraft and sped up launching vice.
• 0.6.2: Added go arounds and ABE TRACON scenarios.
• 0.6.3: Added KJAX scenarios for F11. Updated PHL scenarios for arrival changes.
• 0.6.4: Fixed a bug with intercepting the localizer that occasionally led to aircraft hanging in the air for a while before proceeding.
• 0.6.5: Fixed another bug with intercepting the localizer.
• 0.6.6: Small KJAX scenario fixes and added ISP and HVN arrivals/departures to the JFK scenario.
• 0.7.0: Added LGA scenarios (thanks to Arya T!), and various small bug fixes.
• 0.8.0: When you quit vice, now it remembers all of the aircraft; when you launch it again, you can resume right where you left off. When the sim is paused, hovering the mouse on a radar track displays information about its routing and assignments. Many additional small bugfixes.
• 0.8.1: fixed a bug where the STARS window wouldn't show anything.

Specifying Locations

Throughout the vice configuration files, it's often necessary to specify various locations on the Earth. vice has a built-in database of all of the airports, VORs, NDBs, and fixes in the United States (courtesy of the FAA), which allows using these directly for specifying locations. Locations can also be specified via latitude-longitude positions, given as strings. For convenience, multiple latitude-longitude formats are supported.

(In all three examples above, the location specified is the same—the JFK VOR.)

In vice, if you hold down the control and shift keys and click on a point on the video map, the corresponding latitude-longitude position is copied to the clipboard—this can be very useful when developing new scenarios!

Routes

vice uses a custom syntax for specifying the routes of aircraft, both for arrivals and departures. In addition to the lateral positions along the route, it is possibly to specify speed and altitude restrictions, handoff points, and headings to fly.

Here is an example route from a JFK departure. The first two waypoints are custom fixes at the start and end of the KJFK 31L runway, specified via the "fixes" object in the scenario group, while the next three are standard fixes. The "#223" at the end leaves the aircraft on a 223 heading as it departs RNGRR. It will maintain that heading until it is further vectored by the controller. If there's are further fixes after such a heading, the aircraft may be sent direct to one of those fixes by the controller.

  "_JFK_31L _JFK_13R SKORR METSS RNGRR #223"
            

Altitude and speed restrictions can be specified at fixes. Here's an example from a JFK arrival. The "@a3000" after CATOD specifies a 3,000' altitude restriction at the crossing and "@s210" specifies a 210 kts speed restriction.

  "PZULU [email protected]@s210 [email protected] [email protected]",
            

Finally, a handoff point can be specified using a single "@". When an aircraft reaches that point in the route, it is handed off from the virtual controller to the user. Here is an example from the CAMRN4 arrival at KJFK. Immediately after the aircraft reaches KARRS it will be handed off from the virtual controller that is tracking it (NY_CTR in this case) to the user's control position. The aircraft will continue to CAMRN and then fly a 041 heading until the user gives it vectors.

  "N039.46.43.120,W074.03.15.529 KARRS @ CAMRN #41"
            

Airlines and Aircraft

Both departures and arrivals need to know about which airlines fly their routes and which aircraft they use for them. Airlines are specified via their ICAO strings (e.g., AAL for American Airlines). See the file openscope-airlines.json for the database of possible airlines. In that file, each airline may have one or more aircraft fleets specified, in its "fleets" member. If no fleet is specified, vice randomly chooses an aircraft type from the "default" fleet, but if a particular fleet's aircraft is a better match to a route, you may want to use it. For example, AAL's "long" fleet would be a good choice for trans-Atlantic flights.

For reference, the available types of aircraft and their performance characteristics are available in the openscope-aircraft.json file.

As is probably obvious, both of these databases are by way of openScope, which made them available under the MIT license.

Video Maps

Video maps are specified separately from the rest of the configuration since they require fairly large files and are not normally edited by hand. Video map files are simply JSON files with a series of members, each one of which stores an array of strings giving latitude-longitude positions. Each successive pair of positions specifies a line to be draw when rendering the video map. The following shows an excerpt from the ZNY video maps file that gives a sense of the format.

{
  "ABE": [
    "N041.00.05.616,W075.32.00.217",
    "N041.00.01.277,W075.32.29.551",
    ...
  ],
  "ABE - MVA": [
    "N040.31.00.726,W076.31.35.993",
    "N040.30.09.063,W076.31.21.985",
    ...
  ],
  ...
}
            

There is a utility program for extracting video maps from VSTARS configuration files; it is available from the vstars2vice releases page. Binaries for both Windows and Mac are available. It is a command-line program: the first argument should be the path to a VSTARS configuration file and the second a path to an output file.

Scenario Groups

vice offers users a variety of ATC scenarios, where a scenario consists of one or more airports being controlled, a control position (departure, approach, etc.), and airport configurations—the runways that are active at each airport. Scenarios are organized in scenario groups, which generally collect multiple control scenarios at a single airport. Each scenario group is specified by its own JSON file; see the scenarios/ directory in the vice source code distribution for examples.

These are the elements of a scenario group:

Airports and Departures

The airports in a scenario group are specified via the "airports" member of the scenario group. Each airports is a separate member, named according to the airport's ICAO code (e.g., "KJFK"). The airport object then has the following member variables:

There are two pieces for specifying departures: their initial route leaving the airport, which depends on the active departure runway, and their subsequent route out of the TRACON, which does not. These two parts are specified separately.

The "departure_routes" object gives the initial routing for departures, based both on the runway they are departing as well as their exit fix. Here is an excerpt from the KJFK departure routes:

  "departure_routes": {
    "13R": {
      "ARD,DIXIE,RBV,WHITE": {
        "cleared_altitude": 5000,
        "route": "JFK5",
        "waypoints": "_JFK_13R _JFK_31L #185"
      },
      ...
            

The members of "departure_routes" are strings identifying the departure runway; each departure runway's routes are then represented by an object with one or more members that specify comma-separated lists of exit fixes. (Thus, the specification above applies to departures with exit ARD, DIXIE, RBV, or WHITE, departing runway 13R.) The departure route specification has three members:

• "cleared_altitude": the initial altitude that aircraft are cleared to
• "route": a string naming the route that is added to the start of aircraft's route as shown in flight strips, etc.
• "waypoints": the initial series of waypoints that the aircraft follows. (Here, the first two are custom fixes specified at the ends of the runway.

On departure the aircraft will fly the specified waypoints and then the waypoints specified in the route to its destination. In this case, aircraft will remain on a 185 heading until vectored by the controller (as explained in Routes, above.)

The other half of specifying departures is the array of objects stored in "departures". Each one describes a departure to a particular destination. Here is a KJFK departure to Paris Charles de Gaulle:

    {
      "airlines": [
        {
          "fleet": "long",
          "icao": "AFR"
        }
      ],
      "destination": "LPFG",
      "exit": "HAPIE",
      "route": "HAPIE YAHOO WHALE N251A JOOPY NATZ MALOT NATZ GISTI LESLU M142 LND N160 NAKID M25 ANNET UM25 UVSUV UM25 INGOR UM25 LUKIP LUKIP9E"
    },
  ...
            

Four things must be specified with each departure:

• "airlines": The airlines that fly the route and which part of their fleet of aircraft is used; see airlines and aircraft below for more information
• "destination": the ICAO airport code for the destination. This is only used in flight strips and for the aircraft's datablock on the radar scope; it does not affect its routing.
• "exit": the exit fix for the departure. In conjunction with the departure runway, this is used to determine the aircraft's route leaving the airport using "departure_routes".
• "route": the aircraft's route to the destination. This is mostly used so that flight strips have plausible routes, though vice does its best to have the aircraft follow the given route after it reaches the exit fix.

Arrivals

Arrivals are specified via the "arrival_groups" variable, which allows specifying one or more STARs that bring aircraft to the TRACON. Members of "arrival_groups" give the names of arrival groups; each one stores an array of one or more arrival objects.

Because arrival rates are specified per-arrival group rather than per-STAR, vice can simulate center controllers sequencing multiple STARs into a single arrival flow rather than spawning arrivals on two STARs that follow nearby routes and thus should be sequences.

Each object stored in an "arrival_groups" array corresponds to a STAR. These objects have the following members:

STARs are sometimes able to deliver aircraft to multiple airports. Therefore, the "airlines" member is an object with airport names as members. Each of the airports is associated with an array of objects that specify departure airports, airlines, and (optionally) airline fleets. Here is an excerpt from the CAMRN4 arrival group at KJFK:

  "airlines": {
    "KFRG": [
      {
        "airport": "KDCA",
        "icao": "EJA"
      },
      ...
    ],
    "KJFK": [
      {
        "airport": "MMMY",
        "fleet": "long",
        "icao": "AMX"
      },
      ...
    ]
  }
            

We can see that CAMRN4 applies to both the KFRG and KJFK airports, though with different airlines and different departure airports for the arrivals. The specified departure airports (here, KDCA and MMMY) are only used so that flight strips and data blocks on the scope are realistic, but the specified airlines are used to select the type of aircraft from their fleets. As elsewhere, a value for "fleet" may be specified to limit which types of aircraft may be chosen.

The "runway_waypoints" member can be used for STARs that have different routes depending on the runway. When the user instructs the aircraft to expect a particular approach then the corresponding waypoints are added to its route. As an example, the specification of the KPHL JIIMS4 arrival starts with the following string for "waypoints": "HEKMN N039.27.43.645,W074.56.38.400 @ [email protected]". (The second point is used to set the handoff point to be between HEKMN and JIIMS.) It then has the following "runway_waypoints", corresponding to the runway-specific routes. Note that all start with JIIMS, the same fix at the end of "waypoints".

  "runway_waypoints": {
    "27L": "[email protected] ZMRMN CHPMN PSOUT MKORD #87",
    "27R": "[email protected] ZMRMN CHPMN PSOUT MKORD #87",
    "17": "[email protected] SNEDE #312",
    "35": "[email protected] SNEDE #312",
    "9L": "[email protected] WUDRR WEVVE ERNYY #268",
    "9R": "[email protected] WUDRR WEVVE ERNYY #268"
  },
            

Airspace

Airspace volumes may optionally be specified using the "airspace" object in the scenario group. These volumes may be assigned to controllers in scenarios, in which case vice will show an alert when aircraft are outside of the controller's airspace. The airspace object has two members:

Each member in "boundaries" names a polyline of one or more line segments. Polylines are specified by arrays of locations. The first and second points specify the first line, the second and third points specify the second line, and so forth. Here is an example from the KPHL airspace:

  "PHL_DQO27_33": [
    "N039.21.58.949,W075.28.55.977",
    "N039.25.56.240,W075.29.47.255",
    "N039.26.20.204,W075.27.28.196",
    "N039.22.24.699,W075.26.48.535",
    "N039.21.58.949,W075.28.55.977"
  ]

Note that the first point and the last point are at the same location and thus, "PHL_DQO27_33" is a closed polygon. Airspace boundaries do not have to be polygons like this; because boundaries are generally shared between different volumes of airspace, it's often useful to define boundaries just as polylines and to assemble multiple boundaries to define the lateral extent of a volume of airspace.

Given the boundaries, "volumes" specifies full 3D volumes of airspace. Airspace volumes have three members; "boundaries" is an array of strings that names the boundaries that give the airspace's lateral extent, and "lower" and "upper" specify the altitude range of the airspace. Here is an example from KPHL that uses the boundary defined above:

  "PHL_DU_APP27": [
    {
      "boundaries": [
        "PHL_DQO27_33"
      ],
      "lower": 5000,
      "upper": 6000
    }

Scenarios

Scenarios pull together components from the definitions in scenario groups in order to present specific control scenarios to the user. The scenarios object's members are the names of the scenarios. Each of these scenarios may have the following members: