Difference between revisions of "Understanding the File System"

From DikuMUD Wiki
Jump to navigation Jump to search
(checked against the current code (wiki review 2026-11-15))
 
Line 1: Line 1:
−
I've got all these files and directories...what is all this stuff?
+
What is in the DikuMUD III repository, and which parts you are likely to change. For how the running programs use these directories, see [[Understanding the Architecture of DikuMUD at runtime]].
  
−
Starting at the top:
+
== The top directory ==
 +
{| class="wikitable"
 +
! Name !! What it is
 +
|-
 +
| <code>LICENSE</code> || The licence. It is what lets you run, copy and change the software, and it sets the conditions for doing so. Keep it with any copy you make.
 +
|-
 +
| <code>README.md</code>, <code>README_cmake.md</code> || How to build and start the game, and more build options.
 +
|-
 +
| <code>CLAUDE.md</code>, <code>DIL_UNIT_TESTING.md</code>, <code>WIZARD_LEVELS.md</code> || Notes for developers: building, running and debugging; DIL tests inside the game; the administrator levels.
 +
|-
 +
| <code>vme/</code> || The game itself: sources, configuration, zones, saved data and the web client. See below.
 +
|-
 +
| <code>CMakeLists.txt</code> || The build description. <code>cmake .</code> reads it; see [[Manual:Installation]].
 +
|-
 +
| <code>unit_tests/</code> || The unit tests (Boost.Test), run by <code>make all</code> and <code>ctest</code>.
 +
|-
 +
| <code>docs/</code> || Code documentation, generated by Doxygen during the build if it is installed.
 +
|-
 +
| <code>Dockerfile</code>, <code>docker-compose.yaml</code>, <code>entrypoint.sh</code> || Running the game in a Docker container.
 +
|-
 +
| <code>.github/workflows/</code> || The build and tests that GitHub runs for each change.
 +
|-
 +
| <code>githooks/</code>, <code>clang-format.sh</code>, <code>clang-tidy.sh</code> || Code formatting and checking for contributors.
 +
|-
 +
| <code>resethash.sh</code> || Clears the zone checksums that one of the unit tests compares against.
 +
|-
 +
| <code>.claude/skills/</code> || Notes on writing zones, compiling them and writing DIL, for AI coding assistants. The build compiles their example zones.
 +
|-
 +
| <code>excel/</code> || A spreadsheet of the ability tables.
 +
|-
 +
| <code>agents/</code>, <code>deploy/</code> || Tools the maintainers use for their own game. Not needed to run a MUD.
 +
|}
  
−
LICENSE - You're going to have to keep this file with any version of the software package that you make. Read it to better understand it. It's what authorizes you to run and even copy or change the software, but it also sets conditions on the rights that it gives you.
+
== The vme directory ==
 +
{| class="wikitable"
 +
! Directory !! What it holds
 +
|-
 +
| <code>bin/</code> || The programs, after the build: <code>vme</code> (the game server), <code>mplex</code> (the network front end), <code>vmc</code> (the zone compiler), <code>pp</code> (its preprocessor), <code>defcomp</code> and the unit test programs. The start scripts are here too, and the server and mplex are started from this directory, so their logs (<code>vme.log</code>, <code>mplex.log</code>) and the Discord pipes appear here. The scripts are listed below.
 +
|-
 +
| <code>src/</code> || The C++ source of the server. Subdirectories: <code>mplex/</code> (the front end, with the websocket library it uses), <code>vmc/</code> (the zone compiler; its grammar is <code>vmcpar.y</code> and the DIL grammar <code>dilpar.y</code>), <code>pp/</code> (the preprocessor) and <code>defcomp/</code>. The DIL interpreter is in the <code>dil*.cpp</code> files. Much of the game can be changed in the zones without touching this.
 +
|-
 +
| <code>zone/</code> || The world: one <code>.zon</code> source file per zone, with the rooms, objects, NPCs, resets and DIL programs. vmc compiles each one to a <code>.data</code> and a <code>.reset</code> file here, which the server loads at boot. A compile also leaves <code>.err</code>, <code>.dh</code> and <code>.dot</code> files. See the [[Manual:Zone Manual]].
 +
|-
 +
| <code>include/</code> || The header files that zones include: macros and constants such as <code>macros.h</code>, <code>values.h</code> and <code>vme.h</code>. Most constants here must match the server's source, so change them only together with it, and recompile the server and all the zones afterwards.
 +
|-
 +
| <code>etc/</code> || Configuration and game definitions, read by the server at boot. <code>server.cfg</code> (the main settings), <code>zonelist</code> (which zones to load), the definition files <code>abilities.def</code>, <code>commands.def</code>, <code>professions.def</code>, <code>races.def</code>, <code>sector.def</code>, <code>spells.def</code>, <code>weapons.def</code> and <code>color.def</code> (the build turns each into a <code>.dat</code> file, which is what the server reads), <code>money</code>, <code>messages</code> (combat messages), <code>badnames</code>, the login screen <code>logo</code>, texts such as the message of the day in <code>strings/</code>, and the help pages in <code>help/strings/</code>.
 +
|-
 +
| <code>lib/</code> || The saved state of the game: player files in <code>ply/a/</code> to <code>ply/z/</code>, the player id counter <code>players.id</code>, boards, banned sites, and the data DIL programs save (<code>dilfiles/</code> and other directories named in <code>zonelist</code>). Treat this as live data and back it up.
 +
|-
 +
| <code>log/</code> || Statistics and account logs, and the logs of the start scripts (<code>vme.log</code>, <code>mplex-&lt;port&gt;.log</code>, <code>dispatcher.log</code>, <code>muddiscord.log</code>) with their older, compressed copies.
 +
|-
 +
| <code>www/</code> || The web client in <code>client/</code> (<code>index.html</code>, and <code>client-a.html</code> for screen readers), the pictures it shows in <code>img/</code>, and the page the Docker image serves in <code>docker/</code>.
 +
|-
 +
| <code>nginx/</code> || The web server configuration used in the Docker image.
 +
|-
 +
| <code>doc/</code> || Old documentation from VME 2.0 (2001): text files, the old zone manual and DIL pages. Much of it no longer matches the code; this wiki replaces it.
 +
|-
 +
| <code>scripts/</code> || Conversion scripts from VME 1.x to VME 2.0 (2001). Not needed today.
 +
|}
  
−
README.md - Of course, you already did, right?
+
== Scripts in vme/bin ==
 +
{| class="wikitable"
 +
! Script !! What it does
 +
|-
 +
| <code>startvme.sh</code>, <code>stopvme.sh</code> || Start and stop the whole game: vme, one mplex for each <code>mplexer</code> line in <code>server.cfg</code>, and the Discord programs.
 +
|-
 +
| <code>runvme.sh</code>, <code>runmplex.sh</code> || Run vme or one mplex, rotate its log in <code>vme/log/</code>, and start it again when it exits.
 +
|-
 +
| <code>rundispatcher.sh</code>, <code>runmuddiscord.sh</code>, <code>dispatcher.py</code>, <code>muddiscord.py</code> || The [[Manual:Discord|Discord link]].
 +
|-
 +
| <code>defconvert.perl</code> || Turns the <code>.def</code> files in <code>vme/etc/</code> into <code>.dat</code> files; the build runs it.
 +
|-
 +
| <code>intergration_test.sh</code> || Runs the DIL integration tests: it boots a test world with time-warped vme and checks the results. It copies <code>etc/zonelist.test</code> over <code>etc/zonelist</code>, so save your own <code>zonelist</code> before running it.
 +
|-
 +
| <code>zoneflags.py</code> || Finds flag fields in zone sources that were given the wrong kind of flag, which vmc cannot catch.
 +
|}
 +
The other files in <code>vme/bin/</code> (<code>startvme.perl</code>, <code>ftpcompiler</code>, <code>emailcompiler</code>, <code>htmlcompiler</code>, <code>executer.perl</code> and similar) are older scripts from earlier versions or for one particular site. The start scripts above don't use them.
  
−
vme - the directory with the magic in it!
+
== What you will change first ==
−
 
+
* <code>vme/etc/server.cfg</code>: the name of the game, the name of the first god, the ports. See [[Manual:Installation]].
−
=== vme subdirectories ===
+
* <code>vme/etc/zonelist</code>: which zones are loaded.
−
 
+
* <code>vme/zone/*.zon</code>: the world. Recompile with vmc and restart the server.
−
bin - The binary files used to run and maintain the MUD
+
* <code>vme/etc/strings/</code>: the welcome and login texts, the message of the day, the news.
−
 
 
−
build - When you compile the code, the objects will be built into this directory - not meant to be edited.
 
−
 
 
−
doc - Well, what can we say, we tried, but we're programmers, not tech-writers.
 
−
 
 
−
etc - Configuration data to drive how the MUD works, what it outputs, what makes it unique, etc.
 
−
 
 
−
include - Include files - containing constants that drive how the MUD works - editing anything in here will mean a recompile. Not only that, but it will probably mean some painful errors or problems caused by your change because of something you didn't think of before you changed it.
 
−
 
 
−
lib - The library - bulletin board data, references to current player number, criminal activity, deaths, player bans.
 
−
 
 
−
log - Probably a good place to point your logs to (?)
 
−
 
 
−
scripts - Conversion utilities and other madness to make things easier.
 
−
 
 
−
src - The source code for the MUD engine and the multiplexer code that provides the connectivity to it. You're probably going to want to play with this at some point if you're reading this...but you can do soooo much now with what's in 'zone' that you may not need to.
 
−
 
 
−
todo - A peek into the mind of a wizard considering that which weighs on his shoulders.
 
−
 
 
−
www - The files that make up the web front end and the HTML5 client.
 
−
 
 
−
zone - The Zone files that define the world and how it behaves
 

Latest revision as of 06:14, 15 November 2026

What is in the DikuMUD III repository, and which parts you are likely to change. For how the running programs use these directories, see Understanding the Architecture of DikuMUD at runtime.

The top directory

Name What it is
LICENSE The licence. It is what lets you run, copy and change the software, and it sets the conditions for doing so. Keep it with any copy you make.
README.md, README_cmake.md How to build and start the game, and more build options.
CLAUDE.md, DIL_UNIT_TESTING.md, WIZARD_LEVELS.md Notes for developers: building, running and debugging; DIL tests inside the game; the administrator levels.
vme/ The game itself: sources, configuration, zones, saved data and the web client. See below.
CMakeLists.txt The build description. cmake . reads it; see Manual:Installation.
unit_tests/ The unit tests (Boost.Test), run by make all and ctest.
docs/ Code documentation, generated by Doxygen during the build if it is installed.
Dockerfile, docker-compose.yaml, entrypoint.sh Running the game in a Docker container.
.github/workflows/ The build and tests that GitHub runs for each change.
githooks/, clang-format.sh, clang-tidy.sh Code formatting and checking for contributors.
resethash.sh Clears the zone checksums that one of the unit tests compares against.
.claude/skills/ Notes on writing zones, compiling them and writing DIL, for AI coding assistants. The build compiles their example zones.
excel/ A spreadsheet of the ability tables.
agents/, deploy/ Tools the maintainers use for their own game. Not needed to run a MUD.

The vme directory

Directory What it holds
bin/ The programs, after the build: vme (the game server), mplex (the network front end), vmc (the zone compiler), pp (its preprocessor), defcomp and the unit test programs. The start scripts are here too, and the server and mplex are started from this directory, so their logs (vme.log, mplex.log) and the Discord pipes appear here. The scripts are listed below.
src/ The C++ source of the server. Subdirectories: mplex/ (the front end, with the websocket library it uses), vmc/ (the zone compiler; its grammar is vmcpar.y and the DIL grammar dilpar.y), pp/ (the preprocessor) and defcomp/. The DIL interpreter is in the dil*.cpp files. Much of the game can be changed in the zones without touching this.
zone/ The world: one .zon source file per zone, with the rooms, objects, NPCs, resets and DIL programs. vmc compiles each one to a .data and a .reset file here, which the server loads at boot. A compile also leaves .err, .dh and .dot files. See the Manual:Zone Manual.
include/ The header files that zones include: macros and constants such as macros.h, values.h and vme.h. Most constants here must match the server's source, so change them only together with it, and recompile the server and all the zones afterwards.
etc/ Configuration and game definitions, read by the server at boot. server.cfg (the main settings), zonelist (which zones to load), the definition files abilities.def, commands.def, professions.def, races.def, sector.def, spells.def, weapons.def and color.def (the build turns each into a .dat file, which is what the server reads), money, messages (combat messages), badnames, the login screen logo, texts such as the message of the day in strings/, and the help pages in help/strings/.
lib/ The saved state of the game: player files in ply/a/ to ply/z/, the player id counter players.id, boards, banned sites, and the data DIL programs save (dilfiles/ and other directories named in zonelist). Treat this as live data and back it up.
log/ Statistics and account logs, and the logs of the start scripts (vme.log, mplex-<port>.log, dispatcher.log, muddiscord.log) with their older, compressed copies.
www/ The web client in client/ (index.html, and client-a.html for screen readers), the pictures it shows in img/, and the page the Docker image serves in docker/.
nginx/ The web server configuration used in the Docker image.
doc/ Old documentation from VME 2.0 (2001): text files, the old zone manual and DIL pages. Much of it no longer matches the code; this wiki replaces it.
scripts/ Conversion scripts from VME 1.x to VME 2.0 (2001). Not needed today.

Scripts in vme/bin

Script What it does
startvme.sh, stopvme.sh Start and stop the whole game: vme, one mplex for each mplexer line in server.cfg, and the Discord programs.
runvme.sh, runmplex.sh Run vme or one mplex, rotate its log in vme/log/, and start it again when it exits.
rundispatcher.sh, runmuddiscord.sh, dispatcher.py, muddiscord.py The Discord link.
defconvert.perl Turns the .def files in vme/etc/ into .dat files; the build runs it.
intergration_test.sh Runs the DIL integration tests: it boots a test world with time-warped vme and checks the results. It copies etc/zonelist.test over etc/zonelist, so save your own zonelist before running it.
zoneflags.py Finds flag fields in zone sources that were given the wrong kind of flag, which vmc cannot catch.

The other files in vme/bin/ (startvme.perl, ftpcompiler, emailcompiler, htmlcompiler, executer.perl and similar) are older scripts from earlier versions or for one particular site. The start scripts above don't use them.

What you will change first

  • vme/etc/server.cfg: the name of the game, the name of the first god, the ports. See Manual:Installation.
  • vme/etc/zonelist: which zones are loaded.
  • vme/zone/*.zon: the world. Recompile with vmc and restart the server.
  • vme/etc/strings/: the welcome and login texts, the message of the day, the news.