Player

This page describes the player API

Get players

playerList()

Retrieves all online player IDs.

Details
Example

Remarks

Arguments

Type

Description

Returns

Player IDs collection.

// TODO

Spawn

playerSpawn(player)

Spawns the player.

Details
Example

Remarks

Subsequent calls will re-spawn the player.

Make sure you set health to a valid value, since Spawn method doesn't take care of that.

Arguments

Type

Description

player

Player ID

Returns

0 if successful, -1 if failed

oak.event('playerConnect', async pid => {
console.log('[info] player connected', pid)
oak.playerPositionSet(pid, [-1774.59301758, -4.88487052917, -2.40491962433])
oak.playerHealthSet(pid, 200)
oak.playerSpawn(pid)
})

​Despawn

playerDespawn(player)

Removes the player from the map.

Details
Example

Remarks

Useful when you want to create a spectator mode in your game.

Arguments

Type

Description

player

Player ID

Returns

0 if successful, -1 if failed

oak.cmd('spectator', async pid => {
oak.playerDespawn(pid)
})

Invalid

playerInvalid(player)

Checks whether the player ID is invalid.

Details
Example

Remarks

None.

Arguments

Type

Description

player

Player ID

Returns

0 if invalid

oak.cmd('respawn', async pid => {
if (await oak.playerInvalid(pid)) {
oak.log('Not happy ;1')
return
}
oak.playerDespawn(pid)
})

Kick

playerKick(player, string)

Kicks the player from the game.

Details
Example

Remarks

Useful when you want to create a spectator mode in your game.

Arguments

Type

Description

player

Player ID

string

Reason

Returns

0 if successful, -1 if failed

oak.cmd('kickme', async pid => {
oak.playerKick(pid, 'You were a bad boy!')
})

Kill

playerKill(player)

Force kills the player.

Details
Example

Remarks

Kills the player naturally.

Arguments

Type

Description

player

Player ID

Returns

0 if successful, -1 if failed

oak.cmd('suicide', async pid => {
oak.playerKill(pid)
})

Play anim

playerDespawn(player, string)

Removes the player from the map.

Details
Example

Remarks

There is no animation list provided, search game folder for possible animation names.

Arguments

Type

Description

player

Player ID

string

Animation file name

Returns

0 if successful, -1 if failed

// TODO

Set model

playerModelSet(player, string)

Changes the player model.

Details
Example

Remarks

You can use models from the following listing.

Arguments

Type

Description

player

Player ID

string

Model name

Returns

0 if successful, -1 if failed

oak.cmd('tommy', async pid => {
oak.playerModelSet(pid, 'Tommy')
})

Set health

playerHealthSet(player, float)

Sets the player health.

Details
Example

Remarks

At the moment, this method expects a raw value the game uses to specify health. Maximum health is based off of the mission data, so some maps use value 200, while others can be over 600.

We will make sure health is uniform on the server-side, but right now, you need to set health to 200 if you want full health on freeride map.

Arguments

Type

Description

player

Player ID

float

Health value

Returns

0 if successful, -1 if failed

oak.cmd('healme', async pid => {
oak.playerHealthSet(pid, 200)
})

Set position

playerPositionSet(player, vec3)

Sets the player position.

Details
Example

Remarks

None.

Arguments

Type

Description

player

Player ID

vec3

Array of 3 float values

Returns

0 if successful, -1 if failed

oak.cmd('setpos', async (pid, _x, _y, _z) => {
const x = parseFloat(_x)
const y = parseFloat(_y)
const z = parseFloat(_z)
oak.playerPositionSet(pid, [x, y, z])
})

Set direction

playerDirectionSet(player, vec3)

Sets the player's forward direction vector.

Details
Example

Remarks

None.

Arguments

Type

Description

player

Player ID

vec3

Array of 3 float values

Returns

0 if successful, -1 if failed

oak.cmd('setdir', async (pid, _x, _y, _z) => {
const x = parseFloat(_x)
const y = parseFloat(_y)
const z = parseFloat(_z)
oak.playerDirectionSet(pid, [x, y, z])
})

Set heading

playerHeadingSet(player, float)

Sets the player heading angle.

Details
Example

Remarks

Uses a ±180 degree format.

Arguments

Type

Description

player

Player ID

float

±180 degree angle

Returns

0 if successful, -1 if failed

oak.cmd('rotateto', async (pid, angle) => {
oak.playerHeadingSet(pid, parseFloat(angle))
})

Get name

playerNameGet(player)

Retrieves the player name.

Details
Example

Remarks

None.

Arguments

Type

Description

player

Player ID

Returns

string player name

oak.cmd('alert', async pid => {
const name = await oak.playerNameGet(pid)
oak.chatBroadcast('Guess who is back: ' + name)
})

Get model

playerModelGet(player)

Retrieves the player's model.

Details
Example

Remarks

None.

Arguments

Type

Description

player

Player ID

Returns

string player model name

// TODO

Get health

playerHealthGet(player)

Retrieves the current player's health.

Details
Example

Remarks

At the moment, this method returns a raw value the game uses to specify health. Maximum health is based off of the mission data, so some maps use value 200, while others can be over 600.

We will make sure health is uniform on the server-side, but right now, you need to be aware that full health differs per mission and freeride uses value of 200.

Arguments

Type

Description

player

Player ID

Returns

float player health

oak.cmd('printhp', async pid => {
const hp = parseFloat(await oak.playerHealthGet(pid))
oak.chatSend('Current HP: ' + hp)
})

Get heading

playerHeadingGet(player)

Retrieves the player's heading angle.

Details
Example

Remarks

Uses a ±180 degree format.

Arguments

Type

Description

player

Player ID

Returns

float heading angle

// TODO

Get position

playerPositionGet(player)

Retrieves the player position.

Details
Example

Remarks

None.

Arguments

Type

Description

player

Player ID

Returns

vec3 array of 3 float values

oak.cmd('getpos', async pid => {
const pos = await oak.playerPositionGet(pid)
oak.chatSend(pid, 'My position: ' + pos)
})

Get direction

playerDirectionGet(player)

Retrieves the player direction.

Details
Example

Remarks

Retrieves the player's forward vector direction.

Arguments

Type

Description

player

Player ID

Returns

vec3 array of 3 float values

// TODO

Visibility

There are several visibility options you can set for the player:

Name

Description

VISIBILITY_NAME

Player nameplate visibility

VISIBILITY_ICON

Player's blip visibility on the map

Get visibility

playerVisibilityGet(player, visibility_type)

Retrieves the current player's visibility.

Details
Example

Remarks

None.

Arguments

Type

Description

player

Player ID

visibility_type

Visibility option

Returns

int player visibility option value

// TODO

Set visibility

playerVisibilitySet(player, visibility_type, int)

Sets the current player's visibility setting.

Details
Example

Remarks

None.

Arguments

Type

Description

player

Player ID

visibility_type

Visibility option

int

Visibility state

Returns

0 if successful

// TODO