https://github.com/webdevred/jbeam_edit
A fast, robust command-line parser, formatter, and editor for JBeam files, the JSON-like format used by BeamNG to define vehicles and physics structures.
https://github.com/webdevred/jbeam_edit
beamng haskell jbeam tooling
Last synced: 8 days ago
JSON representation
A fast, robust command-line parser, formatter, and editor for JBeam files, the JSON-like format used by BeamNG to define vehicles and physics structures.
- Host: GitHub
- URL: https://github.com/webdevred/jbeam_edit
- Owner: webdevred
- License: bsd-3-clause
- Created: 2025-03-19T22:15:08.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2026-05-13T16:41:31.000Z (about 1 month ago)
- Last Synced: 2026-05-29T09:34:31.639Z (25 days ago)
- Topics: beamng, haskell, jbeam, tooling
- Language: Haskell
- Homepage:
- Size: 1.04 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# JBeam Tool in Haskell
- [Features](#features)
- [Configuration](#configuration)
- [Usage](#usage)
- [1. Download the latest release](#1-download-the-latest-release)
- [2. Unzip the file](#2-unzip-the-file)
- [3. Run the setup as Administrator](#3-run-the-setup-as-administrator)
- [4. Allow in Windows Defender if needed](#4-allow-in-windows-defender-if-needed)
- [5. Path refresh](#5-path-refresh)
- [6. Open Command Prompt or PowerShell](#6-open-command-prompt-or-powershell)
- [7. Run jbeam-edit on a file](#7-run-jbeam-edit-on-a-file)
- [From source (Linux or development)](#from-source-linux-or-development)
- [Examples](#examples)
- [Planned Features / TODO](#planned-features-todo)
- [Why Haskell + Megaparsec?](#why-haskell-megaparsec)
- [Prerequisites](#prerequisites)
- [Contributing & License](#contributing-license)
[](https://github.com/webdevred/jbeam_edit/actions/workflows/build-and-test.yaml)
[](https://github.com/webdevred/jbeam_edit/actions/workflows/future-proofing.yaml)
[](https://github.com/webdevred/jbeam_edit/actions/workflows/build-and-release.yaml)
[](https://github.com/webdevred/jbeam_edit/actions/workflows/lint-and-format.yaml)
A fast, robust command-line parser, formatter, and editor for JBeam files, the JSON-like format used by BeamNG to define vehicles and physics structures.
## Features
- **Complete Parsing:**
Parses entire `.jbeam` files, including comments and irregular whitespace, without breaking on manual edits.
- **Consistent Formatting:**
Uniform indentation, spacing, and layout for improved readability.
- **Automatic Node Management:**
Renames nodes sequentially (e.g., `["bf1", ...]` → `["bf0", "bf1", "bf2"]`) and updates all references automatically. Feature currently unstable, enabled by build flag `transformation`.
- **Configurable Formatting with JBFL:**
Customize formatting rules using JBFL, a mini-language to specify padding, decimals, indentation, object key alignment, and more with wildcard targeting.
Example JBFL snippet:
```jbfl
.*.nodes[*][*] {
PadDecimals: 3;
PadAmount: 8;
}
.*.flexbodies[*] {
NoComplexNewLine: true;
}
```
## Configuration
Generate a default formatting config with:
```bash
jbeam-edit -cminimal # simple config
jbeam-edit -ccomplex # detailed config
```
Config files are saved in:
- Linux/macOS: `$HOME/.config/jbeam-edit/rules.jbfl`
- Windows: `%APPDATA%\jbeam-edit\rules.jbfl`
Override per project by placing `.jbeam_edit.jbfl` in your project root.
## Usage
### 1. Download the latest release
Go to the [Releases page](https://github.com/webdevred/jbeam_edit/releases) and download the most recent **`.zip`** file.
### 2. Unzip the file
Extract the contents of the downloaded `.zip` archive to a folder of your choice.
### 3. Run the setup as Administrator
Inside the extracted folder, right-click on **setup.exe** and choose **Run as administrator**.
## 4. Allow in Windows Defender if needed
If Windows shows a warning such as:
> *Windows protected your PC*
Click **More info** → **Run anyway**.
### 5. Path refresh
The installer adds `jbeam-edit` to your **PATH**, but:
- You must **open a new Command Prompt or PowerShell window** after installation.
- In some cases, you may need to **log out or restart Windows** for the PATH change to take effect.
- If it still doesn’t work, you can run it directly using the full path, e.g.:
```powershell
"C:\Program Files (x86)\jbeam_edit\jbeam-edit.exe" your-file.jbeam
```
### 6. Open Command Prompt or PowerShell
Press **`Win + R`**, type `cmd` or `powershell`, and hit **Enter**.
### 7. Run jbeam-edit on a file
Navigate to your project folder in CMD/PowerShell and run:
```powershell
jbeam-edit your-file.jbeam
```
Replace `your-file.jbeam` with the path to your JBeam file.
#### Typical workflow:
- Parses and formats the file.
- Sorts and renames nodes, updating references.
- Writes the output back with a `.bak` backup (default).
#### In-place editing (no backup):
```powershell
jbeam-edit -i example.jbeam
```
### From source (Linux or development)
Clone and build with Cabal:
```bash
git clone https://github.com/webdevred/jbeam_edit.git
cd jbeam_edit
cabal update
cabal install
jbeam-edit your-file.jbeam
```
## Examples
For sample `.jbeam` files and JBFL rule files, see the [Examples Directory README](examples/README.md).
## Planned Features / TODO
- Language Server Protocol (LSP) support
- Update specific ranges of vertices
- Expanded tests and example files
- Improved documentation
Considered features: https://github.com/webdevred/jbeam_edit/discussions/134
## Why Haskell + Megaparsec?
- Strong static typing for safer, reliable parsing and transformations.
- Elegant, composable parser combinators.
- Immutable data handling ensures predictable editing.
## Prerequisites
- **Windows users (BeamNG players):** none, just download the installer from [Releases](https://github.com/webdevred/jbeam_edit/releases/latest).
- **Developers / Linux users:**
- [GHC](https://www.haskell.org/ghc/) (Glasgow Haskell Compiler)
- [Cabal](https://www.haskell.org/cabal/) build tool (comes with GHCup)
## Contributing & License
Contributions and bug reports welcome. Licensed under BSD 3-Clause.
Happy parsing and formatting!