La versione 3.6 di Train Director aumenta il livello di personalizzazione degli scenari rispetto alle versioni precedenti. Infatti è ora possibile associare degli scritti a quasi tutti gli elementi presenti in un tracciato: segnali, binari, pedali e treni! Tramite l'uso di scritti, è possibile creare condizioni complesse come per esempio la creazione di itinerari multipli e il controllo della marcia dei treni, compresa la possibilità di creare ritardi casuali nella marcia dei treni.

Il principio su cui si basano gli script è l'esecuzione di funzioni specifiche che vengono attivate quando si verifica un particolare evento. Ogni elemento sul tracciato riconosce eventi diversi. La pagina di riassunto degli script elenca i vari eventi per i vari elementi del tracciato.

Per spiegare l'uso degli script, le seguenti simulazioni di esempio sono incluse con l'eseguibile di Train Director:

  • trainscr.trk: esempio di uso degli script associati ai treni. La simulazione stampa nella finestra degli avvisi quando lo stato del treno cambia (per esempio qunado il treno entra nel tracciato, o quando la sua direzione viene invertita).
  • signalscr.trk: esempio di uso degli script associati ai segnali. La simulazione mostra come sia possibile implementare segnali di avviso o segnali di protezione condizionati all'itinerario di ingresso in una stazione.
  • trackscr.trk: esempio di uso degli script associati ai binari e ai pedali.
  • linkedImages.trk: esempio di uso degli script associati a icone collegate a enti.

Come Associare gli Script agli Elementi

Ogni script è una porzione di un file testo associato a un elemento del tracciato. Il programma permette l'introduzione degli script per i binari direttamente dal dialogo delle proprietà del binario. Il dialogo delle proprietà viene aperto cliccando col bottone destro sull'ente (per le icone si deve usare Ctrl+bottone destro):

Per quel che riguarda i treni, gli script sono specificati nel file .sch insieme all'orario del treno. Questo è un esempio di script associato a un treno: 

Train: T3
    Enter: 0:12, A
        0:14, -, S1
    Script:
        OnShunt:
            do showalert T3 shunting
        end
        OnReverse:
            do showalert T3 reversed
        end
    EndScript
.

Per quel che riguarda i segnali, gli script sono file testo separati chiamati "Train Director Scripts", o più semplicemente file .tds. Questi file possono essere associati ai vari segnali tramite il dialogo delle proprietà del segnale.

La ragione per questa differenza sta nel fatto che per i segnali è molto comune riutilizzare lo stesso script per più di un segnale (per esempio tutti i segnali di avviso con protezione accoppiata avranno lo stesso script).

Tutti gli script usano una sintassi comune, composta dal nome dell'evento, seguito da uno o più righe di condizioni, espressioni o comandi. Gli eventi hanno la seguente struttura:

OnXXXXX:
    # condizioni, espressioni e comandi
    ....
end

dove XXXXX specifica l'evento, ed end specifica la fine delle condizioni, espressioni o comandi associato a tale evento.

Le espressioni servono a leggere o cambiare le proprietà di binari, segnali, treni ecc. Mentre le proprietà sono specifiche dell'elemento, e sono elencate per ogni tipo di elemento nella pagina di riassunto degli script, gli elementi stessi possono essere indicati in vario modo:

  • tramite la coordinata dell'elemento:   Track(x, y)  specifica l'elemento di binario alla coordinata x, y.
  • relativamente al treno o segnale o binario interessato dall'evento:   Track.proprieta, Train.proprieta, Signal.proprieta.
  • relativamente all'elemento che ha scatenato l'evento:  .proprieta.

Per esempio, la proprietà ".aspect" di un segnale può essere cambiata con la seguente espressione:

    .aspect = red

Le espressioni sono anche usate per specificare delle condizioni, tramite l'uso di "operatori" di confronto.

Il seguente è un esempio di espressione condizionale:

    Signal(10,23).aspect = red and Train(R2001).speed > 100 or Train(R2004).status = stopped

Come si vede, diverse espressioni possono essere collegate dagli operatori "and" e "or".

Gli operatori condizionali sono i seguenti:

=     uguale a
!      diverso da
>     maggiore di
>=   maggiore o uguale a
<     minore di
<=   minore o uguale a

and   verificato se la condizione di sinistra e la condizione di destra sono entrambe verificate
or      verificato se o la condizione di sinistra o la condizione di destra è verificata

Oltre agli elementi del tracciato, si può usare l'operando "random" in un'espressione per ottenere un valore da 0 a 99 compresi, come nel seguente esempio:

    random < 40

In questo caso la condizione sarà verificata (in media) il 40% delle volte.

Un altro operando che può essere usato nelle espressioni è "time", per riferirsi all'orologio della simulazione:

    time > 1430

Il valore dell'operando "time" è in hhmm, cioè ore+minuti; nell'esempio precedente la condizione è verificata dopo le 14:30.

Oltre alle espressioni per cambiare le proprietà di un elemento, gli script consentono anche l'uso di 2 tipi di comandi:

  • I comandi di condizione
  • I comandi imperativi

I comandi di condizione hanno la seguente struttura:

    if espressione
        comando1
        comando2
        ...
    else
        comando3
        comando4
        ...
    end

Il comando valuta se l'espressione è verificata, ed in caso affermativo esegue la serie di comandi 1, 2 ecc. ignorando la serie di comandi 3, 4, ecc.
Nel caso l'espressione non sia verificata, il comando ignora la serie di comandi 1,2 ecc. ed esegue invece la serie di comandi 3, 4, ecc.

Si noti che la parte "else" è facoltativa, e può essere omessa se non ci sono comandi da eseguire quando l'espressione non è verificata.

Si noti inoltre che un comando può contenere altri comandi "if", in modo tale da poter specificare ulteriori condizioni che saranno controllate solo dopo che l' "if" esterno è stato verificato.

Sono anche disponibili alcuni comandi imperativi. Tali comandi vengono eseguiti in sequenza, uno dopo l'altro.

Il comando "do" consente di modificare l'operatività del simulatore, similmente a quanto succede già per i pedali.

I possibili usi del comando do sono i seguenti:

do stationsched mostra l'orario delle stazioni
do fast aumenta la velocità della simulazione
do slow diminuisce la velocità della simulazione
do stopsim Ferma l'orologio. Utile quando si evidenzia una condizione che richiede l'intervento del giocatore.
do shunt train inizia la manovra del treno specificato
do traininfopage train mostra l'orario del treno specificato in una pagina HTML
do traininfo train mostra l'orario del treno specificato in un dialogo
do decelerate value train rallenta la velocità del treno specificato del valore di km/h specificato
do accelerate value train aumenta la velocità del treno specificato del valore di km/h specificato
do reverse train inverte la marcia del treno specificato
do click x, y simula un click del bottone sinistro del mouse alla coordinata specificata
do rclick x, y simula un click del bottone destro del mouse alla coordinata specificata
do ctrlclick x, y simula un click del bottone sinistro del mouse col tastro Ctrl premuto
do itinerary name attiva l'itinerario specificato. Non è necessario avere un pulsante associato all'itinerario.
do assign oldtrain,newtrain assegna il materiale di "oldtrain" (che deve essere arrivato a destinazione) al treno "newtrain". I nomi dei treni devono essere separati da una virgola.
do play soundfile suona il file specificato
do skip fa avanzare la simulazione a 3 minuti prima del prossimo evento (utile per non dover aspettare delle ore quando non sono previsti movimenti di treni)
do split train,length spezza il treno specificato in due treni, e fa avanzare in manovra il primo troncone
do script file esegue la funzione OnEnter: nello scritto contenuto nel file specificato
do showinfo file.htm mostra il contenuto del file HTML nella finestra "Scenario Info"
do showalert text mostra la frase specificata nella finestra degli avvisi
do clearalert cancella tutti i messaggi dalla finestra degli avvisi
 

Il comando "call" permette di eseguire i comandi definiti in una procedura predefinita. La sintassi è la seguente: 

    call procName

dove procName è il nome di una procedura. Si veda il capitolo "Procedure" per maggiori dettagli.

Il comando "return" interrompe l'esecuzione di una sequenza di comandi ed esce dalla procedura corrente, o, se presente in un blocco di comandi attivato da un evento, ritorna immediatamente alla simulazione. Per esempio: 

OnUpdate:
    if .aspect = red
        return
    end
    ...
end

Tutti i comandi dopo la riga return verranno ignorati.

Nella pagina successiva vengono presentati in dettaglio gli scritti associabili ai segnali. Si veda inoltre vari scenari disponibili dalla pagina delle simulazioni per esempi di come utilizzare gli scritti.

Procedure

La versione 3.9p di Train Director introduce la possibilità di riutilizzare sequenze di comandi indipendentemente dall'ente che ha attivato lo script. Se quindi ci sono azioni che devono essere attivate più volte all'interno di uno scenario, non è più necessario copiare le sequenze di comandi in più scritti.

I blocchi di comandi riutilizzabili sono identificati da una linea simile alla seguente: 

procedure nome
...
end

dove nome è il nome identificativo della sequenza di comandi. La linea end termina la sequenza dei comandi. È ovviamente possibile definire più procedure in sequenza, come nel seguente esempio: 

procedure nome1
...
end

procedure nome2
...
end

Per chiamare una procedura, si utilizzi il comando call fornendo il nome della procedura desiderata. Per esempio: 

OnUpdate:
    call nome1
    call nome2
end

In questo esempio, saranno eseguiti in sequenza tutti comandi definiti nella procedura nome1, seguiti dai comandi definiti nella procedura nome2.

Si veda il tracciato di esempio 39pCall.trk presente nella cartella Examples nel pacchetto di Train Director per vedere le procedure in azione!