Developer Guide

Developer Guide

Source checkout

git clone https://github.com/noteMASTER11/TaxiDriverReloaded.git
cd TaxiDriverReloaded

The repository contains source only. dist/taxidriver.zip is intentionally distributed through GitHub Releases rather than committed.

Development installation

BeamNG supports unpacked mods, but never enable the unpacked source and packaged taxidriver.zip simultaneously.

A development tree must preserve these roots:

lua/
ui/
mod_info/
CREDITS.txt

The release ZIP must contain these paths directly at archive root. Do not wrap them inside a taxidriver/ folder, and use / path separators inside the ZIP.

Version locations

Update all four values for a release:

1. modVersion in lua/ge/extensions/taxiDriver/taxiDriver.lua;
2. version in ui/modules/apps/TaxiDriverHUD/app.json;
3. version in mod_info/TaxiDriver/info.json;
4. version in package.json.

Also update externalUiRevision and the matching ?v= values in the external bootstrap and UI imports whenever browser-cached assets change.

The archive filename remains exactly taxidriver.zip.

Configuration changes

Balance and timing constants belong in config.lua. Keep pure logic in focused modules when possible. Avoid adding more top-level locals to taxiDriver.lua because the main chunk is close to LuaJIT's 200-local limit.

Changing a difficulty preset mutates the active balanceConfig fields. Every preset must therefore define every field that can differ between presets; otherwise a value from the previously selected preset can remain active.

Adding an order property

1. Create it in createOffer().
2. Preserve it when the offer becomes trip.
3. Expose it from buildHudOffer() or buildHudState().
4. Add a default in $scope.state if the UI reads it before the first backend snapshot.
5. Add localized UI labels to all eight locales.
6. Test dispatcher, floating next offer, and queued-offer transition.

Adding a phase

1. Add the ID to config.lua phases and diagnostic labels.
2. Add localized phase_* keys to all locales.
3. Decide whether it logically contains a passenger.
4. Decide whether penalties, mood, rush timer, and forced stop may advance.
5. Decide whether the native minimap can render.
6. Add a dedicated ng-if screen or include it in an existing screen.
7. Cover transition, reset, stop-mode, mission-end, and serialization cleanup.

Adding a localization

1. Add the language to supportedLanguages in config.lua.
2. Add it to the UI languages array.
3. Add a complete dictionary to locales.json with the exact English key set.
4. Verify placeholders and plural-neutral phrasing.

Adding a sound

1. Put the renamed asset in ui/modules/apps/TaxiDriverHUD/sounds/.
2. Register a pool in appAudio with an appropriate base volume and size.
3. Call playAppSound(poolId) rather than invoking Audio directly.
4. Confirm Silent Mode, AudioUiVol, and the TaxiDriver appVolume multiplier all affect it.
5. Include the pool in the random sound-test list when appropriate.

Static validation

Recommended pre-release checks:

• Parse every GE Lua module as Lua 5.1/LuaJIT syntax.
• Keep the main extension below 200 top-level locals.
• Parse app.js as JavaScript.
• Parse app.html and app.css.
• Parse locales.json and compare every locale's keys with English.
• Run git diff --check.
• Inspect archive entries for missing files, extra root folders, or backslashes.
• Verify the installed archive hash matches the release artifact.
• Run the Realistic Mode × Random Events combinatorics across regular, rush, multi-stop, and delivery work.
• Exercise all order-sorting buttons because native CEF selectors are intentionally not used in the scaled UI.

Runtime smoke test

At minimum test:

1. normal mode start and 10–12 offer fill;
2. regular, rush, multi-stop, and cargo-delivery acceptance;
3. pickup/door/boarding transition;
4. speeding, collision, and harsh-manoeuvre event logging;
5. mood increase and decrease animation;
6. floating-offer expiry and queue acceptance;
7. reset with queued offer;
8. pause during every visible countdown;
9. Realistic Mode with combustion and electric vehicles;
10. station detour with and without a passenger;
11. paid refueling, interruption, completion, and route restoration;
12. cargo mass application, collision damage, completion, cancellation, and reset cleanup;
13. full-phone and minimized-dashboard map geometry;
14. vehicle switch, level reload, odometer continuity, and native selector opening;
15. Magic Fuel, quick presets, projections, and active-order sufficiency;
16. settings/profile/progress/vehicle-history reload after restarting the session.

Release publication

1. Commit and push source changes.
2. Build dist/taxidriver.zip from the committed source.
3. Create a version tag such as v2.25.0 on the release commit.
4. Upload the asset as taxidriver.zip without version text in the filename.
5. Verify metadata version, asset digest, and download URL.
6. Mark Beta builds as GitHub prereleases and use a SemVer prerelease tag such as v3.0.0-beta.