#Introduction

Basic Information

• Mod Name: MTR Fare Pro
• Version: 0.1-beta
• Author: hhd
• Supported Game Versions: Minecraft 1.18.2, 1.19.2, 1.19.4, 1.20.1, 1.20.4 (Fabric)
• Runtime Requirements: Mandatory installation on both client and server
• Compatible MTR Versions: 4.0.3 ~ 4.0.5
• Dependency Mods: Fabric Loader ≥ 0.15.11, Fabric API, Minecraft Transit Railway (MTR) 4.0.3 ~ 4.0.5, Metropolis 0.4.3+ (Minecraft 1.20.1 only)

Feature Overview

MTR Fare Pro is an add-on mod for Minecraft Transit Railway (MTR). It implements a more flexible and realistic railway fare calculation system within the game. Four independent billing modes are available, which server administrators can freely switch between via the configuration file according to their needs. The mod automatically calculates and deducts corresponding fares when players enter and exit stations. Additionally, it supports the Metropolis ticketing system (Minecraft 1.20.1 only).

Four Fare Calculation Modes

1. ZONE

• Mechanism: Adopts MTR’s native zone billing logic without any modifications.
• Calculation Rule: Follows the built-in zone division of MTR; fares are determined based on the zones of the entry and exit stations.
• Features: Fully consistent with vanilla MTR mechanics with no extra computational overhead. Ideal for linear metro networks and players who wish to retain MTR’s default fare experience.

2. DISTANCE

• Mechanism: Calculates fares based on the straight-line geographic distance between entry and exit stations.
• Calculation Rule: Reads each station’s central coordinates to compute the 3D Euclidean distance between two stations. The fare is calculated as Distance (km) × Unit Fare, with a minimum fare of 1 currency unit.
• Formula: fare = max(1, round(√((x₂-x₁)² + (y₂-y₁)² + (z₂-z₁)²) / 1000 × unit_fare))
• Features: Simple computation independent of track networks. A fare can still be generated even if no tracks connect two stations. However, straight-line distance may deviate from the actual travel route length.

3. PATH [Default Mode]

• Mechanism: Computes fares using the shortest physical travel path across the railway network.
• Calculation Rule: The server constructs a weighted graph using all tracks and stations (edge weights equal to straight-line distances between adjacent stations). The Dijkstra algorithm calculates the shortest path distance between any two stations, then computes fares via Route Distance (km) × Unit Fare.
• Formula: fare = max(1, round(Shortest Path Distance (km) × unit_fare))
• Features: Delivers the most authentic fare experience without manual zone setup, reflecting the actual distance players travel. Path data is cached locally and synchronized over the network to eliminate repeated calculations. Optimized for large, non-linear metro networks. If no track connection exists between two stations, the DISTANCE mode fare will be applied instead.

4. PATHAREA

• Mechanism: Hybrid billing combining shortest travel path and zone divisions.
• Calculation Rule: Traverses every station along the shortest route, sums the absolute differences of zone IDs between consecutive stations, then multiplies the total by the unit fare.
• Formula: fare = max(1, Σ|zone(i+1) - zone(i)| × unit_fare)
• Features: Total fare rises with the cumulative zone difference across the journey. Perfect for customizing pricing for individual track segments, balancing realistic travel routes with personalized fare settings. If no track connection exists between two stations, the DISTANCE mode fare will be applied instead.

Configuration File

Config File Path: config/mtr-fare-pro.json

Default Content:

{
  "fare_mode": "PATH",
  "unit_fare": 1
}

Field	Description	Valid Values
fare_mode	Fare calculation mode	ZONE, DISTANCE, PATH, PATHAREA
unit_fare	Base fare rate (currency per km / per segment)	Integer ≥ 1

Network Synchronization

The server automatically synchronizes configuration, station coordinates and path graph data to all connected clients; no separate client-side configuration is required. All in-game fare rules follow the server’s configuration when playing on a multiplayer server.

Additional Features

• Path Caching: Calculation results are automatically saved to config/MTR-Fare-Pro-path-cache.json to avoid recalculation after server restarts. Run the command /mtrfare reload to refresh fares after modifying zones or station layouts.
• Automatic Station Coordinate Fetching: Station central coordinates are extracted directly from MTR’s Simulator or MinecraftClientData with no manual setup required.
• Gate Compatibility: Automatically records entry station data when passing through ticket gates, enabling accurate billing upon exit.
• MTR Ticketing System Compatibility: Uses Mixin injection to hook into MTR’s TicketSystem, overriding native fare logic at station exit. For Minecraft 1.20.1, this mod is also fully compatible with the Metropolis ticketing system.

模组介绍

基本信息

• 模组名称：MTR Fare Pro
• 版本：0.1-beta
• 作者：hhd
• 适用版本：Minecraft 1.18.2, 1.19.2, 1.19.4, 1.20.1 ,1.20.4（Fabric）
• 运行环境：客户端需装，服务端需装
• 适配 MTR 版本：4.0.3 ~ 4.0.5
• 前置模组：Fabric Loader ≥ 0.15.11、Fabric API、Minecraft Transit Railway (MTR) 4.0.3 ~ 4.0.5、Metropolis0.4.3+(仅Minecraft1.20.1)

功能说明

MTR Fare Pro 是一个 MTR（Minecraft Transit Railway）附属模组，为游戏提供了更灵活、更真实的铁路计费系统。模组支持四种独立的计费模式，管理员可根据需求在配置文件中自由切换。玩家进出站时，模组会自动计算并扣除相应车费。与此同时，模组也适配了Metropolis的收费系统(仅Minecraft1.20.1）。

四种计费模式

1. ZONE

• 原理：使用 MTR 原生的区间计费逻辑，不进行任何修改。
• 计费方式：按 MTR 自带的 zone（区域）划分，根据进出站所在区域计算费用。
• 特点：兼容原版 MTR 行为，无额外计算开销。适合线性地铁网络和希望保持 MTR 默认计费体验的玩家。

2. DISTANCE

• 原理：根据进出站的地理直线距离计算车费。
• 计费方式：读取车站的中心坐标，计算进出站之间的三维欧几里得距离，然后按 距离(km) × 单位票价 计算费用，最低为 1 元。
• 公式：fare = max(1, round(√((x₂-x₁)² + (y₂-y₁)² + (z₂-z₁)²) / 1000 × unit_fare))
• 特点：计算简单，不依赖路径网络。即使两站之间没有线路连接，也能给出费用。但直线距离可能与实际乘车距离有偏差。

3. PATH【默认模式】

• 原理：基于实际铁路网络的最短路径距离计算车费。
• 计费方式：模组会在服务端根据所有线路和车站构建加权图（边权为相邻站之间的直线距离），通过 Dijkstra 算法计算任意两站之间的最短路径距离，然后按 路径距离(km) × 单位票价 计算费用。
• 公式：fare = max(1, round(最短路径距离(km) × unit_fare))
• 特点：玩家无需自行设置收费区，就能享受的最真实的计费方式，反映了玩家实际乘车的路径长度。路径数据会缓存到本地文件和网络同步，避免重复计算。适用于大型非线性地铁网络。若两站之间没有线路连接，将会使用DISTANCE模式计算的票价收费。

4. PATHAREA

• 原理：结合最短路径和收费区域的混合计费方式。
• 计费方式：沿最短路径遍历经过的每个车站，统计相邻站之间区域编号（zone）的差值绝对值之和，然后乘以单位票价。
• 公式：fare = max(1, Σ|zone(i+1) - zone(i)| × unit_fare)
• 特点：路线上途径车站的收费区差值总和越大，费用越高。适合想要自定义任意轨行区间价格的情况，兼顾了路径真实性和个性化价格设置。若两站之间没有线路连接，将会使用DISTANCE模式计算的票价收费。

配置文件

配置文件路径：config/mtr-fare-pro.json

默认内容：

{
  "fare_mode": "PATH",
  "unit_fare": 1
}

字段	说明	可选值
fare_mode	计费模式	ZONE、DISTANCE、PATH、PATHAREA
unit_fare	单位票价（元/km 或元/次）	≥ 1 的整数

网络同步

服务端会自动将配置、车站位置、路径图数据同步给加入游戏的客户端，无需客户端单独配置。在服务器中游玩时，以服务器的配置内容为准。

其他特性

• 路径缓存：计算结果自动保存到 config/MTR-Fare-Pro-path-cache.json，重启后无需重新计算。若变更了收费区或者站点设置，需要输入 /mtrfare reload 指令更新票价
• 车站坐标：自动从 MTR 的 Simulator 或 MinecraftClientData 中提取车站中心坐标，无需手动配置。
• 兼容闸机：在进出闸机时自动记录入口站信息，出站时正确计费。
• 兼容 MTR 票务系统：通过 Mixin 注入 MTR 的 TicketSystem，在出站时拦截并替换计费逻辑。在Minecraft1.20.1版本，本模组也兼容 Metropolis的票务系统。