CSV 线路格式

速查目录…

■ 内容目录

■ 1. 综述

CSV格式线路是以纯文本形式编辑的线路。

线路文件是纯文本,且可以使用任意字符编码,但是,我们推荐线路作者们使用UTF8-BOM编码格式。游戏在解析数字数据时,使用的解析方法宽松 的(特别指出处除外),但是,我们推荐线路作者们严格规范地编写线路文件。 这个文件一般来说可以被放在TrainRailway文件夹下的任何地方。文件名可以随意,但扩展名必须是 .csv 。线路文件被从头到尾逐行解析,每行被分割并被从左到右解析。

路线文件包括一系列指令,用来导入线路中用到的模型(Structure(结构)命名空间),线路的属性信息(说明线路使用的默认列车和背景等信息),文件的其余部分是Track(轨道)命名空间。在这一部分中,主轨道位置(一般以米为单位)被用来描述轨道在哪里转弯,车站的位置在哪里,墙壁应当在哪里开始、哪里结束,以此类推。说得明白一点儿,Track(轨道)命名空间的指令是要放在最后的。

这个格式预设了一条游戏默认的主轨道(0号轨道),不可以指定它开始的位置,也不能结束它。和游戏中其他轨道不同的是,它从线路的开始一直延续到线路的终点,代表着玩家驾驶的列车行驶的轨道。除此之外,游戏中定义的其他轨道都是只供装饰,不能行驶的。不过可以使用 轨道循迹物件 来让AI列车在其它轨道上行驶。

可以几何意义上地弯曲和抬升默认的主轨道,而其他轨道都是相对于主轨道定义的,并随主轨道弯曲起伏。除非特别修改定义,线路中每25米划分为一个区间块,特定的命令只有在区间块的边界位置(整25米位置)才能发挥作用。物体的放置总是基于一个坐标系,它的轴并不弯曲,而是直直地指向邻近的下一个区间块。

还可查阅这份CSV格式的速查目录…

■ 2. 语法

对于线路文件中的每一行,在开头和结尾的空格会被统统忽略。然后,每一行指令都会按逗号(U+002C,英文半角的那个)分割。于是,每一行都会被看作这样一个格式:

表达式1, 表达式2, 表达式3, …, 表达式n

表达式内容主要有以下类别:

● 注释

注释就是给人看的,游戏完全不管的。以分号(U+003B,英文半角)开头的表达式都会被视为注释。

● 主轨道位置与距离
位置数字

一个非负的 严格格式 浮点数,代表一个主轨道位置。随后的指令都将以此位置作为基准点。

部分1:部分2:…:部分n

这是一个配合Options.UnitOfLength的更加复杂的距离指定格式,可用于非公制计量单位。每一个 部分i 都是 严格格式 的浮点数。 部分1 会被乘上 系数1, 部分2 乘上 系数2,以此类推,真正的主轨道位置是所有积的和。这个结果必须是非负的。各部分被冒号(U+003A,英文半角)分隔。如果想了解如何设定系数,请参见Options.UnitOfLength一节。

在任何参数中使用距离的命令中,这个冒号表示法就可以被使用,到时我们会用绿色标出这种情况。

n个单位系数被使用Options.UnitOfLength定义,但是使用冒号表示法时输入的部分却没有全部给出,那么这些系数将会被向右匹配,在左边的会被忽略。因此,这几种表示方法是等效的:0:0:20:2,和2.

● 指令

没有参数的指令:

指令名称

含有几个参数的指令:

指令名称 参数1;参数2;参数3;…;参数n
指令名称(参数1;参数2;参数3;…;参数n)

不仅有参数还有后缀和编号的指令:

指令名称(编号1;编号2;…;编号m) 参数1;参数2;参数3;…;参数n
指令名称(编号1;编号2;…;编号m).后缀 参数1;参数2;参数3;…;参数n
指令名称(编号1;编号2;…;编号m).后缀(参数1;参数2;参数3;…;参数n)

规则:

指令名称是大小写都可以的。编号和参数被分号(U+003B,英文半角)隔开。在指令名称、编号和参数周围的空格都是被忽略的,括号周围的空格也是被忽略的。

如果要使用编号,它必须被成对括号(U+0028,英文半角在键盘9上面)和(U+0029,英文半角在键盘0上面)括起来。在使用编号时至少要提供一个参数和一个后缀

有两个使用参数的方法变种,除了$开头的预处理指令($Chr, $Rnd, $Sub, …)之外,可以按照个人喜好二选一。
第一种方法:参数被至少一个空格(U+0020,平常用的那个)和编号、指令的大名以及后缀分开。
第二种方法:参数被成对括号(U+0028,英文半角在键盘9上面的那个)和(U+0029,英文半角在键盘0上面的那个)括起来。
在第二种方法中,当使用编号时就必须使用后缀。在参数周围的空格都会被忽略。

请注意在有些指令中,不管是用哪种表示方法,后缀都是必需的。在接下来的文档中,必需的后缀将被 加粗 ,对于第一种方法加不加均可的后缀将被使用灰色表示。

With 语句
With 命名空间前缀

不严谨地来说,在CSV路线中,“命名空间”的意思和“章节”、“部分”差不多。
其后所有直接以点号 (U+002E,英文半角) 开头的指令都被自动加上 命名空间前缀 。 例如:

With Route
.Gauge 1435
.Timetable 1157_M

和这个是等效的:

Route.Gauge 1435
Route.Timetable 1157_M

■ 3. 预处理

在游戏开始解析线路文件之前,预处理指令将会被预先处理替换。预处理器会按照正常顺序分析这些以$开头的预处理命令。$Chr、$Rnd和$Sub指令可以随便嵌套,$Include、$If、$Else和$EndIf不能出现在另一个指令的括号里。

预处理指令的语法不可以随意使用,必须以下面给出的形式出现。


$Include(文件)
$Include(文件:主轨道位置偏移量)
$Include(文件1; 权值1; 文件2; 权值2; …)
文件i: 要被导入本线路的另一个同格式线路文件 (CSV/RW)。
权值i: 一个正浮点数,表示对应的这个文件被使用的可能性大小。数越大,这个文件就越可能被随机选中。

该指令按照权值随机选出一个线路文件,再将其内容导入本线路中。因为该文件内容会被不加修改直接在该指令的位置插入,可能需要照顾一下With指令等,不要让它们出现冲突。如果参数中最后一个文件没有给出权值,它会被按1处理。

$Include指令在几个线路有大量重复内容时很有用,可以把重复内容单独存进另一个文件,然后在主文件中导入它,以方便编码。这个指令还可以被用来随机选取线路代码。请注意导入的文件中也可以包含$Include指令来引用更多的文件,但是应该避免循环引用,例如A导入B而B又导入A。要导入的那个文件不应该使用.csv作为格式扩展名(也许用.include是个方便区分的好主意),不然玩家可能会一不小心从主菜单选择了这个“不完全的线路文件”然后发现没法加载(除非那个文件本身就是一个单独的线路,然后本来就想让玩家加载它)。

如果任何一个文件i被一个:主轨道位置偏移量后缀,那个文件中所有的主轨道位置表达式都会被按照这个量以米作单位偏移。例如,$Include(stations.include:2000) 会将stations.include文件中的所有内容在插入前都向前偏移2000米。需要注意这些主轨道位置表达式是在所有的预处理命令都被执行完才会被做偏移处理。这意味着像"1$Rnd(2;8)00"这样的主轨道位置表达式尽管在预处理前还不是一个主轨道距离表达式,但是它的随机结果照样会被进行偏移处理。

只有OpenBVE1.2.11版以上支持“主轨道位置偏移量”。


$Chr(Ascii编号)
Ascii编号: 一个在10~13或20~127范围内的数,代表一个拥有对应ASCII码的字符。

这个指令会在原位插入一个对应Ascii码的字符。如果想要在某个地方放置一个字符却又不想破坏指令语法结构(比如站名里开头带空格、带括号逗号分号等,如果不这样加入就会被游戏误读),可以使用这个指令。有关的字符有:

Ascii码 含义 对应字符
10 换行 (CR) 换行
13 换行 (LF) 换行
20 空格 空格
40 括号 (
41 回括号 )
44 逗号 ,
59 分号 ;

“$Chr(13)$Chr(10)"(CRLF)代表一次换行。插入$Chr(59)可能基于它的位置被解释为注释开始或指令参数分隔符。


$Rnd(最小值; 最大值)
最小值:一个整数,代表随机数可以取的最小值。
最大值:一个整数,代表随机数可以取的最大值。

这个指令会在原位插入一个位于最小值最大值之间的随机整数。可以用这个来给线路添加一些随机性。

Example for the use of the $Rnd directive:
10$Rnd(3;5)0, Track.FreeObj 0; 1

会产生以下三个结果之一:

Possible outcome from the previous example is exactly one of these lines:
1030, Track.FreeObj 0; 1
1040, Track.FreeObj 0; 1
1050, Track.FreeObj 0; 1

$Sub(编号) = 表达式
编号: 一个非负整数,代表要存储的变量编号。
表达式: 要存进这个变量的数字的值。

这个指令只应该单独出现,它将会把表达式的值赋给编号为编号的这个变量。它不在原位插入任何内容。可以把一个随机数存起来然后以后多次使用(比如说放置几棵到一条随机但是却相同的轨道的排成一排的树)。下面关于 $Sub(编号) 的介绍处有几个使用实例。

程序实现备注

虽然变量中也可以存储非数字的内容,还是不能把逗号通过$Chr(44)存进去然后希望它在使用时会起分隔符的作用。但是,可以把分号通过$Chr(59)存进去然后把它调用时放在开头使那一行成为注释。不过因为可以使用$Include和$If来进行条件判断,所以并没有必要这么干。


$Sub(编号)
编号:一个非负整数,代表要读出的变量编号。

这个指令会在原位插入编号为编号的变量的内容。在读取前这个变量必须先被赋值。

Example for the use of the $Sub(Index)=Value and $Sub(Index) directives:
$Sub(0) = $Rnd(3; 5)
1000, Track.FreeObj $Sub(0); 47
1020, Track.FreeObj $Sub(0); 47
1040, Track.FreeObj $Sub(0); 47

在这个例子中,三个Track.FreeObj指令都使用同样的随机数值,所以这三个物体会被放在同一条随机的轨道边。如果使用三个$Rnd(3;5)而不是$Sub,这三个物体可能被单独放在不同的轨道边。


$If(条件)
条件:一个数值。如果它等于0,则它代表不成立的情况。如果它不等于0,则代表成立的情况。

$If(如果……那么)指令让游戏只在这个条件成立,即为非零值时才解析下面的线路指令。$If的后面必须有一个$EndIf。在$If和$EndIf之间也可以加一个$Else来表示条件是不成立的时要解析的指令。


$Else()

$Else(否则)指令只在前面的$If的条件是不成立的时才解析下面的线路指令。


$EndIf()

$EndIf指令标识前面的$If指令的影响范围到此结束。

Example of $If, $Else and $EndIf
$Sub(1) = 0
With Track
$If($Sub(1))
    1020, .FreeObj 0; 1
    1040, .FreeObj 0; 2
$Else()
    1030, .FreeObj 0; 3
$EndIf()
Another example of $If, $Else and $EndIf
With Track
1050
$If($Rnd(0;1)), .FreeObj 0; 4, $Else(), .FreeObj 0; 5, $EndIf()

可以嵌套$If指令。如果把$If/$Else/$EndIf放在不同的几行上,可以更清晰地表示块结构并使它更易读(例如第一个例子)。


最后,当预处理结束,线路中的所有指令都会被按照轨道位置重新排序。

Example of a partial route file:
1000, Track.FreeObj 0; 23
1050, Track.RailType 0; 1
10$Rnd(3;7)0, Track.Rail 1; 4
Track.FreeObj 1; 42

经过预处理之后(假设随机结果是3):

Preprocessing the $Rnd directive (assuming 3 is produced):
1000, Track.FreeObj 0; 23
1050, Track.RailType 0; 1
1030, Track.Rail 1; 4
Track.FreeObj 1; 42

最后被按照顺序重新排序:

Sorting by associated track positions:
1000, Track.FreeObj 0; 23
1030, Track.Rail 1; 4
Track.FreeObj 1; 42
1050, Track.RailType 0; 1

■ 4. Options (选项) 命名空间

这个命名空间里的指令设置一些基本设置,并影响其他指令的实际处理效果。所以应当在开始编写写其他指令之前先使用这些指令把设置都调整妥当。


Options.UnitOfLength 与米的换算系数1; 与米的换算系数2; 与米的换算系数3; …; 与米的换算系数n
与米的换算系数i:一个浮点数,表示一个单位等于多少米。与米的换算系数1的默认值是1,其他的默认值都是0。

这个指令可以被用来改变其他指令使用的长度单位。当和形如部分1:部分2:…:部分n的主轨道位置一起使用时,部分i会被乘上系数i,以此类推,真正的主轨道位置是所有积的和。更改了长度单位时,您也应同时使用 Options.BlockLength 将区间块长度也设为相应单位。

换算系数的几个示例:

单位 换算系数
哩/英里 1609.344
冈特测链 20.1168
米/公尺 1
0.9144
呎/英尺 0.3048

在下面的示例中,会被Options.UnitOfLength影响的指令参数将被用绿色表示。


Options.UnitOfSpeed 与千米每时的换算系数
与千米每时的换算系数:一个浮点数,表示一个单位等于多少千米每时。默认值是1。

这个指令可以被用来改变其他指令使用的速度单位。换算系数的几个示例:

单位 换算系数
米每秒 3.6
英里每时 1.609344
千米每时 1

在下面的示例中,会被Options.UnitOfSpeed影响的指令参数将被用蓝色表示。


Options.BlockLength 长度
长度:一个正浮点数,表示区间块的长度,默认的单位是。默认值是25米。

这个指令可以设置区间块的长度。这是个全局设置,一旦设置就不能来回更改。如果Options.UnitOfLength在该指令前被调用过,长度会使用Options.UnitOfLength作为单位。


Options.ObjectVisibility 模式
模式:游戏判断一个物体是否可视采用的算法。默认值是0(原版)。

模式的可选项:

0: 原版:当该物体所在的区间块已经被玩家通过,游戏就认为这个物体不再可见,也不再加载显示这个物体。游戏不会显示任何玩家后方的物体。在朝前看时不会有任何问题,但当向后看时所有物体都会消失,且没有任何途径可解决。自相交的轨道(例如环线)不会被正确显示。该设置会造成不正确且无法解决的视觉效果,保留且默认采取该设置只是为了兼容一些老线路。请不要在新线路中采用这个设置。
1: 基于轨道:游戏仍然会加载列车后方可视范围内的物体。这是按照轨道位置计算的。可惜自相交的轨道(例如环线)还是不会被正确显示。推荐添加这个设置。

Options.SectionBehavior 模式
模式:Track.Section指令应当被如何理解。默认值是0(默认)。

模式的可选项:

0: 默认:在Track.Section 状态0; 状态1; …; 状态n中,任何一个状态i都代表当一个闭塞区间的前方有i个闭塞区间清空时要传达给信号机的信号状态。
1: 简化:在Track.Section 状态0; 状态1; …; 状态n中,每个闭塞区间的信号状态都是比它前面一个闭塞区间的状态值要高的最小值。

Options.CantBehavior 模式
模式:Track.Curve指令应当被如何理解。默认值是0(忽略符号)

模式的可选项:

0: 忽略符号:Track.Curve中的CantInMillimeters参数是无符号的,符号会被忽略,轨道总是会向弯道中心倾斜来提供弯道向心力。轨道不会在直道段倾斜。
1: 保留符号:Track.Curve中的CantInMillimeters参数是有符号的,正值会使轨道向弯道中心倾斜,负值会使轨道向弯道外侧倾斜。轨道会在直道段倾斜,正值使轨道右倾,负值使轨道左倾。

Options.FogBehavior 模式
模式:Track.Fog命令应当被如何理解。默认值是0(基于区间块)

模式的可选项:

0: 基于区间块:雾的颜色和范围从原先Track.Fog设置时的区间块的到新Track.Fog设置时的区间块以线性插值平滑过渡。
1: 线性:雾的颜色和范围从两次Track.Fog调用的位置之间线性插值平滑过渡。这和Track.Brightness的效果类似。

Options.CompatibleTransparencyMode 模式
模式:当一个物体的材质使用的颜色通道不是真彩色时该如何判断透明区域。这可以在游戏设置中调整,但该指令可以超控游戏设置中的选项。

模式的可选项:

0: 特定匹配:如果该图像使用的颜色通道色板内不包括设定的透明色,那么这个图象就会按不透明来处理。
1: 模糊匹配:如果该图像使用的颜色通道色板内不包括设定的透明色,那么就转而匹配色板内与此最接近的颜色。

Options.EnableBveTsHacks 模式
模式:是否应用几项对于部分奇葩的BVETs2/4线路的兼容性设置。这可以在游戏设置中调整,但该指令可以超控游戏设置中的选项。

模式的可选项:

0: 不启用兼容模式。
1: 启用兼容模式。

■ 5. Route (路线) 命名空间

这个命名空间里的指令设置一些线路的基本信息。


Route.Comment 文字
文字:选择线路页面上显示的描述文字。

如果需要插入换行、逗号之类的字符,必须使用$Chr。


Route.Image 文件
文件:选择线路时显示的描述图片,路径按相对于存储这一线路文件的文件夹书写。

Route.Timetable 文字
文字:作为线路默认时刻表表头的文字。

如果需要插入换行、逗号之类的字符,必须使用$Chr。


Route.Change 模式
模式:当游戏启动时,列车的车载信号系统默认处于什么状态。

模式的可选项:

-1:车载信号系统已被启动,制动手柄处于最大常用制动位置。
0:车载信号系统已被启动,制动手柄处于紧急制动位置。
1:车载信号系统未被设置好,制动手柄处于紧急制动位置。

Route.Gauge 毫米数值
毫米数值:一个浮点数,代表轨道的轨距。单位是毫米(0.001m,0.1cm)。默认值是1435(标准轨)。
Note

Route.Gauge和Train.Gauge作用相同。


Route.Signal(状态编号).Set 允许速度
状态编号:一个非负整数,代表信号状态。0代表前方没有区间空闲(红灯),1代表1个区间空闲,以此类推。
速度:一个非负整数,代表这个信号状态下允许的最大通过速度。默认的单位是千米每时

用这个指令来设定信号状态所允许的最大通过速度。状态0代表前方没有区间空闲(红灯),1代表1个区间空闲,以此类推。默认值(根据默认的日式信号系统设置)是:

状态编号 显示 允许速度
0 0 km/h
1 ●● 25 km/h
2 55 km/h
3 75 km/h
4 没有限制
5 ●● 没有限制

Route.RunInterval 间隔0; 间隔1; …; 间隔n-1
间隔i:一个浮点数,指定一辆AI列车从第一站的发车时间和玩家操作的列车的时间差。单位是。正数使AI列车在玩家之前发车,负数使AI列车在玩家之后发车。

该指令创建几辆和玩家在同一轨道上的AI车。这些列车可见,正常工作,且使用和玩家一样的列车模型。其他列车使用和玩家相同的时刻表,但是发车时间和玩家列车有着间隔i的时间差。通过Track.Sta指令,可以为玩家和AI车指定不同的停车站。在玩家列车之后的车辆只会在区间里没有列车时出现,但玩家列车不论是否已经有列车阻挡位置都会被放置。所以,应当正确设置在玩家之前发车的AI车的发车时间,使玩家进入游戏时该列车已经离开玩家要出现的轨道区域。

Note

Route.RunInterval和Train.Interval作用相同。


Route.AccelerationDueToGravity 数值
数值:一个正浮点数,表示以米每秒平方(m/s²)为单位的重力加速度。默认值是9.80665。

Route.Elevation 高度数值
高度数值:一个浮点数,表示主轨道起始点的海拔高度。默认的单位是。默认值是0。

Route.Temperature 摄氏度数值
ValueInCelsius: A floating-point number representing the initial temperature in Celsius. The default value is 20.

Route.Pressure 千帕数值
千帕数值:一个正浮点数,表示以千帕斯卡为单位的环境大气压力。默认值是101.325(标准大气压)。

Route.DisplaySpeed 单位名称,换算系数
单位名称:当显示关于速度的信息时,使用的单位名称。
换算系数:一个千米每时相当于几个单位。例如对于英里每时,换算系数是0.621371。

该指令可以改变关于速度的信息(例如超速提示)中使用的单位。


Route.LoadingScreen文件
文件:一个路径,指向一个图像文件。

该指令可以自定义加载界面的背景图。


Route.StartTime 时间
时间:线路载入,模拟开始的时间。

该指令可以定义玩家进入游戏时的时间。

Note

如果开始时间没有用这一指令特意设定或设定的值不正确,游戏将自动采用第一站的到达时间。


Route.DynamicLight 动态光XML配置文件
动态光XML配置文件:一个路径,指向配置动态光照的XML文件。

该指令可以被用来替代Route.AmbientLightRoute.DirectionalLightRoute.LightDirection

它允许根据时间改变光照,具体细节在这一页上说明:

Dynamic Lighting


Route.AmbientLight 红色分量; 绿色分量; 蓝色分量
红色分量:一个0~255之间的整数,表示漫射环境光颜色的红色值。默认值是160。
绿色分量:一个0~255之间的整数,表示漫射环境光颜色的绿色值。默认值是160。:一个0~255之间的整数,表示漫射环境光颜色的红色值。默认值是160。
蓝色分量:一个0~255之间的整数,表示漫射环境光颜色的蓝色值。默认值是160。

该指令指定漫射环境光的颜色。这个光照亮场景中所有物体的所有面。


Route.DirectionalLight 红色分量; 绿色分量; 蓝色分量
红色分量:一个0~255之间的整数,表示定向照射光颜色的红色值。默认值是160。
绿色分量:一个0~255之间的整数,表示定向照射光颜色的绿色值。默认值是160。
蓝色分量:一个0~255之间的整数,表示定向照射光颜色的蓝色值。默认值是160。

该指令指定定向照射光的颜色。只有物体的迎光面会被照亮,背光面不受影响。应配合Route.LightDirection使用,设定光照方向。


Route.LightDirection θ 倾斜角; φ 方位角
θ 倾斜角:一个以角度为单位的浮点数,控制定向光的仰角。默认值是60。
φ 方位角:一个以角度为单位的浮点数,控制定向光的方位。默认值是-26.57。

该指令定义相对于主轨道位置0的定向光照射方向。这是光照亮区域的计算方向,和光源(太阳)的方向正好相反。首先,θ 倾斜角定义光照仰角。90代表垂直向下,-90代表竖直向上,在这两个极值处φ就不影响位置。 θ值为0时代表从地平线后方水平向前照射。φ 方位角表示一个旋转方向。φ为0代表从前方,90为从正右,-90为正左。分别设置θφ为(180,0)或(0,180)都代表从后方照射。通过调节这两个数值,可以精确地控制光照的方向。

__光照方向示意图

将球面坐标(θ,φ)换算为直角坐标(x,y,z)的公式:

Converting a spherical direction (theta,phi) into a cartesian direction (x,y,z):
ƒ x = cos(theta) * sin(phi)
y = -sin(theta)
z = cos(theta) * cos(phi)

将直角坐标(x,y,z)换算为球面坐标(θ,φ)的公式(y²≠1):

Converting a cartesian direction (x,y,z) into a spherical direction (theta,phi) for y²≠1:
ƒ theta = -arctan(y/sqrt(x2+z2))
phi = arctan(z,x)

将直角坐标(x,y,z)换算为球面坐标(θ,φ)的公式(y²=1):

Converting a cartesian direction (x,y,z) into a spherical direction (theta,phi) for y²=1:
ƒ theta = -y * pi/2
phi = 0

cos(x) 代表余弦,
sin(x) 代表正弦,
arctan(x) 代表反正切,
arctan(x,y) 代表双变量反正切,
sqrt(x) 代表平方根。
如果更喜欢使用直角坐标的话,可以使用这些公式来进行转换。
这几条公式也作为定向光功能的数学证明(三角函数使用弧度制)。


Route.InitialViewpoint 模式
Value: An integer defining the initial camera viewpoint mode. The following values are valid:
0 : The camera will be placed in the cab. (Default)
1 : The camera will be placed in ‘Exterior Camera’ mode.
2 : The camera will be placed in ‘Track Camera’ mode.
3 : The camera will be placed in ‘Flyby Camera’ mode.
4 : The camera will be placed in ‘Flyby Zooming Camera’ mode.

该指令允许自定义游戏开始时的视角。


Route.DeveloperID

该指令只被BVE4等使用,openBVE忽略这一指令。

■ 6. Train (列车) 命名空间

这个命名空间里的指令指定线路使用的列车。


Train.Folder 文件夹名
Train.File 文件夹名
文件夹名:该线路要使用的列车的文件夹名。

Train.Run(轨道类型编号).Set 走行音编号
Train.Rail(轨道类型编号).Set 走行音编号
轨道类型编号:一个非负整数,代表一个轨道类型。这通过Structure.Rail设定,通过Track.RailType使用。
走行音编号:一个非负整数,代表这个轨道类型使用的列车走行音。

列车开发者会为他的列车设定一些在特定轨道种类上的运行时的声音。使用该指令来为轨道类型分配列车走行音。由于走行音编号是由列车开发者指定的,所以需要和列车开发者合作协调,来确保为正确的轨道类型使用相应的走行音。这里有一个编号标准,但使用得并不很广泛。


Train.Flange(轨道类型编号).Set 轮缘摩擦声编号
RailTypeIndex: A non-negative integer representing the rail type as defined via Structure.Rail and used via Track.RailType.
FlangeSoundIndex: A non-negative integer representing the train’s flange sound to associate to the rail type.

列车开发者会为他的列车设定一些在特定轨道种类上的轮缘摩擦声。使用该指令来为轨道类型分配轮缘摩擦声。由于轮缘摩擦声编号是由列车开发者指定的,所以需要和列车开发者合作协调,来确保为正确的轨道类型使用相应的轮缘摩擦声。这里有一个编号标准,但使用得并不很广泛。


Train.Timetable(时刻表编号).Day.Load 文件名
时刻表编号:一个非负整数,代表这个时刻表图片的编号。
文件名:时刻表图片被照亮的一版的文件名,路径应相对于列车文件夹(首先考虑),或相对于Objects文件夹(随后考虑)。

用该指令来加载被照亮的时刻表图片。使用Track.Sta命令可以指定在哪站使用哪张时刻表图片。


Train.Timetable(时刻表编号).Night.Load 文件名
时刻表编号:一个非负整数,代表这个时刻表图片的编号。
文件名:时刻表图片暗光照下的一版的文件名,路径应相对于列车文件夹(首先考虑),或相对于Objects文件夹(随后考虑)。

用该指令来加载暗光照下的时刻表图片。使用Track.Sta命令可以指定在哪站使用哪张时刻表图片。


Train.Gauge 毫米数值
毫米数值:一个浮点数,代表轨道的轨距。单位是毫米(0.001m,0.1cm)。默认值是1435(标准轨)。
Note

Train.Gauge和Route.Gauge作用相同。


Train.Interval 间隔0; 间隔1; …; 间隔n-1
Intervali: A floating-point number representing the time interval between the player’s train and the preceding train, measured in seconds. The default value is 0.
Note

Train.Interval is the same as Route.RunInterval.


Train.Velocity 速度
速度:该指令可以进一步给AI车设置限速。设定为0表示不给AI车设定额外限速。默认单位是km/h,默认值是0。

该指令设定的是额外限速,具体限速仍然受Track.Limit限制。玩家驾驶的列车不受影响,仍然可以一直加速到Track.Limit。


Train.Acceleration

该指令已过时。OpenBVE忽略该指令。


Train.Station

该指令已过时。OpenBVE忽略该指令。

■ 7. Structure (结构) 命名空间

这个命名空间里的指令用来载入在后面的其他指令中要用到的物体模型。总体来说,像Track.Rail、Track.FreeObj之类的命令通过结构编号来指定要使用的物体。这个结构编号对于这个指令是特定的,所以应当先载入要使用的模型。要使用哪个指令,要使用哪个模型,就把它们载入,不需要的就不用载入。

这个命名空间中的指令基本上都是以下这个结构:

Structure.类型 (结构编号).Load 文件名

结构编号是一个非负整数。文件名是一个相对于Object文件夹的路径,指向要加载的模型文件。类型是以下几种之一:

类型: 简介
Ground 用于Cycle.Ground和Track.Ground的地面模型。
Rail 用于Track.Rail、Track.RailStart和Track.RailType的轨道模型。
WallL 用于Track.Wall指令的左侧墙壁模型。
WallR 用于Track.Wall指令的右侧墙壁模型。
DikeL 用于Track.Dike指令的左侧路堤模型。
DikeR 用于Track.Dike指令的右侧路堤模型。
FormL 用于Track.Form指令的站台左边缘地面模型。
FormR 用于Track.Form指令的站台右边缘地面模型。
FormCL 用于Track.Form指令的可以被变换拉伸的站台左边缘地面模型。不支持ANIMATED格式带动画物体。
FormCR 用于Track.Form指令的可以被变换拉伸的站台右边缘地面模型。不支持ANIMATED格式带动画物体。
RoofL 用于Track.Form指令的站台左边缘顶棚模型。
RoofR 用于Track.Form指令的站台右边缘顶棚模型。
RoofCL 用于Track.Form指令的可以被变换拉伸的站台左边缘顶棚模型。 不支持ANIMATED格式带动画物体。
RoofCR 用于Track.Form指令的可以被变换拉伸的站台右边缘顶棚模型。 不支持ANIMATED格式带动画物体。
CrackL 用于Track.Crack指令的填充轨道间间隙的可以被变换拉伸的左侧地面模型。不支持ANIMATED格式带动画物体。
CrackR 用于Track.Crack指令的填充轨道间间隙的可以被变换拉伸的右侧地面模型。 不支持ANIMATED格式带动画物体。
FreeObj 用于Track.FreeObj指令在轨道旁放置的外景物体模型。
Beacon 用于Track.Beacon指令的轨旁无线电应答器模型。
Weather Defines objects for weather generated using Track.Rain and Track.Snow.
DynamicLight Defines dynamic lighting sets.

Generally, supported objects are B3D, CSV, X and ANIMATED. However, the FormCL, FormCR, RoofCL, RoofCR, CrackL and CrackR commands only accept B3D, CSV and X objects.

More information about forms, roofs and cracks…

Additionally, there is the Structure.Pole command, which has a slightly different syntax:

Structure.Pole(NumberOfAdditionalRails; PoleStructureIndex).Load FileName
NumberOfAdditionalRails: An non-negative integer representing the number of additional rails covered by the pole. 0 creates a pole for one rail, 1 for two rails, etc.
PoleStructureIndex: A non-negative integer representing the pole structure index.
FileName: The object file to load, relative to the Object folder.

Please note that all objects but the FreeObj are inserted at the beginning of a block and should thus extend from 0 to BlockLength (by default 25m) on the z-axis. For further information on usage, see the respective commands from the Track namespace.

■ 8. The Texture namespace

Commands from this namespace define which background images to use and how they are aligned.

illustration_background

The background image is displayed as a cylindric wall around the camera whose start (viewed from above) is 60 degrees to the left of the initial forward direction (at the 10 o’clock position). From there, the background image wraps clock-wise around the cylinder with a repetition count specified via Texture.Background(BackgroundTextureIndex).X, which by default creates 6 repetitions in a full circle.

The upper 3/4 of the image is displayed above the horizon, while the lower 1/4 is displayed below the horizon. Via Texture.Background(BackgroundTextureIndex).Aspect, you can choose whether to have a fixed cylinder height or to preserve the aspect ratio of the texture. If the image should have a fixed height, the cylinder has a height of 1/2 its radius, which corresponds to about 20 degree inclination to the top of the image, and about -7 degrees to the bottom of the image. If the aspect ratio of the image is preserved, this takes not only the width and height of the image into account, but also the repetition count.

Regardless of the repetition count you chose, you should make sure that the left and right edges of the textures fit seamlessly together. Please also take into account that top and bottom caps are created which sample from the top and bottom 10% of the image. You should avoid mountain peaks and similar extremes in the top 10% of the image in order for such extremes to not leak into the top cap.

The image loaded into Texture.Background(0) is displayed at the beginning of the route, unless a Track.Back command at the beginning of the route requests a different image.

As an alternative Dynamic or Object based backgrounds may be used. The implementation of these is described upon this page:

Dynamic & Object Based Backgrounds


Texture.Background(BackgroundTextureIndex).Load FileName
FileName: The texture file to load, relative to the Object folder.

This command loads a background image to be later used by Track.Back.

Note

If a dynamic or object based background is to be used, this must instead point to the appropriate XML file.


Texture.Background(BackgroundTextureIndex).X RepetitionCount
RepetitionCount: The number of times the background image is repeated in a full circle. The default value is 6.
Note

Ignored if using a dynamic or object based background.


Texture.Background(BackgroundTextureIndex).Aspect Mode
Mode: The mode of aspect ratio handling to use. The default value is 0 (fixed).

▸ Options for Mode:

0: Fixed: Use a fixed height for the cylinder.
1: Aspect: Preserve the aspect ratio of the image.
Note

Ignored if using a dynamic or object based background.

■ 9. The Cycle namespace

Cycle.Ground(GroundStructureIndex).Params GroundStructureIndex0; GroundStructureIndex1; GroundStructureIndex2; …; GroundStructureIndexn-1
GroundStructureIndex: A non-negative integer indicating the ground structure index for which a cycle is to be defined.
GroundStructureIndexi: A non-negative integer indicating a ground structure that has been previously loaded via Structure.Ground.

When usually using Track.Ground(GroundStructureIndex), the same ground structure object will be repeatedly placed in every block. Via Cycle.Ground, you can override this behavior and automatically cycle through a series of different objects when using Track.Ground(GroundStructureIndex). The cycle repeats indefinitely, where GroundStructureIndex0 starts at track position 0. Technically, the i in GroundStructureIndexi chosen for a particular track position p is Mod[p / BlockLength, n].

Cycle.Rail(RailStructureIndex).Params RailStructureIndex0; RailStructureIndex1; RailStructureIndex2; …; RailStructureIndexn-1
RailStructureIndex: A non-negative integer indicating the rail structure index for which a cycle is to be defined.
RailStructureIndexi: A non-negative integer indicating a rail structure that has been previously loaded via Structure.Rail.

Consider the following definition:

With Structure
.Ground(0) grass.csv
.Ground(1) river.csv
.Ground(2) asphalt.csv

The following two codes will produce the same output:

With Track
0, .Ground 0
25, .Ground 1
50, .Ground 2
75, .Ground 0
100, .Ground 1
125, .Ground 2
; and so on…
With Cycle
.Ground(0) 0; 1; 2
With Track
0, .Ground 0

■ 10. The Signal namespace

Commands from this namespace define custom signals.


Signal(SignalIndex__)__.Load AnimatedObjectFile
SignalIndex: A non-negative integer representing the signal index.
AnimatedObjectFile: A reference to an animated object file, relative to the Object folder.

Use this command to load signals directly from animated objects. The SignalIndex can be later referenced in Track.SigF commands to place the signal.


Signal(SignalIndex__)__.Load SignalFileWithoutExtension; GlowFileWithoutExtension
SignalIndex: A non-negative integer representing the signal index.
SignalFileWithoutExtension: A reference to a B3D/CSV/X object file representing the signal, relative to the Object folder, but without the file extension. Is required to be specified.
GlowFileWithoutExtension: An optional reference to a B3D/CSV/X object file representing the distance glow, relative to the Object folder, but without the file extension.

Use this command to load signals from a series of individual textures applied onto a common object. openBVE looks for X, CSV and B3D objects in this exact order. Textures are required to have the same name as the signal or glow, plus a non-negative aspect index, plus a file extension for textures. The SignalIndex can be later referenced in Track.SigF commands to place the signal.

For the SignalFileWithoutExtension, there should be the following files present (example):

SignalFileWithoutExtension.x
SignalFileWithoutExtension0.bmp
SignalFileWithoutExtension1.bmp
SignalFileWithoutExtension2.bmp
SignalFileWithoutExtensionn.bmp

The aspect indices from 0 through n represent successively more permissive aspects, where 0 is red. The built-in signals, for example, use the indices 0 (), 1 (●●), 2 (), 3 (), 4 () and 5 (●●). You can use as many as required.

All faces in the object will be applied the currently active aspect texture. This means that you cannot use any other texture in the object, but still have to assign texture coordinates appropriately. For the glow object, the above rules also apply. The glow object is usually a rectangle placed clearly in front of the signal, although you can also use different shapes.

The glow textures deserve special attention. All glow textures are pre-processed in the following way:

A B C D E F
illustration_glow_1 illustration_glow_2 illustration_glow_3 illustration_glow_4 illustration_glow_5 illustration_glow_6

The texture you start with should have a sharp shape, usually oval. The shape should be fully saturated in the core and blend into pure white at its outer rim. The surroundings of the shape can be either pure black (A) or pure white (B).

When openBVE loads the glow texture, it will replace all purely black pixels with purely white pixels, thus arriving at (B). From there, the image is inverted (C), then hue-shifted by 180 degrees (D). Compared to (B), this has the overall effect of inverting the lightness of the image, i.e. fully saturated pixels will be left unchanged (e.g. the core), while bright pixels (such as the outer rim of the shape) will become dark, and vice versa. Then, the image is gamma-corrected to further darken the dark parts (E), and finally, the image is blurred slightly (F).

The resulting texture is always additively blended. This means that instead of directly drawing the texture onto the screen, the pixels of the texture are added to the screen pixels. Here, adding black (0) does not change the screen pixels, while adding a fully satured color channel (1) will result in a fully satured color channel, e.g. adding white produces white. Keep in mind that when designing the textures, you will have to follow the inverse rules, e.g. design the image as depicted in (A) or (B), while having in mind how it will be processed afterward.

■ 11. The Track namespace

Commands from this namespace define the track layout. Commands from this namespace should appear after commands from any of the other namespaces, and they usually form the largest part of the route file.

Use of track positions

All commands from the Track namespace need to be associated to track positions. Once a track position has been defined, all subsequent commands are associated to this track position until a new track position is defined. If you do not explicitly state a track position before the first command of the Track namespace is used, 0 will be assumed. While you do not need to use track positions in ascending order, series of commands which are associated the same track position will be sorted into ascending order once the file is loaded. While track positions can be any non-negative floating-point number, many commands in the Track namespace are only to be applied at the beginning of a block, which is 25m by default. For the default situation, this means that some commands are only to be used at track positions 0, 25, 50, 75, 100, 125 and so on. All commands for which this restriction applies are marked as such.

● 11.1. Rails

Track.RailStart RailIndex; X; Y; RailType
RailIndex: A positive integer (>=1) indicating which rail index to use.
X: A floating-point number representing the horizontal distance from the player’s rail, by default measured in meters. Negative values indicate left, positive ones right.
Y: A floating-point number representing the vertical distance from the player’s rail, by default measured in meters. Negative values indicate below, positive ones above.
RailType: A non-negative integer referencing the rail type to use as defined by either a Structure.Rail or a Structure.Cycle command.

This command starts a new rail represented by the index RailIndex. Upon the point where this command is used, a rail of the same RailIndex must either not have been used so far in the route, or must have been ended via a Track.RailEnd command. If a rail of the same RailIndex was already used in the route, the default values of X, Y and RailType are the values last used by that rail, otherwise 0. If the rail is to be updated, use the Track.Rail command. If it is to be ended, use the Track.RailEnd command. You can end a rail of a given RailIndex and start a new rail of the same RailIndex at the same track position provided that the old rail is first ended and the new rail started afterward. For every block, a structure, determined by RailType, is automatically placed.

This command can only be used at the beginning of a block.


Track.Rail RailIndex; X; Y; RailType
RailIndex: A positive integer (>=1) indicating which rail index to use.
X: A floating-point number representing the horizontal distance from the player’s rail, by default measured in meters. Negative values indicate left, positive ones right.
Y: A floating-point number representing the vertical distance from the player’s rail, by default measured in meters. Negative values indicate below, positive ones above.
RailType: A non-negative integer referencing the rail type to use as defined by either a Structure.Rail or a Structure.Cycle command.

This command starts a new rail or updates an existing rail. The rail is represented by the index RailIndex. If a rail of the same RailIndex was already used in the route, the default values of X, Y and RailType are the values last used by that rail, otherwise 0. If the rail is to be ended, use the Track.RailEnd command. You can end a rail of a given RailIndex and start a new rail of the same RailIndex at the same track position provided that the old rail is first ended and the new rail started afterward. In each block, the X and Y values are repeated if a Track.Rail command is not used for that block. As a consequence, updating the X or Y values affects the layout of the rail from the preceding block only. Changing the RailType will affect the rail from the point on where this command is used. If this command is used multiple times on the same track position for the same rail, then the first instance of the command takes effect, while subsequent ones are ignored.

This command can only be used at the beginning of a block.

Using a RailIndex value of 0 is not valid for this command: Errata Note

Track.RailStart vs. Track.Rail

If you want to start a new rail, you can either use Track.RailStart or Track.Rail. When using Track.RailStart, you provide markup that a new rail is in fact to be started, which is invalid if the rail already exists. Using an explicit Track.RailStart will protect you from using a RailIndex which is already in use, in which case an error message is generated.


Track.RailType RailIndex; RailType
RailIndex: A non-negative integer indicating which rail index to change. The player’s rail can be referred to with index 0. The default value is 0.
RailType: A non-negative integer referencing the rail type to use as defined by either a Structure.Rail or a Structure.Cycle command. The default value is 0.

This command changes the rail type for an existing rail, represented by RailIndex. The rail must have been started with a Track.RailStart or Track.Rail command and must not have been ended by a Track.RailEnd command. Changing the RailType will affect the rail from the point on where this command is used.

This command can only be used at the beginning of a block.


Track.RailEnd RailIndex; X; Y
RailIndex: A positive integer (>=1) indicating which rail index to use.
X: A floating-point number representing the horizontal distance from the player’s rail, by default measured in meters. Negative values indicate left, positive ones right.
Y: A floating-point number representing the vertical distance from the player’s rail, by default measured in meters. Negative values indicate below, positive ones above.

This command ends an existing rail, represented by the index RailIndex. The default values of X and Y are the ones last used by the rail. Once this command is used for a specific RailIndex, the corresponding rail is considered to be non-existing afterward.

This command can only be used at the beginning of a block.

Using a RailIndex value of 0 is not valid for this command: Errata Note

Example of Track.RailStart, Track.Rail, Track.RailType and Track.RailEnd commands
With Track
1000, .RailStart 1; 3.8; 0.0; 0
1025, .RailType 1; 1
1050, .Rail 1; 1.9; 0.0; 0
1075, .RailEnd 1

In the preceding example, rail 1 starts with an x-value of 3.8 and bears a rail index which corresponds to an object intended to depict a straight rail. The rail keeps the x-value of 3.8 at track position 1025, where the rail type is changed to correspond to an object intended to depict an s-shaped curve. At track position 1050, the rail is redefined to have an x-value of 1.9, after which the rail is straight again until 1075, where it is ended, still having an x-value of 1.9.


Track.Accuracy Value
Value: A non-negative floating-point number representing the accuracy of the track. The default value is 2.

This command sets the accuracy of the track from this point on. Values should be in the range from 0 to 4, where 0 means perfect accuracy (no inaccuracy at all), 1 means very good accuracy (high speed lines), 2 means good accuracy, 3 means mediocre accuracy, and 4 means poor accuracy. Intermediate values are also possible. Currently, values below 0 are clamped at 0, and values above 4 are clamped at 4.


Track.Adhesion Rate
Rate: A non-negative floating-point number measured in percent representing the adhesion of the track. The default value is 100.

This command sets the adhesion of the track from this point on. As a reference, the value of 135 represents dry conditions, 85 represents frost and 50 represents snowy conditions. With a value of 0, the train will not be able to move at all.


Track.Rain Intensity; WeatherType
Intensity: A non-negative floating-point number measured in percent representing the intensity of the current rainfall. The default value is 0.
WeatherType: A non-negative integer referencing the weather type to use as defined by Structure.Weather from this point onwards.

This command sets the intensity of the current rainfall, and the weather object to be shown.

It is also possible to set the rain intensity using the legacy BVE4 beacon based method. If these commands are present in the route, all Rain commands will be ignored.


Track.Snow Intensity; WeatherType
Intensity: A non-negative floating-point number measured in percent representing the intensity of the current snowfall. The default value is 0.
WeatherType: A non-negative integer referencing the weather type to use as defined by Structure.Weather from this point onwards.

This command sets the intensity of the current snowfall, and the weather object to be shown.

Combining rain and snow

Rain and snow may be combined, and the simulation will show an appropriate random raindrop or snowflake on the windscreen, based upon the following probabilities:

The base probability for a drop / flake to appear is the greater of the rainfall and snowfall intensities.
The snowfall intensity is then used as the probability that this is a snowflake.
For example, with rainfall at 50 and snowfall at 40, there is a 50% chance for a drop to be added to the windscreen on each tick.
Of this, there is a 40% chance that this will be a snowflake.

● 11.2. Geometry

Track.Pitch Rate
Rate: A floating-point number measured in per thousands representing the pitch of the track. The default value is 0.

This command defines the pitch of all rails from this point on. Negative values indicate a downward gradient, positive ones an upward gradient. The value of 0 represents a level track. Rate can be calculated from a length difference X and a height difference Y in the following way:

Rate expressed through X and Y:
ƒ Rate = 1000 * Y / X

This command can only be used at the beginning of a block.


Track.Curve Radius; CantInMillimeters
Radius: A floating-point number representing the radius of the curve, by default measured in meters. The default value is 0.
CantInMillimeters: A floating-point number which represents the superelevation of a banked curve, always measured in millimeters (0.001 meters). The default value is 0. See also Options.CantBehavior.

This command defines the radius of the curve for the player’s rail from this point on. Negative values for Radius indicate a curve to the left, positive ones to the right. The value of 0 represents straight track. The CantInMillimeters parameter defines the cant (superelevation) in millimeters. If Options.CantBehavior is 0 (default), only the absolute value of CantInMillimeters is considered, and the superelevation is always towards the curve center (inward). Also, cant cannot be applied on straight track. If Options.CantBehavior is 1, CantInMillimeters is signed, i.e. negative values bank outward and positive ones inward on curved track. Also, cant can be applied on straight track, where negative values bank toward the left and positive ones toward the right.

This command can only be used at the beginning of a block.


Track.Turn Ratio
Ratio: A floating-point number representing a turn. The default value is 0.

This command creates a point-based turn at the point of insertion. Ratio indicates the ratio between the length difference Z and the horizontal offset X in the following way:

ƒ Ratio = X / Z

A negative ratio represents a turn to the left, a positive one to the right. The value of 0 represents a straight track.

This command can only be used at the beginning of a block.

This command is deprecated - use Track.Curve instead.


Track.Height Y
Y: A floating-point number representing the height of the player’s rail, by default measured in meters.

This command defines the height of the player’s rail above the ground at the point of insertion. It influences the placement of the ground objects defined via Structure.Ground and changed via Track.Ground. The height is interpolated between adjacent Track.Height commands. For example, the following two codes produce equivalent results:

Example of a Track.Height command interpolated at 25m boundaries:
1000, Track.Height 1
1075, Track.Height 4
Example of Track.Height explicitly set each 25m to produce the same result:
1000, Track.Height 1
1025, Track.Height 2
1050, Track.Height 3
1075, Track.Height 4

This command can only be used at the beginning of a block.

● 11.3. Objects

Track.FreeObj RailIndex; FreeObjStructureIndex; X; Y; Yaw; Pitch; Roll
RailIndex: A non-negative integer representing the rail on which to place the object. The default value is 0.
FreeObjStructureIndex: A non-negative integer representing the object to place as defined via Structure.FreeObj. The default value is 0.
X: The x-offset from the (straight) rail, by default measured in meters. Negative values represent the left, positive ones the right. The default value is 0.
Y: The y-offset from the (straight) rail, by default measured in meters. Negative values represent below the top of the rails, positive ones above. The default value is 0.
Yaw: The angle in degrees by which the object is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the object is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the object is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.

This places a “free” object a single time on a specified rail. The object must have been loaded via Structure.FreeObj(FreeObjStructureIndex) prior to using this command.


Track.Wall RailIndex; Direction; WallStructureIndex
RailIndex: A non-negative integer representing the rail on which to start or update the wall. The default value is 0.
Direction: An integer indicating which wall to use as described below.
WallStructureIndex: A non-negative integer representing the object to place as defined via Structure.WallL and Structure.WallR. The default value is 0.

▸ Options for Direction:

-1: The WallL object (left wall) is used.
0: Both the WallL and WallR objects are used.
1: The WallR object (right wall) is used.

This starts or updates a wall on a specified rail. The object must have been loaded via Structure.WallL(WallObjectIndex) or Structure.WallR(WallObjectIndex) prior to using this command. The walls are placed at the beginning of every block until a corresponding Track.WallEnd ends the wall for this rail. Please note that walls are resurrected if a rail is ended via Track.RailEnd and then started again via Track.RailStart or Track.Rail unless the wall was also ended via Track.WallEnd.

This command can only be used at the beginning of a block.


Track.WallEnd RailIndex
RailIndex: A non-negative integer representing the rail on which to end an existing wall.

This ends an existing wall that was previously started via Track.Wall on a specified rail. The wall is not placed for the block in which this command is used.

This command can only be used at the beginning of a block.


Track.Dike RailIndex; Direction; DikeStructureIndex
RailIndex: A non-negative integer representing the rail on which to start or update the dike. The default value is 0.
Direction: An integer indicating which dike to use as described below.
DikeStructureIndex: A non-negative integer representing the object to place as defined via Structure.DikeL and Structure.DikeR. The default value is 0.

▸ Options for Direction:

-1: The DikeL object (left dike) is used.
0: Both the DikeL and DikeR objects are used.
1: The DikeR object (right dike) is used.

This starts or updates a dike on a specified rail. The object must have been loaded via Structure.DikeL(DikeObjectIndex) or Structure.DikeR(DikeObjectIndex) prior to using this command. The dikes are placed at the beginning of every block until a corresponding Track.DikeEnd ends the dike for this rail. Please note that dikes are resurrected if a rail is ended via Track.RailEnd and then started again via Track.RailStart or Track.Rail unless the dike was also ended via Track.DikeEnd.

This command can only be used at the beginning of a block.


Track.DikeEnd RailIndex
RailIndex: A non-negative integer representing the rail on which to end an existing dike.

This ends an existing dike that was previously started via Track.Dike on a specified rail. The dike is not placed for the block in which this command is used.

This command can only be used at the beginning of a block.


Track.Pole RailIndex; NumberOfAdditionalRails; Location; Interval; PoleStructureIndex
RailIndex: A non-negative integer representing the rail on which to start or update the pole. The default value is 0.
NumberOfAdditionalRails: A non-negative integer representing the amount of additional rails covered by this pole (i.e. this rail, plus NumberOfAdditionalRails rails). The default value is 0.
Location: If NumberOfAdditionalRails is 0, the side on which the pole is placed (see below), or the x-offset in multiples of 3.8 meters if NumberOfAdditionalRails is at least 1. The default value is 0.
Interval: An integer multiple of the block length specifying the interval in which poles are placed.
PoleStructureIndex: A non-negative integer representing the object to place as defined via Structure.Pole. The default value is 0.

This starts or updates a pole on a specified rail. The object must have been loaded via Structure.Pole(NumberOfAdditionalRails; PoleStructureIndex) prior to using this command. The poles are placed at the beginning of every block whose track positions are an integer multiple of the Interval (that is not necessarily at the same location this command is placed). If NumberOfAdditionalRails is 0, Locationindicates the side of the rail on which the pole is placed. If Location is less than or equal to 0, the pole is placed as-is (corresponding to the left side). If Location is greater than 0, the object is mirrored on the x-axis and then placed (corresponding to the right side). If NumberOfAdditionalRails is greater than or equal to 1, Location specifies the x-offset in multiples of 3.8 meters. Please note that poles are resurrected if a rail is ended via Track.RailEnd and then started again via Track.RailStart or Track.Rail unless the pole was also ended via Track.PoleEnd.

This command can only be used at the beginning of a block.


Track.PoleEnd RailIndex
RailIndex: A non-negative integer representing the rail on which to end an existing pole.

This ends an existing pole that was previously started via Track.Pole on a specified rail. The pole is not placed for the block in which this command is used.

This command can only be used at the beginning of a block.


Track.Crack RailIndex1; RailIndex2; CrackStructureIndex

This deforms a specified object to fill the space between two Rails.

RailIndex1: A non-negative integer representing the first RailIndex.
RailIndex2: A non-negative integer representing the second RailIndex.
CrackStructureIndex: A non-negative integer representing the object defined in Structure.Crack

Note: If RailIndex1 is to the left of RailIndex2 (e.g. it’s X-cordinate is smaller), then the object defined in Structure.CrackL will be used.
Otherwise, the objects defined in Structure.CrackR will be used.


Track.Ground CycleIndex
CycleIndex: A non-negative integer representing the cycle of ground objects to place as defined via Structure.Ground or Cycle.Ground.

This defines which ground objects to place from this point on. Ground objects are always placed at the beginning of a block at a certain height below the player’s rail (as defined via Track.Height). If no cycle was defined for CycleIndex, then the object loaded into Structure.Ground(CycleIndex) is placed. Otherwise, the cycle of ground objects as defined via Cycle.Ground(CycleIndex) is used.

This command can only be used at the beginning of a block.

● 11.4. Stations

Track.Sta Name; ArrivalTime; DepartureTime; PassAlarm; Doors; ForcedRedSignal; System; ArrivalSound; StopDuration; PassengerRatio; DepartureSound; TimetableIndex
Name: The name of the station. This is displayed in the timetable and in messages, so should not be omitted.
ArrivalTime: The time the player’s train is expected to arrive at this station. Special values may also appear - see below.
DepartureTime: The time the player’s train is expected to depart from this station. Special values may also appear - see below.
PassAlarm: Indicates whether the pass alarm device should remind the driver of stopping at this station. The default value is 0.
Doors: Indicates which doors should open at this station. The default value is 0.
ForcedRedSignal: Indicates whether the signal behind the last station stop should be red on a train approach. The default value is 0.
System: Indicates which built-in safety system should apply until the next station. The default value is 0.
ArrivalSound: The sound file to be played on arrival, relative to the Sound folder.
StopDuration: A positive floating-point number indicating the minimum stop duration in seconds, including door opening/closing times. The default value is 15.
PassengerRatio: A non-negative floating-point number indicating the relative amount of passengers in the train from this station on. As a reference, 100 represents a train with normal amount of passengers, while 250 represents an over-crowded train. Values in-between 0 and 250 should be used. The default value is 100.
DepartureSound: The sound file to be played before departure (departure time minus sound duration minus door closing time), relative to the Sound folder.
TimetableIndex: A non-negative integer representing the timetable to be shown from this station on as defined via Train.Timetable(TimetableIndex).

▸ Available options for ArrivalTime:

time: The train is expected to arrive at this particular time.
omitted: The train may arrive at any time.
P or L: All trains are expected to pass this station.
B: The player’s train is expected to pass this station, while all other trains are expected to stop.
S: The player’s train is expected to stop at this station, while all other trains are expected to pass.
S:time: The player’s train is expected to arrive at this particular time, while all other trains are expected to pass.
D: This station is a dummy station for use in conjunction with ForcedRedSignal. No stop position overlay or timetable entry will be shown.

▸ Available options for DepartureTime:

time: The train is expected to depart at this particular time.
omitted: The train may depart at any time.
T or =: This is the terminal station. If ForcedRedSignal is set to 1, the departure signal will be held at red indefinately.
T:time: This is the terminal station. If ForcedRedSignal is set to 1, the departure signal will still switch to green before the specified time as if this was a regular station.
C: This is a station at which to “change ends”. See the description below.
C:time: This is a station at which to “change ends”. Changing ends will take place at the specified time unless StopDuration interferes. See the description below.
J:index: This is a station at which the train is “jumped” to the station specified by index. See the description below.
J:index:Time: This is a station at which the train is “jumped” to the specified by index. Jumping will take place at the specified time unless StopDuration interfers. See the description below.

▸ Available options for PassAlarm:

0: The pass alarm device does not remind the driver of stopping at this station.
1: The pass alarm device reminds the driver of stopping at this station.

▸ Available options for Doors:

L or -1: The left doors are expected to open at this station.
N or 0: No doors are expected to open at this station, i.e. the train should simply come to a hold.
R or 1: The right doors are expected to open at this station.
B: Both the left and right doors are expected to open at this station.

▸ Available options for ForcedRedSignal:

0: Signals are unaffected by this station.
1: The signal immediately following the last station stop is hold at red until the train reaches the stopping area and the departure time.

▸ Available options for System:

ATS or 0: ATS should be used from this station on. The following track is not be equipped with ATC.
ATC or 1: ATC should be used from this station on. The following track is equipped with ATC.

This command initializes a new station. It should be placed at the beginning of the station platform. In order to finalize the creation of a station, use the Track.Stop command to place stop points following this command. All following Track.Stop commands will be associated to this station. At least one Track.Stop command must follow if trains are expected to stop at this station.

Special Features:

Stations can be marked as “changing ends” in the departure time. At such stations, when the departure time has been reached, the train will automatically jump to the next station. This feature is intended to fake a reverse of traveling direction without the need to jump to stations manually from the menu.

Similarly, stations can be marked as a “jump point” in the departure time. At such stations, when the departure time has been reached, the train will automatically jump to the specified station index.

The first occuring station in a route may not be of the Terminal type.


Track.Station Name; ArrivalTime; DepartureTime; ForcedRedSignal; System; DepartureSound
Name: The name of the station. This is displayed in the timetable and in messages, so should not be omitted.
ArrivalTime: The time the player’s train is expected to arrive at this station. Special values may also appear - see below.
DepartureTime: The time the player’s train is expected to depart from this station. Special values may also appear - see below.
ForcedRedSignal: Indicates whether the signal behind the last station stop should be red on a train approach. The default value is 0.
System: Indicates which built-in safety system should apply until the next station. The default value is 0.
DepartureSound: The sound file to be played before departure (departure time minus sound duration minus door closing time), relative to the Sound folder.

▸ Available options for ArrivalTime:

time: The train is expected to arrive at this particular time.
omitted: The train may arrive at any time.
P or L: All trains are expected to pass this station.
B: The player’s train is expected to pass this station, while all other trains are expected to stop.
S: The player’s train is expected to stop at this station, while all other trains are expected to pass.
S:time: The player’s train is expected to arrive at this particular time, while all other trains are expected to pass.

▸ Available options for DepartureTime:

time: The train is expected to depart at this particular time.
omitted: The train may depart at any time.
T or =: This is the terminal station. If ForcedRedSignal is set to 1, the departure signal will be held at red indefinately.
T:time: This is the terminal station. If ForcedRedSignal is set to 1, the departure signal will still switch to green before the specified time as if this was a regular station.
C: This is a station at which to “change ends”. See the description below.
C:time: This is a station at which to “change ends”. Changing ends will take place at the specified time unless StopDuration interferes. See the description below.

▸ Available options for ForcedRedSignal:

0: Signals are unaffected by this station.
1: The signal immediately following the last station stop is hold at red until the train reaches the stopping area and the departure time.

▸ Available options for System:

ATS or 0: ATS should be used from this station on. The following track is not be equipped with ATC.
ATC or 1: ATC should be used from this station on. The following track is equipped with ATC.

This command initializes a new station. Prefer using the Track.Sta command, which includes more options. For the options of Track.Sta which are not offered by Track.Station, the following values apply:

PassAlarm 0 (not used)
Doors B (both doors must be opened)
ArrivalSound Not played
StopDuration 15
PassengerRatio 100
TimetableIndex Not affected

The command should be placed at the beginning of the station platform. In order to finalize the creation of a station, use the Track.Stop command to place stop points following this command. All following Track.Stop commands will be associated to this station. At least one Track.Stop command must follow if trains are expected to stop at this station.

Stations can be marked as “changing ends” in the departure time. At such stations, when the departure time has been reached, the train will automatically jump to the next station. This feature is intended to fake a reverse of traveling direction without the need to jump to stations manually from the menu.

The first occuring station in a route may not be of the Terminal type.


Track.Stop Direction; BackwardTolerance; ForwardTolerance; Cars
Direction: On which side to place a default stop post. The default value is 0.
BackwardTolerance: A positive floating-point number indicating the allowed tolerance in the backward direction, by default measured in meters. The default value is 5.
ForwardTolerance: A positive floating-point number indicating the allowed tolerance in the forward direction, by default measured in meters. The default value is 5.
Cars: A non-negative integer indicating for how many cars this stop point applies, or 0 for all cars. The default value is 0.

▸ Available options for Direction:

-1: A stop post is created on the left side.
0: No stop post is created.
1: A stop post is created on the right side.

This command places a stop point for the last created station. If there is more than one stop defined for a station, a train is expected to stop at the first Track.Stop command for which Cars is greater than or equal to the number of cars the train has, where a value for Cars of 0 indicates a stop point regardless of the amount of cars to be used as the last stop point for a station.

Example of a station with multiple stop points:
With Track
0100, .Sta STATION
0178, .Stop 1;;;4 ,; for 4 or less cars
0212, .Stop 1;;;6 ,; for 5 or 6 cars
0246, .Stop 1;;;8 ,; for 7 or 8 cars
0280, .Stop 1;;;0 ,; for 9 or more cars

Track.Form RailIndex1; RailIndex2; RoofStructureIndex; FormStructureIndex
RailIndex1: The RailIndex to which the platform is bound.
RailIndex2: The secondary RailIndex to which the platform will deform. Special values may also appear- see below.
RoofStructureIndex: A non-negative integer representing the object to be placed as defined via Structure.Roof
FormStructureIndex: A non-negative integer representing the object to be placed as defined via Structure.Form and Structure.FormC

▸ Available options for RailIndex2:

Any current RailIndex: The form is deformed to meet the specified RailIndex.
L: The specified FormL, FormCL and RoofL objects are placed without deformation.
R: The specified FormR, FormCR and RoofR objects are placed without deformation.

Note: If RailIndex1 is to the left of RailIndex2 (e.g. it’s X-cordinate is smaller), then the objects defined in Structure.FormL, Structure.FormCL and Structure.RoofL will be used.
Otherwise, the objects defined in Structure.FormR, Structure.FormCL and Structure.RoofR will be used.

● 11.5. Signalling and speed limits

Track.Limit Speed; Post; Cource
Speed: A positive floating-point number representing the speed, by default measured in km/h, or 0 to indicate no speed restriction. The default value is 0.
Post: The side on which to place a default Japanese-style speed limit post. The default value is 0.
Cource: The directional indication. The default value is 0.

illustration_limit

▸ Options for Post:

-1: The post is placed on the left side of the track.
0: No post will be placed.
1: The post is placed on the right side of the track.

▸ Options for Cource:

-1: The post applies for a left-bound track.
0: The post does not indicate a particular direction.
1: The post applies for a right-bound track.

This command defines the new speed limit from this point on. If the new speed limit is lower than the current speed limit, the new speed limit will take effect immediately. If the speed limit is higher than the current speed limit, the new speed limit will take effect only once the whole train has passed this point. By setting Speed to 0, the speed restriction is released. By setting Post to either -1 or 1, a default Japanese-style speed post is placed at the respective side of the track. Setting Course to either -1 or 1 includes a directional indication, which is usually used at railroad switches to indicate that the speed limit only applies if the respective direction is being taken. If Speed is set to 0, the setting of Course has no effect.


Track.Section a0; a1; a2; …; an
ai: A non-negative number specifying one of the section’s aspects.

This command starts a section, the functional part of signalling, to be used in conjunction with Track.SigF, which creates a visual representation of a section (a signal). The ai parameters specify the aspects the section can bear. An aspect of 0 corresponds to a red section which must not be passed by a train. The a0 term is mandatory.

Default versus simplified section behavior

There are two different modes of behavior on how to interpret the ai parameters. The mode can be set via Options.SectionBehavior. The following are separate descriptions for default and simplified behavior.

Default behavior:
The ai terms specify the aspect the section should bear depending on how many sections ahead are clear until a red one is encountered. The order of the terms is relevant. The same aspect may occur multiple times.

▸ Meanings of the ai terms:

a0: The aspect to show when this section is occupied by a train or otherwise hold at red.
a1: The aspect to show when this section is clear, but the immediately following section is red.
a2: The aspect to show when this section and the following section are clear, but the one immediately following the latter one is red.
an: The aspect to show when n sections are clear before a red one is encountered.

In the case more sections ahead are clear than indicated by the ai terms, the section will bear the aspect of an.

Simplified behavior:
The ai terms specify the repertoire of aspects the section can have. A section will bear the smallest of the ai which is greater than the current aspect of the upcoming section. If no such ai exists, the section will bear the aspect of an. The order of the ai is irrelevant. If the same aspect occurs multiple times, this has no effect.

Example of a Track.Section command in conjunction with a Track.SigF command:
With Track
1000, .Section 0;2;4, .SigF 3;0;-3;-1

Track.SigF SignalIndex; Section; X; Y; Yaw; Pitch; Roll
SignalIndex: A non-negative integer representing the signal to be placed as defined via Signal(SignalIndex).Load.
Section: A non-negative integer representing the section this signal is attached to, with 0 being the current section, 1 the upcoming section, 2 the section after that, and so on.
X: The X-coordinate to place the signal object, by default measured in meters. The default value is 0.
Y: The Y-coordinate to place the signal object, by default measured in meters. The default value is 0.
Yaw: The angle in degrees by which the object is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the object is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the object is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.

This command creates a non-function signal, that is, a visual representation of a section as defined via Track.Section. Setting Y to a negative number resets the y-coordinate to 4.8 meters and attaches a default signal post. Also see Track.Section.

If no object has been defined by Signal(SignalIndex), one of the default Japanese signals is used:

▸ Default signals for SignalIndex:

3: A three-aspect signal having aspects red, yellow and green.
4: A four-aspect (type A) signal having aspects red, ●●yellow-yellow, yellow and green.
5: A five-aspect (type A) signal having aspects red, ●●yellow-yellow, yellow, yellow-green and green.
6: A repeating signal equivalent to that created by Track.Relay.

Track.Signal Aspects; Unused; X; Y; Yaw; Pitch; Roll
Track.Sig Aspects; Unused; X; Y; Yaw; Pitch; Roll
Type: The number of aspects for this signal. The default value is -2.
Unused: This argument is not used by openBVE.
X: The X-coordinate to place the signal object, by default measured in meters. The default value is 0.
Y: The Y-coordinate to place the signal object, by default measured in meters. The default value is 0.
Yaw: The angle in degrees by which the object is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the object is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the object is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.

▸ Options for Type:

illustration_signals_small
2: A two-aspect (type A) signal having aspects red and yellow.
-2: A two-aspect (type B) signal having aspects red and green.
3: A three-aspect signal having aspects red, yellow and green.
4: A four-aspect (type A) signal having aspects red, ●●yellow-yellow, yellow and green.
-4: A four-aspect (type B) signal having aspects red, yellow, ●●yellow-green and green.
5: A five-aspect (type A) signal having aspects red, ●●yellow-yellow, yellow, yellow-green and green.
-5: A five-aspect (type B) signal having aspects red, yellow, yellow-green, green and ●●green-green.
6: A six-aspect signal having aspects red, ●●yellow-yellow, yellow, yellow-green, green and ●●green-green.

This command creates a functional signal. You can choose from the available options for Aspect to create any of the default Japanese signals. Setting X to 0 creates a functional but invisible signal similar to Track.Section. Setting X to a non-zero number and Y to a negative number resets the y-coordinate to 4.8 meters and attaches a default signal post.

Example of a four-aspect type B signal without a post at x=-3 and y=5:
1000, Track.Signal -4;;-3;5
Example of a four-aspect type B signal including a post at x=-3 and y=4.8:
1000, Track.Signal -4;;-3;-1

Track.Signal is similar to using Track.Section and Track.SigF in one command.


Track.Relay X; Y; Yaw; Pitch; Roll
X: The X-coordinate at which to place the object, by default measured in meters. The default value is 0.
Y: The Y-coordinate at which to place the object, by default measured in meters. The default value is 0.
Yaw: The angle in degrees by which the object is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the object is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the object is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.

This commands creates a default Japanese repeating signal. The repeating signal repeats the state of the upcoming signal. Setting X to zero does not create a repeating signal, but forces the command to be ignored. Setting X to a non-zero number and Y to a negative number resets the y-coordinate to 4.8 and attaches a default signal post.

● 11.6. Safety systems

Track.Beacon Type; BeaconStructureIndex; Section; Data; X; Y; Yaw; Pitch; Roll
Type: A non-negative integer representing the type of the beacon to be transmitted to the train.
BeaconStructureIndex: A non-negative integer representing the object to be placed as defined via Structure.Beacon, or -1 to not place any object.
Section: An integer representing the section to which the beacon is attached, namely 0 for the current section, 1 for the upcoming section, 2 for the section behind that, etc., or -1 for the next red section.
Data: An integer representing arbitrary data specific to the beacon type to be transmitted to the train.
X: The X-coordinate at which to place the object, by default measured in meters. The default value is 0.
Y: The Y-coordinate at which to place the object, by default measured in meters. The default value is 0.
Yaw: The angle in degrees by which the object is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the object is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the object is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.

This command places a beacon (transponder). The object must have been loaded via Structure.Beacon(BeaconStructureIndex) prior to using this command. When the train passes the beacon, the type of beacon and various data will be transmitted to the train, including the state of the referenced section.

It should be noted that the built-in safety systems also receive data from these beacons as Track.Beacon(Type) is roughly equivalent to Track.Transponder(Type). Please see the page about beacon standards for more information.


Track.Transponder Type; Signal; SwitchSystem; X; Y; Yaw; Pitch; Roll
Track.Tr Type; Signal; SwitchSystem; X; Y; Yaw; Pitch; Roll
Type: The type of the transponder. The default value is 0.
Signal: The signal this transponder references. The default value is 0.
SwitchSystem: Whether to automatically switch the safety system. The default value is 0.
X: The X-coordinate at which to place the object, by default measured in meters. The default value is 0.
Y: The Y-coordinate at which to place the object, by default measured in meters. The default value is 0.
Yaw: The angle in degrees by which the object is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the object is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the object is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.

▸ Options for Type:

illustration_transponders
0: An S-type transponder used by ATS-S. Usually placed 600m in front of a signal.
1: An SN-type transponder used by ATS-SN. Usually placed 20m in front of a signal.
2: An accidental departure transponder. Usually placed shortly behind a station stop.
3: An ATS-P pattern renewal transponder. Usually placed 600m, 280m, 180m, 130m, 85m or 50m in front of a signal, depending on the circumstances.
4: An ATS-P immediate stop transponder. Usually placed either 25m or 30m in front of a signal, depending on the circumstances.

▸ Options for Signal:

0: The upcoming signal is referenced.
1: The signal immediately behind the upcoming signal is referenced.
n: The n‘th signal behind the upcoming signal is referenced.

▸ Options for SwitchSystem:

-1: The transponder does not switch the train between ATS-SN and ATS-P.
0: The transponder automatically switches the train to ATS-SN for transponder types 0 and 1, and to ATS-P for types 3 and 4.

This command places a transponder, usually for the built-in safety systems ATS-SN or ATS-P. For more information about these systems and their transponders, see the user’s documentation about ATS.

It should be noted that custom safety system plugins also receive data from these transponders as Track.Transponder(Type) is roughly equivalent to Track.Beacon(Type). Please see the page about beacon standards for more information.

Go here to find out more about ATS-SN and ATS-P.

There is a tutorial available for the proper use of ATS-SN and ATS-P in route files, including all of the five transponders.


Track.AtsSn

This command places an S-type transponder for the built-in safety system ATS-SN, referencing the upcoming signal, and automatically switching to ATS-SN. The command is equivalent to Track.Tr 0;0;0. See there for more information.


Track.AtsP

This command places a pattern renewal transponder for the built-in safety system ATS-P, referencing the upcoming signal, and automatically switching to ATS-P. The command is equivalent to Track.Tr 3;0;0. See there for more information.


Track.Pattern Type; Speed
Type: The type of speed restriction.
Speed: A non-negative floating-point number representing the speed restriction, by default measured in km/h.

▸ Options for Type:

0: A temporary speed restriction.
1: A permanent speed restriction.

This command defines a speed restriction for the built-in safety system ATS-P.

A temporary speed restriction (Type=0) is to be inserted at the point where the speed restriction should apply. ATS-P will know about this speed restriction in advance and will brake the train so that the train meets the speed restriction at that point. Once the point is passed, the speed restriction no longer applies.

A permanent speed restriction (Type=1) is to be inserted at the point where the speed restriction should apply, however, ATS-P does not know about this limit in advance and will only brake the train from that point on. For a higher degree of realism, insert permanent speed restrictions at the same point as ATS-P transponders. A permanent speed restriction, as the name suggests, is remembered by ATS-P and is only released by a subsequent permanent speed restriction.


Track.PLimit Speed
Speed: A positive floating-point number representing the permanent speed restriction for ATS-P, by default measured in km/h.

This command is equivalent to Track.Pattern 1;Speed. See there for more information.

● 11.7. Miscellaneous

Track.Back BackgroundTextureIndex
BackgroundTextureIndex: A non-negative integer representing the background image to be displayed as defined via Texture.Background(BackgroundTextureIndex).

This command defines which background image to show from now on.

This command can only be used at the beginning of a block.


Track.Fog StartingDistance; EndingDistance; RedValue; GreenValue; BlueValue
StartingDistance: A floating-point number indicating the start of fog, by default measured in meters. The default value is 0.
EndingDistance: A floating-point number indicating the end of fog, by default measured in meters. The default value is 0.
RedValue: An integer ranging from 0 to 255 representing the red component of the fog. The default value is 128.
GreenValue: An integer ranging from 0 to 255 representing the green component of the fog. The default value is 128.
BlueValue: An integer ranging from 0 to 255 representing the blue component of the fog. The default value is 128.

This command defines the fog from this point on, or deactivates fog. If fog is to be enabled, StartingDistance must be less than EndingDistance. If fog is to be disabled, StartingDistance must be greater than or equal to EndingDistance.

Fog affects the coloring of objects. Objects before the starting distance appear as-is, objects after the ending distance appear in the fog color, and objects in-between blend linearly between those. The background image is affected by fog as well. For the fog calculations, the background image is assumed to be at 600 meters distance from the camera, regardless of the actual viewing distance.

Depending on Options.FogBehavior, there are two options how this command affects fog from this point on. In block-wise mode, the current fog blends from the beginning of this block to the new settings at the end of this block. The new setting is kept for following blocks. This is the default behavior. In interpolation mode, each Track.Fog command defines a control point for fog, where all of the settings (distances and colors) are interpolated linearly between the control points.

This command can only be used at the beginning of a block.


Track.Brightness Value
Value: A non-negative integer within the range from 0 to 255. The default value is 255.

This command marks a point which affects the brightness in the cab. Value is measured from 0 (dark) to 255 (light), and is linearly interpolated between successive Track.Brightness commands for any given point on the track. This command should be used for tunnels, bridges, station roofs, or anything else that would affect the brightness as perceived inside the cab.

Example:
With Track
1200, .Brightness 255 ,; before the bridge starts
1205, .Brightness 128 ,; directly under the bridge here
1210, .Brightness 255 ,; as soon as the bridge ends

Track.Marker FileName; Distance
FileName: The file name for the marker image, relative to the Object folder.
Distance: A non-zero floating-point number indicating the length for which the marker image is displayed, by default measured in meters.

▸ Behavior for Distance:

negative value: The marker image starts to display at the Track.Marker command, and ends -Distance meters after the Track.Marker command.
positive value: The marker image starts to display Distance meters before the Track.Marker command, and ends at the Track.Marker command.

This command shows a so-called marker image, which is displayed in the top-right corner of the screen. You can use these images for advisory or informational purposes. The RGB color of 64,64,64 inside the image is made transparent.


Track.Marker FileName.xml

A Track.Marker command, linking to a single XML file is also supported. These allow more control over markers than is available in the routefile commands.

These are fully described on the the XML Markers page…


Track.TextMarker Text; Distance; FontColor
Text: The marker text to display. (No special characters supported).
Distance: A non-zero floating-point number indicating the length for which the text is displayed, by default measured in meters.
FontColor: The font color for this marker text

▸ Behavior for Distance:

negative value: The marker image starts to display at the Track.Marker command, and ends -Distance meters after the Track.Marker command.
positive value: The marker image starts to display Distance meters before the Track.Marker command, and ends at the Track.Marker command.

▸ Available options for FontColor:

1: Black.
2: Gray.
3: White.
4: Red.
5: Orange.
6: Green.
7: Blue.
8: Magenta.

This command creates a simple textual marker, which is added to the list of messages in the upper left-hand corner of the screen.


Track.PointOfInterest RailIndex; X; Y; Yaw; Pitch; Roll; Text
Track.POI RailIndex; X; Y; Yaw; Pitch; Roll; Text
RailIndex: A non-negative integer representing the rail for the point of interest.
X: A floating-point number representing the horizontal offset from the rail, by default measured in meters. Negative values indicate left, positive ones right.
Y: A floating-point number representing the vertical offset from the rail, by default measured in meters. Negative values indicate below, positive ones above.
Yaw: The angle in degrees by which the view is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the view is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the view is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.
Text: A textual representation of the point of interest.

This command creates a point of interest which the user can jump to by pressing the CAMERA_POI_PREVIOUS (NUM 1) or CAMERA_POI_NEXT (NUM 7) keys. The camera will be placed at the specified location with the specified orientation. If Text is non-empty, a message will appear briefly showing the text.


Track.PreTrain Time
Time: The time at which the pretrain is at this track position.

This commands creates a position-time-association for an invisible preceding train in order to influence signalling. Contrary to a real preceding train as created by Route.RunInterval, the invisible preceding train created by Track.PreTrain is a way of scripting where the invisible preceding train is at any given time. The position-time-associations must be in increasing order, that is, at a later track position, the associated time must also be later. Before the first scripted time, the invisible preceding train resides at the first scripted position. In-between the first and last scripted time, the invisible preceding train moves (linearly) between the scripted points. After the last scripted time, the invisible preceding train is removed and thus clears signalling.


Track.Announce FileName; Speed
FileName: The file name for the sound to play, relative to the Sound folder.
Speed: The reference speed in km/h for speed-dependant sounds, or 0 to play the sound speed-independently. The default value is 0.

This command plays an announcement or other kind of sound in the cab once the player’s train crosses the point where this command is used. If Speed is set to 0 (default), the sound is played as-is. If a Speed is given though, the sound plays at is original pitch at the specified speed, and is pitch-modulated proportionally for other speeds, useful for custom flange sounds, pointwork sounds, etc.


Track.Doppler FileName; X; Y
FileName: The file name for the sound to play, relative to the Sound folder.
X: A floating-point number representing the horizontal offset from rail 0, by default measured in meters. Negative values indicate left, positive ones right.
Y: A floating-point number representing the vertical offset from rail 0, by default measured in meters. Negative values indicate below, positive ones above.

This command places an environmental sound effect at the specified location. The sound will play in a loop for the duration of the simulation and employs the doppler effect. (Note: All sounds in openBVE employ the doppler effect.)


Track.Buffer

This command places a bumper. The train can collide with the bumper in both the forward and backward directions. Place this command at the beginning and the end of the route. An object is not automatically created, so use Track.FreeObj to create a visual representation of the bumper if necessary.


Track.Destination Type; BeaconStructureIndex; NextDestination; PreviousDestination; TriggerOnce; X; Y; Yaw; Pitch; Roll
Type: Defines the types of trains for which this destination setter applies: -1 for AI trains only, 0 for all trains and 1 for the player train only.
BeaconStructureIndex: A non-negative integer representing the object to be placed as defined via Structure.Beacon, or -1 to not place any object.
NextDestination: An integer representing the destination value set when passing over this beacon in a forwards direction, or -1 to disable.
PreviousDestination: An integer representing the destination value set when passing over this beacon in a reverse direction, or -1 to disable.
TriggerOnce: If set to 0, this beacon will be triggered by all valid trains which pass over it. If set to 1, it will be triggered by the first valid train only.
X: The X-coordinate at which to place the object, by default measured in meters. The default value is 0.
Y: The Y-coordinate at which to place the object, by default measured in meters. The default value is 0.
Yaw: The angle in degrees by which the object is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the object is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the object is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.

This command places a special beacon, which sets the destination variable, available for use by plugins and animated objects. The object must have been loaded via Structure.Beacon(BeaconStructureIndex) prior to using this command.


Track.HornBlow Type; BeaconStructureIndex; TriggerOnce; X; Y; Yaw; Pitch; Roll
Type: Defines the type of horn to play: 0 for the primary horn, 1 for the secondary horn and 2 for the music horn.
BeaconStructureIndex: A non-negative integer representing the object to be placed as defined via Structure.Beacon, or -1 to not place any object.
TriggerOnce: If set to 0, this beacon will be triggered by all valid trains which pass over it. If set to 1, it will be triggered by the first valid train only.
X: The X-coordinate at which to place the object, by default measured in meters. The default value is 0.
Y: The Y-coordinate at which to place the object, by default measured in meters. The default value is 0.
Yaw: The angle in degrees by which the object is rotated in the XZ-plane in clock-wise order when viewed from above. The default value is 0.
Pitch: The angle in degrees by which the object is rotated in the YZ-plane in clock-wise order when viewed from the left. The default value is 0.
Roll: The angle in degrees by which the object is rotated in the XY-plane in clock-wise order when viewed from behind. The default value is 0.

This command places a special beacon, which commands an AI driver to play the horn. Both an AI controlled player train and pure AI trains will trigger this beacon, unless TriggerOnce is set. The object must have been loaded via Structure.Beacon(BeaconStructureIndex) prior to using this command.


Track.DynamicLight DynamicLightIndex
DynamicLightIndex: A non-negative integer, representing the Dynamic Lighting set to be used from this point onwards, as defined by Structure.DynamicLight

This command may be used as an alternative to the Route.AmbientLight , Route.DirectionalLight and Route.LightDirection commands.

It allows the lighting to be varied using a time-based model, and is described fully on the following page:

Dynamic Lighting


Track.AmbientLight RedValue; GreenValue; BlueValue
RedValue: An integer ranging from 0 to 255 representing the red component of the ambient light. The default value is 160.
GreenValue: An integer ranging from 0 to 255 representing the green component of the ambient light. The default value is 160.
BlueValue: An integer ranging from 0 to 255 representing the blue component of the ambient light. The default value is 160.

This command defines the ambient light color to be used from this point onwards. All polygons in the scene are illuminated by the ambient light regardless of the light direction.


Track.DirectionalLight RedValue; GreenValue; BlueValue
RedValue: An integer ranging from 0 to 255 representing the red component of the directional light. The default value is 160.
GreenValue: An integer ranging from 0 to 255 representing the green component of the directional light. The default value is 160.
BlueValue: An integer ranging from 0 to 255 representing the blue component of the directional light. The default value is 160.

This command defines the directional light to be used from this point onwards. The polygons in the scene are only fully illuminated by the directional light if the light direction points at the front faces. If pointing at back faces, no light is contributed. Route.LightDirection should be set to specify the light direction.


Track.LightDirection Theta; Phi
Theta: A floating-point number representing the angle in degrees which controls the pitch of the light direction. The default value is 60.
Phi: A floating-point number representing the angle in degrees which controls the planar rotation of the light direction. The default value is about -26.57.

This command defines the light direction from this point onwards. This is the direction the light shines at, meaning the opposite direction the sun is located at. First, Theta determines the pitch. A value of 90 represents a downward direction, while a value of -90 represents an upward direction. With those extremes, the value of Phi is irrelevant. A value of 0 for Theta represents a forward direction originating at the horizon behind. Once the pitch is defined by Theta, Phi determines the rotation in the plane. A value of 0 does not rotate, a value of 90 rotates the direction to the right and a value of -90 rotates to the left. A backward direction can be both obtained by setting Theta and Phi to 180 and 0 or to 0 and 180, respectively. Values in-between allow for more precise control of the exact light direction.

The direction of the light is relative to the initial direction at the zero-point of the route (e.g Track position 0), not the current position.

illustration_light_direction

Converting a spherical direction (theta,phi) into a cartesian direction (x,y,z):
ƒ x = cos(theta) * sin(phi)
y = -sin(theta)
z = cos(theta) * cos(phi)
Converting a cartesian direction (x,y,z) into a spherical direction (theta,phi) for y²≠1:
ƒ theta = -arctan(y/sqrt(x2+z2))
phi = arctan(z,x)
Converting a cartesian direction (x,y,z) into a spherical direction (theta,phi) for y²=1:
ƒ theta = -y * pi/2
phi = 0

In the formulas above, cos(x) represents the cosine, sin(x) the sine, arctan(x) the inverse tangent, arctan(x,y) the two-argument inverse tangent and sqrt(x) the square root. The formulas can be used to convert between spherical and cartesian coordinates if working with either one seems more intuitive than working with the other one. The formulas also serve as the official documentation on how the light direction is mathematically defined (using radians for the trigonometric functions).