{"id":23112919,"url":"https://github.com/isms/circlemud-world-parser","last_synced_at":"2025-08-16T19:31:30.860Z","repository":{"id":36915679,"uuid":"41222730","full_name":"isms/circlemud-world-parser","owner":"isms","description":"Parse CircleMUD and DikuMUD world files to JSON","archived":false,"fork":false,"pushed_at":"2024-03-20T18:03:33.000Z","size":1170,"stargazers_count":16,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-04T16:53:39.006Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/isms.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}},"created_at":"2015-08-22T20:10:48.000Z","updated_at":"2023-07-21T19:05:24.000Z","dependencies_parsed_at":"2024-12-17T02:21:26.071Z","dependency_job_id":"0f93937c-69d4-4422-9ee2-bd9f416222cb","html_url":"https://github.com/isms/circlemud-world-parser","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/isms/circlemud-world-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isms%2Fcirclemud-world-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isms%2Fcirclemud-world-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isms%2Fcirclemud-world-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isms%2Fcirclemud-world-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isms","download_url":"https://codeload.github.com/isms/circlemud-world-parser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isms%2Fcirclemud-world-parser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270763000,"owners_count":24641007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2024-12-17T02:20:57.589Z","updated_at":"2025-08-16T19:31:30.419Z","avatar_url":"https://github.com/isms.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"CircleMUD World Parser\n======================\n\nThis repo contains code for parsing [CircleMUD](http://www.circlemud.org/) world files (and therefore, in many cases older [DikuMUD](https://en.wikipedia.org/wiki/DikuMUD)). The flat files are parsed into simple Python data structures. From there, they can be output to JSON (the default command line functionality).\n\nWhat is a world file?\n---------------------\n\nMUDs are text-based games made up primarily of interconnected rooms, non-player characters, objects (like weapons, armor, food), and other players.\n\n![](https://upload.wikimedia.org/wikipedia/en/2/27/JediMUD_screenshot.png)\n\nAll of the rooms, items, and everything else that made up the game were persisted in simple textfiles. The specification for these file formats is described in \"[The CircleMUD Builder's Manual](http://www.circlemud.org/cdp/building/building.html)\" by Jeremy Elson, the creator of CircleMUD.\n\nHere are the different types of files in CircleMUD v3.1:\n\n| File extension | Description                                                 |\n|----------------|-------------------------------------------------------------|\n| `wld`          | Rooms                                                       |\n| `mob`          | Mobiles (also known as \"mobs\" or NPCs)                      |\n| `obj`          | Objects                                                     |\n| `shp`          | Shops                                                       |\n| `zon`          | Zone files (what to load where, how often to refresh, etc.) |\n\nThe problem\n-----------\n\nCircleMUD world files are in a custom format that, in the original codebase, were parsed directly into memory by [db.c](https://github.com/Yuffster/CircleMUD/blob/master/src/db.c).\n\nThis is inconvenient if you want to inspect these entries or use them in other games. Because the values are not annotated and because many of the interesting features are compressed into [bitvectors](https://en.wikipedia.org/wiki/Bit_array), many lookups are necessary to understand even the simplest entry.\n\nFor example, here is one entry for an object in `lib/world/obj/30.obj` within the stock [CircleMUD world files](https://github.com/Yuffster/CircleMUD/tree/master/lib/world):\n\n```\n#3005\nkey dull metal~\na key of dull metal~\nA key made of a dull metal is lying on the ground here.~\n~\n18 cdq 16385\n3005 0 0 0\n1 0 0\n```\n\nIn the past, others have parsed these files to [XML](http://inventwithpython.com/blog/2012/03/19/circlemud-data-in-xml-format-for-your-text-adventure-game/), but the XML had some validity issues, certain file types weren't converted, and the original source code wasn't published.\n\nHere's the same item as above in our new JSON file:\n\n```json\n{\n    \"affects\": [], \n    \"aliases\": [\n      \"key\", \n      \"dull\", \n      \"metal\"\n    ], \n    \"cost\": 0, \n    \"effects\": [\n      {\n        \"note\": \"NORENT\", \n        \"value\": 4\n      }, \n      {\n        \"note\": \"NODONATE\", \n        \"value\": 8\n      }, \n      {\n        \"note\": \"NOSELL\", \n        \"value\": 65536\n      }\n    ], \n    \"extra_descs\": [], \n    \"id\": 3005, \n    \"long_desc\": \"A key made of a dull metal is lying on the ground here.\", \n    \"rent\": 0, \n    \"short_desc\": \"a key of dull metal\", \n    \"type\": {\n      \"note\": \"KEY\", \n      \"value\": 18\n    }, \n    \"values\": [\n      3005, \n      0, \n      0, \n      0\n    ], \n    \"wear\": [\n      {\n        \"note\": \"WEAR_TAKE\", \n        \"value\": 1\n      }, \n      {\n        \"note\": \"WEAR_HOLD\", \n        \"value\": 16384\n      }\n    ], \n    \"weight\": 1\n}\n```\n\nUsage\n-----\n\nBefore using this, make sure the requirements are installed:\n\n    pip install -r requirements.txt\n\nLet's say we want to convert the objects in `lib/world/obj/30.obj` to JSON. Using this package, you can run\n\n    python parse.py 30.obj \u003e obj/30.json\n    \nor\n\n    python parse.py --dest obj/30.json 30.obj\n    \nwhich are equivalent. The input file will be recognized as CircleMUD object file and parsed appropriately. The same will be true of any of the accepted file formats. Any parsing errors will be logged to `stderr` but will not cause the script to exit and will not be transferred via pipes or written to output files. For example:\n\n```\n$ python parse.py world/obj/0.obj \u003e 0.obj.json\n2015-08-23 01:22:37,159 - __main__ - ERROR - Error parsing:\n\n\t0\n\tbug~\n\ta bug~\n\tThis object is BAD!  If you see it, there must be a bug in the game.  Please\n\treport it immediately using the BUG command.~\n\t~\n\t13 0 0\n\t0 0 0 0\n\t0 0 0\n\t\n\tTraceback (most recent call last):\n\t  File \"circlemud-world-parser/utils.py\", line 89, in parse_from_string\n\t    d = parse_function(text)\n\t  File \"circlemud-world-parser/object.py\", line 62, in parse_object\n\t    weight, cost, rent = [int(v) for v in fields[7].split()]\n\tValueError: too many values to unpack\n\t\n$ head 0.obj.json\n[\n  {\n    \"affects\": [], \n    \"aliases\": [\n      \"wings\"\n    ], \n    ...\n```\n\nIf you want to check out the JSON for all of the stock CircleMUD world files, it's in the [`output` folder](https://github.com/isms/circlemud-world-parser/tree/master/output) of this repo.\n\nOther notes\n-----------\n\n### Converting a whole `world` directory\n\nYou may want to convert all of the files in the CircleMUD world folder (typically found at `lib/world/`).\n\nA bash script, `convert_all.sh` is also included which will parse all recognized files to JSON in a folder called `output/` while maintaining the same folder structure. Given a folder like this:\n\n    world\n    ├── mob\n    ├── obj\n    ├── shp\n    ├── wld\n    └── zon\n\nYou can run the following command:\n\n    ./convert_all.sh world/\n\nAnd you will end up with this:\n\n    output\n    ├── mob\n    ├── obj\n    ├── shp\n    ├── wld\n    └── zon\n\nThe new folders will have JSON files instead of `.obj`, `.mob`, `.wld` and so forth.\n\n### Make shortcuts\n\nTests can be run with `make test`, and all of the stock CircleMUD files in `world/` can be converted to JSON in the `output/` directory with `make all`.\n\n### Non-standard codebases\n\nHeavily modified codebases may not be parsed correctly. Any extra fields or non-standard entries are likely to cause parsing errors. Notes on bitvector entries (such as HUMMING or ANTI-MAGE) are based on the stock CircleMUD values, so if the MUD has added extras these won't be recognized and will end up as `null` in JSON.\n\nThese are all stored in `constants.py` which should be easy to change.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisms%2Fcirclemud-world-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisms%2Fcirclemud-world-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisms%2Fcirclemud-world-parser/lists"}