smr

Running the game locally

Space Merchant Realms, or SMR, is a game engine you run rather than just read. The README's setup assumes Docker, version 19.03.0 or newer, plus the Docker Compose plugin version 2, and Composer 2.0.5 or newer if you want to run unit tests on your machine. The first step is to clone the repository, then create installation specific copies of sample files: .env from .env.sample, .my.cnf from .my.cnf.sample, and config/config.specific.php from its sample. The samples ship with sensible defaults, but the README warns that the options must stay consistent across the files. To build the database, you run a flyway container which applies patches, and you add new schema changes by dropping a V(number)__(name).sql file into db/patches and rerunning. A phpMyAdmin container is available if you want to inspect MySQL in a browser. Starting the services brings up traefik and smr. For administration, you register a normal account, then run db/init_admin.sh to grant it admin permissions, which opens an Admin Tools link. Creating a game requires the 1.6 Universe Generator permission and then flipping the game table's enabled flag to true so it shows in the join list. The whole flow is container based, so the environment stays repeatable. The container based setup means a contributor on Linux, macOS, or Windows sees the same database and services. That parity reduces the it works on my machine class of bugs that open source game servers often suffer when everyone builds the stack their own way.

Code style and structure

The coding style section sets rules that new code should follow, even though not all existing code does yet. Opening braces go on the same line with a single space before them, and even single line if statements keep their braces. Variable names use camelCase, except inside templates where they use UpperCamelCase to mark the mental switch between contexts. Function names are camelCase and class names are UpperCamelCase, while associative array indices use UpperCamelCase. On structure, classes belong in src/lib/Smr so the PSR-4 autoloader picks them up, and engine files with their templates live in src/engine and src/templates, wired together through Page::process. Links are generated by functions on Globals or on the relevant object, such as Globals::getCurrentSectorHREF or a player's getExamineTraderHREF, which keeps hotkey hooks working. Request input from POST or GET is read through Smr\Session::getRequestVar so values persist in the session across AJAX refreshes. The abstract versus normal class split changed intent: shared default behavior now lives in abstract classes, while child classes implement game specific overrides. These conventions are the map a contributor uses to place new code without breaking the page dispatch model. The UpperCamelCase rule for template variables is a small but real aid when reading mixed code, since it flags context at a glance. New contributors who follow the page dispatch model spend less time guessing where a feature lives and more time extending it along the existing lines.

Testing

SMR uses PHPUnit for its unit tests. The README explains that you first make sure the MySQL container is running for any integration tests that touch the database, then run composer phpunit to execute the full suite, and add new tests under the /test directory. A notable wrinkle comes from the storage engine: the SMR database uses MyISAM, which cannot roll back transactions after each test the way InnoDB would. To work around that, integration tests extend SmrTest\BaseIntegrationSpec, which truncates all tables not populated by the flyway migration at startup, so data written during a test is cleaned up afterward. The README also walks through wiring PHPUnit into IDEA based IDEs such as IntelliJ and PHPStorm, listing the PHP and PHP Docker plugins you need and the steps to register a remote interpreter from the phpunit Docker Compose service. You then point the interpreter at the project's autoload and phpunit.xml paths inside the container. That setup lets a developer run tests from the IDE against the same container the CI uses. The detail shows the project cares about a reproducible test environment rather than leaving contributors to guess at local configuration. The MyISAM workaround is a good example of the project adapting its tests to the database it actually uses. Rather than switch storage engines, the suite cleans up after itself in a way that matches production, so a passing test means the code behaves the same where it will really run.

Editorial conclusion

Space Merchant Realms is licensed under AGPL-3.0 and written in PHP, using Docker Compose for local setup and PHPUnit for its test suite.