Custom peds
Use the complete exported ped pack, including its definition, textures and variation metadata.
Place the files
Section titled “Place the files”With resources.pack.path = "client", a ped pack can use this layout:
client/└── assets/ └── harbor_worker/ ├── content.xml ├── peds.meta └── stream/ ├── harbor_worker.ydd ├── harbor_worker.yft ├── harbor_worker.ymt └── harbor_worker.ytdKeep the filenames and dependencies supplied with the pack. The files above illustrate a typical layout. Individual models can have a different asset set. Preserve any component folders and texture dictionaries from the export.
The content.xml in this folder creates a resource root. Its paths resolve
from assets/harbor_worker/. For an RPF pack, follow
RPF archives.
Register the ped definition
Section titled “Register the ped definition”Add this content.xml alongside peds.meta:
<?xml version="1.0" encoding="UTF-8"?><CDataFileMgr__ContentsOfDataFileXml> <dataFiles> <Item> <filename>peds.meta</filename> <fileType>PED_METADATA_FILE</fileType> </Item> </dataFiles></CDataFileMgr__ContentsOfDataFileXml>Use the peds.meta supplied with the pack. Its model name and references must
match the exported assets. In this example, the model is named harbor_worker.
Models, textures and variation files are discovered automatically.
Choose a unique name for an addon ped. If you rename it, update the asset names and metadata references together. A different resource folder does not isolate identically named assets. See Names and loading order.
Create a ped
Section titled “Create a ped”Publish the resources, restart the server to select the release, then restart GTA through the helper for the new asset set.
This server example creates an NPC near the beach in dimension 0. Replace
harbor_worker with the model name declared in your peds.meta and choose a
position suitable for testing:
// @ts-check/// <reference types="@revomp/types-server" />import * as revo from 'revo-server';
const ped = new revo.Ped( 'harbor_worker', { x: -1225, y: -1765, z: 3.9 }, Math.PI,);Run the example from a configured server entry point. The heading is in radians. Clients load the model when the ped enters their stream. The constructor returns the server object immediately.
Client code that needs the GTA ped can use entityStreamIn or check ready on
an existing reference. See Streaming and readiness.
Use ped.destroy() on the server to remove the NPC.
The same model name can be passed to LocalPed in a client script for a local
preview. To change an existing player’s model, assign
the name harbor_worker to the player’s modelHash on the server. Model changes load
asynchronously on clients.
Appearance and testing
Section titled “Appearance and testing”Component and prop variations depend on the model. Use setComponentVariation
and setProp with drawable and texture indices supplied by that ped. Clothing
indices from a freemode model may refer to different items or be unavailable.
Face blending, face features, overlays and hair colours apply to
mp_m_freemode_01 and mp_f_freemode_01. A custom ped’s face and hair are defined
by its exported assets and supported variations.
Check the ped’s body, textures and any supplied variations. Test the animations and vehicle interactions your mode uses, then leave streaming range and return. With two clients, check its appearance from both views.
| Symptom | Check |
|---|---|
| The ped never appears | Verify the model name, exported files and PED_METADATA_FILE declaration. Confirm the player is nearby and in the same dimension. |
| Parts of the body or textures are missing | Check the drawable, texture and variation files supplied with the model, including their names and references. |
| Clothing or props do not change | Check that the model provides the requested drawable and texture indices. |
| Animations distort the model | Check the exported skeleton, rig and compatibility with the animations being used. |
| Loading fails or GTA crashes when the ped appears | Check the complete asset set, variation metadata and referenced dependencies for compatibility with the installed game build. |
Check the client logs
for metadata errors such as failed to load data file. Include the reported
path and type when investigating a pack.
Changes to ped definitions, variation metadata or the asset set require a GTA restart. Follow the restart rules when publishing updates.
For scripted movement and task recovery, see NPCs and scripted behavior.