1.  Introduction
2.  Documentation
3.  Non-Free content (in GPL sense)
4.  Track editor
5.  Linux Installation from Source
6.  Windows Installation from Source (Release version)
6.1 Windows Installation from Source, additional notes
7.  Windows Installation from Source (Debug version)
8.  Testing
9.  Getting Help
10. Running under Valgrind with Linux
11. Changes
12. TODO/Notes


1. Introduction
---------------
First a big welcome, I hope you will enjoy your ride:-)

This is an all in one package of TORCS. Be aware that some included
artwork has non free (in the GPL sense) licenses, you will find a "readme.txt"
in those directories. The rest is either licensed under the GPL or the Free
Art License. If you want to create cars or advanced tracks using the accc tool,
you will require stripe from http://www.cs.sunysb.edu/~stripe.

If you use TORCS for research/projects you can have a look into the FAQ for
citation guidelines.

Kind regards

Bernhard


2. Documentation
----------------
You can find a variety of links on www.torcs.org (video tutorials about content
creation/usage, written documentation like the robot tutorial, etc.). The TORCS
API and architecture documentation can be generated with Doxygen 1.8, run
"make doc", the result can be found in doc/manual/api, point to index.html.


3. Non-Free content (in GPL sense)
----------------------------------
Here the list with the directories containing non free content, look at the
readme.txt for details:
- data/cars/models/pw-*
- data/cars/models/kc-*


4. Track editor
---------------
The track editor is not included in this distribution, you can get it from
http://sourceforge.net/projects/trackeditor. The sources are included in the jars.


5. Linux Installation from Source
---------------------------------
- Requires plib 1.8.5, FreeGLUT or GLUT, be aware to compile plib with -fPIC
  on AMD64 if you run a 64 bit version of Linux. Be aware that maybe just
  1.8.5 works.
- Untar the archive
- cd into the torcs-1.3.9 directory
- ./configure (use --help for showing the options, of interest might be
  --enable-debug and --disable-xrandr).
- make
- make install
- make datainstall
- start with "torcs"

Command line arguments:
* -l list the dynamically linked libraries
* -d run under gdb and print stack trace on exit, makes most sense when compiled
     with --enable-debug
* -g run under Valgrind (requires a debug build for useful results)
* -e display the commands to issue when you want to run under gdb
* -s disable multitexturing, important for older graphics cards
* -m use X mouse cursor and do not hide it during races
* -r pathtoraceconfigfile, run race from command line only, for testing and AI
     training, see FAQ for details
* -k (keep) suppress calls to dlclose to keep modules loaded (for Valgrind runs,
     to avoid "??" in the call stack)

Using vscode in Linux:
- Install vscode, usually your distro provides a package
- Install bear, usually your distro provides a package
- In vscode install the extension pack "C/C++ Extension Pack" from franneck94
- Run in the torcs source code directory the command "bear -- make" to generate
  the required files for vscode c++ (e.g. compile_commands.json)


6. Windows Installation from Source (Release version)
-----------------------------------------------------
- hint: you can have a release and a debug build side by side, the release
  version goes to "runtime" and the debug to "runtimed".
- requires Visual Studio 2022 (VS 2022).
- untar the archive into a path without whitespaces and special characters.
- cd into the torcs-1.3.9 directory
- run setup_win32.bat
- run setup_win32-data-from-CVS.bat
- select the TORCS solution (TORCS.sln), select the x64-Release version.
- compile project (0 build warnings)
- cd into the "runtime" directory.
- run "wtorcs.exe"

Command line arguments:
* -s disable multitexturing, important for older graphics cards
* -r pathtoraceconfigfile, run race from command line only, for testing and AI
     training, see FAQ for details 


6.1. Windows, generate Documentation from Source
------------------------------------------------
To build the HTML documentation on Windows, install a current Doxygen release
1.14.0 (https://www.doxygen.nl/) and Graphviz (https://graphviz.org/), and add
their bin directories to PATH so that "doxygen --version" and "dot -V" work in a
new PowerShell or Command Prompt window. From the source directory containing
TORCS.sln, run "doxygen src/doc/torcsdoc.conf". When it finishes (can take a
while), open doc/manual/api/index.html in a browser.


7. Windows Installation from Source (Debug version)
---------------------------------------------------
- hint: you can have a release and a debug build side by side, the release
  version goes to "runtime" and the debug to "runtimed".
- requires Visual Studio 2022 (VS 2022).
- untar the archive into a path without whitespaces and special characters.
- cd into the torcs-1.3.9 directory
- run setup_win32_debug.bat
- run setup_win32-data-from-CVS_debug.bat
- select the TORCS solution (TORCS.sln), select the x64-Debug version
- compile project (0 build warnings)
- cd into the "runtimed" directory.

Command line arguments:
* -s disable multitexturing, important for older graphics cards
* -r pathtoraceconfigfile, run race from command line only, for testing and AI
     training, see FAQ for details 


8. Testing
----------
If you find problems which should be already fixed or new ones please report them
to the torcs-users mailing list.


9. Getting Help
---------------
During the game press F1. For more in depth information visit www.torcs.org,
you find there a lot of information, look at the documentation section on
the left, have as well a look into the list of howto's. If you are stuck
have a look into the FAQ to learn how and where to report a problem.


10. Running under Valgrind with Linux
------------------------------------
First you need to build a debug version of TORCS, make sure that the CFLAGS,
CPPFLAGS and CXXFLAGS environment variables are empty (usually they are). Then
run "make distclean", then the configure script with the option --enable-debug
and all other options which you require, build and install as usual.

To find memory leaks run first (Valgrind must be available in the path):
./torcs -g

You will find the logfile valgrind.log in the .torcs directory. If you have
"??" in the call stack, you can run TORCS with the -k option to avoid unloading
the modules:
./torcs -g -k

You should use -k just to investigate the "??" in the call stacks, because the
suppression of dlclose can hide problems related with module release and cause
problems because modules are just recycled but not reloaded.

Of course you can use this with the console (command line) mode as well, e.g.:
./torcs -g -r ~/.torcs/config/raceman/champ.xml
./torcs -g -k -r ~/.torcs/config/raceman/dtmrace.xml

Some additional notes:
- Valgrind (version 3.6.1) reports on systems with the ATI flgrx OpenGL driver (8.961)
  lots of leaks, according AMD Valgrind misinterprets memory blocks handed over to the
  kernel. When I wrote suppressions the flgrx driver hung the X Server up, conclusion:
  Give it a try (maybe another Valgrind/driver/kernel combination does/will do better),
  but if you run in the mentioned problems, just use the TORCS command line mode or
  install temporarily the Open Source ATI driver alternative, maybe this does do better
  (not tested, send me a report;-) )
- You can edit the "torcs" script and add "--leak-check=full --show-reachable=yes"
  to see what is still reachable at exit. This is useful to reduce the amount of cached
  xml file handles or hunt down missing releases of handles (they are not reported
  usually because they are reachable via the cache), beware, it is perfectly
  fine that the GUI and some handles are held permanent.


11. Changes
-----------

Changes since 1.3.9
-------------------
- Added quiet mode trackgen to avoid long log files (Bernhard).
- MAX_NODES increased in easymesh.cpp, from 15000 to 150000 (Bernhard).
- Added track generation and helper scripts, see tracktools, work in progress. E.g.
  fetching track data from OpenStreetMap, autoclosing track loop, etc. (Bernhard).
- Adopted skills, readme and checklists to enable small llms to help generate
  tracks (Bernhard).
- Skip trackgen window for calculations (-z option) (Bernhard).
- Improved tracktools script to add pits (Bernhard).
- Added tracktools scripts for elevation and banking (Bernhard).
- GUI library refactoring to get rid of "void *" and  related casts (Bernhard).
- Implemented fallback behaviour if the selected track in the racemanager got
  deleted, useful when working on tracks (Bernhard).
- Fixed track selection map previews not recovering after visiting a track without
  a PNG map (Bernhard).  
- Added mouseover warning message for disabled buttons (Bernhard).
- Prevented starting races with an empty driver selection and added menu warnings
  for selecting at least one driver (Bernhard).
- Little refactoring of RtTrackGlobal2Local, unified left and right case, added
  unit tests (Bernhard).
- Reverted experimental penalty ranking back to more FIA alike penalty handling
  (#19, reported by David Bears) (Bernhard).
- Apply pit speed limit if car is going in reverse (Athozus).
- Increased calling rate of human players to 250Hz, to reduce input lag, see
  RCM_MAX_DT_HUMAN, robots are still at 50Hz (Bernhard).
- Update to from autoconf 2.69 to 2.72, needed adoption for
  compatibility (Bernhard).
- Added anti-aliasing (MSAA) setting into display section, defaults to 4x
  (Bernhard).
- Added anisotropic filtering setting into the opengl section, the default is
  16x or the maximum your hardware supports (Bernhard).
- Updated trb1 setups (fast/slow threshold to 9 cm/s, fast damper settings, brake
  pressure and balance) (Bernhard).
- Updated default surface material properties, biggest changes are in curb-5cm-r
  and curb-5cm-l and bumpyness of grass (Bernhard).
- Increased pre race stabilization time from one to three seconds to avoid cars
  bouncing at race start (Bernhard).
- Adjusted excessive curb roughness on some tracks (Bernhard).
- Fixed -Wformat-truncation warnings of new gcc version (Bernhard).
- Fixed -Wstringop-truncation warnings of new gcc version (Bernhard).
- Fixed -Wregister warnings of new gcc version (Bernhard).
- Fixed -Woverloaded-virtual warnings of new gcc version (Bernhard).
- Fixed -Wmaybe-uninitialized warning of new gcc version (Bernhard).
- Fixed -Waddress warning of new gcc version (Bernhard).
- Capping repair and refuel amounts in the pit time calculation to avoid too
  high pit stop times in the race engine (Bernhard).
- Capping repair and refuel amounts in the pit menu, added mouseovers to the
  buttons (Bernhard).
- Replaced the splash screen png with a higher resolution version, this
  was created by Eckhard Jäger (Eckhard, Bernhard).
- Updated trb1 category with new suspension defaults (Bernhard).
- Updated trb3 category with new suspension defaults (Bernhard).
- Improved chasing camera (cGrCarCamBehind, used in some F2 and F3 views), the
  stiffness is now framerate independent and is visually closer to other
  racing games (Bernhard).
- Fixed washed out png image screenshots (Bernhard).
- Fixed gear button neutral fallback for joysticks (Bernhard).
- Improved version 4 track loading and added regression tests (Bernhard).
- Fixed Windows debug realloc copy size, release builds were not affected by
  this (Bernhard).
- Hardened Easymesh sentinel handling (Bernhard).
- Prevented invalid Easymesh node insertion (Bernhard).
- Added trackgen regression tooling (Bernhard).
- Easymesh refactoring and improvements (Bernhard).
- Adopted Easymesh to generate much more regular meshes, new parameter to
  control mesh resolution gradient, see "terrain transition" in the track
  manual (Bernhard).
- Updated trackgen and Easymesh regressions, unit tests (Bernhard).
- Limited terrain refinement on the inside of tight curves (Bernhard).
- Refactoring, only have from Easymesh derived code in easymesh.cpp (Bernhard).
- Added trackgen test fixtures for bridge generation (Bernhard).
- Added initial bridge generation in trackgen for the *-trk model (Bernhard).
- Added terrain domain splitting into multiple domains for tracks with one
  or more crossing bridges and terrain generation per domain (Bernhard).
- Fixed tracktools elevation relief alignment (Bernhard).
- Reduced large-coordinate camera vibration with precise simulation positions
  and rebased rendering, relevant on enormous tracks like IOM TT (Bernhard).
- Limited generated track curve radii in dp-diarc track solver from
  tracktools to 4000m (Bernhard).
- Heavy refactoring of trackgen, unified a lot of code which was duplicated
  and unified left/right cases, polished function signatures (Bernhard).
- Added track menu map renderer to tracktools (Bernhard).
- Added SVG centerline importer to tracktools (Bernhard).
- Added centerline georeferencing tool to tracktools (Bernhard).
- Updated car parameters for F330 P4, 250 GTO and GT 40 (Bernhard).
- Refactor common code in track segment resolution (Bernhard).
- Make olethros compatible with new tracks, pretty big refactoring (Bernhard).
- Updated OpenAL to OpenAL Soft 1.25.2 (Bernhard).
- Cosmetic fix for assertion emitted from updated OpenAL when quitting TORCS
  right out of a paused race, the emited message was confusing (Bernhard).
- Added new textures and surface definitions/defaults for trackgen bridge
  generation (Bernhard).
- Added georeference options to track XML model (Bernhard).
- Added new track categories "test" and "experimental" (Bernhard).
- Regenerated all menu track maps, updateded look (Bernhard).
- Added 73 (!) new tracks in the experimental category (Bernhard).
- Added 2 bridging tracks to the test category (Bernhard).
- Moved old tracks into current subdirectories (Bernhard).
- Updated doxygen configuration, documentation fixes (Bernhard).
- Updated track manual (Bernhard).
- Integrated track toolchain documentation into TORCS documentation and
  track documentation updates (Bernhard).
- Integrated robot tutorial into TORCS documentation and complete rework
  with more focus to usage in teaching (Bernhard).
- Added skill and integration tests for robot tutorial maintenance (Bernhard).
- Fixed parameter parser leaks on parameter read errors, is not relevant with
  shipped correct files (Bernhard).
- Updated installers, version bump to 1.3.10 (Bernhard).


12. TODO/Notes
--------------

TODO for 1.3.11 "30 years"
---------------
- Add SDL 3 for video mode/screen detection, sound sample loading and
  eventually game controller (hotplug?)
- Prepare 30 years thing
- Finish my track list (>10 more to go)
- Hud (Tires etc.)
- Add macro- and micro-sector timing to show current gaps
- Grid result up/down
- Try to reproduce #20 Segfault during race, reported by David Bears


TODO for 1.3.12 "analysed"
---------------
- Data recorder ("Telemetry")
- Data analyser (high/low-pass filtering, comparison, etc.)
- Speed/Shock
- Replay?
- Dynamic track
- Wind/Temp
- Brake migration (e.g. 55:45 at 0% brakes, 56.25:43.75 at 50% brakes, 57.5:42.5 at 100% brakes)


TODO for 1.3.13 "ruled"
---------------
- Rules
- Timed races (e.g. 24h).
- Rules/Modes which do not requrie 1.4 changes
- Starting/race modes (multi-class for TRB?)
- Use vs redistributable for heap mamagement (required rebuilding libraries and adoption
  of installer), put files directy into torcs install instead of using installer? -> not yet
- Integrate plib build into TORCS build on Windows to reduce the hassle, maybe other libraries
  too, use vcpkg (https://github.com/microsoft/vcpkg) or similar?
- Eventually get rid of learning64.def
- Define some more lib output and other paths properly, maybe after getting rid of 32 bit build?


TODO for 1.3.14 "managed"
---------------
- Document race manager XML
- Expose secret settings in GUI (e.g. Button masking)

TODO for 1.3.15 or 1.4.x "artistic"
------------------------
- Ingame track generation wizard (themed)

TODO for 1.3.16 or 1.4.x "everywhere"
------------------------
- Merge simuv3 parts into simuv2
- Review WD's ABS suggestion, apply.
- Review WD's 4WD analysis/patch.
- Remove circular dependency (raceman.h, simu.h).
- Eventually differential(s) adjustable during ride
- Remove sound property calculation in wheel.cpp.

TODO for 1.3.16+
----------------
- Maintainance only, move development to 2.0
- Compiler and library adoptions, fixes, compatible content updates
- Docker image for headless simulation and cross build evaluation

TODO for 2.0.x
--------------
- situation time as long (avoid floating point drift, can be also used as timestep id),
  situation time is then timestepid*RCM_MAX_DT_SIMU
- remove legacy s->deltaTime and tRaceEngineInfo->lastTime 
- Robot interface adoptions (maybe askfeatures, callonce, grid, postprocess, we will see...).
  How to identify robots, get rid of Index (name only)?
- Make it possible for a robot module to carry any arbitrary number of
  drivers (instead of static 10).
- Pre race setup (fuel, tire selection, with UI for human player)
- Robot Tutorial update (move to doxygen) -> move to after changing robot interfaces
- More Rules.
- Brake/Engine Wear (with cooling)
- Apply SDL patch from Brian Gavin but moving directly to SDL 3.0.
	- Remember Freeglut/F10 hack, maybe similar care is required here.
	- Check if this is a thing with SDL:
	  Added manifest to wtorcs.exe with "Per Monitor High DPI Aware", this should fix full screen
      scaling issues with multi monitor systems and other than 100% dpi settings (Bernhard).
- Car asignment for human players.
- Sound (alut depricated/scheduling for lots of cars)
- Pace car and trucks to remove wrecks (remove "virtual" crane?).
- Track extensions (crossings, split/join, variable width)
- Skidmarks/shadows masking with stencil
- Phong specular highlights/in shadow occlusion
- Skidmarks to simu/persistency (get rid of frame rate dependency)
- Review/reduce dynamic memory allocation/release during rendering
- Store all graphics engine state in a context struct/object (to be able to render telemetry
  in the car setup screen or during a running session)
- track wall properties
- Solve problems with side entering/exiting pit lane rules (repeated violations give
  only one penalty under some conditions).
- Revisit GfImgWritePng, do we really need the gamma there? I left it for now because it is
  also used by trackgen for height maps.
- GfFatal implements exit on Linux, but not on Windows -> equalize, clean up, maybe remove
  explicit exits after GfFatal added for Windows version
- New HUD and menus

TODO TRB
--------
- Update/find new hosting provider
- Content exchange
- E-Mail exchange

TODO for Compliance
-------------------
acura -> replace with car9-trb1
mc-larenf1 -> replace with car10-trb1
p406 -> replace with car1-trb4
rework buggy, baja bug
replace rally cars
Remove invalid geometry from tracks 
convert force units internally from lbs to lbf


Later:
-------------------
- Decide about plib (not maintained anymore?) -> integration of minimal subset as base
  for own engine? Vulkan with RT?
- GUI for event blacklisting.
- Ongoing for every release: rework free car models (several holes, no
  emmissive color of lod (model becomes dark at a certain distance), single
  sided, add cockpit, lods).
- Ongoing for every release: Improve visual quality of some existing tracks.
- Fix sound in split screen multiplayer.
- Ongoing: Replace some defines with "static const" to be able to see the
  symbol name when debugging.
- move berniw/bt spline code into math to share it.
- hunt down all glGet* crap during the simulation.
- (Problem when driver list changes during championship.)
- Blind mode should not load graphics engine.


TODO LATER
----------
- Networking (2.0).
- SMP simulaton core (for myself).
- 3d-grass.
- Dynamic sky.
- TRB integration.
- Separate components more clean (e.g. ssgInit should go back to
  ssggraph, etc.)
- Avoid cameras cutting the landscape.
- Start position marks on track (same technique like fake shadow, skids).
- Start procedures (pace car, etc).
- Better transparency for track objects.
- More driving aids, switch to AI and back.
- Opponent sets for human players (e.g 20 Open Wheel cars, etc.)
- Free camera controlled with mouse and keys.


IDEAS FOR MUCH LATER
--------------------
- Weather.
- Dynamic day/night-time, car lights.
- Pit crew.
- Dynamic "intelligent" Objects (e.g. Helicopter)
- Solid/dynamic obstacles.
- Nicer trees etc, terrain LOD.
- Dirt on cars.
- free terrain.
- Open track dynamically generated when driving.
- Random track generator.
- Separate pit path, Y segments, etc?
- TORCS as benchmark or screensaver?
- Force feedback.
- Story mode with message.
- Traffic simulator
- (Ingame car livery design (themed))
