x86GP2 CUSTOM COCKPIT SCRIPTING 1.2
====================================

This guide explains how to create a custom cockpit using a Lua script.

1. FOLDER STRUCTURE
-------------------
Cockpits are stored in:

    CONTENT/cockpits/

Create a folder with your cockpit's name. Inside it, create a file named
cockpit.lua and a folder named assets. Put all graphics in the assets folder.

Example:

    CONTENT/
      cockpits/
        1994_x86GP2/
          cockpit.lua
          assets/
            cockpit.png
            steering.png
            needle.png

To select the cockpit, add this command to the TAD file:

    cockpit "1994_x86GP2"

The value can be "default" or the name of a folder inside CONTENT/cockpits/.

CTRL+SHIFT+F5 will reload the script while the game is running.
The LCD screen doesn't always refresh instantly.


2. SCRIPT STRUCTURE
-------------------
Cockpit scripts use standard Lua. You can use Lua variables, calculations,
conditions, functions, and other language features.

Three main functions make up a cockpit script:

    config()    Set cockpit options and indicator positions. Called once at the beginning.
    load()      Load textures from the assets folder. Called once at the beginning.
    cockpit()   Draw the cockpit and its components. Called every frame.

Basic example:

    local cockpit_texture

    function config()
        Cockpit("tyres", "hide")
    end

    function load()
        cockpit_texture = rl.LoadTexture("cockpit.png")
    end

    function cockpit()
        rl.ResetColor()
        rl.DrawTexture(cockpit_texture, 0, 0, 1.0)
    end


3. CONFIGURATION: config()
-------------------------

The config() function uses Cockpit() commands to change cockpit settings.
All settings are optional. Anything you do not specify keeps its default.

Text parameters are not sensitive to capitalization or spaces. For example,
"Car Damage", "car damage", and "cardamage" all refer to the same item.


  Hide the 3D tyres

    Cockpit("tyres", "hide")

    Hides the 3D tyres in cockpit view.


  Set tyre track width

    Cockpit("tyres", "track", 0.85)

    Sets the wheeltrack, the span of the tyres. The value is
    measured in meters from the center of the car to the center of each tyre.

    The default is 0.85. With the tyres being 0.30m wide,
    this produces a total outside width of 2.0m.


  Adjust the cockpit view

    Cockpit("view", x, y, z)

    Offsets the default cockpit view along the x, y, and z axes.
    Values are given in GP2 units.


  Move an onboard indicator

    Cockpit("dash", "indicator name", x, y)

    Changes the position of an original GP2 onboard indicator.
    The indicator must remain within the original 4:3 screen area.

    Available indicator names:

      DA Auto Brakes               DA Auto Gears
      DA Spin Correction           DA Racing Line
      DA Indestructibility         DA Suggested Gear
      DA Throttle Help

      Current Gear                 Suggested Gear
      Revs Led #1                  Revs Led #2
      Revs Led #3                  Revs Led #4

      Reliability Problem          Low Fuel
      Split Time                   Pit Message
      Driver Status                Opposition Spread
      Pitstop Status               Car Damage

      Ace Skill Level              Pro Skill Level
      Semi-pro Skill Level         Amateur Skill Level
      Rookie Skill Level

      Graphics Detail High         Graphics Detail Medium
      Graphics Detail Low

    To identify the indicators visually, use the cockpit editor in GP2Edit.


  Hide an oboard indicator

    Cockpit("hide", "indicator")

     Available indicator names:
        Damage Indicator
        Graphics Detail
        Gear Indicator
        Driving Aids
        Opponent Skill Level
        Opponent Spread
        RPM Lights
        Warning Light

   
    
   LCD Customisation

    Selecting which session you wish to customise the LCD for.

        Opening the block
            Cockpit("LCD session", "name of session")
            session names: practice, qualifying, race

        Closing the block
            Cockpit("LCD session", "end")

            A session block has to be closed before starting another one

        Printing text to the LCD screen
            Cockpit("LCD text", "text", x, y, fine_x, fine_y)

            x and y are not in pixels, they are tex rows and columns
            fine_x and fine_y are used when those don't prove to be precise enough

        Printing a value to the LCD screen
            Cockpit("LCD value", "name of value", x, y, fine_x, fine_y)

            list of names:
                speed
                position
                fuel laps
                lap number
                car number
                race lap count
                cars running


4. LOADING TEXTURES AND FONTS: load()
---------------------------

Use rl.LoadTexture() to load images. Filenames are looked up in your
cockpit's assets folder.

    texture = rl.LoadTexture("filename.png")

Example:

    function load()
        cockpit_texture = rl.LoadTexture("cockpit.png")
        steering_texture = rl.LoadTexture("steering.png")
        needle_texture = rl.LoadTexture("needle.png")
    end

Use rl.LoadFont() to load a font. Filenames are looked up in your
cockpit's assets folder. Supported formats: ttf, otf

    font = rl.LoadFont("font.ttf", font_size)


5. DRAWING: cockpit()
---------------------

The cockpit() function draws the cockpit graphics. Drawing and color
functions are provided through the rl namespace.


5.1  COLOR AND TRANSPARENCY

Color is a state machine: once you set a tint, it stays that way affecting subsequent drawing
commands until you change or reset it.

    rl.ResetColor()
        Resets the tint to white (no tint).

    rl.SetColor(r, g, b)
        Sets an RGB tint. Each component ranges from 0 to 255.

    rl.SetAlpha(a)
        Sets the alpha (transparency) value.

    rl.SetCockpitColor()
        Uses the selected car's cockpit color from the TAD file.

    rl.SetMirrorColor()
        Uses the selected car's mirror color from the TAD file.

    rl.SetFrontwingColor()
        Uses the selected car's front wing color from the TAD file.

    rl.SetLCDFontColor(r, g, b)

    rl.SetRPMIndicatorColor(background R, background G, background B, normal R, normal G, normal B, redline R, redline G, redline B)


5.2  TEXTURES AND SPECIAL DRAWING FUNCTIONS

    rl.DrawTexture(texture, x, y, scale)

        Draws a loaded texture at the given position and scale.

        Screen coordinates start at the BOTTOM CENTER:
          x = 0, y = 0   Bottom center of the screen
          Positive x     Moves right
          Positive y     Moves up

        Coordinates use a fixed virtual resolution of 480, regardless
        of the actual window size.

        If you want to use the texture in its original size, use scale = 1.0.
        If your cockpit image is 1080 pixels tall but you want it to fill the original 480 screen, you can use:

            scale = 480.0 / 1080.0

        This allows high-resolution textures to display more detail
        when the windows is at a higher resolution.


    rl.DrawTextureEx(texture, x, y, origin_x, origin_y, rotation, scale)

        Draws a texture with rotation. Useful for analogue gauge needles.

        An origin of (0, 0) uses the bottom center of the texture.
        A custom origin is specified relative to its top-left corner.
        The rotation angle is in degrees.

        For a 300 x 300 texture, an origin of (150, 150) rotates
        it around its center.


    rl.DrawSteeringWheel(texture, x, y, scale)

        Special function that automatically takes the
        rotation of the steering wheel into account.


    rl.DrawFrontwing(texture, x, y)

        Draws the left side of the front wing and automatically
        mirrors it to create the right side.


    rl.DrawMirrorImage("L", x, y)

        Draws one of the game's mirror images:
          "L" = Left mirror
          "R" = Right mirror
          "C" = Center mirror


    rl.DrawLCD(x, y)

        Draws the original GP2 LCD display.


    rl.DrawLCDMenu(x, y)

      Draws the LCD menu when in the pits. If you don't draw the LCD screen
      (for example due to having analogue guages), the pit menu still has to appear somewhere.
      Don't mix the two. Either use rl.DrawLCD or rl.DrawLCDMenu.


    rl.DrawRPM(rpmStartX, rpmStartY, rpmEndX , rpmEndY, rpmP1X, rpmP1Y, rpmP2X, rpmP2Y, rpmSegments, rpmMin)
      Draws x86GP2's new digital RPM indicator

      rpmStartX, rpmStartY      Where it starts drawing the left side
      rpmEndX, rpmEndY          Where it finishes drawing the right side
      rpmP1X, rpmP1Y            The left side points that make it curved
      rpmP2X, rpmP2Y            The right side points that make it curved
      rpmSegments               How many segments you want to divide it to
      rpmMin                    Where the range starts for the first segment

    
    rl.SetRPMIndicatorBgAlpha(A)

      Sets the background alpha for the RPM indicator


5.3  DRAWING TEXT WITH FONTS
    
    rl.DrawFont(font, "text", x, y)
    


6. READING GAME MEMORY
----------------------

Memory-reading functions are intended for advanced users.
They can be used to build custom analogue gauges or display values
that the standard cockpit does not provide.

For example, a value read from memory could be converted to a rotation
angle and passed to rl.DrawTextureEx() to animate a custom gauge.

The address is an IDA address.

    value = ReadMem8(address)
        Reads an 8-bit value (byte).

    value = ReadMem16(address)
        Reads a 16-bit value (short/word).

    value = ReadMem32(address)
        Reads a 32-bit value (int/dword).

    value = ReadMemParam("name of parameter")
        Reads a pre-defined parameter from memory.

        available:  speed
                    rpm
                    gear
                    fuel laps
                    car number
                    runners
                    lap number
                    laps this race

    value = IsLCDActive("display mode")
        Returns a boolean (true or false) telling you whether that display mode is active

        modes:  gap
                lap time
                pit message
                failure
                logger
                pit menu



7. QUICK REFERENCE
------------------

Configuration
    Cockpit("tyres", "hide")
    Cockpit("tyres", "track", value)
    Cockpit("view", x, y, z)
    Cockpit("dash", "indicator name", x, y)
    Cockpit("LCD session", "name of session")
    Cockpit("LCD session", "end")
    Cockpit("LCD text", "text", x, y, fine_x, fine_y)
    Cockpit("LCD value", "name of value", x, y, fine_x, fine_y)

Textures
    rl.LoadTexture("filename")

Fonts
    rl.LoadFont("filename", font_size)

Color
    rl.ResetColor()
    rl.SetColor(r, g, b)
    rl.SetAlpha(a)
    rl.SetCockpitColor()
    rl.SetMirrorColor()
    rl.SetFrontwingColor()
    rl.SetLCDFontColor(r, g, b)
    rl.SetRPMIndicatorBgAlpha(A)
    rl.SetRPMIndicatorColor(background R, background G, background B, normal R, normal G, normal B, redline R, redline G, redline B)

Drawing
    rl.DrawTexture(texture, x, y, scale)
    rl.DrawTextureEx(texture, x, y, origin_x, origin_y, rotation, scale)
    rl.DrawFont(font, "text", x, y)
    rl.DrawSteeringWheel(texture, x, y, scale)
    rl.DrawFrontwing(texture, x, y)
    rl.DrawMirrorImage("L" / "R" / "C", x, y)
    rl.DrawLCD(x, y)
    rl.DrawLCDMenu(x, y)
    rl.DrawRPM(rpmStartX, rpmStartY, rpmEndX , rpmEndY, rpmP1X, rpmP1Y, rpmP2X, rpmP2Y, rpmSegments, rpmMin)

Memory
    ReadMem8(address)
    ReadMem16(address)
    ReadMem32(address)
    ReadMemParam("name of parameter")
    IsLCDActive("display mode")
