A Parser, Formatter, and Editor for jbeam Files
This project is a command-line tool designed to work with jbeam files (the structured, JSON-like format used in BeamNG to define vehicles, physics, and structures). Initially implemented in Haskell as a fast and robust demo, it has grown into a comprehensive utility for manipulating jbeam data.
- Parses entire
.jbeamfiles, including comments. - Ignores irrelevant whitespace.
- Handles both clean and manually edited files without breaking.
- Reformats the entire file with uniform indentation, spacing, and layout.
- Improves readability and maintainability of JBeam data.
- Sorts and sequentially renames all nodes (e.g.,
["bf1", ...]becomes["bf0", "bf1", "bf2"]). - Updates all references to renamed nodes throughout the file to prevent inconsistencies.
jbeam_edit supports user-defined rule files in JBFL (JBeam Formatting Language), a declarative mini-language for specifying formatting behavior.
.*.nodes[*][*] {
PadAmount: 8;
PadDecimals: 3;
}
.*.flexbodies[*] {
NoComplexNewLine: true;
}
- Target specific parts of the data tree using wildcard patterns.
- Control indentation, spacing, padding, and decimal precision.
- As a maintainer, enforce customized formatting rules to fit your preference.
- Integration with editors via Language Server Protocol (LSP)
- Indent JBFL property to specify number of spaces for indentation
- Detect support vertices (nodes with a high number of beam connections) and group them automatically.
- Handle cases where meta nodes (e.g.,
{"group":"..."}) interrupt node groups. - Allow prefix replacement via command-line arguments (e.g., replace
"bf"in nodes, beams, triangles, and flexbodies). - Expand test coverage.
- Add dedicated, curated example files to demonstrate typical workflows and tool capabilities.
(Currently available example
.jbeamfiles come from a collaborator’s real mod and serve as examples until we produce example files dedicated for the project.) - Improve documentation to support new contributors and clarify configuration use.
- Rapid Prototyping & Robustness - Haskell’s strong type system and expressive syntax allowed for quick development of a reliable prototype.
- Elegant Parser Composition - Utilizing the Parsec family of parser combinators enabled building modular, reusable components that make the parser clear and maintainable.
- Safe Data Transformation - Haskell’s emphasis on immutability and pure functions ensures that even complex transformations of your jbeam files are performed safely and predictably.
I have considered porting this project to C/C++ in the future.
Many developers running Windows already have Visual Studio and MSVC installed, so a C/C++ version might simplify the build process by eliminating the need for additional toolchains (like GHC).
Although a C/C++ rewrite might improve accessibility on Windows, it would come at the expense of Haskell’s expressive power, type safety, and the elegant parser composition facilitated by Parsec.
For now, the project remains a Haskell-based tool, but the idea of a C/C++ port is kept in mind as it might broaden the user base in the future.
- Haskell Compiler: GHC (https://www.haskell.org/ghc/)
- Build Tool: Stack (https://docs.haskellstack.org)
Clone the repository and build the project using your preferred Haskell build tool:
git clone https://github.com/webdevred/jbeam-tool.git cd jbeam-tool stack build
Run the tool from the command line as follows:
stack exec jbeam-tool -- [options] <input-file>
The tool will:
- Parse the provided jbeam file.
- Format it according to the default or user-defined rules.
- Automatically sort nodes, rename them sequentially, and update all related references.
For full usage details and configuration options, please refer to EXPLANATION_OF_SOURCE_CODE.org
Contributions, bug reports, and feature requests are welcome!
This project is licensed under the BSD Clause 3 License – see the LICENSE file for details.
If you have any questions or suggestions, feel free to open an issue or contact me directly.
Happy parsing and formatting!