### Install R3EXS Gem

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Installs the R3EXS gem using RubyGems. Requires Ruby and Devkit to be installed first. This command fetches and installs the latest version of the tool.

```bash
gem install R3EXS
```

--------------------------------

### R3EXS CLI Translation Workflow (Bash)

Source: https://context7.com/luotat/r3exs/llms.txt

This bash script outlines the complete command-line workflow for translating an RPG Maker VX Ace game using R3EXS. It covers decryption, conversion to JSON, string extraction, manual translation editing, string injection, conversion back to rvdata2, and replacing the original game data. This is suitable for one-time translation projects.

```bash
# Step 1: Decrypt the game archive
R3EXS decrypt -o ./Data ./Game.rgss3a

# Step 2: Convert rvdata2 files to JSON (partial mode for translation)
R3EXS rvdata2_json -s ./Data

# Step 3: Extract all translatable strings
R3EXS ex_strings -s ./JSON

# Step 4: Edit ManualTransFile.json with your translations
# {
#   "Attack": "Attaque",
#   "Defense": "Defense",
#   "Hello!": "Bonjour!",
#   ...
# }

# Step 5: Inject translations back into JSON files
R3EXS in_strings -s ./JSON

# Step 6: Convert JSON files back to rvdata2
R3EXS json_rvdata2 -s ./JSON_NEW

# Step 7: Replace original Data folder with Data_NEW
mv ./Data_NEW/* ./Data/
```

--------------------------------

### Inject Translated Strings with R3EXS.in_strings

Source: https://context7.com/luotat/r3exs/llms.txt

Injects translated strings from a ManualTransFile.json back into JSON game data files. Supports injecting into data files only, or includes script strings. Creates new JSON files in the specified output directory. Includes error handling for missing translation files and script info.

```ruby
require 'R3EXS'
require 'pathname'

target_dir           = Pathname('./JSON')
output_dir           = Pathname('./JSON_NEW')
manualtransfile_path = Pathname('./ManualTransFile.json')

# Basic injection (data files only)
R3EXS.in_strings(target_dir, output_dir, manualtransfile_path, false)
# Arguments: target_dir, output_dir, manualtransfile_path, with_scripts

# Injection with scripts
R3EXS.in_strings(target_dir, output_dir, manualtransfile_path, true)

# Error handling
begin
  R3EXS.in_strings(target_dir, output_dir, manualtransfile_path, true)
rescue R3EXS::ManualTransFilePathError => e
  puts "ManualTransFile.json not found: #{e.manualtransfile_path}"
rescue R3EXS::ScriptsInfoPathError => e
  puts "Scripts_info.json not found: #{e.scripts_info_path}"
end
```

--------------------------------

### Extract Translatable Strings with R3EXS.ex_strings

Source: https://context7.com/luotat/r3exs/llms.txt

Extracts translatable strings from JSON files into a ManualTransFile.json dictionary. Supports extraction of data files only, or includes script strings and symbol strings. Can also separate script strings into a dedicated file. Includes error handling for invalid JSON format and missing directories.

```ruby
require 'R3EXS'
require 'pathname'

target_dir = Pathname('./JSON')
output_dir = Pathname('./')

# Basic extraction (data files only)
R3EXS.ex_strings(target_dir, output_dir, false, false, false)
# Arguments: target_dir, output_dir, with_scripts, with_symbol, with_scripts_separate

# Full extraction with scripts and symbols
R3EXS.ex_strings(target_dir, output_dir, true, true, false)

# Separate scripts strings to ManualTransFile_scripts.json
R3EXS.ex_strings(target_dir, output_dir, true, true, true)

# Error handling
begin
  R3EXS.ex_strings(target_dir, output_dir, true, false, false)
rescue R3EXS::R3EXSJsonFileError => e
  puts "JSON files not in R3EXS format: #{e.json_path}"
rescue R3EXS::JsonDirError => e
  puts "JSON directory not found: #{e.json_dir}"
end
```

--------------------------------

### Inject Strings from JSON with R3EXS CLI

Source: https://context7.com/luotat/r3exs/llms.txt

Injects translated strings from a ManualTransFile.json back into JSON files. Supports including Scripts, specifying custom translation file paths, and custom output directories.

```bash
# Basic injection (excluding Scripts)
R3EXS in_strings ./JSON

# Include Scripts injection
R3EXS in_strings -s ./JSON

# Custom ManualTransFile.json path
R3EXS in_strings -m ./Translations/ManualTransFile.json ./JSON

# Custom output directory
R3EXS in_strings -o ./JSON_Translated ./JSON

# Full injection workflow
R3EXS --verbose in_strings -s -m ./ManualTransFile.json -o ./JSON_NEW ./JSON
```

--------------------------------

### Inject Strings into Ruby Source (Ruby)

Source: https://context7.com/luotat/r3exs/llms.txt

This snippet demonstrates how to use the R3EXS::StringsInjector class to replace strings within Ruby source code based on a provided translation hash. It requires the source code, an Abstract Syntax Tree (AST) representation of the code, and a hash mapping original strings to their translated counterparts. The output is the modified source code with translated strings.

```ruby
translations = {
  "Hello, World!" => "Hola, Mundo!",
  "player_name"   => "nombre_jugador"
}

injector = R3EXS::StringsInjector.new(translations)
binary_source = source_code.dup.force_encoding('ASCII-8BIT')
translated_source = injector.rewrite(binary_source, ast)

puts translated_source
```

--------------------------------

### Deserialize JSON to rvdata2 with R3EXS CLI

Source: https://context7.com/luotat/r3exs/llms.txt

Converts edited JSON files back to binary rvdata2 format. Supports partial deserialization (requires original files), complete deserialization, and specifying custom output directories.

```bash
# Partial deserialization (requires original Data folder)
R3EXS json_rvdata2 ./JSON

# Partial deserialization with explicit original directory
R3EXS json_rvdata2 -r ./Data_Original ./JSON

# Complete deserialization (no original files needed)
R3EXS json_rvdata2 -c ./JSON

# Include Scripts deserialization
R3EXS json_rvdata2 -s ./JSON

# Custom output directory for new rvdata2 files
R3EXS json_rvdata2 -o ./Data_Translated ./JSON

# Full workflow example
R3EXS json_rvdata2 -c -s -o ./Data_NEW ./JSON
```

--------------------------------

### Extract Strings from Ruby Source with R3EXS.StringsExtractor

Source: https://context7.com/luotat/r3exs/llms.txt

Utilizes low-level AST visitor classes (StringsExtractor) with the Prism parser to precisely extract translatable strings from Ruby source code. Can extract string literals and symbols. Demonstrates basic usage for parsing and visiting AST nodes.

```ruby
require 'R3EXS'
require 'prism'

# StringsExtractor - Extract strings from Ruby source
source_code = <<~RUBY
  class Game
    def greet
      puts "Hello, World!"
      @name = :player_name
    end
  end
RUBY

strings = []
extractor = R3EXS::StringsExtractor.new(strings, true)  # with_symbol=true
ast = Prism.parse(source_code).value
extractor.visit(ast)

puts strings  # => ["Hello, World!", "player_name"]
```

--------------------------------

### Serialize rvdata2 to JSON with R3EXS CLI

Source: https://context7.com/luotat/r3exs/llms.txt

Converts binary rvdata2 files to JSON format for editing. Options include serializing only translatable content, complete serialization, and including Scripts, notes, or custom output directories.

```bash
# Serialize only translatable parts (default mode for translation)
R3EXS rvdata2_json ./Data

# Complete serialization (preserves all data)
R3EXS rvdata2_json -c ./Data

# Include Scripts.rvdata2 serialization
R3EXS rvdata2_json -s ./Data

# Include notes attribute serialization
R3EXS rvdata2_json -n ./Data

# Custom output directory
R3EXS rvdata2_json -o ./JSON_Output ./Data

# Full options with verbose output
R3EXS --verbose rvdata2_json -c -s -n -o ./JSON ./Data
```

--------------------------------

### Serialize RVData2 to JSON with R3EXS

Source: https://context7.com/luotat/r3exs/llms.txt

Serializes RVData2 files into JSON format. Supports partial serialization for translatable content or complete serialization including scripts and notes. Includes error handling for corrupted files and missing directories.

```ruby
require 'R3EXS'
require 'pathname'

target_dir = Pathname('./Data')
output_dir = Pathname('./JSON')

# Partial serialization (translatable content only)
R3EXS.rvdata2_json(target_dir, output_dir, false, false, false)
# Arguments: target_dir, output_dir, complete, with_scripts, with_notes

# Complete serialization with scripts and notes
R3EXS.rvdata2_json(target_dir, output_dir, true, true, true)

# Error handling
begin
  R3EXS.rvdata2_json(target_dir, output_dir, false, false, false)
rescue R3EXS::Rvdata2FileError => e
  puts "Corrupted rvdata2 file: #{e.rvdata2_path}"
rescue R3EXS::Rvdata2DirError => e
  puts "Directory not found: #{e.rvdata2_dir}"
end
```

--------------------------------

### Deserialize JSON to RVData2 with R3EXS

Source: https://context7.com/luotat/r3exs/llms.txt

Deserializes JSON files back into RVData2 binary format. Supports partial deserialization by merging translations with original data or complete deserialization. Requires original RVData2 files for partial mode. Includes error handling for invalid JSON files and missing script info.

```ruby
require 'R3EXS'
require 'pathname'

target_dir   = Pathname('./JSON')
output_dir   = Pathname('./Data_NEW')
original_dir = Pathname('./Data')

# Partial deserialization (merges translations with original data)
R3EXS.json_rvdata2(target_dir, output_dir, original_dir, false, false)
# Arguments: target_dir, output_dir, original_dir, complete, with_scripts

# Complete deserialization
R3EXS.json_rvdata2(target_dir, output_dir, original_dir, true, true)

# Error handling
begin
  R3EXS.json_rvdata2(target_dir, output_dir, original_dir, false, true)
rescue R3EXS::RPGJsonFileError => e
  puts "Invalid RPG JSON file: #{e.json_path}"
rescue R3EXS::R3EXSJsonFileError => e
  puts "Invalid R3EXS JSON file: #{e.json_path}"
rescue R3EXS::ScriptsInfoPathError => e
  puts "Scripts_info.json not found: #{e.scripts_info_path}"
end
```

--------------------------------

### Extract Strings to JSON with R3EXS CLI

Source: https://context7.com/luotat/r3exs/llms.txt

Extracts translatable strings from JSON files into a ManualTransFile.json. Options include extracting from Scripts, creating separate files, including symbols, and specifying custom output directories.

```bash
# Extract strings from data files (excluding Scripts)
R3EXS ex_strings ./JSON

# Include Scripts extraction
R3EXS ex_strings -s ./JSON

# Extract Scripts strings to a separate file
R3EXS ex_strings -s -p ./JSON

# Include Symbol extraction from Scripts
R3EXS ex_strings -s -y ./JSON

# Custom output directory
R3EXS ex_strings -o ./Translations ./JSON

# Full extraction with all options
R3EXS --verbose ex_strings -s -p -y -o ./Translations ./JSON
```

--------------------------------

### Decrypt RGSS3A Files with R3EXS

Source: https://context7.com/luotat/r3exs/llms.txt

Decrypts RGSS3A game archive files to a specified output directory. Supports verbose output to show progress or silent operation. Includes error handling for unsupported encryption formats and system errors.

```ruby
require 'R3EXS'

R3EXS.rgss3a_rvdata2('./Game.rgss3a', './Data', true)  # verbose=true

R3EXS.rgss3a_rvdata2('./Game.rgss3a', './Data', false)

begin
  R3EXS.rgss3a_rvdata2('./Game.rgss3a', './Data', false)
rescue R3EXS::RGSS3AFileError => e
  puts "Unsupported encryption format: #{e.message}"
rescue SystemCallError => e
  puts "System error: #{e.message}"
end
```

--------------------------------

### Extract all strings

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Extracts all translatable strings from the JSON files, creating a manual translation file. Can optionally extract scripts and symbols.

```APIDOC
## POST /ex_strings

### Description
Extracts all translatable strings from the JSON files, creating a manual translation file. Can optionally extract scripts and symbols.

### Method
POST

### Endpoint
/ex_strings

### Parameters
#### Path Parameters
- **the *.json dir** (string) - Required - The directory containing the JSON files from which to extract strings.

#### Query Parameters
- **-o, --output_dir** (string) - Optional - The directory where the translation file(s) will be saved. Defaults to the current directory.
- **-p, --with_scripts_separate** (boolean) - Optional - Enables extraction of scripts into a separate file (ManualTransFile_scripts.json). Defaults to false.
- **-s, --with_scripts** (boolean) - Optional - Enables extraction of scripts. Defaults to false.
- **-y, --with_symbol** (boolean) - Optional - Enables extraction of symbols within scripts. Defaults to false.

### Request Example
```bash
# Do not extract Scripts
R3EXS ex_strings ./JSON

# Extract Scripts
R3EXS ex_strings -s ./JSON

# Extract Scripts and separate them into ManualTransFile_scripts.json
R3EXS ex_strings -s -p ./JSON
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful string extraction and the output file path.

#### Response Example
```json
{
  "message": "Strings extracted successfully to ManualTransFile.json"
}
```
```

--------------------------------

### Extract All Strings to JSON

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Extracts all translatable strings from JSON files into a single translation file. Options allow for including script strings (-s) and separating script strings into a distinct file (-p). The output directory for the translation file can be specified with -o.

```bash
// Do not extract Scripts
R3EXS ex_strings ./JSON

// Extract Scripts
R3EXS ex_strings -s ./JSON

// Extract Scripts and separate them into ManualTransFile_scripts.json
R3EXS ex_strings -s -p ./JSON
```

--------------------------------

### Decrypt RGSS3A Archive with R3EXS CLI

Source: https://context7.com/luotat/r3exs/llms.txt

Decrypts and extracts rvdata2 files from a Game.rgss3a archive. Supports specifying an output directory and enabling verbose logging for progress monitoring.

```bash
# Basic decryption - extracts to current directory
R3EXS decrypt ./Game.rgss3a

# Decrypt to a specific output directory
R3EXS decrypt -o ./Data ./Game.rgss3a

# Enable verbose output to see decryption progress
R3EXS --verbose decrypt ./Game.rgss3a
```

--------------------------------

### Deserialize JSON files to rvdata2 file

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Deserializes JSON files back into .rvdata2 format, allowing for the re-injection of translated strings into the game.

```APIDOC
## POST /json_rvdata2

### Description
Deserializes JSON files back into .rvdata2 format, allowing for the re-injection of translated strings into the game.

### Method
POST

### Endpoint
/json_rvdata2

### Parameters
#### Path Parameters
- **the *.json dir** (string) - Required - The directory containing the JSON files to be deserialized.

#### Query Parameters
- **-c, --complete** (boolean) - Optional - Enables complete deserialization. Defaults to false.
- **-o, --output_dir** (string) - Optional - The directory where the new .rvdata2 files will be saved. Defaults to './Data_NEW'.
- **-r, --original_dir** (string) - Optional - The original directory containing .rvdata2 files, required if --complete is not enabled. Defaults to './Data'.
- **-s, --with_scripts** (boolean) - Optional - Enables deserialization of Scripts JSON. Defaults to false.

### Request Example
```bash
# If --complete was not enabled in rvdata2_json
# Provide --original_dir or ensure ./Data folder exists in the current directory
R3EXS json_rvdata2 ./JSON

# If --complete was enabled in rvdata2_json
# --original_dir is not required
R3EXS json_rvdata2 -c ./JSON
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful deserialization and the output directory.

#### Response Example
```json
{
  "message": "JSON files deserialized to rvdata2 successfully in ./Data_NEW"
}
```
```

--------------------------------

### Deserialize JSON to rvdata2

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Deserializes JSON files back into '.rvdata2' format. Requires the directory containing the JSON files. Options include enabling complete deserialization (-c) and specifying original '.rvdata2' directory (-r) if complete serialization was not used. The output directory for the new '.rvdata2' files can be set with -o.

```bash
// If --complete was not enabled in rvdata2_json
// Provide --original_dir or ensure ./Data folder exists in the current directory
R3EXS json_rvdata2 ./JSON

// If --complete was enabled in rvdata2_json
// --original_dir is not required
R3EXS json_rvdata2 -c ./JSON
```

--------------------------------

### Serialize rvdata2 to JSON

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Serializes '.rvdata2' files from a specified directory into JSON format. Options include enabling complete serialization (-c), including notes (-n), and including scripts (-s). The output directory for JSON files can be set with -o.

```bash
// Serialize only translatable parts
R3EXS rvdata2_json ./Data

// Complete serialization
R3EXS rvdata2_json -c ./Data
```

--------------------------------

### Decrypt RGSS3A Archive with R3EXS Ruby API

Source: https://context7.com/luotat/r3exs/llms.txt

Utilizes the R3EXS Ruby API to decrypt Game.rgss3a archives. This method leverages a C extension with SIMD optimizations for high-performance decryption and supports both standard and Fux2Pack2 encryption formats.

```ruby
require 'R3EXS'

# Example usage (assuming R3EXS.rgss3a_rvdata2 is the correct method name)
# R3EXS.rgss3a_rvdata2('path/to/Game.rgss3a', 'output/directory')
```

--------------------------------

### Unpack Game.rgss3a file

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Decrypts the Game.rgss3a file into individual .rvdata2 files. This is the first step to accessing and modifying game data.

```APIDOC
## POST /decrypt

### Description
Decrypts the Game.rgss3a file into individual .rvdata2 files. This is the first step to accessing and modifying game data.

### Method
POST

### Endpoint
/decrypt

### Parameters
#### Path Parameters
- **Game.rgss3a file path** (string) - Required - The path to the Game.rgss3a file to be decrypted.

#### Query Parameters
- **-o, --output_dir** (string) - Optional - The directory where the decrypted .rvdata2 files will be saved. Defaults to the current directory.

### Request Example
```bash
R3EXS decrypt ./Game.rgss3a
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful decryption and the output directory.

#### Response Example
```json
{
  "message": "Game.rgss3a decrypted successfully to ./"
}
```
```

--------------------------------

### Decrypt Game.rgss3a File

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Decrypts the 'Game.rgss3a' file, outputting its contents as '.rvdata2' files. The output directory can be specified using the -o option. This is the first step in accessing game data for translation.

```bash
R3EXS decrypt ./Game.rgss3a
```

--------------------------------

### Serialize rvdata2 files to JSON file

Source: https://github.com/luotat/r3exs/blob/main/README_EN.md

Serializes .rvdata2 files into JSON format, making them easier to edit and manage. Supports selective serialization of notes and scripts.

```APIDOC
## POST /rvdata2_json

### Description
Serializes .rvdata2 files into JSON format, making them easier to edit and manage. Supports selective serialization of notes and scripts.

### Method
POST

### Endpoint
/rvdata2_json

### Parameters
#### Path Parameters
- **the *.rvdata2 dir** (string) - Required - The directory containing the .rvdata2 files to be serialized.

#### Query Parameters
- **-c, --complete** (boolean) - Optional - Enables complete serialization, including all data. Defaults to false.
- **-n, --with_notes** (boolean) - Optional - Enables serialization of notes attributes. Defaults to false.
- **-o, --output_dir** (string) - Optional - The directory where the generated JSON files will be saved. Defaults to './JSON'.
- **-s, --with_scripts** (boolean) - Optional - Enables serialization of Scripts.rvdata2. Defaults to false.

### Request Example
```bash
# Serialize only translatable parts
R3EXS rvdata2_json ./Data

# Complete serialization
R3EXS rvdata2_json -c ./Data
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful serialization and the output directory.

#### Response Example
```json
{
  "message": "rvdata2 files serialized to JSON successfully in ./JSON"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.