{"id":17059091,"url":"https://github.com/toxicfrog/ss2map","last_synced_at":"2026-04-29T22:03:16.245Z","repository":{"id":228258118,"uuid":"773432752","full_name":"ToxicFrog/ss2map","owner":"ToxicFrog","description":"Tools for System Shock 2 and Thief map inspection","archived":false,"fork":false,"pushed_at":"2025-06-26T01:14:18.000Z","size":1075,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-26T01:34:23.150Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","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/ToxicFrog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2024-03-17T16:43:10.000Z","updated_at":"2025-06-26T01:14:21.000Z","dependencies_parsed_at":"2024-03-23T01:37:56.361Z","dependency_job_id":"4d5df195-54aa-4276-8379-d7b5cc828962","html_url":"https://github.com/ToxicFrog/ss2map","commit_stats":null,"previous_names":["toxicfrog/ss2map"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ToxicFrog/ss2map","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fss2map","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fss2map/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fss2map/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fss2map/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ToxicFrog","download_url":"https://codeload.github.com/ToxicFrog/ss2map/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fss2map/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32445555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T20:22:27.477Z","status":"ssl_error","status_checked_at":"2026-04-29T20:22:26.507Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":[],"created_at":"2024-10-14T10:32:34.352Z","updated_at":"2026-04-29T22:03:16.210Z","avatar_url":"https://github.com/ToxicFrog.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ss2map -- tools for System Shock 2 map inspection\n\nThis repo contains some small tools for examining System Shock 2 maps. (It also\nworks on Thief 1/2 maps, but that is not the main focus and some things do not\nwork as well.)\n\nCurrently it contains three tools:\n\n- `mislist`, for listing map contents\n- `misview`, for viewing map geometry\n- `mishtml`, for generating an interactive, searchable HTML map\n\nThe first two are primarily useful for testing and debugging. `mishtml` is the\nmain focus, and is what is used to generate [these online SS2 maps](https://funkyhorror.ancilla.ca/toxicfrog/maps/ss2).\n\nIt also contains a Lua library for reading Dark Engine tagfiles (`.MIS`/`.GAM`),\nin `db`. It is fairly minimal and only supports the subset of file contents needed\nfor these tools, but is designed for extensibility.\n\n## Prerequisites and Setup\n\nAll of these programs are written in Lua. They are only tested with [LuaJIT](https://luajit.org/),\nalthough they may work with Lua 5.2+ as well. Even if they do, LuaJIT is recommended\nfor performance reasons.\n\nThey also require [vstruct](https://github.com/toxicfrog/vstruct/) and\n[this util library](https://github.com/toxicfrog/luautil/). Both are included in\nthe repo as git submodules, so you should already have them available if you are\nrunning directly out of the working copy.\n\n`misview` and `mishtml` additionally require the [love2d game engine](https://love2d.org/),\nwhich is used for rendering and (in the former) input handling. Due to limitations\nin Love2d's graphics subsystem, `mishtml` cannot operate headless, sorry.\n\n### Property definitions (proplist.txt)\n\nIn order to deserialize and display object properties, the programs require a\n`proplist.txt` file, which lists all of the properties supported by the Dark\nEngine and their corresponding types. For convenience, these are built in; you\ncan find them in the `proplists` directory:\n\n- `ss2.proplist`: System Shock 2 v2.48\n- `t1.proplist`: Thief Gold v1.26\n- `t2.proplist`: Thief 2 v1.25\n\nThe Lua files in that directory contain additional information about on-disk\nproperty layout not included in the `proplist.txt`. To select one of these, use\nthe `--propformat` command line flag, e.g. `--propformat ss2`.\n\n#### Adding support for new properties\n\nSee [proplists/README.md](./proplists/README.md) for detailed instructions on\nboth how to add support for individual properties, and how to generate a new\nproplist file to support a different engine version.\n\n### Gamesys (shock2.gam)\n\nIn order to read object type information and inherited properties, the programs\nrequire a gamesys. This is (by default) called `shock2.gam` for System Shock 2,\nand `dark.gam` for Thief and Thief 2. If you have mods installed they may use a\ndifferent gamesys; notably, the SCP fan-patch for System Shock 2 uses `shockscp.gam`.\nMake sure you're using the right one!\n\n### Mission files (*.mis)\n\nThese contain the actual map data. Unfortunately the MIS files that come with the\ngames have some data removed to save space (known as \"stripping\"). If you're using\nthe latest fan-patches you probably don't need to worry about this:\n\n- **Thief 1/Gold:** [TFix](https://www.ttlg.com/forums/showthread.php?t=134733) includes unstripped missions.\n- **Thief 2:** the \"with mods\" version of [T2Fix](https://www.ttlg.com/forums/showthread.php?t=149669) includes unstripped missions; you can also install [AM16's Fixes](https://www.ttlg.com/forums/showthread.php?t=141121) separately if you don't want the other T2Fix mods.\n- **System Shock 2:** the [Shock Community Patch](https://www.systemshock.org/index.php?topic=7116.0) includes unstripped missions.\n\nIf you need to work with stripped levels, you can restore the stripped data by\nopening them up in a recent version of ShockEd or DromEd and using the\n`Extra -\u003e Reconstruct Stripped -\u003e Room Brushes` command.\n\n## Included Tools\n\nAll tools are launched from a `bash` wrapper script which handles checking for\n`luajit` or `love`, setting up necessary environment variables, and then launching\nthe actual program.\n\nAll commands can be run with `--help` to list all supported command line flags.\n\nNote that all tools use the (x,y) coordinates for objects as stored in the mission\nfile. This does not neccessarily correspond to the in-game compass and automap\n(which can be set arbirarily relative to the MIS file).\n\n### mislist\n\nThis produces a textual listing of all objects in the level. By default it shows\nname, ID, position, and orientation; it can optionally display object properties\n(direct and inherited), ancestry chains (MetaProp and archetype), and interobject\nlinks.\n\nExample usage:\n\n    mislist \\\n      --propformat ss2 \\\n      --gamesys ss2/shockscp.gam \\\n      --links --props --inherited --ancestry \\\n      ss2/medsci1.mis\n\nUsed in conjunction with standard text processing tools like `grep`, this can also\nbe used to do things like produce quick summaries of how many instances of a given\nobject are in each level.\n\n### misview\n\nThis presents an interactive view of the level terrain. It is not nearly as capable\nas the exported HTML map, but uses the same rendering code as the HTML exporter,\nand is thus primarily useful for quickly testing changes to the map loader and\nrenderer.\n\nIt can load multiple maps at once:\n\n    misview \\\n      --propformat ss2 \\\n      --gamesys ss2/shockscp.gam \\\n      ss2/*.mis\n\nOnce loaded, the following controls are available:\n\n    arrow keys or click + drag: pan view\n    w/s: zoom in/out\n    n/p: next/previous map\n    i: switch between interior (detail) and exterior (outline) view\n    r: hot-reload renderer\n    q: quit\n\n### mishtml\n\nThis generates an interactive HTML map of the given level(s) and drops it into `www/`.\nThe entry point is `www/map.html`. This can be viewed locally or uploaded to a web\nserver.\n\nThe terrain is pre-rendered and exported as a PNG, while object data is exported\nas JSON and rendered in the browser. Under the hood this shares most of its implementation\nwith `misview`, but has a different command line interface.\n\nIf you just need to regenerate the JSON but not the terrain images, use the\n`--no-genimages` command line flag to speed things up significantly by skipping\nterrain generation.\n\nInformation about the game to generate maps for, including which maps to load\nin what order and how objects should be categorized, is stored in separate\n*gameinfo scripts* for each game, loaded with `--gameinfo`. You also need a\n`--gamedir` so that it knows what directory to look for the map and gamesys files\nin.\n\n    mkdir -p maps/ss2/\n    mishtml \\\n      --html-out maps/ss2 \\\n      --propformat ss2 \\\n      --gamedir ss2 \\\n      --gameinfo gameinfo/ss2-objects.lua,gameinfo/ss2-maps.lua\n\nYou can also omit the gameinfo that lists the maps and instead list maps on the\ncommand line, at the cost of losing some useful map metadata in the UI:\n\n    mkdir -p maps/ss2/\n    mishtml \\\n      --html-out maps/ss2 \\\n      --propformat ss2 \\\n      --gamesys ss2/shockscp.gam \\\n      --gameinfo gameinfo/ss2-objects.lua \\\n      ss2/{earth,station,eng,medsci,hydro,ops,rec,command}*.mis\n\n#### Using the Map\n\nThe center display shows the map. Circles are entities, lines and boxes are terrain.\nYou can click and drag to pan, and use the mousewheel to zoom. Mousing over an entity\nwill display its information in the lower right, and you can click to \"lock\" the\ninformation and keep it there even as you mouse over other things.\n\nThe top left display lets you coarsely control which categories of entities are\ndisplayed on the map, which is useful if you are only interested in specific things.\n\nThe top right lets you search. You can search by object name (e.g. `20 nanites`),\nobject ID (e.g. `144`), or slash-separated object type, e.g. `goodies/nanites`.\nThe search is a case-insentive substring search and will list all objects in the\nlevel (or, with `Search All`, across all levels) matching it; they will also be\nmarked on the map with stars. Mousing over an object in the list will hilight it\non the map and display its object info in the lower left.\n\nSearches will also return all containers that contain the searched-for object, so\nif you search for (e.g.) `audio log`, you will also see crates, corpses, etc in\nthe search results -- mouse over them to view their contents.\n\n## Known Issues and Future Work\n\n- The terrain renderer currently assumes all terrain brushes are rectangular prisms. This works remarkably well but produces obviously wrong results in a few places. Support for cylinders, pyramids, offset pyramids, and spheres is needed.\n- The terrain renderer is not good at detecting interior walls constructed via additive geometry.\n- The terrain renderer does not support Z-slicing. This is necessary to sensibly support room-over-room, which is an issue for some SS2 maps and most Thief maps.\n- The proplist loader does not support aggregate types (since proplist.txt does not contain sufficient information to decode them). Support for at least some common types, like position and dimensions, should be added.\n- The proplist loader does not support bitflags.\n- All of these programs assume that Y increases towards the top of the screen and X increases towards the right, i.e. southwest gravity. In ShockEd, however, X increases towards the *bottom* of the screen and Y to the *right*, i.e. northwest gravity *with horizontal Y and vertical X*. Since everything else assumes Y is vertical and X is horizontal, fixing this will require some care, although the actual changes needed are probably not extensive.\n- The cute little map icons are hardcoded in the javascript, and thus don't match up with the actual maps as exported if you only export a subset of SS2 maps, or export them in a different order.\n- Support for `.DIF` files (easy, they're just another tagfile) and `.DML` files (needs another bespoke parser).\n- Support for `objshort.str` (localized object names) and `levelNN.str` (audio log titles)\n- Ability to read map info out of a separate file, so that map icons and titles don't need to be hardcoded in the frontend and can be different for e.g. Thief vs SS2.\n\n## Credits\n\nImplementation by Rebecca Kelly (ToxicFrog); developed in cooperation with\n[Night Dive Studios](https://www.nightdivestudios.com/).\n\nIn addition, study of Telliamed's [DarkLib](https://whoopdedo.org/projects.php?dark)\nshed considerable light on some details of Dark Engine file formats.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoxicfrog%2Fss2map","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoxicfrog%2Fss2map","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoxicfrog%2Fss2map/lists"}