🎨 FiveM Tattoo Extractor

The Ultimate High-Performance GTA V & FiveM Tattoo Pipeline

Extract, filter, smart-crop, resize, and convert ~1,800 GTA V tattoos in seconds.
Generates CDN-ready folders, clean WebP/PNG thumbnails, TypeScript definitions, and ready-to-use configs for QBCore, ESX, illenium-appearance, rcore_tattoos, and custom NUI React/Vue interfaces.

Language: English | Polski

💡 Why FiveM Tattoo Extractor?

In vanilla GTA V, tattoos are scattered across hundreds of encrypted RPF archives (ped_mp_overlay_txds.rpf) and messy DLC patchday subfolders. Furthermore:

Many texture files contain internal shader render targets (tat_rt_*), hair overlays, makeup, facepaint, or flannel shirt patterns that are NOT genuine body tattoos.
Raw textures often have massive empty transparent borders and irregular aspect ratios that look terrible in custom shop UIs.
Managing tattoo files manually for FiveM NUI requires weeks of manual extracting, cropping, renaming, and JSON/Lua writing.

FiveM Tattoo Extractor solves all of this automatically in under 15 seconds.

🌟 Key Features

⚡ Blazing Fast Parallel Processing: Uses all CPU cores to extract, crop, resize, and convert ~1,800 textures concurrently in seconds.
📂 Flat & Clean CDN Hierarchy: Eliminates messy DLC folders (basegame/, mp2023_02/, mpbiker/). Outputs files directly as: <gender>/<zone>/<tattoo_name>.<ext> (e.g. male/torso/mp_biker_tat_000.webp).
✂️ Smart Alpha Trimming & Centering: Automatically detects non-transparent pixel bounds, crops redundant transparent margins, and centers tattoos on clean square canvases with preserved aspect ratios.
🎯 Anti-Junk Tattoo Filtering: Eliminates render targets (tat_rt_*), hires clones (*_hires), specular/normal maps (_n, _s), hair overlays, badges, makeup, and shirts.
🎮 Custom FiveM Addon Scanner: Point to any custom addon folder (stream/*.ytd) to extract and generate configs for custom tattoo packs.
🔌 Framework Exporters: Generates ready-to-paste configs for QBCore, ESX, illenium-appearance, and rcore_tattoos.
🖼️ Built-in Live Preview Gallery: Search, filter by gender/zone, and click any tattoo card to open a full-resolution zoom modal with complete Jenkins hash, price, and dimension details.
📐 Custom Resolution & WebP Compression: Choose 128x128, 256x256, 512x512, 1024x1024, or Original size, with lossless or lossy WebP (quality 50–100%).
🌓 Modern Dark / Light Theme: Discord/VSCode inspired dark palette with instant runtime toggle.
📊 Excel / CSV & TypeScript Outputs: Outputs tattoos.csv for in-game economy balancing and tattoos.d.ts for frontend TypeScript development.
📦 Automated ZIP Packager: Automatically packages the entire output directory into tattoos_cdn.zip ready for Cloudflare R2 / AWS S3 / VPS hosting.
🌍 9 Languages with OS Auto-Detection: Instant live switching between English, Polski, Deutsch, Español, Français, Português, Italiano, Русский, and 中文.
💻 Headless CLI Mode: Run seamlessly in CI/CD pipelines and automated server scripts with command-line flags.
🔄 GitHub Auto-Update Checker: Checks GitHub Releases in the background on startup and notifies you of new versions.
🛑 Graceful Job Cancellation: Stop any running extraction safely without freezing or terminating the application.

⚙️ How It Works

flowchart TD
    A[GTA V Directory / Addon Folder] --> B[CodeWalker RPF Engine & AES Decryption]
    B --> C[Metadata Parser: shop_tattoo.meta & *_overlays.xml]
    C --> D[Build & Junk Filter: Build <= 3095, Anti-rt/hair/makeup]
    D --> E[Multi-Core Parallel Processor]
    E --> F[Smart Alpha Cropping & Centering]
    E --> G[Lanczos3 Resizing: 128/256/512/1024]
    E --> H[Lossless/Lossy WebP / PNG / DDS Encoders]
    F & G & H --> I[Flat CDN Directory Structure: male/ female/]
    I --> J[tattoos.json + tattoos.lua + tattoos.d.ts + tattoos.csv]
    I --> K[Framework Configs: Illenium, QBCore, RCore, ESX]
    I --> L[tattoos_cdn.zip Package]

RPF Scanning & AES Decryption: Utilizes the official open-source CodeWalker.Core library to scan GTA V RPF archives and decrypt assets using native GTA5 keys.
Metadata Association: Reads shop_tattoo.meta and *_overlays.xml files to resolve preset names, labels, prices, collections, and body zones (ZONE_HEAD, ZONE_TORSO, ZONE_LEFT_ARM, etc.).
Build Cutoff Filtering: Excludes newer DLC packs if a specific build (e.g. Build 3095) is selected.
Image Processing Pipeline: Decodes DDS DXT5 textures to 32-bit RGBA, detects non-transparent pixel bounding boxes, crops borders, applies Lanczos-3 interpolation, and encodes to lossless WebP/PNG.
Deduplication & FiveM Output: Merges patchday textures cleanly to ensure zero duplicate collisions and writes comprehensive JSON, Lua, CSV, and TypeScript files.

📁 Output Directory Structure

output_folder/
├── male/
│   ├── head/
│   │   └── mp_2023_02_tat_008.webp
│   ├── torso/
│   │   ├── mp_biker_tat_000.webp
│   │   └── mp_2023_02_tat_004.webp
│   ├── left_arm/
│   ├── right_arm/
│   ├── left_leg/
│   └── right_leg/
│
├── female/
│   ├── head/
│   ├── torso/
│   ├── left_arm/
│   ├── right_arm/
│   ├── left_leg/
│   └── right_leg/
│
├── tattoos.json            <-- Full dataset for React / Vue / Svelte NUI Frontends
├── tattoos.lua             <-- Standard FiveM Lua Config table
├── tattoos_illenium.lua    <-- Ready for illenium-appearance
├── tattoos_qb.lua          <-- Ready for qb-tattoos / qb-clothing
├── tattoos_rcore.lua       <-- Ready for rcore_tattoos
├── tattoos_esx.lua         <-- Ready for esx_tattooshop
├── tattoos.d.ts            <-- TypeScript Type Definitions
├── tattoos.csv             <-- Excel / Google Sheets spreadsheet
├── tattoos_cdn.zip         <-- (Optional) Ready-to-upload CDN package
├── manifest.json           <-- Complete metadata manifest
└── report.json             <-- Extraction metrics & VRAM statistics

🚀 Step-by-Step Usage Guide

1. Launch the Application

Download the latest executable from Releases or build it from source.
Run TattooExtractor3095.exe.

2. Configure Paths

Folder GTA V: Auto-detected automatically. Or click Browse... to select your GTA V installation (e.g. C:\Program Files\Epic Games\GTAV or C:\Program Files (x86)\Steam\steamapps\common\Grand Theft Auto V).
Folder wynikowy / Output Folder: Choose an empty destination directory on your disk.
CDN URL (Optional): If you host images on a CDN, enter your URL (e.g. https://cdn.myserver.com/tattoos).
Addony FiveM (Optional): If you have custom server tattoos, select their stream/ folder.

3. Choose Settings & Filters

Select your desired Format (WebP, PNG, DDS).
Choose Resolution (256x256 recommended for FiveM NUI).
Select your target GTA V Build (Default: Build 3095 (The Chop Shop)).
Adjust WebP Quality (100% Lossless recommended).
Set an optional Price Multiplier (e.g. 1.5x or 2.0x for in-game economy balance).

4. Start Extraction

Click EKSPORTUJ DLA FIVEM UI.
In ~15 seconds, all images, configs, and datasets will be generated.
Click Otwórz folder / Open Folder to view your files, or switch to the 🖼️ Galeria / Gallery tab to browse your tattoos!

🔌 FiveM Framework Integrations

1. React / Vue / Svelte NUI Frontends

Import tattoos.json and use the built-in image or cdnUrl fields:

import tattoos from './tattoos.json';
import type { TattooItem } from './tattoos';

export const TattooCard = ({ item }: { item: TattooItem }) => (
  <div className="tattoo-card">
    <img 
      src={item.cdnUrl || `https://cdn.myserver.com/tattoos/${item.image}`} 
      alt={item.label}
      loading="lazy"
    />
    <h4>{item.label}</h4>
    <p>${item.price.toLocaleString()}</p>
    <span>{item.zone}</span>
  </div>
);

2. illenium-appearance

Replace or extend your tattoos.lua in illenium-appearance with the generated tattoos_illenium.lua:

Config.TattooList = {
    ['torso'] = {
        { name = 'MP_MP_Biker_Tat_000_M', label = 'TAT_BI_000', collection = 'mpbiker_overlays', hashMale = 'MP_MP_Biker_Tat_000_M', hashFemale = 'MP_MP_Biker_Tat_000_F', zone = 'ZONE_TORSO', price = 1000, image = 'male/torso/mp_biker_tat_000.webp' },
    },
}

3. QBCore (qb-tattoos / qb-clothing)

Use tattoos_qb.lua directly in your QBCore tattoo resource:

Config.TattooList = {
    ['MP_MP_Biker_Tat_000_M'] = { label = 'TAT_BI_000', collection = 'mpbiker_overlays', hash = GetHashKey('MP_MP_Biker_Tat_000_M'), price = 1000, zone = 'ZONE_TORSO', gender = 'male', image = 'male/torso/mp_biker_tat_000.webp' },
}

4. rcore_tattoos

Copy tattoos_rcore.lua into your rcore_tattoos configuration.

5. ESX (esx_tattooshop)

Copy tattoos_esx.lua into your esx_tattooshop config file.

🖼️ Interactive Live Preview Gallery

The application includes a built-in interactive Live Gallery:

Click the 🖼️ Galeria / Gallery tab.
Click Wczytaj z folderu wynikowego / Load from Output Folder.
Search tattoos by name or label in real time.
Filter by gender (male, female) or body zone (head, torso, left_arm, right_arm, left_leg, right_leg).
Click on any tattoo thumbnail to open a high-resolution detail modal displaying Jenkins Hash, exact dimensions, pricing, and texture name.

🎮 Custom FiveM Addon Scanner

Have custom addon tattoos on your server?

In the Addony FiveM (opcja) field, select your addon resource's folder (containing .ytd files and optional .xml / .meta overlay definitions).
The extractor will automatically:
- Extract and crop all textures inside custom .ytd files.
- Match overlay metadata and assign zones and labels.
- Include custom addon tattoos in tattoos.json, tattoos.lua, and all framework configs.

💻 CLI / Headless Automation

Automate tattoo extractions in your CI/CD pipelines, Docker containers, or server build scripts:

# Run headless extraction
fivem-tattoo-extractor.exe \
  --gta "C:\Program Files\Epic Games\GTAV" \
  --out "./tattoos_output" \
  --cdn "https://cdn.myserver.com/tattoos" \
  --build 3095 \
  --res 256 \
  --format webp

CLI Options Reference

Flag	Short	Description	Default
`--gta`	`-g`	Path to GTA V installation directory	Required
`--out`	`-o`	Output directory path	`./tattoos_output`
`--cdn`	`-c`	CDN Base URL (e.g. `https://cdn.example.com/tattoos`)	`""`
`--build`	`-b`	GTA V Build Cutoff (`3095`, `3258`, `3323`, `99999`)	`3095`
`--res`	`-r`	Thumbnail resolution (`128`, `256`, `512`, `1024`, `0` = original)	`256`
`--format`	`-f`	Image format (`webp`, `png`, `dds`)	`webp`

🎮 Supported GTA V Builds

Build	Update Name	Primary DLC Packs
Build 3407+	2025 Updates	`mp2025_01`+
Build 3323	Agents of Sabotage	`mp2024_02`
Build 3258	Bottom Dollar Bounties	`mp2024_01`
Build 3095	The Chop Shop (Default FiveM)	`mp2023_02`
Build 2944	San Andreas Mercenaries	`mp2023_01`
Build 2802	Los Santos Drug Wars	`mpchristmas3`
Build 2699	The Criminal Enterprises	`mpsum2`
Build 2545	The Contract	`mpsecurity`
Build 2372	Los Santos Tuners	`mptuner`
Build 2189	Cayo Perico Heist	`mpheist4`
Build 2060	Los Santos Summer Special	`mpsum`
Build 1604	Arena War	`mpchristmas2018`

🛠️ Building from Source

Prerequisites

.NET 8.0 SDK
Windows 10/11 (x64)

Build Commands

# 1. Clone repository
git clone https://github.com/00Kubi/fivem-tattoo-extractor.git
cd fivem-tattoo-extractor

# 2. Restore NuGet dependencies
dotnet restore

# 3. Build & Publish Release binary
dotnet publish -c Release -r win-x64 --self-contained false -p:PublishSingleFile=true -o ./publish

🏗️ Architecture & Tech Stack

TattooExtractor3095/
├── Core/
│   ├── Extractor.cs            # Multi-threaded extraction pipeline coordinator
│   ├── BuildFilter.cs          # GTA V build & DLC cutoff filter
│   ├── TattooFilter.cs         # Smart anti-junk & zone normalization logic
│   ├── ImageExporter.cs        # Alpha bounds cropping, Lanczos3 resize & WebP encoding
│   ├── FrameworkGenerators.cs  # QBCore, ESX, Illenium, RCore config generators
│   ├── CustomAddonScanner.cs   # Custom FiveM resource stream scanner
│   ├── CsvExporter.cs          # Excel/CSV dataset generator
│   ├── TypeScriptGenerator.cs  # TypeScript definition generator
│   ├── ZipPackager.cs          # ZIP archive packager
│   └── UpdateChecker.cs        # GitHub Releases version check
├── Forms/
│   ├── MainForm.cs             # Tabbed Windows Forms GUI
│   └── GalleryViewer.cs        # Tattoo detail & zoom modal
├── Localization/
│   └── I18n.cs                 # 9-language translation engine with OS detection
├── Models/
│   ├── TattooModels.cs         # Strongly-typed data models
│   └── TattooWorkItem.cs       # Thread work-item model
├── UI/
│   └── Theme.cs                # Dark & Light UI theme engine
├── Utils/
│   ├── HashUtils.cs            # Jenkins 32-bit Hash & string sanitization
│   └── SoundUtils.cs           # Audio chime feedback
└── Program.cs                  # CLI parser & application bootstrap

📄 License

Distributed under the MIT License. See LICENSE for more information.

_{Built with ❤️ for the FiveM & GTA V Modding Community.}

Navigation Menu

Repository files navigation

🎨 FiveM Tattoo Extractor

The Ultimate High-Performance GTA V & FiveM Tattoo Pipeline

📖 Table of Contents

💡 Why FiveM Tattoo Extractor?

🌟 Key Features

⚙️ How It Works

📁 Output Directory Structure

🚀 Step-by-Step Usage Guide

1. Launch the Application

2. Configure Paths

3. Choose Settings & Filters

4. Start Extraction

🔌 FiveM Framework Integrations

1. React / Vue / Svelte NUI Frontends

2. illenium-appearance

3. QBCore (qb-tattoos / qb-clothing)

4. rcore_tattoos

5. ESX (esx_tattooshop)

🖼️ Interactive Live Preview Gallery

🎮 Custom FiveM Addon Scanner

💻 CLI / Headless Automation

CLI Options Reference

🎮 Supported GTA V Builds

🛠️ Building from Source

Prerequisites

Build Commands

🏗️ Architecture & Tech Stack

📄 License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
Core		Core
Forms		Forms
Localization		Localization
Models		Models
UI		UI
Utils		Utils
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Program.cs		Program.cs
README.md		README.md
README.pl.md		README.pl.md
fivem-tattoo-extractor.csproj		fivem-tattoo-extractor.csproj

Latest commit

History

Folders and files

Repository files navigation

🎨 FiveM Tattoo Extractor

The Ultimate High-Performance GTA V & FiveM Tattoo Pipeline

📖 Table of Contents

💡 Why FiveM Tattoo Extractor?

🌟 Key Features

⚙️ How It Works

📁 Output Directory Structure

🚀 Step-by-Step Usage Guide

1. Launch the Application

2. Configure Paths

3. Choose Settings & Filters

4. Start Extraction

🔌 FiveM Framework Integrations

1. React / Vue / Svelte NUI Frontends

2. illenium-appearance

3. QBCore (qb-tattoos / qb-clothing)

4. rcore_tattoos

5. ESX (esx_tattooshop)

🖼️ Interactive Live Preview Gallery

🎮 Custom FiveM Addon Scanner

💻 CLI / Headless Automation

CLI Options Reference

🎮 Supported GTA V Builds

🛠️ Building from Source

Prerequisites

Build Commands

🏗️ Architecture & Tech Stack

📄 License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages