Game environment

Environment settings

vcmpError PluginFuncs.SetServerOption(vcmpServerOption option, uint8_t toggle)

Sets a boolean server flag.

Parameters:
  • option (vcmpServerOption) – The option to toggle on or off
  • toggle (uint8_t) – 1 to enable, 0 to disable
Raises:

vcmpErrorArgumentOutOfBounds if the server does not support the option given.

See also:

vcmpServerOption

uint8_t PluginFuncs.GetServerOption(vcmpServerOption option)

Checks if a boolean server flag is enabled.

Parameters:
Returns:

1 if enabled, 0 if disabled

Raises:

vcmpErrorArgumentOutOfBounds if the server does not support the option given.

Note

You must call PluginFuncs.GetLastError() to check if an error condition was raised.

void PluginFuncs.SetWorldBounds(float maxX, minX, maxY, minY)

Sets the boundaries of the game world. Players who attempt to travel beyond these boundaries will automatically and uncontrollably jump toward the acceptable play area.

Parameters:
  • maxX (float) – The maximum X coordinate of the new play area
  • minX (float) – The minimum X coordinate of the new play area
  • maxY (float) – The maximum Y coordinate of the new play area
  • minY (float) – The minimum Y coordinate of the new play area

Note

Although this plugin call always succeeds, VC:MP prevents any entity from traveling outside the boundaries (-2350.0, -1950.0, -200.0), (1550.0, 1950.0, 20000.0) as traveling outside these bounds causes the game to crash.

void PluginFuncs.GetWorldBounds(float* maxXOut, float* minXOut, float* maxYOut, float* minYOut)

Gets the boundaries of the game world.

Parameters:
  • maxXOut (float*) – Pointer to a float to store the maximum X coordinate in
  • minXOut (float*) – Pointer to a float to store the minimum X coordinate in
  • maxYOut (float*) – Pointer to a float to store the maximum Y coordinate in
  • minYOut (float*) – Pointer to a float to store the minimum Y coordinate in
void PluginFuncs.SetWastedSettings(uint32_t deathTimer, uint32_t fadeTimer, float fadeInSpeed, float fadeOutSpeed, uint32_t fadeColour, uint32_t corpseFadeStart, uint32_t corpseFadeTime)
void PluginFuncs.GetWastedSettings(uint32_t* deathTimerOut, uint32_t* fadeTimerOut, float* fadeInSpeedOut, float* fadeOutSpeedOut, uint32_t* fadeColourOut, uint32_t* corpseFadeStartOut, uint32_t* corpseFadeTimeOut)
void PluginFuncs.SetTimeRate(int32_t timeRate)
Parameters:
  • timeRate (int32_t) – The number of milliseconds it takes for one game second to elapse, or 0 to stop time
Default:

0 (time does not move by default)

int32_t PluginFuncs.GetTimeRate(void)
Returns:The number of milliseconds it takes for one game second to elapse
void PluginFuncs.SetHour(int32_t hour)
Parameters:
  • hour (int32_t) – The new in-game hour
Default:

12

int32_t PluginFuncs.GetHour(void)
Returns:The current in-game hour
void PluginFuncs.SetMinute(int32_t minute)
Parameters:
  • hour (int32_t) – The new in-game minute
Default:

0

int32_t PluginFuncs.GetMinute(void)
Returns:The current in-game minute
void PluginFuncs.SetWeather(int32_t weather)
Parameters:
  • hour (int32_t) – The new in-game weather
See also:

weather

Default:

0

int32_t PluginFuncs.GetWeather(void)
Returns:The current in-game weather
See also:weather
void PluginFuncs.SetGravity(float gravity)
Parameters:
  • gravity (float) – The new gravitational rate of acceleration
Default:

0.008

float PluginFuncs.GetGravity(void)
Returns:The current gravitational rate of acceleration
void PluginFuncs.SetGameSpeed(float gameSpeed)
Parameters:
  • gameSpeed (float) – The new game speed
Default:

1.0

float PluginFuncs.GetGameSpeed(void)
Returns:The current game speed
void PluginFuncs.SetWaterLevel(float waterLevel)
Parameters:
  • waterLevel (float) – The new water level
Default:

6.0

float PluginFuncs.GetWaterLevel(void)
Returns:The current water level
void PluginFuncs.SetMaximumFlightAltitude(float height)

Sets the height at which helicopters and planes will stop ascending.

Parameters:
  • height (float) – The new maximum flight altitude
Default:

10000.0

float PluginFuncs.GetMaximumFlightAltitude(void)
Returns:The current maximum flight altitude
void PluginFuncs.SetKillCommandDelay(int32_t delay)

Sets how many milliseconds must pass after a player uses the /kill command before they actually die. If higher than 25000ms (25 seconds), players will not be able to kill themselves using the built-in /kill command.

Parameters:
  • delay (int32_t) – The new command delay
Default:

0

int32_t PluginFuncs.GetKillCommandDelay(void)
Returns:The current kill command delay
void PluginFuncs.SetVehiclesForcedRespawnHeight(float height)

Sets the height above which unoccupied vehicles will respawn by themselves. Used to prevent vehicles from becoming inaccessible if players fly them too high to be streamed to other players and then quit the server.

Parameters:
  • height (float) – The new forced respawn height
Default:

200.0

float PluginFuncs.GetVehiclesForcedRespawnHeight(void)
Returns:The current forced respawn height

World interactions

vcmpError PluginFuncs.CreateExplosion(int32_t worldId, int32_t type, float x, float y, float z, int32_t responsiblePlayerId, uint8_t atGroundLevel)

Creates an explosion at a certain location and optionally attributes the explosion to a particular player.

Parameters:
  • worldId (int32_t) – The virtual world to create the explosion in
  • type (int32_t) – The explosion type
  • x (float) – The X coordinate for the explosion
  • y (float) – The Y coordinate for the explosion
  • z (float) – The Z coordinate for the explosion; ignored if atGroundLevel is true
  • responsiblePlayerId (int32_t) – The ID of the player to attribute the explosion to, or -1 to attribute to no particular player
  • atGroundLevel (uint8_t) – If 1, creates an explosion on the ground regardless of the given Z coordinate. Otherwise, creates explosion at the given Z coordinate.
Raises:

vcmpErrorArgumentOutOfBounds if type is less than 0 or greater than 11.

vcmpErrorNoSuchEntity if no player with the given player ID exists.

Note

Explosions can be created for a specific player only by creating an explosion in their unique world. See PluginFuncs.GetPlayerUniqueWorld().

vcmpError PluginFuncs.PlaySound(int32_t worldId, int32_t soundId, float x, float y, float z)

Plays a sound at a certain location.

Parameters:
  • worldId (int32_t) – The virtual world to create the sound in
  • soundId (int32_t) – The ID of the sound to play
  • x (float) – The X coordinate for the sound
  • y (float) – The Y coordinate for the sound
  • z (float) – The Z coordinate for the sound

Note

Sounds can be created for a specific player only by creating an sound in their unique world. See PluginFuncs.GetPlayerUniqueWorld().

Note

If either the X, Y or Z coordinate are set to NaN, the sound will not play at a particular position in the world and will instead play at full volume regardless of where players are.

void PluginFuncs.HideMapObject(int32_t modelId, int16_t tenthX, int16_t tenthY, int16_t tenthZ)

Hides a default object in the game world.

Parameters:
  • modelId (int32_t) – The ID of the object model to hide
  • tenthX (int16_t) – The X coordinate for the object, multiplied by 10 and rounded off as a 16-bit integer.
  • tenthY (int16_t) – The Y coordinate for the object, multiplied by 10 and rounded off as a 16-bit integer.
  • tenthZ (int16_t) – The Z coordinate for the object, multiplied by 10 and rounded off as a 16-bit integer.

Note

If you intend to hide every single Vice City map object, you should create an empty file named store/maps/hidevicecity.txt in the server directory instead.

void PluginFuncs.ShowMapObject(int32_t modelId, int16_t tenthX, int16_t tenthY, int16_t tenthZ)

Unhides a default object in the game world.

Parameters:
  • modelId (int32_t) – The ID of the object model to unhide
  • tenthX (int16_t) – The X coordinate for the object, multiplied by 10 and rounded off as a 16-bit integer.
  • tenthY (int16_t) – The Y coordinate for the object, multiplied by 10 and rounded off as a 16-bit integer.
  • tenthZ (int16_t) – The Z coordinate for the object, multiplied by 10 and rounded off as a 16-bit integer.
void PluginFuncs.ShowAllMapObjects(void)

Unhides any and all default game map objects that were previously hidden by PluginFuncs.HideMapObject().

Map/radar blips

int32_t PluginFuncs.CreateCoordBlip(int32_t index, int32_t world, float x, float y, float z, int32_t scale, uint32_t colour, int32_t sprite)

Creates a map blip that appears on the radar and main menu map.

Parameters:
  • index (int32_t) – An index for the blip; if the index is already used by another map blip, the server will try to use another index instead
  • world (int32_t) – The virtual world to create the icon in
  • x (float) – The X coordinate for the map icon
  • y (float) – The Y coordinate for the map icon
  • z (float) – The Z coordinate for the map icon
  • scale (int32_t) – The scale of the blip, between 0 and 2 inclusive
  • colour (uint32_t) – The colour for the map icon, if applicable
  • sprite (int32_t) – The type of map icon to create, or 0 to create a plain coloured blip
Returns:

The actual index assigned to the map blip

Raises:

vcmpErrorPoolExhausted if there is no space for more map blips.

Note

You must call PluginFuncs.GetLastError() to check if an error condition was raised.

vcmpError PluginFuncs.DestroyCoordBlip(int32_t index)

Deletes a map blip.

Parameters:
  • index (int32_t) – The index of the map blip to delete
Raises:

vcmpErrorNoSuchEntity if no such map blip exists.

vcmpError PluginFuncs.GetCoordBlipInfo(int32_t index, int32_t* worldOut, float* xOut, float* yOUt, float* zOut, int32_t* scaleOut, uint32_t* colourOut, int32_t* spriteOut)

Gets information about a map blip.

Parameters:
  • index (int32_t) – The index of the map blip to get information for
  • worldOut (int32_t*) – A pointer to an int32_t to store the blip’s world in
  • xOut (float*) – A pointer to a float to store the blip’s X coordinate in
  • yOut (float*) – A pointer to a float to store the blip’s Y coordinate in
  • zOut (float*) – A pointer to a float to store the blip’s Z coordinate in
  • scaleOut (int32_t*) – A pointer to an int32_t to store the blip’s scale in
  • colourOut (uint32_t*) – A pointer to an uint32_t to store the blip’s colour in
  • spriteOut (int32_t*) – A pointer to an int32_t to store the blip’s sprite in
Raises:

vcmpErrorNoSuchEntity if no such map blip exists.

Radio streams

vcmpError PluginFuncs.AddRadioStream(int32_t radioId, const char* radioName, const char* radioUrl, uint8_t isListed)

Creates a radio stream pointing to an internet audio stream that can be used as an in-game radio station.

Parameters:
  • radioId (int32_t) – An index for the stream; if the index is already used by another radio stream, the server will try to use another index instead
  • radioName (const char*) – The name of the radio station to show when changing stations in a vehicle
  • radioUrl (const char*) – The URL for the radio stream
  • isListed (uint8_t) – 1 if this station should appear in the in-vehicle radio station scroll cycle. 0 if the server should be required to assign this radio station to a vehicle.
Returns:

The actual index assigned to the map blip

Raises:

vcmpErrorPoolExhausted if there is no space for more radio stations.

Note

You must call PluginFuncs.GetLastError() to check if an error condition was raised.

vcmpError PluginFuncs.RemoveRadioStream(int32_t radioId)

Deletes a radio stream.

Parameters:
  • index (int32_t) – The index of the radio stream to delete
Raises:

vcmpErrorNoSuchEntity if no such radio stream exists.

Entity status

uint8_t PluginFuncs.CheckEntityExists(vcmpEntityPool entityPool, int32_t index)
Parameters:
  • entityPool (vcmpEntityPool) – The entity pool to check against
  • index (int32_t) – The index of the entity to check for the existence of
Returns:

1 if an entity with the given index exists in the given pool. 0 otherwise.