****************************
**** Re-Volt v1.2 Patch ****
****************************

[ NOTE: This readme is best viewed with a constant width font such as 
Consolas or Courier. ]

This brand new update for the PC version of Acclaim's classic R/C racer 
"Re-Volt" is aimed at bug fixes, compatibility and user improvements, 
new features, additional content and more. Work in progress.

Have suggestions, ideas for new Re-Volt features, or bugs to report? Feel 
free to join and post in our forum boards. 
[ http://z3.invisionfree.com/Our_ReVolt_Pub ]


|---------------------|
|--- Documentation ---|
|---------------------|

[ NOTE: This section is meant for car and track makers and is updated 
from time to time to reflect features in the latest Alpha release. ]

[ HINT: It may be convenient to work with tracks and cars in "DEV mode". 
This mode enables several helpful features for car / track making, in 
addition to MAKEITGOOD and TVTIME cheats. To access DEV mode, run Re-Volt 
with -dev command line. ]

====================
 Textures & Mipmaps
====================

[NOTE: Applies to both cars and tracks. ]

--------------
 Texture Size
--------------

Supports standard texture sizes that work with any graphics card. Your 
texture has to be square (i.e., same width and height) with power-of-two 
dimensions (like 256x256, 512x512, etc). We have currently set a safe 
higher limit of 8192x8192.

[ NOTE: The legacy Re-Volt versions only support one texture size: 
256x256. To learn how to make your track using hi-res textures backward 
compatible, see the Mipmaps section just below. ]

---------
 Mipmaps
---------

Mipmaps are low resolution copies of the main texture. Mipmaps improve 
both the performance and visuals of your content, especially when used 
with hi-res textures.

Several mipmap levels can be used, each level must be half the size of 
the previous and named with a different ".bm[p]" extension: the last 
character keeps increasing. (eg., a 256x256 "texture.bmp" will have a 
128x128 "texture.bmq" file as the first mipmap level and a 64x64 
"texture.bmr" as the second mipmap level).

We also allow the use of mipmaps that go upward (i.e., with the above 
mentioned example, you may include a hi-res 512x512 version called 
"texture.bmo"). By including your hi-res texture this way, you will be 
able to keep the actual "texture.bmp" file at 256x256 and enable your 
content to be played in legacy Re-Volt versions.

For a quick reference, here is a list of supported sizes and their 
corresponding file names, as per the above example:
      8192 x 8192   -   texture.bmk
      4096 x 4096   -   texture.bml
      2048 x 2048   -   texture.bmm
      1024 x 1024   -   texture.bmn
       512 x 512    -   texture.bmo
     [ 256 x 256    -   texture.bmp ]
       128 x 128    -   texture.bmq
        64 x 64     -   texture.bmr
        32 x 32     -   texture.bms
        16 x 16     -   texture.bmt
         8 x 8      -   texture.bmu
         4 x 4      -   texture.bmv
         2 x 2      -   texture.bmw
         1 x 1      -   texture.bmx

[ NOTE: Intermediate mipmap levels cannot be skipped. For example, do not 
include a texture.bmp" (256x256) and a "texture.bmn" (1024x1024) without 
a "texture.bmo" (512x512) inbetween. ]

[ NOTE: For uses of mipmaps with hi-res textures, see: ]
[ http://z3.invisionfree.com/Our_ReVolt_Pub/index.php?showtopic=1443&st=500&#entry10637343 ]

--------------
 Texture Sets
--------------

Mipmaps also find a third use as "texture sets". The game will pick 
textures of the appropriate size to load, depending on the available 
system resources. Therefore, it is always recommended to include 
appropriate mipmap levels for your content.

[ HINT: Use the -texinfo command line to display the texture sets info 
that was detected for your system. ]

--------------------
 Alpha Transparency
--------------------

Supports bitmap textures with alpha channel for transparency data. Only 
32-bit ARGB (A8 R8 G8 B8) format is supported.

Alpha channel transparency can be used to create rich and varied effects, 
eg., transparency gradients and well anti-aliased shapes. Colorkeying is 
disabled in this case, which means pure-black color (RGB 000) can be used 
freely on opaque surfaces.

[ NOTE: Care should be taken to save your alpha-enabled texture in the 
correct format ARGB. Some other 32-bit BMP formats such as XRGB, while 
creating a 32-bit bitmap file, does not save your alpha channel in the 
extra space. This would result in a fully transparent texture in-game. ]

[ NOTE: For example uses of 32-bit textures, see: ]
[ http://z3.invisionfree.com/Our_ReVolt_Pub/index.php?showtopic=1619 ]

================
 For Car Makers
================

Customize user cars through new entries in the car's "Parameters.txt" 
file.

[ NOTE: To make sure your car stays compatible with legacy versions of 
the game, precede each line of a new entry in the parameters file with 
";)", without quotes. This is done in our examples below. ]

------------
 Carbox Art
------------

To add a box-art image to your car, use the TCARBOX parameter. This entry 
works the same way as the TPAGE parameter. General syntax:
    ;)TCARBOX  <path to carbox texture>
    
The carbox texture should be a full 256x256 bitmap image (although other 
sizes may be supported), with pure white (RGB 255,255,255) background. 
Mipmaps may be used for improved quality and performance (see the 
Textures & Mipmaps section).

[ NOTE: View online help and download an example car here: ]
[ http://z3.invisionfree.com/Our_ReVolt_Pub/index.php?showtopic=1443&st=100&#entry10628143 ]

---------------
 Custom Shadow
---------------

Each car can have its own shadow map, or it can use one of the preset 
stock shadows (useful for default car repaints). 

The shadow map is generally a 64x64 bitmap image containing a white 
silhouette of the car on a black background. They can be generated from 
the top view of the car (preferably from a 3D modeller) and then post- 
processed in an image editor.

Re-Volt requires 5 coordinates supplied in the car Parameters.txt file to 
position the shadow under the car. These are the Left, Right, Front and 
Back edges and Height relative to the model center. These values are 
independent of the car CoM and do not need to be updated upon changing 
the CoM.

Parameters to be added:
  - TSHADOW to specify the shadow texture, similar to TPAGE and TCARBOX 
    parameters. This parameter can be ignored if the car is not using a 
    custom shadow texture.
  - SHADOWINDEX to use one of the default car shadows found in 
    "cars\misc\Shadow.bmp". Set this parameter to -1 to use the generic 
    square shadow. This parameter can be ignored if TSHADOW is used. 
  - SHADOWTABLE parameter followed by 5 offset values for the Left / 
    Right / Front / Back / Height of shadow relative to model center. 
    Remove this line or set all offsets to zero if you'd like the shadow 
    to be automatically placed under the car's body (in this case, the 
    shadow will not cover wheels extending out of the body).

General syntax:
    ;)TSHADOW     <path to shadow texture (or) NONE>
    ;)SHADOWINDEX -1  ; 0 to 27, (or) -1
    ;)SHADOWTABLE -10.2 10.2 30.4 -30.4 -4.2

[ NOTE: For a walkthrough on generating and setting up a car shadow, and 
to download an example car, see: ]
[ http://z3.invisionfree.com/Our_ReVolt_Pub/index.php?showtopic=1680 ]

---------------
 Stats Display
---------------

User cars can show the Speed / Acceleration / Weight bars in the car 
selection screen.

To use this feature, calculate and fill in the TopEnd and Acc parameter 
values using Start Race -> Calc Car Stats option in DEV mode. Weight 
takes the same value as the car mass.

[ NOTE: v1.2 also requires the Trans parameter to be properly filled in. ]

Then add the following line in the Frontend section of the parameters 
file.
    ;)Statistics  TRUE

[ HINT: TopEnd gives the maximum top-speed that can actually be reached 
by the car. Acc gives time, in seconds the car takes to reach the top 
speed. ]

[ NOTE: To download an example car with custom shadow and stats, see: ]
[ http://z3.invisionfree.com/Our_ReVolt_Pub/index.php?showtopic=1443&st=1150&#entry22000166 ]

--------------------
 Hood & Rear Camera
--------------------

Configure the hood and rear-view cameras for your car by adding the new 
CAMATTACHED section in your parameters file. Below is a sample:
    ;====================
    ; Camera details
    ;====================
    
    ;)CAMATTACHED {   ; Start Camera
    ;)HoodOffset      -0.12 -71.81 -60.01 ; Offset from model center
    ;)HoodLook        0.02 ; Look angle (-0.25 to 0.25, 0.0 - straight)
    ;)RearOffset      -0.12 -71.81 27.24
    ;)RearLook        0.03
    ;)}               ; End Camera

--------------
 Camber Angle
--------------

Configure the camber angle for each wheel of your car using the Camber 
entry. This sets the rotation angle (in degree) of the wheel along the 
Z axis. General syntax (in each WHEEL section):
    ;)Camber    -10

[ NOTE: The camber sign is automatically adjusted for left / right 
wheels. A negative Camber value makes the bottom of the wheel farther out 
than the top.]

-----------------
 Special Effects
-----------------

Enable Rotor, UFO or Mystery effect for your user car by adding new 
parameters in the "Handling related stuff" in the parameters file. 
General syntax:
    ;)Flippable FALSE   ; Rotor car effect
    ;)Flying    FALSE   ; Flying like the UFO car
    ;)ClothFx   FALSE   ; Mystery car cloth effect

[ NOTE: Mystery car effect will also need modification to the car mesh to 
flag the polygons that form the edges of the cloth. For more details, 
see: ]
[ http://z3.invisionfree.com/Our_ReVolt_Pub/index.php?showtopic=1443&st=1000&#entry10640663 ]

To use Panga affect (i.e., head turning and ducking according to speed), 
modify the SPINNER section. Further, you can use rotation only, ducking 
(translation) only, or both.
General syntax (in the SPINNER section):
    ;)Type            0   ; 1: Default rot, 2: Turn with steer, 
                          ; 4: Translate with speed, 6: both 2 and 4
    ;)Trans           0.000000 3.000000 6.000000  ; Translation max
    ;)TransVel        0.001000    ; Velocity factor
    
[ NOTE: Unlike in legacy versions (eg., default Panga car) where TransVel 
was zero to make the spinner turn with steer, now TransVel specifies the 
speed of turning, so it should be non-zero. A TransVel value of zero 
denotes that the spinner doesn't turn at all. ]

------------------
 AI Selectability
------------------

Disable a user car for AI selection by adding the CPUSelectable parameter 
in the "frontend and selectability" section in the parameters file. 
General syntax:
    ;)CPUSelectable  FALSE

--------------
 DEV Commands
--------------

[ NOTE: These commands work in DEV mode, some commands may also work by 
manually entering MAKEITGOOD edit mode or other appropriate cheat codes. ]

Instant Car Refresh: Press Ctrl + R to refresh the car data. Allows you 
to quickly make changes to the car parameters and data (textures, hull, 
etc) while Re-Volt is running and view those changes in-game. This works 
both in Frontend preview screen and in-game.

==================
 For Track Makers
==================

Customize user tracks through new entries in the "level".inf file and the 
extensive "custom" folder support.

--------------
 Custom Music
--------------

To play a custom music track in your level instead of the default CD 
audio, use the MUSIC entry in the "level".inf file. General syntax:
    MUSIC <Path to music file>

Supported formats are OGG (recommended), MP3 and WAV.

[ NOTE: This entry was previously called MP3 which is now a deprecated 
keyword. The MUSIC keyword is recommended for new tracks. ]

[ NOTE: If both MUSIC and REDBOOK lines are present in the inf, MUSIC has 
the higher priority. ]

-----------------------
 Supporting Game Modes
-----------------------

Practice: User tracks can be played in Practice mode. Add a single star 
object for this mode, when the player finds and catches it, the progress 
will be saved.

Battle & Stunt: These special type of tracks can be created and supported 
with the help of a new GAMETYPE entry in the "track".inf file. General 
syntax: 
    GAMETYPE 1    ;Track type (1:battle, 2:stunt)
Add several stars for Battle Tag mode, and upto 64 stars for Stunt Arena. 
Progress for Stunt track type is saved and displayed.

Reverse Mode: Support for Reverse mode can be added by including a 
"reversed" folder in your track folder, containing the needed files (see 
the default levels for an example).
[ HINT: Several edit modes (AI Nodes, Pos Nodes) support automatically 
reversing the data for you, by using the LShift + R command. ]

------------------------
 Advanced Customization
------------------------

Added support for advanced custom content in user tracks. This includes 
but not limited to:
  - Animated objects
  - Skymap, clouds, other graphics
  - Sound effects
  - Loadscreen image
  - HUD, menu and font

This works by replacing default (stock) data with custom content. When a 
model, sound, texture, etc. has to be loaded, the file is first searched 
inside the "custom" sub-folder located in the current track's folder.

The only thing to do to add custom content in your track is to create a 
"custom" folder inside the track's directory and place the custom files 
inside, with the same name as the stock content you want to replace.

Here is the list of the customizable files:
  - Skyboxes: sky_bk.bmp to sky_tp.bmp
  - All Objects added in Edit mode (MAKEITGOOD): the .m files and their 
    associated .hul or .ncp file, if any.
  - All the .wav files (sfx).
  - All track files: .fob, .fld, .fan, .fin, .cam, .pan, .tri, .taz, 
    .por, .w, vis, .rim, .ncp, .lit.
  - The track textures.
  - trolley.bmp, sun.bmp, dragon.bmp, water.bmp, clouds.bmp
  - loadlevel1.bmp to loadlevel4.bmp
  - fxpage1.bmp to fxpage3.bmp
  - font.bmp, loading.bmp and spru.bmp
  - gogo.m and go1.m to go3.m

This is an exhaustive list. Some of these files should practically never 
be customized. The support for some formats was only added to be able to 
release a track compatible with both v1.2 and legacy Re-Volt version (see 
the Compatibility Notes section below).

[ NOTE: In Reverse mode, the custom version of the files that Re-Volt 
expects to find in the "reversed" folder have to be placed inside the 
"custom\reversed" folder to be detected. ]

[ NOTE: For an example track utilizing custom features, see: ]
[ http://z3.invisionfree.com/Our_ReVolt_Pub/index.php?showtopic=1443&st=800&#entry10639949 ]

---------------------
 Compatibility Notes
---------------------

With support for custom track files (.fob, .fin, etc), it is possible to  
to include, for example, a simplified .fob file in the main track folder 
and a custom .fob file placed in the "custom" folder. That way, the track 
can be played with both v1.2 and legacy Re-Volt versions.

The recommended practice is to first create the simplified track files,  
then copy those files into the "custom" folder and continue working in 
Edit mode to add v1.2 specific customizations. Any modifications will now 
be saved in the "custom" folder without touching the main track files.

When designing simplified track files for legacy versions, the following 
limitations need to be taken into account:

Texture Animation: The simplified world (.w) file should contain no more 
than 16 texture animation slots, any more will crash legacy versions.

Camera Nodes: This edit mode gives you an option whether to save the .cam 
file in the old format or the new v1.2 format (with support for higher  
range). If you are sure your track coordinates are within the range of 
(-32768 to 32768), you can choose to save in the old format without 
having to worry about compatibility.
If your track exceeds the specified range, first create a simplified .cam 
file with nodes staying within the range and save it with the old format. 
Then copy this .cam file to your "custom" folder and continue adding the 
rest of the nodes, this time saving it with the new format.

Conveyor Effect: The direction of conveyor effect is hardcoded in legacy 
versions, hence not easy to support in those versions. It is recommended 
to first create the world (.w) or instance (.fin) file with no conveyor 
effect, then use custom support to add the effect later.

Limitations: Any content exceding these limits will simply be ignored by 
legacy versions and are not of concern for compatibility.
  - Pickups: 40.
  - Objects: 128.
  - Instances: 200.
Below limits are not usually exceeded but if otherwise, you might want to 
use custom support to include simplified files.
  - Track Zones: 128.
  - Collision polygons: 16384.

--------------
 DEV Commands
--------------

[ NOTE: These commands work in DEV mode, some commands may also work by 
manually entering MAKEITGOOD edit mode or other appropriate cheat codes. ]

Full Track Reload: Make changes to track files while Re-Volt is running, 
then simply restart the track to reload all the files.

Preview Objects: In Objects edit mode, press Ctrl + P to preview objects 
animation instantly, then use the same command to get back to editing.

Show Camera Position: Press RShift + F9 to show position and direction of 
the camera. This can help setting the required StartPos and StartRot 
values in the "track".inf file, by placing the camera at the start line 
and noting the camera values.

Hide HUD and Menus: Shift + F5 to hide HUD, then with the game paused, 
press and hold Shift to hide the pause menu. This helps, eg., taking a 
screenshot for the main track gfx.


-------------------------------------------------------------------------

Copyright © Huki and jigebren 2015
Webpage: http://rv12.revoltzone.net
Email: rv12@revoltzone.net
