CHF Editor — Star Citizen Character Preset Inspector & Controlled Editor

Inspect, diff, validate, and make narrowly scoped changes to Star Citizen .chf character presets (v7/v8) with a local Python GUI and CLI.

CHF Editor is a public-source Star Citizen character preset tool for examining .chf files, comparing character DNA presets, exploring DNA regions and weights, inspecting ItemPorts and materials, and creating controlled variants. It is designed for reproducible technical investigation rather than blind preset rewriting.

The application runs locally on Windows, preserves the original input, refuses to overwrite an existing output, and does not include character presets, extracted game files, or game assets.

Note

CHF Editor is an unofficial community project and is not affiliated with or endorsed by Cloud Imperium Games.

Important

A structurally valid file is not proof that Star Citizen will load it, save it, or show the intended visual change. Test those outcomes separately in the game.

At a glance

Game / format	Star Citizen character presets, CHF v7/v8
Interfaces	Tkinter GUI and Python CLI
Core workflows	Inspect, compare/diff, controlled DNA variants, controlled material variants, validation
Platform	Windows
Compression	Zstandard through a compatible native libzstd.dll
Data model	Local-first; bring your own legally obtained .chf files
License	PolyForm Noncommercial License 1.0.0

What you can do

Task	Available now
Explore a Star Citizen character preset	View its structure, DNA regions, ItemPorts, materials, and available evidence in the GUI.
Compare two CHF files	Inspect logical differences with the diff command or GUI.
Test a DNA change	Change one weight and balance it with another weight in the same region.
Test a material change	Change one existing float or color component with an exact source SHA-256 guard.
Validate an export	Check size, CRC32C, Zstandard bounds, v7/v8 structure, and the expected logical diff; re-read the result independently.

The tool does not render characters, compose complete character recipes, automatically infer visual meaning from unverified fields, or act as a general-purpose save editor.

What is validated?

The catalog records 9 material observations and 5 DNA observations on historical references in LIVE 4.10.193.11644. Validation is specific to the tested preset, field context and build.

On 2026-10-07, the owner validated the six positive screenshot-backed material effects on those references. The catalog and GUI record that acceptance without promoting ambiguous or negative results, or transferring it to a new preset. See validation status.

Evidence	Current status
Freckles opacity; hair, beard and eyebrow melanin	Historical visible effects and authenticated saved values in the tested contexts.
Root hair dye, isolated red channel	Historical visible effect; re-save fingerprint incomplete. A secondary copy had no visible effect and was reset on saving.
Dye Amount and Natural Color Variation	Bounded UI associations; visible effect not isolated.
Female Nose, Mouth and linked Eye regions	Recorded region-level UI pairs; effects reported or inconclusive. Individual contributors remain unknown.
Other DNA regions, male UI-region mappings, individual head IDs, general value ranges	Not validated as editing controls. Source names and file structure alone are insufficient.

In the two reviewed private v8 exports, 91/93 female and 109/111 male material occurrences have no matching catalog observation; 9/13 female and 13/13 male DNA regions have no matching UI evidence. All material parameters in those files have source names, which does not establish their effects. Counts vary by file, and a matching historical observation still needs validation on a new preset. Read the complete validation status for separate loading, saving, visible-effect and negative-result details.

Get started

Requirements

• Windows
• Python 3
• Tkinter for the GUI
• A compatible native Zstandard DLL (libzstd.dll) for CHF operations
• Your own legally obtained Star Citizen .chf character preset files

Clone and launch the GUI:

git clone https://github.com/ussmarines/.chf-editor.git
cd .chf-editor
python gui.py

In the GUI, select your Zstandard DLL and browse for local presets. The tabs cover Overview, DNA, ItemPorts, Materials, Diff, and Evidence. No game installation path is built into the application.

Use Detect / check to verify the native library with an actual compression/decompression roundtrip. The GUI and CLI also accept CHF_ZSTD_DLL and can detect an existing DLL in standard Python library locations. Nothing is downloaded automatically. The material editor defaults to Catalog observations; choose Observed visual changes for positive historical evidence or All raw parameters for unvalidated experiments. Values are raw CHF values, not BioCorp percentages.

Command-line examples

Set the DLL path once in your PowerShell session:

$dll = 'C:\path\to\libzstd.dll'
python chf.py --zstd-dll $dll inspect 'C:\presets\character.chf'
python chf.py --zstd-dll $dll diff 'C:\presets\before.chf' 'C:\presets\after.chf'

Create a single controlled DNA experiment:

python chf.py --zstd-dll $dll variant 'C:\presets\source.chf' 'C:\presets\nose-test.chf' --part Nose --slot 0 --balance-slot 1 --value 12000 --game-version 'LIVE build' --control 'manual Nose weight experiment'

The CLI also provides variant-param for one existing material value. Run python chf.py variant-param --help for its required source hash, field indices, and value options. Every export includes an experiment manifest; keep it with your local test files.

Evidence and safety

Report four results independently: file structure, loading in the game, saving by the game, and visible effect. A field name or a result from one preset does not establish the same behavior for another preset.

Keep presets, manifests, screenshots, videos, and extracted game files private. Store local experiments under outputs/, which Git excludes. Review your changes before opening a pull request; automated checks look for common sensitive patterns in changed files but cannot detect everything.

Documentation

Guide	Purpose
Controlled game comparison	Make comparable before/after saves and captures.
CHF format	Understand the supported v7/v8 container and payload.
Editing workflow	Preserve a source, make one change, and validate each result.
Architecture	See the reader, evidence catalog, writer, and GUI boundaries.
Remaining work	Follow the phase-one validation and mapping priorities.
Experiments and evidence	Understand the published evidence and its limits.
Mapping revalidation	Review rechecked historical observations, source-label coverage, and provenance gaps.
Validation status	See what is validated, negative, inconclusive, or still unknown, and how guided editing uses that evidence.
Agent workflow	Run bounded experiments with clear provenance.
Tools and skills	Find official sources and set up a fork.
Archive integration	See what was retained from the supplied Starfall research.
Security policy	Report vulnerabilities privately.

Contribute

Contributions are welcome: bug reports, documentation corrections, focused code changes, and reproducible findings about the CHF format.

Open an issue for a proposal or submit a pull request with a focused change, relevant checks, and a clear description of evidence and limitations. Read the contribution guide before submitting. Please do not include private character files or personal data.

License and support

The code is available under the PolyForm Noncommercial License 1.0.0. Contributions and forks must respect its noncommercial terms and preserve the required copyright and attribution notice.

You may support the project through PayPal.