Developer docs

Contributing to Blastmud #

Get the source #

Making changes #

Make changes and test them locally (see dev env setup). If everything works correctly, submit a PR.

Feel free to discuss in an issue first before starting work - we can tell you if we think your idea is a good idea.

PRs are reviewed, and if we think it is appropriate for the game, it will be merged to main by a member of the core (Wizards) team. Merged PRs are tested, and if tests pass, they are automatically deployed. You can watch the status of the deployment over at [https://concourse.blastmud.org/].

Note that changes to the gameserver can be made without disconnecting all users, due to the design of the game. Changing the listener is a larger affair because it involves disconnecting all users. Confining your changes to the gameserver part of the code will mean we need to do less coordination to deploy it.

If you propose a change to us, you agree that unless you explicitly state otherwise, you grant everyone a licence to use it under the same licence terms (as documented in the LICENSE file) as the other code in the repository you are contributing to.

Rules to increase the chances your change will be accepted #

  • The game must stay within the guidelines to be rated as PG in Australia, rather than M, MA15+, R18+ or Refused Classification (i.e. illegal to distribute in Australia). No content that would make it RC can be accepted - this includes any content about any form of sexual violence, characters under 18 years of age (due to the interaction with the nature of this game), detailed instruction or promotion in crime or violence, incest or hard fetishes, or incentivised drug use (including any kind of buff from anything that could be construed as drugs). No PRs or other content of the kind described under this point may be submitted to any Blastmud resource (i.e. this restriction does not apply solely to PRs for the main branch). To avoid a higher classification, it is also necessary that violence remains mild and infrequent (taking the game as a whole), and that there is nothing more than infrequent discreet references to sexual activity (and not related to incentives / rewards).
  • Your change shouldn’t compromise security or privacy. It shouldn’t create a risk that users can execute arbitrary code, access confidential information, misuse resources, or deny service to users. It should respect the privacy of users and not use personally-linked information for any purpose not mentioned in the privacy policy. It should not leak secrets such as deployment keys or the actual IP addresses of the systems on which Blastmud is deployed (other than the public proxy).
  • Your change should be appropriate to the theme of the game.
  • Your change should be safe to roll-back if it doesn’t work correctly (if this is genuinely not possible, please discuss it with us).
  • Your game should ensure the game remains balanced and fair both for players who primarily want to engage in PvE play, and those who want to engage in PvP with other willing participants.

Setting up a blastmud development environment #

  • Check it out locally with git. git clone https://git.blastmud.org/blasthavers/blastmud.git.
  • Ensure you have Rust installed. Visit https://rustup.rs/ for help getting started.
  • Run cargo test && cargo build to test and install the code.
  • Setup postgresql. See the Postgres docs for help. Create a postgresql database (in these instructions, I assume you call it blast) and user (called blast in these instructions as well) for Blastmud.
  • Run psql -d template1 <schema/schema.sql as a user with access to create databases.
  • Install migra - pip3 install migra.
  • Diff the blast DB from the temporary blast_schemaonly DB with migra "postgres:///blast" "postgres:///blast_schemaonly" > /tmp/update.sql
  • Check /tmp/update.sql and if it looks good, apply it with psql -U blast -d blast </tmp/update.sql
  • Create a config directory under the blastmud directory you checked out, and put a listener.conf and gameserver.conf in it, with the content below. Also make a run directory under config.
  • From the config directory, run ../target/debug/blastmud_listener. In another tab, run ../target/debug/blastmud_game.
  • Connect to port 1234 on localhost to test it out locally.

listener.conf # 

listeners:
  - 127.0.0.1:1234
gameserver: 127.0.0.1:1235
ws_listener: 127.0.0.1:1236
pidfile: ./run/listener.pid

gameserver.conf # 

listener: 127.0.0.1:1235
pidfile: ./run/gameserver.pid
database_conn_string: host=/var/run/postgresql user=blast password=blastuserpasswordhere dbname=blast

Adjust password for the database, and the path to the postgresql socket accordingly (you can also put host=localhost to connect over TCP if you prefer, but this is less efficient).

Getting around the Blastmud codebase #

Listener #

The listener lives under blastmud_listener/ accepts WebSocket and telnet connections. It establishes and maintains a connection to the gameserver, and sends information about new connections and user commands (lines of input) to the gameserver. It accepts commands from the gameserver.

Restarting it will disconnect all users.

blastmud_interfaces #

These live under blastmud_interfaces/ and define the contract between the listener and the gameserver.

Since it is a dependency for the listener, changing it will require restarting the listener and disconnecting all users.

Gameserver #

This lives under blastmud_game. It is stateless (other than temporary caches that can be replaced at any time), with all state living in the database, so that it can be restarted at any time without impacting users.

It is further divided up as follows:

main.rs is the entrypoint.

version_cutover.rs handles seamless cutovers - the new version starts up, finds the existing version, and sends it SIGUSR1 to tell it to shut down gracefully. Users will not notice any impact on thier game session.

The static_content module has submodules for npcs, rooms, species, possession_types (including weapons), and fixed_items (features within rooms that can be looked at for example).

The regular_tasks module has the infrastructure for anything that happens repeatedly (although most actual task logic is in other modules - e.g. NPC movement is in static_content/npc).

The models module defines the structure of the content that is stored as BSON within the database. This for example defines all the fields on users and items.

The listener module defines the interaction with the listener.

The services module provides common calculations (e.g. around combat, capacity limits, skill checks, and broadcasting to everyone in a room).

The db module provides support for interacting with the database.

The message_handler module handles messages from the listener. message_handler/user_commands in particular has all the logic for handling commands sent by users.

Key models within the gameserver #

  • A Session represents a connected (but possibly unregistered) session.
  • A User represents a particular registered user of the game. Sessions get attached to users on login. Note that every User has an Item of type player as well - User has the (often OOC) details that only make sense for a real player, such as their password, while everything common to players and NPCs lives on the item.
  • An Item represents something that can be seen in the game - a player, NPC, possession, room, and so on.
  • A Task represents something that will happen in the future, either as a once-off or recurring.
Edit Propose change