VORP Core Characters API Documentation

This documentation covers the VORP Core Framework Characters API for developers creating scripts and integrations.

Table of Contents

1. Events
2. Functions
3. StateBags

Events

Character-related events are triggered during character selection, creation, and other character lifecycle events.

Events > Character Joined Event

This event is triggered when a player has successfully selected a character and joined the server. It provides an opportunity to execute custom logic or initialize player-specific data based on the chosen character.

Availability: Both client and server side

-- CLIENT
AddEventHandler("vorp_core:Client:OnPlayerJoined", function()
  -- Player has joined with their character
  -- Initialize client-side character-specific data
end)

-- SERVER
AddEventHandler("vorp_core:Server:OnPlayerJoined", function(source)
  -- Player has joined with their character
  -- Initialize server-side character-specific data
end)

Use Cases:

• Initialize player-specific data when character is selected
• Set up character-dependent systems
• Load character-specific configurations
• Trigger welcome messages or tutorials

Events > Character Created Event

This event is triggered when a player has created a new character for the server.

-- CLIENT
AddEventHandler("vorp_core:Client:OnCharacterCreated", function()
  -- New character has been created
  -- Handle client-side new character logic
end)

-- SERVER
AddEventHandler("vorp_core:Server:OnCharacterCreated", function(source)
  -- New character has been created
  -- Handle server-side new character logic
end)

Example Usage Case: Someone might use this to create/select a first spawn location for a character, set up default inventory items, or initialize character-specific databases.

Use Cases:

• Set first spawn location for new characters
• Initialize default inventory items
• Create character-specific database entries
• Set up default character settings
• Trigger character creation tutorials

Functions

Character-related functions for managing character appearance and data.

Functions > Get All Components

This function retrieves all components in the player's cache. It is useful for updating or modifying the player's appearance based on the components stored in the cache.

local components = exports.vorp_character:GetAllComponents()

Returns:

• components - Table containing all cached player components

Use Cases:

• Updating player appearance
• Modifying cached components
• Saving current appearance state
• Synchronizing appearance across systems

Example Usage:

local components = exports.vorp_character:GetAllComponents()
if components then
  -- Process or modify components
  for componentType, componentData in pairs(components) do
    print("Component Type:", componentType)
    print("Component Data:", json.encode(componentData))
  end
end

StateBags

StateBags provide efficient access to character state information that can be checked from other scripts.

StateBags > Bandana State

Check if a player is wearing a bandana on their face. This can be used in other scripts to detect bandana usage through the characters bandana commands.

-- CLIENT
local isBandanaOn = LocalPlayer.state.BandanaState

-- SERVER  
local isBandanaOn = Player(source).state.BandanaState

Returns:

• true - Player is wearing a bandana on their face
• false - Player is not wearing a bandana

Use Cases:

• Hide player identity in criminal activities
• Modify player recognition systems
• Trigger bandana-specific interactions
• Law enforcement identification systems

Example Usage:

-- Check bandana state before revealing player identity
if not LocalPlayer.state.BandanaState then
  -- Player face is visible, show name
  DisplayPlayerName()
else
  -- Player is wearing bandana, show generic identifier
  DisplayGenericIdentifier()
end

StateBags > Character Shop State

Check if a player is currently in character shops (clothing stores, barbers, etc.).

-- CLIENT
local inCharacterShop = LocalPlayer.state.InCharacterShop

-- SERVER
local inCharacterShop = Player(source).state.InCharacterShop

Returns:

• true - Player is currently in a character shop
• false - Player is not in a character shop

Use Cases:

• Prevent certain actions while in shops
• Disable conflicting systems during character customization
• Track shop usage analytics
• Manage shop-specific interactions

Example Usage:

-- Prevent certain actions while in character shop
if LocalPlayer.state.InCharacterShop then
  -- Player is in shop, disable conflicting features
  DisableControlAction(0, 24, true) -- Attack
  DisableControlAction(0, 25, true) -- Aim
else
  -- Player is not in shop, normal controls available
end

Integration Examples > Complete Character Event Handler

-- Server-side character management
AddEventHandler("vorp_core:Server:OnPlayerJoined", function(source)
  print("Player " .. source .. " joined with character")
  
  -- Check if wearing bandana
  if Player(source).state.BandanaState then
    print("Player is wearing a bandana")
  end
  
  -- Check if in character shop
  if Player(source).state.InCharacterShop then
    print("Player is in a character shop")
  end
  
  -- Get character components
  TriggerClientEvent("getCharacterComponents", source)
end)

AddEventHandler("vorp_core:Server:OnCharacterCreated", function(source)
  print("New character created by player " .. source)
  
  -- Set up new character defaults
  -- Initialize spawn location, inventory, etc.
end)

Integration Examples > Client-Side Character Component Management

-- Client-side component handling
RegisterNetEvent("getCharacterComponents")
AddEventHandler("getCharacterComponents", function()
  local components = exports.vorp_character:GetAllComponents()
  
  if components then
    -- Send components back to server for processing
    TriggerServerEvent("processCharacterComponents", components)
  end
end)

-- Monitor character shop state
CreateThread(function()
  local wasInShop = false
  
  while true do
    local inShop = LocalPlayer.state.InCharacterShop
    
    if inShop and not wasInShop then
      print("Entered character shop")
      -- Handle shop entry
    elseif not inShop and wasInShop then
      print("Exited character shop")
      -- Handle shop exit
    end
    
    wasInShop = inShop
    Wait(1000)
  end
end)

Notes

• Character events are fired on both client and server sides for maximum flexibility
• StateBags provide efficient real-time access to character state information
• The GetAllComponents function is useful for appearance management systems
• Bandana state affects player identification and recognition systems
• Character shop state helps manage conflicting interactions during customization
• Events can be used to initialize character-specific data and systems
• Always check if data exists before processing to avoid errors