Additional asset types
Animation dictionaries, particle assets and native audio packs use the same resource discovery as models and maps.
| Asset | Loading requirements |
|---|---|
Animation dictionary (.ycd) |
Discovered automatically. Request the dictionary before playing a clip. |
Particle dictionary (.ypt) |
Discovered automatically. Request the dictionary before starting an effect. |
Native audio data (.rel) and wave packs (.awc) |
Declare the audio metadata and wave-pack folder in content.xml. |
Animation and particle dictionaries
Section titled “Animation and particle dictionaries”With resources.pack.path = "client", a pack can use this layout:
client/└── assets/ └── harbor_effects/ └── stream/ ├── harbor_animations.ycd └── harbor_particles.yptThese two dictionaries need no content.xml declarations. Include any additional
files referenced by the export, such as texture dictionaries.
In a client script, request the animation dictionary with
natives.requestAnimDict(name) and wait for natives.hasAnimDictLoaded(name)
before playing a clip. Use the dictionary and clip names supplied by the asset
author.
For particles, call natives.requestNamedPtfxAsset(name) and wait for
natives.hasNamedPtfxAssetLoaded(name). Select the dictionary with
natives.useParticleFxAsset(name) before starting the effect. The effect name
is defined inside the dictionary.
Both requests are asynchronous. Check readiness on later frames and give the
request a timeout so an invalid name cannot leave the script waiting forever.
The native functions above are exported by the natives module.
Native GTA audio packs
Section titled “Native GTA audio packs”A pack containing game audio data, sound definitions and a wave bank can use:
client/└── assets/ └── harbor_audio/ ├── content.xml └── audio/ ├── harbor_game.dat151.rel ├── harbor_sounds.dat54.rel └── sfx/ └── harbor_bank/ └── harbor.awcRegister the supplied audio data and wave-pack folder in content.xml:
<?xml version="1.0" encoding="UTF-8"?><CDataFileMgr__ContentsOfDataFileXml> <dataFiles> <Item> <filename>audio/harbor_game.dat</filename> <fileType>AUDIO_GAMEDATA</fileType> </Item> <Item> <filename>audio/harbor_sounds.dat</filename> <fileType>AUDIO_SOUNDDATA</fileType> </Item> <Item> <filename>audio/sfx/harbor_bank</filename> <fileType>AUDIO_WAVEPACK</fileType> </Item> </dataFiles></CDataFileMgr__ContentsOfDataFileXml>The .dat paths are logical names passed to GTA. Keep the physical
.dat151.rel and .dat54.rel suffixes on the exported files.
AUDIO_WAVEPACK names the folder containing the .awc files.
All paths resolve from the folder containing this content.xml.
Use the actual names and declarations supplied with the pack. Audio data can refer to specific banks, sound sets and other data files. Preserve those references when organizing the files.
Playback uses the pack’s authored sound names and the appropriate GTA audio natives or vehicle metadata. Registering the pack makes its definitions available. A script still needs to start the sound, or a vehicle definition needs to reference the audio configuration.
For MP3, Ogg Vorbis and other supported standalone audio files, use
Audio or LocalAudio with a
resources:// URI. Those files do not need native audio declarations.
Other metadata types
Section titled “Other metadata types”Streaming extensions and metadata types are resolved through the installed game build. Files with an unrecognized streaming extension are skipped by native asset registration.
For metadata, declare the appropriate GTA fileType and resource-relative
path in content.xml. The type must exist in the game build and have an
available loader. The path can identify a file, logical name or folder,
depending on that type, as the audio example shows.
The client logs distinguish these failures:
| Message | Meaning |
|---|---|
unsupported data file type |
GTA does not recognize the declared fileType. |
data file mounter ... is unavailable after game loaded |
The type has no available loader after startup. |
failed to load data file |
GTA’s loader rejected the file or declaration. Check the format, path and dependencies. |
raw streaming registration failed |
A recognized streaming asset could not be registered. |
Check playback or the intended gameplay behavior after loading. A successful registration log only confirms that the asset was accepted by the loader.
Updating these assets
Section titled “Updating these assets”Adding or removing native assets requires a GTA restart. Changes to particle
dictionaries, native audio data, wave packs or content.xml also require one.
An existing .ycd can be replaced during reconnect when GTA can release it
and the rest of the bundle remains compatible. Follow any restart message
shown by the client. See the
resource update workflow.