[PATCH] Vehicle-specific speed bonus parameters for pakset balancing

[maxim13]

Hello,

I would like to propose a new optional mechanism that gives pakset authors more precise control over vehicle revenue balancing.

Pull request: [simutrans/simutrans#15](https://github.com/simutrans/simutrans/pull/15)

Direct patch: [pull request patch](https://github.com/simutrans/simutrans/pull/15.patch)

## Motivation

The current speed bonus uses a common timeline reference speed for all vehicles of the same waytype. This makes it difficult for a pakset author to balance vehicles intended for different roles. For example, an urban bus and an intercity coach use the same road reference speed even though they are expected to operate under very different conditions.

This is particularly visible in pak128 after the year 2000. Roads in large cities commonly have a speed limit of about 50 km/h, while the timeline reference speed continues to rise. As a result, buses, trams, trolleybuses and urban mail vehicles can run nearly fully loaded and still receive too little revenue to cover their operating costs.

This creates an undesirable gameplay incentive: players are encouraged to replace ordinary surface transport with high-speed tunnels or elevated routes simply to make urban transport economically viable. Such infrastructure should remain a valid choice, but it should not be practically mandatory.

Changing the reference speed globally for all road or track vehicles would be too coarse because it would also affect intercity and high-speed vehicles. The proposed mechanism lets the pakset author balance each vehicle according to its intended role.

## Proposed DAT parameters

The patch adds two optional parameters to vehicle definitions:

```text
speed_bonus_reference_percent=100
speed_bonus_max_percent=0
```

`speed_bonus_reference_percent` defines the vehicle's fare reference speed as a percentage of the current timeline reference speed for its waytype. The default value `100` leaves the existing reference speed unchanged.

`speed_bonus_max_percent` defines an upper limit on the payment factor produced by the speed bonus calculation. The default value `0` means that there is no vehicle-specific cap. The existing global lower limit, `bonus_basefactor`, continues to apply as before.

For example, an urban bus could use:

```text
speed_bonus_reference_percent=50
speed_bonus_max_percent=70
```

Its fare would then be calculated against half of the normal road reference speed for the current period. The second value prevents the vehicle from receiving an unintended high-speed payment if it is used on a much faster route.

The engine does not assign these values automatically. Selecting appropriate values remains the responsibility of the pakset author.

## Multi-vehicle and articulated convoys

The parameters belong to the vehicle that actually carries the goods, passengers or mail. Revenue for the contents of each vehicle is calculated using that vehicle's own descriptor.

Therefore:

- a locomotive carrying no cargo does not affect the fare of its carriages;
- different passenger or freight cars in the same convoy may use different values;
- one section of an articulated vehicle does not impose its values on the other sections;
- the total revenue of a mixed convoy is the sum of the results calculated for its individual carrying vehicles.

## Backward compatibility

The default values `100/0` preserve the previous behaviour:

- vehicles without the new parameters use the existing revenue calculation;
- existing version 13 vehicle pak objects continue to load and receive the default values;
- existing `speedbonus.tab` values and `bonus_basefactor` keep their current semantics;
- existing saved games require no migration because these values belong to vehicle descriptors in the pakset, not to vehicle instances in the savegame.

MakeObj writes vehicle descriptor version 14 to store the two new `uint16` values. Simutrans reads both versions 13 and 14. As usual for a new pak object version, version 14 vehicle objects produced by the new MakeObj are not expected to work with older Simutrans versions.

## User interface and scripting

For vehicles with non-default values, the depot, vehicle list and convoy details display:

```text
Fare reference speed: 50% of era speed
Maximum speed payment: 70%
```

These lines are hidden for vehicles using `100/0`, so existing paksets do not gain additional UI clutter.

The values are also exposed through the Squirrel vehicle descriptor API. The existing legacy revenue API remains available, while a vehicle-aware revenue calculation can be requested when a vehicle descriptor is available.

The patch includes documentation of the new DAT parameters.

## Validation

- Simutrans and MakeObj build successfully on macOS.
- The branch is rebased on the current master.
- All 284 automated Simutrans Standard scenario tests pass.
- The automated integration test builds a version 14 vehicle object with `50/70`, verifies increased revenue at an urban speed and verifies the payment cap at high speed.
- A default-value test verifies that `100/0` produces the legacy revenue result.

I also performed a local pak128 gameplay experiment using buses with equal capacity and operating costs on a well-loaded route limited to 50 km/h:

- the vehicle with the legacy calculation earned approximately 100 currency units per month and was deeply unprofitable;
- the vehicle using `50/70` earned more than 400 currency units per month and became profitable;
- an articulated bus with `50/70` on one 25-passenger section and default values on another 25-passenger section produced an intermediate result and remained slightly unprofitable.

The articulated vehicle result provides an additional practical check that each carrying section uses its own parameters.

These experimental values are not proposed as final pak128 balancing values. They were used only to validate the mechanism and the direction of the revenue change. Actual pakset balancing would be discussed separately after the engine feature is accepted.

## Scope

This patch provides a balancing mechanism only. It does not:

- rebalance any existing pakset;
- automatically classify vehicles as urban, intercity or high-speed;
- change existing vehicle speed, capacity or operating-cost values;
- replace the existing speed bonus system;
- require existing vehicle DAT files to define the new parameters;
- add a translation for only one language.

I would appreciate feedback on the overall concept, parameter names, default values, user-interface wording and implementation.

[prissi]

My personal commet is that there are already too many parameters for balancing. Furthermore, pak128 is not very well balanced at all, teh profitability of vehciles vary largely.

And not only pak128: Sue to its age, several paksets are not very well balanced for later starting years (>1990), lacking slow but cheap city buses and similar innercity commuter vehicles with low top speed and short loading times but high capacity.

Having vehicles with no speed bonus will be very difficult to find in the depot. Instead having a low top speed and low running city bus is very obvious. (Like the double decker in pak64) Moreover, the only thing stopping to use such a vehicle for long-distance transport would be a low top speed, which means that one can anyway lower the top speed so that 50 kmh city buses are profitable.

Finally, this patch still needs the pakset rebalancing, which is the way more difficult task. So in order to keep the pakset maintenance simplier, I my personl impression is that this patch may be something for extended, but not for standard.

[maxim13]

  I understand the concern about adding more parameters and making balancing
  more complicated. However, in my opinion, the existing tools are not
  sufficient to balance fast intercity transport and slow urban transport at the
  same time.

  For example, if the speed limit inside cities is 50 km/h while the era's
  reference speed is around 100 km/h, a city bus receives close to the minimum
  fare for carrying passengers. In theory, this could be compensated for by
  making a very cheap bus with a top speed of 50 km/h. However, its power,
  purchase price, and running costs would then need to be significantly out of
  line with those of other vehicles. Even then, the low revenue per passenger-
  kilometre might still be insufficient to cover the maintenance costs of even
  basic stops.

  As a result, it would still be more profitable for the player to build high-
  speed tunnels or other fast infrastructure directly beneath the city so that
  passengers pay a reasonable fare. In other words, the current system does not
  merely encourage fast transport—it makes it difficult to create a natural and
  economically viable role for urban transport.

  I agree that the main and much more difficult task is a complete rebalance of
  pak128, and I would like to undertake it. I see this patch as necessary
  preparation for such a rebalance, because it provides a tool that is currently
  missing for properly balancing urban transport.

  At the same time, I believe that the proposed mechanic makes sense in its own
  right and could be useful not only for pak128, but also for other paksets that
  need to support both fast intercity and slow urban transport. Therefore, I
  think it is reasonable to evaluate this patch not only in the context of
  pak128's current balance, but also by whether it addresses a problem that is
  extremely difficult to solve with the existing tools.