crowly/mugins repository overview

muginsd - the MUGINS GameMaster as a Remote Provider muginsd re-implements the MUGINS Level 2 GameMaster (the BBC BASIC program GAME2 2.42) in PHP, hosted over aun-filestore's Remote Provider Protocol

the same way SqlServer is hosted in sql-serverd. BBC Micro Adventurer clients (ADV2, unmodified) talk to it over Econet via a filestored instance; muginsd connects to that filestored over the relay and has no transport of its own. MUGINS is a multi-user dungeon: one GameMaster, many Adventurers, played over Econet. See docs/MUGINS.TXT and docs/TECH.TXT for the original description, docs/basic/ for the de-tokenised BBC BASIC, and docs/protocols/mugins.md for the wire protocol this implements. docs/mugins-server-plan.md is the implementation plan.

Layout src/include/classes/ Command/Muginsd.php Symfony Command: relay wiring + event loop Messages/MuginsRequest.php inbound packet decode Messages/MuginsReply.php outbound packet builder Services/Provider/Mugins.php the ProviderInterface implementation Services/Provider/Mugins/ Game.php the whole in-memory world + packet entry points Map.php MapCell.php the 16x16 dungeon grid Player.php PlayerTable.php the player list (GAME2 slot semantics) CommandDispatcher.php verb -> handler (PROC_DOPROCS) ReplyFormatter.php GAME2 PROC_ADD word wrap + reply flag bytes Discovery.php the FindServer exchange Spellbook.php JEVOG / AUNIJANOG + a registry for more src/muginsd executable entry point third-party/aun-filestore git submodule: HomeLan\FileStore* is reused from here data/default-map.txt the GAME2 2.42 map data unit-tests/ PHPUnit suite HomeLan\FileStore* classes come from the third-party/aun-filestore submodule via a multi-root PSR-4 map in src/composer.json; the runtime dependency set (ReactPHP, Ratchet, Symfony Console, Monolog) is pinned in this project's own composer.json so src/vendor/ is self-sufficient.

Build & test make deps # git submodule update + composer install make test # PHPUnit make phpstan # level 10 make lint # phpcs (PSR-12 + tabs) make all # test + phpstan + lint Run Against a running filestored whose ProxyProvider reserves 0xB0 and 0x4D and whose Remote Provider relay is enabled (see docs/protocols/mugins.md):

./src/muginsd --config /etc/muginsd or in a container (native PHP, no PDO/LDAP):

make docker make docker-run # or: docker run --rm --network host muginsd:latest Native binary (TypePHP, experimental) make mugins-typephp runs the aun-filestore TypePHP (swoole/typephp) AOT toolchain against packaging/typephp/project.muginsd.yml, reusing that project's staged ReactPHP / Ratchet tree. Defaults to a C++-generation dry run; TYPEPHP_DRY=0 make mugins-typephp compiles and links build/muginsd. Needs podman (or PODMAN=docker). See packaging/typephp/README.md.

Continuous integration .github/workflows/ci.yml - PHPUnit, PHPStan (level 10), PHPCS on every push / PR. .github/workflows/typephp-native.yml - the TypePHP build: a C++-generation gate on push / PR, and a full build/muginsd compile + smoke test + release artifact on workflow_dispatch / a published release. .github/workflows/docker.yml - builds packaging/docker/Dockerfile and pushes it to Docker Hub as crowly/mugins (:latest on the default branch, semver tags on v* tags, linux/amd64 + linux/arm64). Needs the DOCKERHUB_USERNAME and DOCKERHUB_TOKEN repository secrets; PRs build without pushing. All three fetch the third-party/aun-filestore submodule from its .gitmodules URL. To fetch from a different remote set the AUN_FILESTORE_REPO_URL repository variable; a private HTTPS remote also needs an AUN_FILESTORE_TOKEN secret.

Configuration All keys and defaults are in src/include/config.inc.php and documented in docs/protocols/mugins.md. Override them from any *.conf file in the directory passed to --config.