Skip to content

feat(gta-core-five): add replace_ptxclipregions_file manifest statement to override particle clip-region data#4060

Open
eryxiz wants to merge 1 commit into
citizenfx:masterfrom
eryxiz:feat/replace-ptxclipregions-file
Open

feat(gta-core-five): add replace_ptxclipregions_file manifest statement to override particle clip-region data#4060
eryxiz wants to merge 1 commit into
citizenfx:masterfrom
eryxiz:feat/replace-ptxclipregions-file

Conversation

@eryxiz

@eryxiz eryxiz commented Jul 10, 2026

Copy link
Copy Markdown

Goal of this PR

Let a resource replace ptxclipregions.dat, the particle-texture UV clip-region
table, through a new replace_ptxclipregions_file manifest statement.

Custom particle assets can already be streamed, but if a particle uses a custom
texture atlas whose frame layout differs from the base game there is currently no
way to tell the engine how that atlas is split into frames, so such particles fall
back to the full-texture default (0,1,0,1) and render incorrectly. This gives
creators a way to supply the matching clip-region data.

ptxclipregions_patch.mp4

How is this PR achieving the goal

Adds a replace_ptxclipregions_file 'file.dat' manifest statement, parsed in
citizen-resources-gta.

The game parses ptxclipregions.dat once at ptfx init and keeps the pointers
rage::ptxClipRegions::GetData returns alive for the process lifetime, so
rebuilding its table in place would dangle them. Instead, this hooks GetData
(the single accessor every particle draw goes through) and serves the
resource-provided overrides from its own store, leaving the game's table
untouched; lookups that miss fall through to the original.

The store is populated when the resource mounts and cleared on disconnect. Reads
use a shared_mutex with an atomic fast-path, and the backing pool is
append-only so the pointers handed back stay valid.

Resource usage:

-- fxmanifest.lua
files {
    'ptxclipregions.dat',
}

replace_ptxclipregions_file 'ptxclipregions.dat'

The file must be declared in files{} so the client downloads it and the VFS can
read it.

This PR applies to the following area(s)

FiveM

Successfully tested on

Game builds: 2372, 2545, 2612, 2699, 2802, 2944, 3095, 3258, 3323, 3407, 3570

Platforms: Windows

Checklist

  • Code compiles and has been tested successfully.
  • Code explains itself well and/or is documented.
  • My commit message explains what the changes do and what they are for.
  • No extra compilation warnings are added by these changes.

@github-actions github-actions Bot added the invalid Requires changes before it's considered valid and can be (re)triaged label Jul 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

invalid Requires changes before it's considered valid and can be (re)triaged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant