ACS Coupling System

A more readable, more flexible, and preferrably easily extensible datastructure in the config.txt was needed, and some way of standardising the logic (at the very minimum, an include file, but preferrably a library). It needed to support many more different types of coupler, vehicles with different couplers on each end, and so on.

The ACS System is an extension of the BlueStar coupling standard for TRS models (effectively BlueStar V2) and provides for the effect of working couplings on rolling stock. From version 5 of the ACSLib ACS vehicles are compatible with older BlueStar/CoupleStar ones.

To add ACS couplings it is necessary to edit the asset config file, add attachment points to the mesh (see below for an alternative which can sometimes be used) and to create a script or edit the existing one. Due to the fact that you need access to the source files of the asset and to be able to script it is an advanced technique that cannot easily be carried out by an end-user.

For couplers implemented as meshes in the mesh-table (usually but not always animated), position and orientation tags can be used to locate the attached meshes:

For front couplings the tag 'position 0,Y,0' should be added.
For back couplings two tags are needed, 'position 0,Y,0' and orientation '0,0,3.14159'
in both cases the value Y is 0.46 metres inboard of the Y value of limfront and limback respectively.

The Attachment Points

All of the coupler, hoses and cables are attached to two points, one on the face of the front buffer beam (a.couple0) and one on the face of the rear beam (a.couple1). a.limfront should be 0.46m forward of a.couple0 and a.limback 0.46m rearward of a.couple1. a.couple0 and a.couple1 must be at x=0 and z=0.

Create a.couple0 in top view and move it into position. Then clone and position it to create a.couple1 and rotate it 180°. The Y axis of the two coupler points should point towards 0,0,0.

The Config File

First off, here is an example config.txt fragment:

extensions {
  max_permitted_speed-60850 "125mph"
  active-coupling-standard-60850 {
    version-major "2"
    version-minor "0"
    brakes "air"
    front {
      coupler "knuckle|screwlink|hook"
      gangway "gangway"
      airbraketype "single"
      airbrakeside "left" 
      vacbrake "none"
      multiple-working "none"
      heating-type "electric"
      rch "high"
    }
    back {
      coupler "knuckle|screwlink|hook"
      gangway "gangway"
      airbraketype "single"
      airbrakeside "left" 
      vacbrake "none"
      multiple-working "none"
      heating-type "electric"
      rch "high"
    }
  }
}

So, what does all this do, and what are the options?

Extension Container

extensions {
  ...
}

This is for TRS2006 compatibility - it's all going in the extensions container. This does work in TRS2004 as well. Watch for the caveat at the end though...

Max Permitted Speed

      Max_Permitted_Speed-60850 "125mph"

Not strictly part of the coupling code, but may as well mention it. This is for the Max Permitted Speed rule to tell how fast this vehicle should be permitted to travel. It will tell both AI drivers and the human driver (via the Custom HUD rule) what the maximum permitted speed is for the train they are driving, based on information from each vehicle. (And in a future version of the rule, more stuff too...)

ACS Container

      active-coupling-standard-60850 {
        ...
      }

This is the container within which all the config information will be held.

ACS Version

        version-major "2"
        version-minor "0"

Version numbers. This is useful when later code needs to read earlier format config files. Should make extending the standard a lot easier.

Braking System

        brakes "air"

Defines what type of braking system is fitted to this vehicle. Options are:

"air"
"vac"
"dual"
"none"

This is independant of what hoses are available - unbraked but through piped stock is an entirely possible combination, and is representable.

Position

        front {
          ...
        }
        back {
          ...
        }

Containers for the front and back of the vehicle. 'Front' is defined as "the a.limfront end", and 'back' "the a.limback end". Available options for both are the same, so I'll describe them just once.

Coupler Type

          coupler "knuckle|screwlink|hook"

What type of coupler do we have on this end of the vehicle? Options are:

"hook" -- connects to screwlink/instanter/3link/hst-emergency-bar.
"3link" -- connects to hook.
"instanter" -- connects to hook.
"screwlink" -- connects to hook.
"hst-emergency-bar" -- connects to hook.
"bar-full" -- connects to "bar-none". Half of a handed pair for when one vehicle has the entire bar coupling.
"bar-none" -- connected to by "bar-full". The other half of the handed pair.
"bar" -- connects to self only. Used when both vehicles have half the bar coupling.
"knuckle" - standard knuckle coupler.
"tightlock" -- different to a standard knuckle, refers to a knuckle style coupler often fitted to multiple unit trains that also include electrical connections.
"wedgelock" -- London Underground coupler.
"bsi" -- Found on Sprinter DMUs and derived designs.
"dellner" -- Also compatible with scharfenberg coupling.
"scharfenberg" -- Also compatible with dellner coupling.
"(other string identifier)" -- Any string that is not recognised from the above list is assumed to be a symmetrical meet-in-the-middle type of coupler.

Certain couplers are purely compatible with other identical couplers, others are inter-compatible. Some produce handed pairs - e.g. a 3 link chain couples to a hook, and wagons with this coupling are typically fitted with both a hook and a chain.

Multiple coupler options can be specified, and are separated with a vertical bar character. The earlier option is used in preference, so list the best coupler option first.

A typical unfitted freight wagon with a 3 link coupling is specified as "3link|hook". A vehicle fitted with a knuckle, screwlink and hook (e.g. a swingknuckle fitted locomotive) is specified as "knuckle|screwlink|hook". A BR coaching stock dropknuckle (a knuckle and a hook, but no chain) is specified as "knuckle|hook". If the vehicle also has an emergency screwlink which is not permanently fitted, then "knuckle|hook|screwlink" would be appropriate -- this would cause ACS to prefer the chain type coupler from the adjacent vehicle rather than using the emergency screwlink, which would only be used when necessary. A Victorian Railways transitional coupler (which has a chain and a knuckle, but no hook) is specified as "knuckle|3link".

Dellner and Scharfenberg couplings are treated as compatible, so a dellner will also couple to a scharfenberg.

If your coupler type isn't listed, define a standard name for it, and start using it. ACS supports arbitrary extension - any new coupler it hasn't seen before will be treated as a symmetrical coupler. ACS will tell you if it has connected to an identical coupler on the adjacent vehicle.

If you need a new handed pair type (where the coupler on the end of one wagon is not the same as that on the end of another), then you will need to contact the ACS author to get one added.

Gangways

          gangway "gangway"

Passenger gangway between vehicles. Options are:

"none"
"rubbing-plate"
"gangway"

This is really intended for coaching stock - it is assumed that all gangways are compatible. I've been considering a 'one piece' gangway option - to aid with the centre of multiple unit trains, where there is no separation point (it will help with deciding which vehicle should display the gangway) - but I'm not sure whether this is of sufficient benefit to include, as it involves a whole new set of logic here that most people won't use, and for the cases it is interesting, the same person has made both vehicles, and can therefore do it themselves... Comments please.

Pipes for Air Brakes

          airbraketype                      "single"
          airbrakeside                      "left"

Brake pipes for air brakes. Options for airbraketype are:

"twin"
"single"
"none"

Twin is the UK standard two pipe air brake system (train pipe and brake pipe). Single is the US standard air brake system where reservoirs are charged from the brake pipe rather than the train pipe (this has appeared on some modern freightcars for reasons unknown, so is included).

Options for airbrakeside are:

"left"
"right"

Most traincars (UK, US, etc.) use left-sided airbrakes, so airbrakeside "left" will generally be used, but the right option was added to support both left and right-handed brake pipes on Australian content.

Pipes for Vac Brakes

          vacbrake "none"

Brake pipes for Vacuum brakes. Options are:

"twin"
"single"
"high"
"none"

Single is the UK default for fitted stock, high connections seems to be the standard on UK steam locos. Twin pipes (operating at two different vacuum levels) has been tried in the UK - and while not much fitted stock has the twin pipe system, most air brake, through vac piped stock seems to have two vac pipes.

Multiple Working Cables

          multiple-working "none"

Multiple working connections. Options are:

"(color)-(shape)" -- e.g. "blue-star" or "red-diamond", etc
"AAR" -- as used on GM locos
"SR27" -- bagpipes
"(other identifier string e.g. classname)"

Train Heating

          heating-type "electric"

Coach heating. Options are:

"none"
"steam"
"electric" -- standard ETH
"dual" -- both Steam and standard ETH
"southern-electric" -- The Southern, who pioneered electric train heating in the UK, fitted heating that was compatible with their DC powered EMUs, and thus ran from the same voltage as the DC power supply. When the rest of BR went ETH, different standards were adopted, resulting in the Southern having a different and incompatible ETH standard...

Lighting Control Cables

          rch "high"

Through wiring for lighting control, to the Railway Clearing House standard. Also used more recently for other things - e.g. remote control via various methods - including TDM. I believe it is also used for signals to control doorlocks on stock so fitted - though I could be wrong on this. Options are:

"high" -- positioned as is fairly standard on coaching stock
"low" -- positioned as is fairly standard on streamlined locos, e.g. the front of a DVT, or a cl90
"none"

Notes

For all of these where "none" is an option, entirely missing out that line is equivalent to stating "none". This should make stock which doesn't use most of the features much more palatable to produce. This will also help when extending the standard - as new features will automatically be assumed to be not present on stock built to older standards...

That's all very well and good, but how is this supposed to be backwards compatible with the old bluestar standard?

I'm making the code fall back to reading the old config entries if it can't find the new ones. The real problem is that new stock will also have to include config.txt entries for the old bluestar, so that old vehicles know what to do when they couple to this one. Yes, this means that the old tags will never actually go away, but at least TRS2006 doesn't whinge about them so hard as of SP1...

The Script

Basic ACS handler:

void ACShandler(Message msg)
  {
    if(msg.dst == me)
    {
      // tokenize msg.minor into ('|') separate strings
      string[] callback = Str.Tokens(msg.minor, "|");
      
      if (callback.size() >= 3)
      {
        if (callback[1] == "back")
        {
          if(callback[0] == "coupler")
          {
            if(callback[2] != "none")
            {
              //backCoupled = true;
            }
            else
            {
              //backCoupled = false;
            }
          }
        }

        if (callback[1] == "front")
        {
          if(callback[0] == "coupler")
          {
            if(callback[2] != "none")
            {
              //frontCoupled = true;
            }
            else
            {
              //frontCoupled = false;
            }
          }
        }
      }
      else
      {
        TrainzScript.Log("ERROR: ACS Library returned invalid callback \"" + msg.minor + "\" - not divisible into at least 3 parts!");
      }
    }
  }