Skip to content

Faces, overlays and hair

Face customization applies to mp_m_freemode_01 and mp_f_freemode_01. Use the server’s Ped methods for players and NPCs, or the same methods on a client-created LocalPed for a preview.

setHeadBlendData() sets the base face by blending parent shapes and skin tones:

Fields Purpose
shapeFirst, shapeSecond Parent indices for facial shape.
skinFirst, skinSecond Parent indices for skin tone. They can differ from the shape parents.
shapeMix, skinMix Blend amounts from 0 to 1 for shape and skin respectively.
shapeThird, skinThird, thirdMix Optional third parent indices and their influence. All default to 0.

Parent indices must be integers from 0 to 255 and available in the loaded game build. Here, 255 is the numeric upper limit and has no special default meaning. If a parent is unavailable, clients skip applying the face settings.

Use setFaceFeature(feature, scale) to adjust individual features of that face. The PedFaceFeature enum includes nose width, jaw shape, chin length and other sliders. Each accepts -1 to 1, with 0 leaving that feature at the head blend’s base shape.

Set the head blend before applying these details. Calling a face, overlay or hair colour setter without one creates a blend with all parent indices set to 0. Changing the blend later keeps the stored sliders, overlays and colours.

This server example sets a head blend, two facial features, eyebrows and hair on a male freemode ped. Set the model when creating the NPC or before applying the player’s character appearance.

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
/** @param {revo.Ped} ped A player or NPC using mp_m_freemode_01. */
export function applyFace(ped) {
ped.setHeadBlendData({
shapeFirst: 21,
shapeSecond: 0,
skinFirst: 21,
skinSecond: 0,
shapeMix: 0.35,
skinMix: 0.6,
});
ped.setFaceFeature(revo.PedFaceFeature.NoseWidth, -0.2);
ped.setFaceFeature(revo.PedFaceFeature.JawWidth, 0.15);
ped.setHeadOverlay(revo.PedHeadOverlay.Eyebrows, 2, 0.85);
ped.setHeadOverlayColor(
revo.PedHeadOverlay.Eyebrows,
revo.PedOverlayColorType.Hair,
3,
);
ped.setComponentVariation(revo.PedComponent.Hair, 4, 0);
ped.setHairColor(3, 7);
}

setHeadOverlay(overlay, index, opacity) selects details such as facial hair, eyebrows, makeup, freckles or ageing. Use PedHeadOverlay to select the slot.

Indices start at 0. Pass -1 to remove an overlay. Opacity ranges from 0 to 1 and defaults to 1. An unavailable index leaves the overlay disabled.

For overlays that support tinting, call setHeadOverlayColor() with the appropriate palette:

PedOverlayColorType Overlays
Hair Facial hair, eyebrows and chest hair.
Makeup Blush and lipstick.
Default Overlays that use their own colours.

Colour indices range from 0 to 63. The optional second colour defaults to 0. Selecting a colour keeps the overlay’s current index and opacity. Enable the overlay with setHeadOverlay() to make it visible.

The hairstyle uses PedComponent.Hair. setHairColor(color, highlight) sets its base and highlight colours, both from 0 to 63. Highlight defaults to 0. For hairstyle selection and resets, see Ped clothing and props.

Client scripts can query the available selections through natives:

Query Result
getPedHeadBlendFirstIndex(type) and getPedHeadBlendNumHeads(type) First parent index and count for each of the four parent groups, with type from 0 to 3.
getPedHeadOverlayNum(overlay) Number of variations for that overlay slot.
getNumPedHairTints() Number of hair colours.
getNumPedMakeupTints() Number of makeup colours.

Use these counts when building the editor’s options, within the API ranges above. The full list of overlay indices accepted by the API is -1 to 254. For colour swatches, getPedHairTintColor(index) and getPedMakeupTintColor(index) return [undefined, red, green, blue].

Match the preview to the spawned character

Section titled “Match the preview to the spawned character”

Keep one appearance record for the character, including the model, all head blend fields, sliders, overlay selections and colours, hairstyle and hair colours. Apply that record to the LocalPed preview and, after server validation, to the player. The server’s stored appearance is synchronized with other clients.

When reusing a preview for another character, also apply that character’s defaults. Set unused facial sliders to 0 and unused overlays to -1 so selections from the previous character are cleared. The head blend setter keeps those selections.

Local preview setup and camera placement are covered separately.

Server Ped · Client LocalPed · Head blend fields