[Y_Less]

y_races

Introduction

The races system in YSI is one of the very first bits of code I wrote for it, back before it was even called YSI. The main "OnPlayerEnterCheckpoint" code remained almost identical to its original version from "San Andreas:Underground" 7 years ago until today when I made some updates (but the main structure is STILL the same).

This library fairly obviously provides functions for defining and running races. You can have (by default) up to 16 races running in parallel, with 1024 checkpoints between them. The old system was set to 256 checkpoints per race - this new version doesn't restrict the number per-race but globally instead, so you can have one with 1 checkpoint (a drag-race perhaps) and another with 1023 (some sort of ridiculous Le-Mans length tour).

Use

Using the basic system is very simple, but as with all of YSI there are many options that can be changed by advanced users:

pawn Code:

#include <YSI\y_races>

new
    gRace;

public OnScriptInit()
{
    // Declare a new race.
    gRace = Race_Create();
    // Set it to have 0 laps.
    Race_SetLaps(gRace, 0);
    // Set the price to join the race to $200.
    // Note that if you want, you can set this to 0 and create your own payment system.
    Race_SetEntry(gRace, 200);
}

That code creates and initialises a race. The function "Race_Create" also has several optional parameters so you can write the code above as:

pawn Code:

public OnScriptInit()
{
    gRace = Race_Create(.laps = 0, .entry = 200);
}

Now this race is very boring - it doesn't have any starting points or any checkpoints, so let's add some:

pawn Code:

// Add some points to the starting grid.
// This is a drag race between two cars along the LV airstrip.
// X, Y, Z, Angle.
Race_AddStart(gRace, 425.0, 2488.0, 16.2, 90.0);
Race_AddStart(gRace, 425.0, 2512.0, 16.2, 90.0);
// Add two checkpoints - its a drag race there and back!
// No angle this time.  Arrows and chequred flags are done automatically.
Race_AddCheckpoint(gRace, -78.5, 2500.0, 16.1);
Race_AddCheckpoint(gRace, 434.0, 2500.0, 16.1);

Finally, we need some players:

pawn Code:

YCMD:join(playerid, params[], help)
{
    #pragma unused params
    if (help)
    {
        SendClientMessage(playerid, 0xFF0000AA, "Adds you to the race.");
    }
    else
    {
        Race_PlayerJoin(playerid, gRace);
    }
    return 1;
}

And the very last thing, once everyone has been added to the race. Start it:

pawn Code:

YCMD:start(playerid, params[], help)
{
    #pragma unused params
    if (help)
    {
        SendClientMessage(playerid, 0xFF0000AA, "Begin the race.");
    }
    else
    {
        Race_Start(gRace);
    }
    return 1;
}

Callbacks

This include adds several callbacks that can be used:

pawn Code:

// Called when a player finishes the race.
forward OnPlayerFinishRace(playerid, race, position, prize, time);

// Called when a player drops out of the race.
forward OnPlayerExitRace(playerid, race);

// Called when the race is over.
forward OnRaceEnd(race);

Note that currently none of these are forwarded, nor are they handled by y_hooks.

Race_Create

As mentioned above, this function has a number of optional parameters. They are:

• laps = 0 - The number of laps to run the race for. If this value is "0" then the race is a straight shot to some point. If the value is anything other than "0" then the start checkpoint is also the end checkpoint.
  
  
• entry = 0 - How much a race costs to enter. Set to 0 for a custom entry/prize system. The prize money is relative to the entry cost and the number of people who entered - the first three positions win by default.
  
  
• countdown = 3 - When the race starts players are frozen in place and a timer counting down is shown. By default this goes from 3.
  
  
• arial = false - Is this race for planes (i.e. should it use the donut checkpoints instead of the regular vehicle ones)?
  
  
• fixedPrize = true - Use the default inbuilt prize money system.
  
  
• exitTime = 0 - How many seconds can a player be out of their vehicle during a race before they are disqualified? 0 is infinite.
  
  
• interior = 0 - Is the race in an interior? And if so, which one?
  
  
• world = 0 - The virtual world to host the race in.
  
  
• restart = false - By default, once a race is completed it will be deleted from the system. Set this parameter to "true" to enable the race to be reused.

Note that all of these options also have equivalent "Race_SetXXX" functions that can be called instead.

Position

This include also has experimental code to get a player's position in the race. Simply call:

pawn Code:

Race_GetPlayerPosition(playerid);

As often as you want to update any indication of their position. Note that the information is only updated once every 500 ms (half a second - load balanced).

Download

This is part of YSI:

https://sampforum.blast.hk/showthread.php?tid=194480