########################
	[DE] AFR200 Scripterweiterung von der_Nik_
########################

	!!!English version below!!!

----------------
Installation
----------------

Zum Installieren einfach den Ordner "OMSI 2" in "Steam\Steamapps\common" (Ordner, in dem OMSI 2 installiert ist) einfügen und überschreiben.

Hinweis: Bei Updates des Busses kann es dazu kommen, dass die Mod wieder überschrieben wird. Dann einfach noch einmal installieren. Die hierfür benötigten Dateien werden bei der Erstinstallation zusammen mit Backups der überschriebenen Originaldateien (für eine Deinstallationen) in "OMSI 2\Addons\Thueringer_Wald\AFR200 Mod der_Nik_".

----------------
Features
----------------
	
- Neue Verkaufsanzeige
	Die Verkaufsanzeige wurde nach Vorbild der alten Drucker der SWEG neu gestaltet. Die Zielcodeeingabe ist zwar funktionsfähig, hat aber keinen Einfluss auf den Fahrscheinverkauf.

- Optimierung des Fahrscheinverkaufs
	Der Fahrscheinverkauf ist nun auch mit dem Ticketpack von Bad Hügelsdorf 2020 kompatibel. Über "24h" + "Kind" kann die Kindertageskarte verkauft werden, alle weiteren Tickets werden durch mehrmaliges Drücken von "24h" Ausgewählt.

- Realistische Wegimpuls-Vorschaltung (bei entsprechend angepasster Hofdatei)
	Wie in der Realität kann die Haltestellenfortschaltung durch die Anzahl der Radumdrehungen und der daraus resultierenden zurückgelegten Distanz ermittelt werden.

- Ansagenverzögerung: Bei aktivierten Ansagen wird die Ansage entsprechend der Constfile-Einstellung verzögert abgespielt.

- Verspätungsanzeige
	Optional kann eine Verspätungsanzeige eingeblendet werden. Diese Funktion ist fiktiv, der Vorbilddrucker bei der SWEG nicht über eine solche Funktion. Es soll aber auch AFR200 mit Verspätungsanzeige gegeben haben, deshalb habe ich sie mit eingebaut.
	Die Verspätungsanzeige kann mittels "F" -> 06 -> "Auslösen" Ein- und Ausgeblendet werden.

- Dynamische Zielwechsel: per Befehl in der Hofdatei kann innerhalb einer Route das Matrixziel gewechselt werden

- Der Kilometerstand wird automatisch übernommen und muss nicht mehr manuell eingegeben werden

----------------
Fortschaltung
----------------

Falls in der Hofdatei Datensätze zur Route vorhanden sind, nutzt der Drucker automatisch die Wegimpuls-Fortschaltung, die anstelle des OMSI-Fahrplans die zurückgelegte Distanz als Referenz für die Fortschaltung nutzt. Dies Entspricht auch der Fortschaltung, die die mir bekannten AFR200-Drucker in der Realität genutzt haben. Hierdurch wird z.B. auf der Karte Thüringer Wald verhindert, dass der Drucker bei Stichfahrten wild hin- und herschaltet, auch auf die "kein Halt"-Haltestellen in der Hofdatei kann verzichtet werden, da die Fortschaltung unabhängig vom OMSI-Fahrplan funktioniert.
Diese Art der Fortschaltung hat jedoch wie in der Realität ihre Tücken:
- Leider lassen sich Haltestellendistanzen nicht Automatisch aus OMSI auslesen, deshalb ist eine manuelle Ermittlung und Eintragung in die HOF-Datei (unten beschrieben) erforderlich. Falls keine Wegimpulsdaten vorhanden sind, nutzt der Drucker die aus dem Addon bekannte Fortschaltung anhand des OMSI-Fahrplans.
- Für eine Korrekte Funktion ist zwingend der exakte Raddurchmesser in der Constfile anzugeben. Ein Falscher Raddurchmesser führt zu einer falschen Skalierung der Distanzen (nur wichtig, falls der Drucker in andere Busse verbaut wird).
- Die Manuelle Fortschaltung setzt den Wegimpuls zurück, deshalb sollte diese nur genutzt werden, wenn man an einer Haltestelle steht, und dann auf die aktuelle Haltestelle gestellt werden. Ca. 50 Meter nach der Haltestelle schaltet der Drucker dann wieder weiter und beginnt ab dort mit der Wegimpulszählung bis zur darauffolgenden Haltestelle. Die ca. 50m Versatz bleiben dabei dauerhaft erhalten, sodass der Bus immer erst kurz nach der Haltestelle umschaltet und nicht schon, während man noch an der Haltestelle steht.
- Falls die Route bereits vor der eigentlichen Starthaltestelle in den Drucker eingegeben wird, beginnt der Wegimpuls bereits ab diesem Moment zu zählen. Ggf. ist deshalb ein manuelles zurückschalten an der Starthaltestelle nötig.

----------------
Konfiguration in der Constfile
----------------

Die Constfile wurde um folgende Befehle ergänzt:

afr_delay
	Hiermit kann die Verspätungsanzeige standardmäßig eingeblendet werden. 

afr_wegimpuls_schaltdistanz
	Distanz, nach der bei manualler Fortschaltung Weitergeschalten wird. Sollte auf 50 belassen werden.

afr_wegimpuls_raddurchmesser
	Raddurchmesser des linken Vorderrads (für Wegimpuls-Fortschaltung). Der Raddurchmesser der Vorderachse kann in der .bus-Datei unter "achse_raddurchmesser" ausgelesen werden.

afr_ansagenverz_mode
	Ansagenverzögerung: relative oder absolute Verzögerung?
	0	keine Verzögerung
	1	relative Verzögerung
	2	absolute Verzögerung, ab Abfahrt
	3	absolute Verzögerung, vor Ankunft
	
afr_ansagenverz_wert_rel
	Relative Verzögerung: Wert, bei dem die Ansage abgespielt werden soll
	0.25 = nach 1/4 der Fahrt zur nächsten Haltestelle
	0.5 = auf halber Strecke zwischen den Haltestellen
	usw.

afr_ansagenverz_wert_time
	Absolute Verzögerung: Wert, wie viel vor/nach der Haltestelle die Ansage abgespielt werden soll. Zeit in Sekunden für Fahrplanabhängige Fortschaltung.

afr_ansagenverz_wert_dist
	Absolute Verzögerung: Wert, wie viel vor/nach der Haltestelle die Ansage abgespielt werden soll. Strecke in Metern für Wegimpuls-Fortschaltung.

----------------
Konfiguration in der Hofdatei
----------------

In der Hofdatei können durch spezielle Haltestellen-Einträge kartenspezifische Einstellungen gemacht werden.

Die Erläuterungen haben folgendes Layout:
Haltestellenname [tabstop] String 0 [tabstop] String 1 usw.

#AFR-Options	Betriebsname
	Der Betriebsname wird auf dem Startbildschirm des AFR200 angezeigt und enthält max. 16 Zeichen. Fehlt dieser Eintrag, wird "AFR200 MOBIL" angezeigt.

#AFR-Tickets_1	Ticketstring0	Ticketstring1	Ticketstring2	usw.
	Hiermit können die auf dem Verkaufsscreen gezeigten Kürzel manuell definiert werden. Empfohlen sind 2 Zeichen, Technisch können aber bis zu 6 Zeichen angezeigt werden.
	Es können pro Haltestelleneintrag 8 Tickets Definiert werden, die Reihenfolge ergibt sich aus dem Ticketpack:
	#AFR-Tickets_1: Tickets 0 bis 7
	#AFR-Tickets_2: Tickets 8 bis 15
	usw.
	Standardmäßig werden folgende Kürzel benutzt:
	EE - Einzelfahrt Erwachsen
	KE - Kurzstrecke Erwachsen (nicht auf Thüringer Wald)
	TE - Tageskarte Erwachsen
	EK - Einzelfahrt Kind
	KK - Kurzstrecke Kind (nicht auf Thüringer Wald)
	WE - Wochenkarte Erwachsen (auf Thüringer Wald)
	WK - Wochenkarte Kind (auf Thüringer Wald)

#wegimpuls_73101_1	Abstand0	Abstand1	Abstand2 usw.
	Mit diesen Einträgen werden die Haltestellenabstände für die Wegimpuls-Fortschaltung definiert.
	73101 beschreibt Linie & Route (hier: Linie 731, Route 1). 7602 Wäre Linie 76, Route 2 usw.
	1 Beschreibt wie schon bei den Tickets eine Fortlaufene Nummerierung, sodass die Anzahl der Haltestellen pro Route nicht beschränkt ist.
	_1: Abstände 0 bis 7
	_2: Abstände 8 bis 15
	usw.
	WICHTIG: Abstand 0 beschreibt den Abstand bis zur 0. Haltestelle (Starthaltestelle), Abstand 1 dann den Abstand von der 0. zur 1. Haltestelle. Der Erste Eintrag (Abstand0) ist deshalb immer eine "0" bzw. wird von OMSI gar nicht ausgelesen.
	Dieses System klingt auf den ersten Blick vielleicht etwas verwirrend, hat sich für mich aber zum erfassen der Distanzen als am praktikabelsten erwiesen.
	
#zielwechsel_73101	05_129	07_29	usw.
	Mit diesem Eintrag kann der Dynamische Zielwechsel entlang einer Route definiert werden.
	Der Schlüsselbefehl setzt sich zusammen aus "#zielwechsel_" + Linie & Route (wie oben).
	Anschließend können in den Strings bis zu 8 Zielwechsel nach folgendem Format definiert werden: Haltestellenindex (2 Ziffern) + "_" + Zielcode.
	"05_29" bedeutet, dass ab der 4. Haltestelle der Zielcode 29 verwendet werden soll (der Index beginnt bei 0). Das Ziel wird dann umgeschaltet, sobald die Haltestelle vor der definierten verlassen wurde und der Drucker vorschaltet.

----------------
Ermitteln der Haltestellenabstände
----------------

Um die Haltestellenabstände zu Ermitteln, enthält der Drucker 2 spezielle Funktionen:

"F" -> 99 -> "Auslösen"
	Über Funktion 99 kann man einen Wegzähler aktivieren. Dieser wird anschließend vor der Haltestellenazeige angezeigt.

"F" -> 98 -> "Auslösen"
	Über Funktion 98 kann der Wegzähler auf 0 zurückgesetzt werden.
	Hinweis: Ein Zurücksetzen des Zählers hat bei bereits vorhandenen Wegimpulsdaten Auswirkungen auf die Haltestellenfortschaltung! In der Regel ist das aber kein Problem, da die Messfahrt ja erfolgt, solange noch keine Routendaten vorhanden sind. Im Anschluss kann der Wegzähler aber auch genutzt werden, um z.B. Fehler in der Fortschaltung zu ermitteln, in diesem Fall sollte die Funktion 98 dann nur mit Bedacht genutzt werden.

Dies ermöglicht es, während einer Linienfahrt die zurückgelegte Strecke zu erfassen und mitzuschreiben. Hierbei empfehle ich, die Haltestellen einer Route aus der Hofdatei zu kopieren und z.B. in Excel untereinander einzufügen (in der Regel können Textabschnitte direkt als Block in Excel eingefügt werden, Zeilenumbrüche werden automatisch als neue Zelle erkannt). Rechts daneben kann anschließend während der Fahrt die an der Entsprechenden Haltestelle abgelesene Distanz abgelesen werden (hieraus ergibt sich auch der oben erwähnte Eintrag für die 0. Haltestelle, da die Starthaltestelle ebenfalls Teil der Route und somit Teil der vorliegenden Liste ist. An der Starthaltestelle Sollte der Wegzähler natürlich zurückgesetzt und entsprechend eine "0" eingetragen werden).
Um Rundungsfehler zu vermeiden, empfehle ich, den Wegzähler während einer Messfahrt nicht zurückzusetzen und zuerst die Distanz ab Starthaltestelle einzutragen. Nach Abschluss der Messfahrt kann anschließend in Excel die Differenz zwischen den Einträgen und somit der Abstand ermittelt werden. Ein Beispiel hierzu findet sich unten.
WICHTIG: Ein Manuelles Fortschalten der Haltestelle führt zum automatischen Reset des Wegzählers, deshalb sollte diese Funktion während Messfahrten nicht genutzt werden.

Resultat einer Messfahrt könnte dann z.B. folgende Tabelle sein:

Haltestelle  	Messung
---------------------------------
Haltestelle 0	    0
Haltestelle 1	  230
Haltestelle 2	  780
Haltestelle 3	 1100
Haltestelle 4	 1660
Haltestelle 5	 2310

Im Anschluss Berechnen wir eine Spalte weiter jeweils die Differenz zwischen dem Wert eine Zeile oberhalb und dem aktuellen Wert.
Für Haltestelle 0 ergibt sich immer 0.
Für Haltestelle 1 ergibt sich 230 - 0 = 230.
Für Haltestelle 2 ergibt sich 780 - 230 = 550.
Für Haltestelle 3 ergibt sich 1100 - 780 = 320.
Für Haltestelle 4 ergibt sich 1660 - 1100 = 560.
Für Haltestelle 5 ergibt sich 2310 - 1660 = 650.

In Excel kann man das über Formeln automatisiert ausrechnen lassen. Als Resoltat erhält man nun folgende Tabelle:

Haltestelle  	Messung	Differenz
---------------------------------
Haltestelle 0	    0	    0
Haltestelle 1	  230	  230
Haltestelle 2	  780	  550
Haltestelle 3	 1100	  320
Haltestelle 4	 1660	  560
Haltestelle 5	 2310	  650

Diese Daten werden nun wie oben beschriebenin eine oder mehrere (bei >8 Haltestellen, siehe oben) Haltestellen der Hofdatei übertragen. Für unser Beispiel ergibt sich (Beispielhaft Linie 1, Route 1):

#wegimpuls_101_1	0	230	550	320	560	650	0	0

Die Strings 6 und 7 werden nicht gebraucht, da unsere Route mit 6 Haltestellen nur die Strings 0-5 Benötigt. Diese können entweder mit "0" beschriftet werden oder komplett leer gelassen werden.

---------------------------------
2025 (c) der_Nik_ - ohne Gewär 







########################
	[EN] AFR200 Script Extension by der_Nik_
########################

----------------
Installation
----------------

To install, simply copy the folder "OMSI 2" into "Steam\Steamapps\common" (the folder where OMSI 2 is installed) and allow it to overwrite existing files.

Note: When the bus is updated, the mod may be overwritten. In that case, simply install it again.
The required files are placed together with backups of the overwritten original files (for possible uninstallation) in "OMSI 2\Addons\Thueringer_Wald\AFR200 Mod der_Nik_".

----------------
Features
----------------
	
- New sales display  
  The sales display has been redesigned after the old SWEG ticket printers. The destination code input works but has no effect on ticket sales.

- Optimized ticket sales  
  Ticket sales are now compatible with the Bad Hügelsdorf 2020 ticket pack. Using "24h" + "Kind" sells a child day ticket; all other tickets are selected by repeatedly pressing "24h".

- Realistic distance-pulse stop progression (with suitably adapted HOF file)  
  As in reality, stop progression can be triggered by wheel rotations and the resulting distance traveled.

- Announcement delay  
  When announcements are enabled, playback is delayed according to the Constfile setting.

- Delay display  
  Optionally a delay display can be shown. This is fictional—the real SWEG printer did not have such a function, but some AFR200 units reportedly did, so it was included.
  The delay display can be toggled with "F" -> 06 -> "Auslösen".
 
- Dynamic destination changes: using a command in the HOF file, the matrix destination
  can be changed within a route.

- Automatic odometer  
  The mileage is now adopted automatically and no longer needs to be entered manually.

----------------
Stop progression
----------------

If route data is present in the HOF file, the printer automatically uses distance-pulse stop progression, which references the traveled distance instead of the OMSI timetable.
This matches the behavior of real AFR200 printers. On the “Thüringer Wald” map, for example, this prevents erratic switching during branch trips and makes “no-stop” entries unnecessary.

However, this method has some quirks, just like in reality:

- Stop distances cannot be read automatically from OMSI, so they must be determined manually and entered in the HOF file (see below).
  If no distance-pulse data exists, the printer falls back to the familiar OMSI-timetable stop progression.

- For correct operation the exact wheel diameter must be specified in the Constfile. A wrong value causes incorrect distance scaling. (only important if the printer is transfered to other buses)

- Manual stop advance resets the distance counter and should only be used while standing at a stop. About 50 m after the stop the printer advances again and starts counting toward the next stop.
  This ~50 m offset remains permanent so that switching never happens while still at the stop.

- If the route is entered into the printer before the actual starting stop, the distance counter starts immediately.
  A manual step back at the start stop may therefore be necessary.

----------------
Configuration in the Constfile
----------------

The Constfile has been extended with the following commands (keep names exactly as shown):

afr_delay  
    Enables the delay display by default.

afr_wegimpuls_schaltdistanz  
    Distance (in meters) after which manual advancement switches to the next stop.
    Recommended value: 50.

afr_wegimpuls_raddurchmesser  
    Wheel diameter of the left front wheel (for distance-pulse advancement).
    The front axle’s diameter can be read from the .bus file under "achse_raddurchmesser".

afr_ansagenverz_mode  
    Announcement delay mode:
    0 = no delay
    1 = relative delay
    2 = absolute delay, counted from departure
    3 = absolute delay, counted before arrival

afr_ansagenverz_wert_rel  
    Relative delay factor:
    0.25 = after 1/4 of the trip to the next stop
    0.5  = halfway between stops
    etc.

afr_ansagenverz_wert_time  
    Absolute delay in seconds (for timetable-based advancement).

afr_ansagenverz_wert_dist  
    Absolute delay in meters (for distance-pulse advancement).

----------------
Configuration in the HOF file
----------------

Special stop entries allow map-specific settings.

Format:  
StopName [tab] String 0 [tab] String 1 etc.

#AFR-Options    CompanyName  
    Text shown on the AFR200 start screen (max. 16 characters).
    If missing, "AFR200 MOBIL" is displayed.

#AFR-Tickets_1  TicketString0 TicketString1 ...  
    Defines the ticket codes shown on the sales screen.
    2 characters are recommended (up to 6 are possible).
    Up to 8 tickets per stop entry:
        #AFR-Tickets_1  → tickets 0–7
        #AFR-Tickets_2  → tickets 8–15
        etc.
    Default codes:
		EE = Single ticket Adult
		KE = Short-distance ticket Adult (not on Thüringer Wald)
		TE = Day ticket Adult
		EK = Single ticket Child
		KK = Short-distance ticket Child (not on Thüringer Wald)
		WE = Weekly ticket Adult (on Thüringer Wald)
		WK = Weekly ticket Child (on Thüringer Wald)

#wegimpuls_73101_1  Distance0 Distance1 ...  
    Defines stop-to-stop distances for distance-pulse advancement.
    73101 = line 731, route 1 (example).
    The trailing number (_1, _2 …) continues counting so there is no stop limit.
    _1 covers distances 0–7, _2 covers 8–15, etc.
    Important: Distance0 is always 0 (to the starting stop).

#zielwechsel_73101    05_129    07_29    etc.
    This entry defines the dynamic destination change along a route.
    The key command is composed of "#zielwechsel_" + line & route (as described above).
    Up to 8 destination changes can then be defined in the strings using the format:
    stop index (2 digits) + "_" + destination code.
    "05_29" means that starting from stop number 4, destination code 29 will be used
    (the index starts at 0). The destination is switched as soon as the previous stop
    has been departed and the printer advances.

----------------
Determining Stop Distances
----------------

To determine the distances between stops, the printer contains two special functions:

"F" -> 99 -> "Enter"
    Using function 99 you can activate a distance counter. This counter will then be shown in front of the stop display.

"F" -> 98 -> "Enter"
    Using function 98 you can reset the distance counter to 0.
    Note: Resetting the counter will affect stop advancement if distance-pulse data already exist.
    Normally this is not a problem, because the measurement run is carried out before any route data are present.
    Afterwards the counter can also be used to detect errors in the stop advancement.
    In that case, however, function 98 should be used with caution.

This allows you to record and log the distance travelled during a line run.
I recommend copying the stops of a route from the HOF file and pasting them, for example, into Excel
(text sections can usually be pasted directly as a block; line breaks are automatically recognized as new cells).
Next to each stop you can enter the distance read from the printer during the trip.
This also explains the entry for stop 0 mentioned earlier, because the starting stop is part of the route
and therefore part of the list.
At the starting stop the counter should of course be reset and a “0” entered.

To avoid rounding errors, I recommend not resetting the counter during a measurement run
and first recording the total distance from the starting stop.
After the run you can calculate the difference between successive entries in Excel to obtain each segment distance.
An example is shown below.

IMPORTANT: Manually advancing the stop will automatically reset the distance counter.
Therefore, do not use this function during measurement runs.

Result of a measurement run could be the following table:

Stop            Reading
---------------------------------
Stop 0             0
Stop 1           230
Stop 2           780
Stop 3          1100
Stop 4          1660
Stop 5          2310

Then, one column further, calculate the difference between the value in the row above and the current value.

For Stop 0: always 0
For Stop 1: 230 - 0   = 230
For Stop 2: 780 - 230 = 550
For Stop 3: 1100 - 780 = 320
For Stop 4: 1660 - 1100 = 560
For Stop 5: 2310 - 1660 = 650

In Excel you can automate this with formulas.
The resulting table looks like this:

Stop            Reading   Difference
------------------------------------
Stop 0             0          0
Stop 1           230        230
Stop 2           780        550
Stop 3          1100        320
Stop 4          1660        560
Stop 5          2310        650

These data are then transferred, as described above, into one or more stop entries in the HOF file
(for more than 8 stops, see above).
For our example (Line 1, Route 1) the entry would be:

#wegimpuls_101_1    0    230    550    320    560    650    0    0

Strings 6 and 7 are not needed, because our route with six stops only requires strings 0–5.
They can either be set to “0” or left completely empty.

---------------------------------
2025 (c) der_Nik_ – no warranty