{"id":23501223,"url":"https://github.com/arx-tools/arx-convert","last_synced_at":"2026-04-25T23:10:25.292Z","repository":{"id":57184485,"uuid":"293961576","full_name":"arx-tools/arx-convert","owner":"arx-tools","description":"Converts various Arx Fatalis formats (DLF, FTS, LLF, AMB and FTL) to JSON/YAML and back","archived":false,"fork":false,"pushed_at":"2026-04-24T18:34:40.000Z","size":2198,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-24T20:34:05.806Z","etag":null,"topics":["arx-fatalis","converter","json","yaml"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arx-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-09-09T00:40:36.000Z","updated_at":"2026-04-24T18:34:44.000Z","dependencies_parsed_at":"2023-02-10T06:46:26.394Z","dependency_job_id":"0d11bb95-4148-43b9-b4ae-6dc18dfb93aa","html_url":"https://github.com/arx-tools/arx-convert","commit_stats":{"total_commits":450,"total_committers":1,"mean_commits":450.0,"dds":0.0,"last_synced_commit":"eaf08c05b12c22c3240acc0ff3c37349b00e721e"},"previous_names":["meszaros-lajos-gyorgy/arx-level-json-converter"],"tags_count":106,"template":false,"template_full_name":null,"purl":"pkg:github/arx-tools/arx-convert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arx-tools%2Farx-convert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arx-tools%2Farx-convert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arx-tools%2Farx-convert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arx-tools%2Farx-convert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arx-tools","download_url":"https://codeload.github.com/arx-tools/arx-convert/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arx-tools%2Farx-convert/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32279672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arx-fatalis","converter","json","yaml"],"created_at":"2024-12-25T07:13:42.609Z","updated_at":"2026-04-25T23:10:25.280Z","avatar_url":"https://github.com/arx-tools.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arx Fatalis converter\n\nConverts various Arx Fatalis formats (DLF, FTS, LLF, AMB and FTL) to JSON/YAML and back\n\n**IMPORTANT: Arx Fatalis files are partially compressed. See \"compression\" section for more info**\n\n## Installation\n\n### node.js\n\n`npm i -g arx-convert`\n\n### browser\n\n```html\n\u003cscript type=\"importmap\"\u003e\n  {\n    \"imports\": {\n      \"arx-convert\": \"https://esm.sh/arx-convert\",\n      \"arx-convert/types\": \"https://esm.sh/arx-convert/types\",\n      \"arx-convert/utils\": \"https://esm.sh/arx-convert/utils\"\n    }\n  }\n\u003c/script\u003e\n\u003cscript type=\"module\"\u003e\n  import { DLF, FTS, LLF } from 'arx-convert'\n  import { type ArxPolygon, ArxPolygonFlags, type ArxFTS, type ArxLLF, type ArxDLF } from 'arx-convert/types'\n  import { isQuad } from 'arx-convert/utils'\n\n  // ...\n\u003c/script\u003e\n```\n\n### Recommended requirements\n\nnode.js 18.0+ (because the lib uses prefix-only core modules)\n\nIt might work with older versions of node.js, but I haven't tested it there.\n\n## Command-line API\n\n`arx-convert \u003cinputfile\u003e --from=\u003cformat\u003e --to=\u003cformat\u003e --output=\u003coutputfile\u003e [--format] [--pretty] [--prettify]`\n\nthe inputfile and --output parameters can be omitted and then the code can be used in pipelines\n\n`cat \u003cinputfile\u003e | arx-convert --from=\u003cformat\u003e --to=\u003cformat\u003e \u003e \u003coutputfile\u003e`\n\nthe `\u003cformat\u003e` parameter can be one of the following arx formats: `dlf`, `llf`, `fts`, `amb`, `ftl` or `tea`\n\nand it can also a data format for the other side: `json` and `yaml`(can also be spelled as `yml`)\n\nprettifying the json output can be done by using any of the 3 parameters: `--format`, `--pretty` or `--prettify`\n\n### Examples\n\n```sh\n# prints out version\n--version\n-v\n\n# converts an unpacked fts file to a json through piping\ncat fast.fts.unpacked | arx-convert --from=fts --to=json --prettify \u003e fast.fts.json\n\n# converts an unpacked dlf file to a minified json through files\narx-convert level8.dlf.unpacked --from=dlf --to=json --output=level8.dlf.min.json\n\n# converts a json to an unpacked dlf\ncat level8.dlf.min.json | arx-convert --from=json --to=dlf \u003e level8.dlf.repacked\n\n# converts json to an unpacked fts\narx-convert fast.fts.json --from=json --to=fts --output=fast.fts.repacked\n\n# converts an unpacked dlf to yaml\ncat level8.dlf.unpacked | arx-convert --to=yaml --from=dlf \u003e level8.dlf.yml\n\n# converts yaml to an unpacked dlf\ncat level8.dlf.yml | arx-convert --from=yaml --to=dlf \u003e level8.dlf.repacked\n```\n\n## Javascript/Typescript API\n\nThe package is published as a commonjs lib and the files can be found in the `dist` folder, but only if you\ninstall it via npm. If you downloaded the source files from github, then you need to transpile the typescript\nfiles yourself using the `npm run build` command.\n\nThe built js files come with sourcemaps, which you can use by running your node.js file with the\n[--enable-source-maps](https://nodejs.org/api/cli.html#--enable-source-maps) flag\n\n### Javascript example\n\n```js\nconst fs = require('node:fs/promises')\nconst path = require('node:path')\nconst { FTS } = require('arx-convert')\n\n;(async () =\u003e {\n  // reads an unpacked fts file into a buffer\n  const binary = await fs.readFile(path.resolve(__dirname, './fast.fts.unpacked'))\n\n  // converts the buffer into a json using the FTS converter\n  const json = FTS.load(binary)\n\n  // save as a minified json\n  await fs.writeFile(path.resolve(__dirname, './fast.fts.min.json'), JSON.stringify(json), 'utf8')\n\n  // save as a formatted json\n  await fs.writeFile(path.resolve(__dirname, './fast.fts.json'), JSON.stringify(json, null, '\\t'), 'utf8')\n})()\n```\n\n### Typescript example\n\n```ts\nimport fs from 'node:fs/promises'\nimport path from 'node:path'\nimport { DLF } from 'arx-convert'\nimport type { ArxDLF } from 'arx-convert/types'\n\n;(async () =\u003e {\n  // reads an unpacked dlf file into a buffer\n  const binary = await fs.readFile(path.resolve(__dirname, './level1.dlf.unpacked'))\n\n  // converts the buffer into a json using the DLF converter\n  // optionally you can assign a type to the variable\n  const json: ArxDLF = DLF.load(binary)\n\n  // save as a minified json\n  await fs.writeFile(path.resolve(__dirname, './level1.dlf.min.json'), JSON.stringify(json), 'utf8')\n\n  // save as a formatted json\n  await fs.writeFile(path.resolve(__dirname, './level1.dlf.json'), JSON.stringify(json, null, '\\t'), 'utf8')\n})()\n```\n\n## Compression\n\nSome Arx Fatalis files are partially compressed with Stormlib Pkware and you need a separate\ntool for unpacking/repacking: [node-pkware](https://www.npmjs.com/package/node-pkware)\n\nAlso, Arx Fatalis file headers are not constant in size, but there is a tool\nthat can give you the exact offset you need to pipe into node-pkware: [arx-header-size](https://www.npmjs.com/package/arx-header-size)\n\nInstall these tools by running\n\n```sh\nnpm i node-pkware arx-header-size -g\n```\n\n### Example for unpacking a compressed file\n\n```sh\narx-header-size level3.dlf --format=dlf # this will print out 8520\nexplode level3.dlf --offset=8520 --output=level3.dlf.unpacked\narx-convert level3.dlf.unpacked --from=dlf --to=yaml --output=level3.dlf.yml\n```\n\n### Example for repacking a file that needs compression\n\n```sh\narx-convert level3.dlf.yml --from=yaml --to=dlf --output=level3.dlf.repacked\nimplode level3.dlf.repacked --offset=8520 --binary --large --output=level3.dlf\n```\n\n### General scripts with detection to whether the input needs decompression or not\n\n#### unpack.sh\n\n```sh\n#!/bin/bash\n\n#\n# usage: unpack.sh goblin_lord.ftl\n#        unpack.sh ../goblin_lord/goblin_lord.ftl json\n#\n\n# try reading the 1st argument from the command line\nif [ $# -lt 1 ]; then\n  echo \"missing filename, expected format: $0 \u003cfilename\u003e\"\n  exit 1\nfi\n\n# read the 1st argument\nINPUT=$1\n\n# get the extension of the input file's name and make it lowercase\nINPUT_FORMAT=$( \\\n  echo $INPUT \\\n  | tr '[:upper:]' '[:lower:]' \\\n  | tr '.' '\\n' \\\n  | tail -1 \\\n)\n\n# if a 2nd argument exists, then read it, otherwise set yaml as the output format\nif [ $# -lt 2 ]; then\n  OUTPUT_FORMAT=yml\nelse\n  OUTPUT_FORMAT=$2\nfi\n\n# get the offset in bytes, might also get back \"not compressed\"\nOFFSET=$(arx-header-size $INPUT --format=$INPUT_FORMAT)\n\nif [[ $OFFSET == \"not compressed\" ]]; then\n  arx-convert $INPUT --from=$INPUT_FORMAT --to=$OUTPUT_FORMAT --pretty --output=\"$INPUT.$OUTPUT_FORMAT\"\nelse\n  explode $INPUT --offset=$OFFSET | arx-convert --from=$INPUT_FORMAT --to=$OUTPUT_FORMAT --pretty --output=\"$INPUT.$OUTPUT_FORMAT\"\nfi\n```\n\n#### repack.sh\n\n```sh\n#!/bin/bash\n\n#\n# usage: repack.sh level3.dlf.json\n#        repack.sh ../level3/level3.dlf.json\n#\n\n# try reading the 1st argument from the command line\nif [ $# -lt 1 ]; then\n  echo \"missing filename, expected format: $0 \u003cfilename\u003e\"\n  exit 1\nfi\n\n# read the 1st argument\nINPUT=$1\n\n# something.ftl.json -\u003e json\nINPUT_FORMAT=$( \\\n  echo $INPUT \\\n  | tr '[:upper:]' '[:lower:]' \\\n  | tr '.' '\\n' \\\n  | tail -1 \\\n)\n\n# something.ftl.json -\u003e ftl\nOUTPUT_FORMAT=$( \\\n  echo $INPUT \\\n  | tr '[:upper:]' '[:lower:]' \\\n  | tr '.' '\\n' \\\n  | tail -2 \\\n  | head -1 \\\n)\n\narx-convert $INPUT --from=$INPUT_FORMAT --to=$OUTPUT_FORMAT --pretty --output=\"$INPUT.$OUTPUT_FORMAT.tmp\"\n\n# get the offset in bytes, might also get back \"not compressed\"\nOFFSET=$(arx-header-size $INPUT --format=$OUTPUT_FORMAT)\n\nif [[ $OFFSET == \"not compressed\" ]]; then\n  mv \"$INPUT.$OUTPUT_FORMAT.tmp\" \"$INPUT.$OUTPUT_FORMAT\"\nelse\n  implode \"$INPUT.$OUTPUT_FORMAT.tmp\" --offset=$OFFSET --binary --large --output=\"$INPUT.$OUTPUT_FORMAT\"\n  rm \"$INPUT.$OUTPUT_FORMAT.tmp\"\nfi\n```\n\n### Uncompressed FTS files in Arx Libertatis 1.3\n\n`FTS.save()` now takes a 2nd parameter to control whether the given fts data should be marked as compressed\nor uncompressed\n\n- `FTS.save(ftsData, true)` -\u003e fts files get compressed (true can be omitted as it is the **default** value)\n- `FTS.save(ftsData, false)` -\u003e marks the fts file as uncompressed, no pkware compression is required afterwards\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farx-tools%2Farx-convert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farx-tools%2Farx-convert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farx-tools%2Farx-convert/lists"}