The goal of this project is to implement parsers for uncommon game files and save them in widely used format. Supports a variety of files for EA games Need For Speed series 1 - 6. Right now I'm focused on The Need For Speed SE (1996) game only, however some files, like FSH, were used even in NFS HP 2 (2002)

Feel free to contribute

3-in-1 solution

This project, apart from file parsers themselves, provides:

1. Conversion of resources to common widely used format

Various kinds of game resources can be easily converted to formats:

• 3D models: obj, blend, glb
• archives: directory
• audio: wav
• fonts: fnt + png (raster Windows Font). Nice edit tool: https://snowb.org/
• images: png
• info files (palette, positions, skipped resources etc.): txt
• metadata: json
• videos: mp4

Output files are directly used in my project The Need For Speed Web

2. Knowledge base of resource formats

At this moment, this repo contains the fullest publicly available documentation of formats, used in TNFS SE (PC version). The documentation is auto-generated from this repo's parsers source code

Observe documentation

3. GUI application

Project provides a full-featured GUI application where you can:

• Open and view any supported game resource file
• Edit resource files (experimental feature - use with caution)
• Convert resources to common formats with customizable settings
• Configure system settings (paths to Blender and FFmpeg executables)
• Run custom commands on specific file types

Roadmap and Milestones

Milestones are AI-generated to guide public planning and will evolve over time.

• View the roadmap: docs/milestones.md

Installation:

These are required for both release artifacts and development mode:

• If you need to convert audio/video files - install ffmpeg
• If you need to convert 3D models - install blender (version 4+)

The GUI application runs in a native web view (powered by pywebview) on Windows + MacOS, so it looks and feels like a standalone desktop app, no external browser is required: it uses the OS-native web renderer (WebView2 on Windows, WebKit on macOS). On linux, it requires browser to be installed on the system. Recomended browser is Chrome

Release Artifacts (Recommended for Windows and MacOS)

You can use pre-built installer from the Releases page.

Windows/MacOS:

1. Download nfs-resources-converter-windows-setup-<version>.
2. Run the installer to install the application and set up file associations (*.fsh, *.fam, *.qfs, *.tri etc.).

Running app (Windows/macOS Security Warnings):

Since the pre-built application is unsigned, you may encounter security warnings when running it for the first time on Windows or macOS:

• Windows (SmartScreen):

  1. If you see the "Windows protected your PC" screen, click More info.
  2. Click Run anyway to start the app.

• macOS (Gatekeeper):

  1. Locate the app in Finder (do not open it from Launchpad).
  2. Right-click (or Control-click) the app icon and select Open from the context menu.
  3. In the warning dialog that appears, click Open.
  4. Alternatively, if the app is blocked, go to System Settings > Privacy & Security, scroll down to the Security section, and click Open Anyway next to the blocked app.

Development Mode (Recommended for Linux)

If you want to run the project from source (required for Linux):

0. Install a fresh version of python (the project uses 3.14.6) and pip
1. Install dependencies pip install -r requirements.txt
2. Run the application: python run.py

Debugging the Angular frontend

The GUI now runs inside a native web view (pywebview) instead of an external Chrome instance, so the JavaScript ⟷ Python bridge (window.pywebview.api) is available only inside that native window. This means the frontend can no longer be debugged from a separate browser tab — it must be loaded by the application window itself. Development mode does exactly that: it points the native window at the Angular dev server (ng serve), so you keep live reload, source maps and full DevTools while talking to the real backend.

Prerequisites (once): install the frontend toolchain.

cd frontend
npm install

Then, every time you want to debug:

1. Start the Angular dev server (live reload + source maps), from the frontend directory:

npm run start

This serves the app on http://localhost:4200. Its proxy.conf.json forwards /eel.js (the bridge shim) and /resources (serialized resource previews) to http://127.0.0.1:8000.

2. In another terminal, start the application in development mode (from the project root):

python run.py --dev

This launches the native window pointed at the dev server with developer tools enabled. It also starts a small static server on port 8000 that serves the eel.js shim and the serialized resource files the proxy expects. You can open a specific file as usual, e.g. python run.py --dev NFSSE/SIMDATA/MISC/AL1.TRI, and override the dev server URL with --dev-server http://localhost:4200 if you changed the Angular port.

3. Debug: right-click anywhere in the window and choose Inspect Element to open the native DevTools (WebKit Web Inspector on macOS, the Edge/WebView2 DevTools on Windows). You get the console, network panel and breakpoints. Edit any file under frontend/src and the window reloads automatically. (On Linux debugging works differently — see below.)

Note: editing Python (backend) code does not hot-reload — restart python run.py --dev to pick up backend changes. Editing the Angular code reloads instantly.

Debugging on Linux (different from macOS/Windows)

On Linux the GUI still runs on Eel (a Chrome/Chromium application window), not the native web view used on macOS and Windows. Because of that, debugging works differently: there is no native window to inspect. In development mode Eel does not open its own window at all — it only runs as the backend web server on port 8000 (so proxy.conf.json can forward /eel and /resources to it).

So on Linux, to debug:

1. Start the Angular dev server as above (npm run start in frontend).
2. Start the backend in development mode (python run.py --dev).
3. Open the app in a normal browser tab at http://localhost:4200. Use the browser's built-in DevTools there, with full live reload and source maps.

Support for Linux Binary (Help Wanted!)

Currently, pre-built binary support for Linux is suspended because the standalone binary fails to launch (tested on Arch Linux, installed via dpkg).

If you are an experienced developer on this platform and would like to help restore binary support, your contributions are highly welcome! In the meantime, please use the Development Mode described above.

All commands below will work in development mode if you replace the binary file name with "python run.py", for instance:

python run.py NFSSE/SIMDATA/MISC/AL1.TRI

Usage:

GUI Application (Main Entry Point)

./nfs-resources-converter

This command launches the GUI application, which is the main interface for the project. The GUI provides:

• File Management: Open, close, save, and reload resource files
• Resource Viewer/Editor: View and edit the contents of supported game resource files
• Converter: Convert game resources to common formats with customizable settings
• System Configuration: Configure paths to external tools (Blender, FFmpeg)

You can also open a specific file directly:

./nfs-resources-converter NFSSE/SIMDATA/MISC/AL1.TRI

WARNING: The editor does not make backups and saved file consistency is not guaranteed! Use only on copied files.

Command Line Tools

The following command line tools are still available for those who prefer terminal usage:

Converter

./nfs-resources-converter convert /media/fast/NFSSE --out /tmp/NFSSE_PARSED

This command will recursively walk over the /media/fast/NFSSE directory, parse all supported resources and save them in common formats in the /tmp/NFSSE_PARSED directory. Output directory will have the same structure as input one. You can also point the script to a single file to convert just that file.

WARNING: Please do not set as output an existing directory with important data, as it can be overwritten!

Show Settings Location

./nfs-resources-converter show_settings

This command displays the full path to the settings file used by the application. The settings file is stored in your home directory.

Uncompress File

./nfs-resources-converter uncompress /path/to/compressed/file.qfs

This command uncompresses compressed game resource files and saves uncompressed data to file. The uncompressed file will be saved in the same directory as the original file with "_uncompressed" added to the filename. For example, AL1.QFS becomes AL1.QFS_uncompressed.

Custom Commands

Custom commands are more complex scripts that can be run on particular resource files. They are available in the GUI through the block actions menu (flash icon at the top).

*.TRI: flatten track

Makes open track fully flat. Useful for testing car acceleration/deceleration dynamics.

./nfs-resources-converter custom_command --custom-command flatten_track examples/maps/TR3.TRI --out examples/maps/flat/

*.TRI: reverse track

Makes track go backwards. Note that reversed tracks may have some issues and glitches.

./nfs-resources-converter custom_command --custom-command reverse_track examples/maps/TR3.TRI --out examples/maps/reversed/

*.TRI: scale track

Scales track length without affecting road width, props etc. Scale with factor 0.5 (make track 2x shorter):

./nfs-resources-converter custom_command --custom-command scale_track --custom-command-args=0.5 /media/fast/AL1.TRI --out /media/fast/AL1_SCALED.TRI

Support me

You can support project by:

• giving any feedback, bug report, feature request, providing missed info about resources to Issues
• fork & submit a Pull Request
•