1.1 Controls

The car can be driven with a joystick, keys, or even a mouse. A joystick is highly recommended.

Keys, buttons, and joystick axes are mapped to functions in an XML file in the data directory (usually /usr/local/share/vamos/controls). By default the file default-controls is used. You can specify a different file with the -a or --controls= options. The default control bindings are as follows:

Key	Stick	Action
<Up>*	Forward	Throttle.
<Down>*	Backward	Brake.
<Left>*	Left	Turn left.
<Right>*	Right	Turn right.
<Insert>*	Button-1*	Shift up.
<Delete>*	Button-2*	Shift down.
<Home>*	Button-3*	Clutch.
<a>		Place the car back at the starting line.
<r>		Place the car back on the road.
<s>		Start the engine after a stall.
<f>		Fill the fuel tank.
<c>		Reload the car definition file.
<t>		Reload the track definition file.
<p>		Pause the application.
<q>		Exit the application.
<F9>		Cycle through the views.

The `*' symbol indicates that the action is performed gradually after the key or button is pressed.

When shifting, pressing the key or button causes the clutch to be disengaged before the new gear is selected. Releasing the button releases the clutch. The clutch is engaged slowly when shifting from neutral, and more quickly for other gears. The clutch is always disengaged quickly.

1.2 Control File Format

Here's the format of a controls file.

     <controls name="Name">
       <!-- Key Binding -->
       <bind>
         <function>function name</function>
         <key>k</key>[<up|down/>]
         [<time>t</time>]
       </bind>
     
       <!-- Button Binding -->
       <bind>
         <function>function name</function>
         <button>b</button>[<up|down/>]
       </bind>
     
       <!-- Axis Binding -->
       <bind>
         <function>function name</function>
         <axis>a</axis>
         [<factor>f</factor>]
         [<offset>o</offset>]
         [<minimum>m</minimum>]
       </bind>
     </controls>

The function tag gives the name of the function to bind. Any member funciton of Gl_Car_World that takes two double arguments and returns a bool can be bound. The case of the name inside the function tag must match the actual function's name, and underscores must be replaced with single spaces.

The down tag binds the function to a key (or button) press; up binds it to a key release. If neither is specified, the function is bound to a key press.

The time tag sets how long it takes for setting to be ramped up to its target value. It is used for controling continuous values, like throttle, from the keyboard. The default time is 0.

For joystick axes, vaules range from -1 to 1. This number is multiplied by the value in the factor tag and then the value in the offset tag is added. The result is clipped at minimum. The defaults are 1, 0, 0, respectively.

1.2.1 Bindable Functions

These are the functions that can be bound to controls.

pause

Pause the simulation.

quit

Quit the program.

cycle view

Change the point-of-view from car to trackside to overhead.

read car

Read the car definition file.

read track

Read the track definition file.

read world

Read the world definition file.

restart car

Put the car at the starting line.

reset car

Put the car back on the track.

fill tank

Fill the car's gas tank.

gas

Operate the throttle.

brake

Operate the brakes.

steer

steer left

steer right

Operate the steering wheel. The 'steer left' and 'steer right' functions are useful for binding to keys.

shift up

shift down

Select an adjacent gear, except when in neutral.

shift up disengage

shift down disengage

Select an adjacent gear and operate the clutch, except when in neutral.

initial shift up

initial shift down

Select an adjacent gear when in neutral.

initial shift up disengage

initial shift down disengage

Select an adjacent gear and operate the clutch when in neutral.

clutch

Operate the clutch.

engage clutch

disengage clutch

Operate the clutch, except when in neutral

initial engage clutch

initial disengage clutch

Operate the clutch when in neutral

A function can be bound to more than one control. However, when the simulation is running, the joystick is read after the keys. If, for example, you bind the throttle to the up arrow key and to a joystick axis, the joystick (if present) will override the keyboard.

Similarly, more than one function can be bound to a control. Each function is called in turn until one of them returns true.

For shifting, you will likely bind two functions to each shifting control, one for shifting from neutral (e.g. initial shift up) and the other for shifting from other gears (e.g. shift up). If you bind the clutch to a key or button, rather than a continuous contral, you will also bind two functions to the clutch controls. The reason is that you may want different behavior from the clutch in these two situations.

When shifting from neutral to first, you will let the clutch out slowly to get the car started without stalling. When shifting to other gears you will operate the clutch more quickly. You can make this happen by binding both initial shift up disegnage and shift up disengage to the same key or button, and using a larger value in the time tage for initial shift up disengage.