{"id":17059149,"url":"https://github.com/toxicfrog/doomrl-server","last_synced_at":"2025-04-12T17:51:16.751Z","repository":{"id":23906589,"uuid":"27286621","full_name":"ToxicFrog/doomrl-server","owner":"ToxicFrog","description":"A dgamelaunch-like frontend for DoomRL, supporting recording, spectators, and shared high scores","archived":false,"fork":false,"pushed_at":"2024-11-26T19:34:44.000Z","size":430,"stargazers_count":8,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T12:11:49.226Z","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/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}},"created_at":"2014-11-29T00:25:00.000Z","updated_at":"2024-11-26T19:34:48.000Z","dependencies_parsed_at":"2022-08-22T05:50:52.292Z","dependency_job_id":null,"html_url":"https://github.com/ToxicFrog/doomrl-server","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fdoomrl-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fdoomrl-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fdoomrl-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToxicFrog%2Fdoomrl-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ToxicFrog","download_url":"https://codeload.github.com/ToxicFrog/doomrl-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248610409,"owners_count":21132920,"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","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:51.310Z","updated_at":"2025-04-12T17:51:16.731Z","avatar_url":"https://github.com/ToxicFrog.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DoomRL-server\n\nA `nethack.alt.org`-inspired frontend for hosting a multiplayer DoomRL server. Features:\n\n- per-player game settings, save files, and unlocks\n- multiple save files per player\n- shared scoreboard\n- games in progress can be spectated\n- mortems and recordings of finished games are saved for later viewing\n- closed caption support (also usable without the server; see `ttysound/README.md`)\n- a web interface that lets people view the scoreboard, spectate, and even play the game from their browser\n\n\n\n## Installing doomrl-server\n\nIf you're running NixOS, there are overlays and a service configuration in `etc/`. See `etc/README.md` for details.\n\nIf you aren't, read on.\n\n`doomrl-server` expects to run as a user shell or inetd service, getting input on stdin and replying on stdout; it contains no netcode and doesn't run as a daemon. The easiest configuration is just to create a `doomrl` user with `doomrl-server` as the shell, then set up something that lets people log in as that user (using passwordless ssh, perhaps). If you want to get more complicated you can add telnet support (via `xinetd`) and even a web client (which requires telnet support set up), which probably has the lowest barrier to entry for users.\n\nThroughout these instructions I'm going to assume that:\n- you want DoomRL installed in /opt/doomrl, and doomrl-server in /usr/src/doomrl-server\n- you want doomrl-server user data stored in /srv/doomrl\n- you're using nginx as the web server and systemd as your init system\n\n### Prerequisites\n\n- DoomRL\n- `python3`, `less`, and `nano`\n- `xinetd` and `telnetd` (for telnet access)\n- a simple static web server like `nginx` (for the web scoreboards)\n- `websockify` (for the web client)\n\nMost of these you should be able to install with your package manager. DoomRL you can [download from chaosforge](https://drl.chaosforge.org/downloads). Go ahead and unpack it to `/opt/doomrl`:\n\n    $ mkdir /opt/doomrl\n    $ curl https://drl.chaosforge.org/file_download/37/doomrl-linux-x64-0997-lq.tar.gz \\\n        | tar xz --strip-components=1 -C /opt/doomrl\n\nWe use the LQ (Low Quality) version here because the server doesn't play music, and thus doesn't need the extra ~100MB of soundtrack. The `--strip-components` results in DoomRL being unpacked directly into `/opt/doomrl`, i.e. the game binary is `/opt/doomrl/doomrl`, not `/opt/doomrl/doomrl-linux-x64-0997-lq/doomrl`.\n\n### Using it as a shell\n\nJust download doomrl-server:\n\n    $ git clone https://github.com/toxicfrog/doomrl-server /usr/src/doomrl-server\n\nCreate a user for it:\n\n    $ useradd -g nobody -d /srv/doomrl -M -N -r -s /usr/src/doomrl-server doomrl\n    $ chown -R doomrl:nogroup /srv/doomrl\n\nAnd set up the configuration file, editing it if necessary:\n\n    $ cp /usr/src/doomrl-server/etc/doomrl-server.conf /etc\n    $ nano /etc/doomrl-server.conf\n\nAnd you're done! Anyone logging in as `doomrl` will run the doomrl server as their shell. `/srv/doomrl` will be created, if it doesn't already exist, the first time the server runs. You should be able to test this with `sudo -u doomrl /usr/src/doomrl-server/doomrl-server` -- it should give you a DooM banner and a `guest\u003e` prompt.\n\n### Setting up telnet access\n\nIt's convenient if users can just `telnet yourserver.net 3666` and play doomrl. For this we use xinetd (to accept the connection) and telnetd (to perform initial negotiation and set up the terminal).\n\nThere's an xinetd configuration file in `etc/`, so this is probably as simple as:\n\n    $ cp /usr/src/doomrl-server/etc/doomrl-server.xinetd /etc/xinetd.d\n    $ nano /etc/xinetd.d/doomrl-server.xinetd\n    $ systemctl restart xinetd\n\nTest it with `telnet localhost 3666` (assuming you haven't edited the port) and you should get the banner and guest prompt as before.\n\n### Setting up the web server\n\ndoomrl-server writes HTML scoreboards and postmortems to `$user_dir/www/`. These are static HTML (+ a bit of javascript) and require no server-side support; you can just point anything that can serve static HTML at them and away it goes. Sample configurations are provided in `etc/` for nginx and thttpd.\n\n### Setting up the web client\n\nThe web client is automatically included in the generated HTML. For it to work, you need to run `websockify` to connect a websocket to the doomrl-server xinetd service; as with nginx, there's a sample service configuration (`etc/websockify-doomrl.service`).\n\nIf you're running doomrl-server telnet and websocket on ports other than the default (3666 and 3667 respectively), in addition to editing the websockify service file, you'll need to edit `DOOMRL_WS_PORT` in `www/replay.html` and `www/tty.html`.\n\n\n\n## Configuring doomrl-server\n\ndoomrl-server doesn't have much configuration except the paths contained in `/etc/doomrl-server.conf`. What it does have is read from `$user_path` if it exists, and from `$data_path` otherwise -- so you can override the defaults that come with doomrl-server by creating files in `$user_path`.\n\n### Banners\n\nThe `motd` and `webmotd` files contain the banners printed when a user logs in over telnet (or using the web client) and when a user views the scoreboard in their browser, respectively. The default banner is just a DooM logo and links to the DoomRL and doomrl-server websites. You can customize these for your site by creating `/srv/doomrl/motd` and `/srv/doomrl/webmotd` files containing the banners you want.\n\n### Maintenance and debug mode\n\nIf want to temporarily bring the server down for maintenance, creating the file `/srv/doomrl/maintenance` will prevent new connections, instead printing the contents of the file and disconnecting the user. Note that this will *not* disconnect currently playing users.\n\nThe file `/srv/doomrl/debug`, if it exists, will put the server in debug mode. Mostly, this just means if something goes wrong, the user will get a full stack trace. You can also create the file `/srv/doomrl/players/\u003cplayer name\u003e/debug` to enable debug mode only for some players.\n\nThe `rebuild` command (which forces an immediate rebuild of the web scoreboard) is also limited to users with debug privileges.\n\n### DoomRL configuration files\n\nDoomRL configuration files are located in `/usr/src/doomrl-server/config/`. Of these, the files `controls.lua`, `colours.lua`, and `user.lua` are copied at player registration time and can be edited by the player afterwards; the other files are read-only. The defaults should be fine for most purposes, but you might want to edit them to, say, enable a custom mod server.\n\nIf you want to override any of these files, you need to copy *the entire `config/` directory* into `/srv/doomrl`; copying just some of the files will break user registration.\n\nTODO: instructions on regenerating user symlinks when you move configuration files around.\n\n### Closed captions\n\n`doomrl-server` supports closed captions, via loading a custom audio library. This support is automatically activated if the library is present. The library is included in the doomrl-server distribution.\n\nTo build it, you'll need a C compiler, `make`, and `libSDL` (including the development headers) installed. Once you have those, just `make -C /usr/src/doomrl-server/ttysound` and it'll build the library. To remove it, `rm /usr/src/doomrl-server/ttysound/libttysound.so`.\n\nNo further setup is needed (but some configuration settings are available; see below).\n\nFor information on using closed caption support stand-alone (i.e. not as part of doomrl-server), see `ttysound/README.md`.\n\n#### Configuration\n\nIn the config files that ship with doomrl-server, CC support, if available, is activated via the `DeafMode` setting (by analogy to `ColorBlindMode`). Setting it to `\"default\"` will select the default setting for this server. Other values select different CC styles or disable CC entirely.\n\nTo change the default setting for new users, edit `user.lua`. To change the default setting for this server (i.e. what users get when they select `\"default\"`), edit `soundcc.lua`.\n\nFor more information on valid values for `DeafMode` and adding or editing CC styles, see `ttysound/README.md`\n\n\n## Directory layout\n\n    $data_path/config/\n    $user_path/config/\n\nHolds the configuration used by doomrl when launched via doomrl-server.\n\n    $user_path/players/*/\n\nEach one of these is a player-specific DoomRL directory. Most of the contents are symlinks to files in `$data_path` and `$doom_path`.\n\n    $user_path/players/*/saves/\n\nGames in progress, each one named for that game.\n\n    $user_path/players/*/archive/\n\nArchived mortem and ttyrec files and the server scores file for that player.\n\n    $user_path/www/\n\nHolds the static web scoreboard. Regenerated every time a game is finished.\n\n\n\n## Importing scores from offline\n\nDoomRL-server doesn't read the score.wad file directly; rather, after each game, it extracts the scoreline for that game, adds some additional info to it, and stores in in `players/$PLAYER/archive/scores`. Similarly, postmortems are renamed to make them easier for the server to find. Thus, importing a player is a bit more complicated than just copying the files into place; to automate this, the `import-player` script is available.\n\nTo use it, register the player, and then, *from the root of your doomrl-server install*, run `import-player \u003cname\u003e \u003cplayer.wad\u003e \u003cscore.wad\u003e \u003cmortem/\u003e`. The `player.wad` file is the only mandatory part, and contains user progression, unlock and achievement information. `score.wad` contains the player's high score list. `mortem/` can only be imported if `score.wad` is as well, and will attempt to import all of the mortem files and match them up with high score list entries.\n\nIn the latter case, it may not always be able to narrow it down to a single high score entry. In that case, you will get a `writing duplicate scorelines, please edit and correct` message. Open the `players/\u003cname\u003e/archive/scores` file, find the duplicate entries, and read the corresponding mortem files to figure out which is the correct one (if possible) and delete the rest.\n\n\n\n## Future Work\n\n`wins` command to list winning games only.\n\nArchive ttyrecs compressed and decompress on demand.\n\nLet players upload and download their score.wad/player.wad/mortem files without admin intervention.\n\n\"There are %d other players online\" banner?\n\nProperly handle OSError when (e.g.) playing ttyrecs, since sometimes we see that before we see the SIGHUP from the user disconnecting.\n\n`savescum` command to restore old save files (probably marking those games non-scoring or storing them in a separate scores file).\n\nSound support in the web client: stream music and sound effects to the browser, either by generating an actual audio stream, or by sending the browser links to mp3 or ogg files to play in TTY comments (i.e. ESC ] 5 0 ; # + \u003ccomment text\u003e ESC) -- the latter has the advantage that it'll be recorded in the ttyrec and can thus be replayed in a sound-capable terminal.\n\n\n\n## License\n\nCopyright © 2019 ToxicFrog\nDistributed under the MIT License; see the file COPYING for details.\n\nASCII DOOM logo copyright © 1994 F.P. de Vries.\nhttp://www.gamers.org/~fpv/doomlogo.html\n\n\n\n## Disclaimer\n\nThis project is not affiliated in any way with Doom or DoomRL.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoxicfrog%2Fdoomrl-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoxicfrog%2Fdoomrl-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoxicfrog%2Fdoomrl-server/lists"}