Ped Camera System

The Ped Camera System provides a specialized camera designed for close-up character viewing, perfect for character customization, showcasing outfits, or detailed character inspection. This system offers more restrictive movement than the orbital camera, optimized for pedestrian/character focus.

Basic Usage

To enable the Ped Camera inside of your resource file just add usePedCam() useControllablePedCam() inside your code like example below.

usePedCam()
useControllablePedCam()

Features

Character-focused camera with restricted movement
Close-range operation with tight distance controls
Limited vertical movement to maintain character focus
Z-position adjustment for fine-tuned camera height
Smooth interpolation for natural camera movement
Collision detection optimized for character viewing

Core Functions

Initialization

`EnablePedCam`

Enables the ped camera system and starts the main camera loop.

Returns: number - Handle for the camera instance

Example:

local cameraHandle = EnablePedCam()

`DisablePedCam`

Disables the ped camera system and returns to gameplay camera.

Parameters:

immediately (boolean, optional) - If true, disables immediately without interpolation

Example:

DisablePedCam(false) -- Smooth transition
DisablePedCam(true)  -- Immediate disable

Position Control

`SetPedCamLookAtPosition`

Sets the target position that the camera will focus on.

Parameters:

position (vector3) - World coordinates to focus on

Example:

local pedPosition = GetEntityCoords(playerPed)
SetPedCamLookAtPosition(pedPosition)

`GetPedCamLookAtPosition`

Gets the current look-at position.

Returns: vector3 - Current target position

Distance Control

`SetPedCamDistanceToLookAtPos`

Sets the distance from the camera to the target position.

Parameters:

distance (number) - Distance in game units

Example:

SetPedCamDistanceToLookAtPos(2.5) -- Close-up view

`GetPedCamDistanceToLookAtPos`

Gets the current distance to the target position.

Returns: number - Current distance

`SetPedCamMinDistanceToLookAtPos`

Sets the minimum allowed distance for the ped camera.

Parameters:

minDistance (number) - Minimum distance in game units

`SetPedCamMaxDistanceToLookAtPos`

Sets the maximum allowed distance for the ped camera.

Parameters:

maxDistance (number) - Maximum distance in game units

Angle Control

`SetPedCamAngleX`

Sets the horizontal rotation angle around the target.

Parameters:

angle (number) - Angle in degrees (0-360)
disableInterpolation (boolean, optional) - Skip smooth interpolation

Example:

SetPedCamAngleX(90.0) -- Side view of character

`AddPedCamAngleX`

Adds to the current horizontal angle.

Parameters:

addAngle (number) - Degrees to add to current angle
disableInterpolation (boolean, optional) - Skip smooth interpolation

`SetPedCamAngleY`

Sets the vertical rotation angle (pitch). Note: This is restricted to prevent extreme angles.

Parameters:

angle (number) - Angle in degrees (limited to -5° to 5°)
disableInterpolation (boolean, optional) - Skip smooth interpolation

Restrictions:

Minimum angle: -5° (looking slightly down)
Maximum angle: 5° (looking slightly up)
Important: Currently always sets to 0° regardless of input

`AddPedCamAngleY`

Adds to the current vertical angle.

Parameters:

addAngle (number) - Degrees to add to current angle
disableInterpolation (boolean, optional) - Skip smooth interpolation

Z-Position Control

`SetPedCamPositionZ`

Sets the Z-offset for the camera's look-at position, allowing fine height adjustment.

Parameters:

posZ (number) - Z-offset in game units (limited to -0.80 to 0.70)
disableInterpolation (boolean, optional) - Skip smooth interpolation

Restrictions:

Minimum Z-offset: -0.80 (lower view)
Maximum Z-offset: 0.70 (higher view)

Example:

SetPedCamPositionZ(0.5) -- Raise camera focus point

`AddPedCamPositionZ`

Adds to the current Z-position offset.

Parameters:

addOffset (number) - Offset to add to current Z-position
disableInterpolation (boolean, optional) - Skip smooth interpolation

`GetPedCamPositionZ`

Gets the current Z-position offset.

Returns: number - Current Z-offset (defaults to 0 if not set)

Status Functions

`IsPedCamCreated`

Checks if the ped camera is currently active.

Returns: boolean - True if camera exists

`GetPedCamId`

Gets the internal camera ID.

Returns: number - Camera ID or nil if not created

Complete Usage Example

Here's a comprehensive example showing how to set up a ped camera for character viewing:

local gPedCamPreviewIsEnabled = false

function Game.StartPedCam(entityId)
    if entityId then
        -- Get camera position offset from the entity
        local cameraPosition = GetOffsetFromEntityInWorldCoords(
            entityId, 
            0.13,  -- X offset (slightly to the side)
            0.0,   -- Y offset (no front/back offset)
            0.05   -- Z offset (slightly up)
        )
        
        -- Configure camera settings
        SetPedCamLookAtPosition(cameraPosition)
        SetPedCamDistanceToLookAtPos(3.0)        -- Medium distance
        SetPedCamMinDistanceToLookAtPos(0.4)     -- Very close minimum
        SetPedCamMaxDistanceToLookAtPos(3.0)     -- Moderate maximum
        SetPedCamAngleY(0)                       -- Neutral vertical angle
        
        -- Enable the controllable ped camera
        EnableControllablePedCam()
        gPedCamPreviewIsEnabled = true
    end
end

function Game.StopPedCam()
    DisableControllablePedCam(true)
    ClearFocus()
    gPedCamPreviewIsEnabled = false
end

Key Differences from Orbital Camera

Movement Restrictions

The Ped Camera has several built-in restrictions designed for character viewing:

Vertical Angle Limits: Y-angle is restricted to -5° to 5° (and currently forced to 0°)
Z-Position Limits: Z-offset is restricted to -0.80 to 0.70 game units
Closer Operation: Designed for much closer distances than orbital camera

Optimized for Characters

Default distance ranges are much smaller (0.4 to 3.0 units vs 3.0 to 7.0)
Z-position adjustment allows fine-tuning of character focus height
More restrictive movement prevents awkward camera angles

Advanced Configuration

Character Customization Setup

function setupCharacterCustomizationCamera(playerPed)
    local pedCoords = GetEntityCoords(playerPed)
    
    -- Focus on character's torso area
    SetPedCamLookAtPosition(pedCoords)
    SetPedCamDistanceToLookAtPos(1.5)  -- Close for detail
    SetPedCamMinDistanceToLookAtPos(0.8)
    SetPedCamMaxDistanceToLookAtPos(2.5)
    
    -- Adjust height to focus on torso/face
    SetPedCamPositionZ(0.3)  -- Raise focus point
    
    EnablePedCam()
end

Dynamic Height Adjustment

function adjustCameraForClothing(clothingType)
    if clothingType == "hat" or clothingType == "hair" then
        SetPedCamPositionZ(0.6)  -- Focus on head
    elseif clothingType == "shirt" or clothingType == "jacket" then
        SetPedCamPositionZ(0.2)  -- Focus on chest
    elseif clothingType == "pants" or clothingType == "shoes" then
        SetPedCamPositionZ(-0.3) -- Focus on lower body
    end
end

Best Practices

Use appropriate distance ranges - Keep distances small for character detail
Utilize Z-position adjustment - Fine-tune the height focus for different body parts
Consider entity offsets - Use GetOffsetFromEntityInWorldCoords() for precise positioning
Handle character movement - Update look-at position if character moves
Test angle restrictions - Remember that Y-angles are heavily restricted

Performance Notes

Optimized collision detection for close-range operation
Same interpolation smoothing as orbital camera (factor 5.0)
Efficient state management with minimal memory footprint
Runs at 60 FPS for smooth character viewing

Troubleshooting

Camera too close/far:

Adjust min/max distance settings
Check if entity position is correct

Cannot look up/down:

This is by design - Y-angle is restricted to maintain character focus
Use Z-position adjustment instead for height changes

Jerky movement:

Ensure stable frame rate
Check for conflicting camera systems or input handlers

PreviousProgress Bar System NextOrbital Camera System

Last updated 2 months ago