TrainzOnline - User contributions [en]

Talk:ACS Coupling System

2025-04-15T21:35:38Z

Slenderman8888: Created page

== Establish standard positions for hoses, cables, etc ==
There should be an official set of XYZ positions on where to place cables and hoses for each state to allow for seamless compatibility between stock. From my experience it seems like some creators just pick their own positions with the result being incorrect connections.
On my own traincars that feature ACS connections, I have based all my cable and hose placements off of Peter Hicks' Aircon Mk2 coaching stock. I propose that the hose and cable positions of these coaches should be used to define a set of uniform standard positions on where hoses should go when in the "connected" positions. --[[User:Slenderman8888|Slenderman8888]] ([[User talk:Slenderman8888|talk]]) 07:35, 16 April 2025 (AEST)

ACS Coupling System

2024-11-25T22:07:04Z

Slenderman8888: Added missing staggered RCH option, as seen on Peter Hicks' Mk2's and Bloodnok's Mk3a's.

===Introduction===

There are many and varied problems with the existing BlueStar standard - but the main ones are the inflexibility beyond the initial application (coupling mineral wagons and transition era locos), and the rather arcane numeric values put into the config.txt.

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.

[[File:Acs attachments.png|border|middle|x375px]]

===The Config File===
First off, here is an example config.txt fragment:

<pre>
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"
}
}
}
</pre>

So, what does all this do, and what are the options?
====Extension Container====
<pre>
extensions {
...
}
</pre>

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====
<pre>
Max_Permitted_Speed-60850 "125mph"
</pre>

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====
<pre>
active-coupling-standard-60850 {
...
}
</pre>

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

====ACS Version====
<pre>
version-major "2"
version-minor "0"
</pre>

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====
<pre>
brakes "air"
</pre>

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====
<pre>
front {
...
}
back {
...
}
</pre>

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====
<pre>
coupler "knuckle|screwlink|hook"
</pre>

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====
<pre>
gangway "gangway"
</pre>

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====
<pre>
airbraketype "single"
airbrakeside "left"
</pre>

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====
<pre>
vacbrake "none"
</pre>

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====
<pre>
multiple-working "none"
</pre>

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====
<pre>
heating-type "electric"
</pre>

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====
<pre>
rch "high"
</pre>

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
*"staggered" -- positioned on coaching stock where one cable is mounted higher than one on the opposite side, e.g. Mk2d-Mk2f and Mk3a coaching stock
*"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:

<pre>
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!");
}
}
}
</pre>

[[Category:Modeling]]

HowTo/Create an Interactive Session

2017-08-30T21:15:02Z

Slenderman8888: /* Penalising Derailments */

The Trainz [[session|"Session"]] concept is very powerful and yet also easy enough that anyone can create their own Sessions. The simplest Session involves adding consists to a route, assigning some AI orders, and setting a few basic startup settings for the session in the default rules.

This document is a quick introduction to sessions aimed at getting people to think beyond this most basic level of session, and to take more advantage of the power and flexibility of the session concept.

It assumes you are familiar with Driver and basic Surveyor usage including placing scenery and trains. If you aren't familiar with these concepts, then you may need a more basic introduction to Trainz [[Driver]] and [[Surveyor]] and go through the [[HowTo/Create your first Session]] tutorial. For an overview of Session Rules and how they operate, check out [[Session_Rules_Overview]].

=Creating an interactive session=

You might be interested in our latest Twitch TV video tutorial [https://youtu.be/sI6jzb3i4Tw HERE] on session creation.

In the routes menu, find the route 'Springfield Industrial District' (you may have to unselect 'show only favorite routes'). This example uses this route because it's small, and it is built-in with Trainz 12. Show the sessions, and then click 'new session'.

Place a CHN ND5-1 on one of the turntable tracks, and a CHN G70K tanker in the yard next to the turntable.

==Setting the initial startup options==

Now open the 'Edit Session' dialog on the main menu. Change the session name and type something in for the description.

You should have something that looks roughly like this:

[[Image:Session-tutorial-1.jpg|640px]]

If you are using [[TS2010]], remove the 'ConsistDataHandler' and 'QuickDrive' rules. Nice though they are, we don't want the player of this session to be able to arbitrarily create new vehicles. To delete the rule, click on it to select it, and then click the 'Delete' button.

Note: If you are using [[TS12]] or [[Trainz Simulator Mac]], you won't have 'startup options' - '[[QuickDrive]]' has taken over this role. So instead of deleting those two rules, edit the 'QuickDrive' rule (highlight it and click the 'Edit' button), and tick the "Gameplay Session" option in the QuickDrive options. Save the changes.

==Adding a displayed score==

Add the [[Display Custom HUD Rule]] - click 'add', find 'Display Custom HUD' in the list, select it, and click the tick button.

Add a [[Variable Modify Rule]]. Once you've added this, click the 'Edit' button, and you can set the rule properties. Anything you can click on is underlined. Click on 'Add', and set this to 'Change'. Also set the number to '0'. It should look like this:

[[Image:Session-tutorial-2.jpg|640px]]

Confirm these changes by clicking the tick button on the 'Properties' dialog.

Add a [[Variable Show Rule]].

==Checking the user makes a train correctly==

Add a [[Consist Check Rule]]. Select 'Complete whenever a train matching the description exists'. This opens up several more options. Under 'Specific Vehicles', click the plus, and add our ND5. Repeat this and add the G70K as well. Also tick 'Enforce strict exclusive checking'. It should look like this:

[[Image:Session-tutorial-3.jpg|640px]]

'Enforce strict exclusive checking' will make the consist check rule check the consist more thoroughly - so if someone picks up too many vehicles in the yard, it won't trigger.

Confirm these changes by clicking the tick button on the 'Properties' dialog.

Finally, Add a 'Variable Modify' rule at the bottom, under 'Consist Check'. We will click the right arrow button once to indent the rule one level to the right.

This means this rule will not take effect immediately, but will be triggered by the 'Consist Check' rule, when the consist exists.

Now tick the 'Edit Session' dialog.

==Driving your first session==

Let's try this out in Driver now.

Click on the Driver button next to the main menu. Save the session. (If it asks to save the map, you've done something wrong - did you place the trains in the wrong layer?)

In Driver, you should see the 'Custom HUD' panel, and in it, an extra field labelled 'Score'. It should be zero.
Take the ND5 over to the G70K tanker, and couple up to it. If the rules are set up right, 'Score' should change to '1'.

[[Image:Session-tutorial-4.jpg|640px]]

==Adding a pickup task at an industry==

Okay, let's take this a stage further. Go back to surveyor, and set the current layer to the session layer in the layers tab.

==Configuring an industry==

Configure 'Palmer Chemicals', by clicking on the industry track (between the two arrows) with the question mark icon from the 'scenery' tab. This is a 'multiple industry new' track. As this is a new session, it won't have any configuration yet - so we'll need to add some. See [[HowTo/Configure an Interactive Industry]] for details.

==Checking the user uses the industry==

Go back to the 'Edit Session' dialog. At the bottom, add a 'Resource Check' rule. Edit the resource check rule.

Pick the 'Watch Vehicle Queue' option. Within this, set 'CHN G70K Tanker' as the target object. Set the queue to be 'liquid' (there should be only one option). Set the product to be Aviation Fuel. Set the amount to be '72040' (you can actually type in '99999' and it'll autocorrect to the maximum size of the queue if it's larger than what the queue can hold). Ensure 'Complete when the designated queue equals or exceeds required amount' is set. It should look like this:

[[Image:Session-tutorial-5.jpg|640px]]

Tick the Properties dialog.

Now add a 'Variable Modify' rule below the [[Resource Check Rule]], configure it to add one to the variable 'score', and indent it one step to the right. Your session rules should look like this:

[[Image:Session-tutorial-6.jpg|640px]]

==Testing the extended session==

Now let's try this out in Driver. Couple the ND5 to the tanker as before. The score should update to 1 when you do this. Now take the wagon up the hill to Palmer Chemicals.

Stop the wagon next to the three pink tanks, and wait for it to load. Once it is loaded, the score should update to 2.

[[Image:Session-tutorial-7.jpg|640px]]

==Adding a delivery task at an industry==

And another stage. Go back to surveyor, and reselect the session layer.

Go to the airport, and in it's properties, set it's Aviation Fuel queue to start at Zero and consume Zero.

Now in 'Edit Session', add another 'Resource Check' rule to the bottom of the list. Configure this one to watch an industry queue on 'Local Airport'. There will be several queues here - you want 'av_in_q', with product 'Aviation Fuel'. We're going to watch for 144000 units, and complete when the queue equals or exceeds the required amount.

It should look like this:

[[Image:Session-tutorial-8.jpg|640px]]

Underneath and indented beyond this, we're going to need another Variable Modify rule.

When we test this in Driver, we'll need to fill the tanker twice - and deliver two loads. Only at the second load will the score go to 3.

==Checking vehicles are left in designated places==
''TBD''

==Adding instructions==
''TBD''

==Penalising Speeding==
''TBD''

==Penalising Passing Red Signals==
''TBD''

==Penalising Derailments==
click the add button in session rules and look for the rule "wait for derailment" add this in your session rules. this rule detects when a train derails then add a child rule end session since a derailment will mean the locomotive will no longer work end the session now

==Adding a 'session complete' achievement==
''TBD''

=Hints and Tips=

Some background information you may find useful.

==Layers==

TS2010 introduced the concept of layers to Trainz, and when working on a session, you will need to use them. The key thing is that this allows you to add most types of Trainz assets to the session, which previously could only be used in a route. As well as the usual Traincars, this can be scenery objects, trackside objects, even splines.

A good tip is to lock the route layer(s). This will help prevent accidental editing of the route layers.

Pay particular attention to layers if you use the 'quicklaunch' feature to launch Driver direct from Surveyor and return to Surveyor afterwards. The layer you had selected before probably won't still be selected afterwards, so you'll need to check it every time you return from Driver.

=='Base session' assets==

Some routes come with a 'base session'. This generally has pre-configured settings for industries and other scripted assets in it. You may find, should your chosen map depend heavily on multiple industry assets or other similar scripted content, that you may need to base your session on a 'base session' asset, rather than creating a new session.

In this case, the default rules list may differ - as it may have been created in a different version of Trainz, or the route creator may have decided to change a few things. Feel free to add any missing rules you want, or remove extras you don't.

==Default rules==

In the 'Edit Session' dialog in TS2010, we have six rules by default.
* '[[Startup Options Rule]]' allows us to specify the control mode for the session, the weather, the start time, and a few other bits'n'pieces.
* '[[Driver Setup Rule]]' allows us to assign drivers to trains, and optionally give those drivers AI orders.
* '[[Driver Commands Rule]]' allows us to specify what orders can be assigned to AI drivers in the session.
* '[[Clean up Derailed Trains Rule]]' will mop up derailed vehicles.
* '[[ConsistDataHandler Rule]]' is used by QuickDrive
* '[[QuickDrive Rule]]' provides the quick drive interface that allows you to create consists and so on in Driver.

TS12 and Trainz Simulator Mac does not have 'Startup Options' - 'QuickDrive' now performs that role.

As a general rule, for a pre-planned interactive session, you probably don't want to permit the human driver to issue AI orders, or to be able to use the features of QuickDrive.

However, you probably want to be able to issue AI orders to background AI traffic while making the session, and you'll certainly need to fix those orders later when it turns out they don't quite do what you wanted them to. If you turn them off now, you'll have to turn them back on again when doing these operations - so my advice would be to only turn them off (by unticking them all) in 'Driver Commands' at the end of the creation process, once the session is finished. It'll get too annoying to keep turning them on and off when you need to fix problems with the background AI otherwise.

With TS2010, QuickDrive will unfortunately have to be removed from the rules list. It'd be way too easy for people to cheat using it.

With TS12 and Trainz Mac, it is possible to disable the advanced features of quickdrive, but still use it's better Cab/DCC mode selection screen - simply tick the 'Gameplay Session' checkbox in the QuickDrive options. This will deny the player access to the parts of QuickDrive which would cause problems in an interactive session.

==See Also==
* [[Session_Rules_Overview]]

[[Category:How-to guides]]