Developers' Guide

This guide should answer most questions related to developing for the website. If you're interested in becoming a developer please reach out to us, and don't hesitatie to ask any additional questions you might have.

1. MOMW Guidelines
2. Getting Started
3. Building and testing the website locally
4. How to add a Mod to the database
5. How to add a Mod to a Mod List
6. How to add a Mod Category
7. How to add a mod list
8. How to add a mod tag
9. How to add new pages to the website
10. Maintaining the MOMW stack

MOMW Guidelines

You can consider this list a set of commandments; specific rules and patterns we must adhere to:

1. The website must update when mods update

   Always keep mods up-to-date. If a mod update breaks the website the website must update promptly.

2. The website must get tested locally before changes are submitted

   We provide the means to test your changes to the website locally before you submit any changes, so use them! Changes always get commited to the beta branch before being committed to master, so submit your merge requests accordingly.

3. The website must never have dead links

   The website makes it easy to redirect urls if urls need to be changed. Users landing on the 404 page is a failure of action on our part.

4. The website must adhere to mod permissions and developers must report or submit upstream fixes wherever possible

   If a mod is broken make sure to report the issue to the mod author so that they can address it. In situations where the mod author is absent or unable to update the mod we can make our own patches, but be sure mod permissions allow patches, and make an effort to contact the mod author to get their approval.

5. The website must stay organized

   Make sure to adhere to the organizational structures for files you're touching. For example, Mod Category files are alphabetized by mod name for ease of use, and changelogs are structured with latest changes on top.

Getting Started

So you want to be a developer, huh? Well, the first thing you need is a Gitlab Account in order to submit changes to our repository. It's also important to have a good IDE to develop in. The website uses Django/Python for the backend and .yaml, .toml, and .json files for the data, so make sure the IDE you choose has ample support for those formats. For Python development we also use Black for styling.

Once you have your programs sorted out, you'll need to clone the repository with git. A good IDE should have this feature built-in. Remember to follow the guidelines for any changes you make, and also ensure any Merge Requests you submit are targeting the beta branch.

Building and testing the website locally

Linux:

Building the website is as easy as navigating to the root of the modding-openmw.com git repository you cloned and running make venv pip-requirements reset server. Depending on your distribution you may need to install some prerequisite files. Once the server starts you'll be able to visit localhost:8000 in your browser to view the local test site.

Windows:

The Windows configuration requires you to install wsl. Instructions to do so can be found here. The default configuration should work without issues. With wsl installed you will need to manually install some prerequisite files. In your Windows terminal use the wsl command to enter the Linux environment. Run sudo apt install make python3 python3-pip python-is-python3 libxml2-dev python3-venv to get the prerequisite files and logout once it's finished.

With wsl and all the prerequisite files installed, navigate to the root modding-openmw.com repository you cloned in your terminal and run Powershell.exe -executionpolicy bypass -File .\bin\reset-tool.ps1. This will open up a menu where you can use the R command to start the server. Once the server starts you'll be able to visit localhost:8000 in your browser to view the local test site.

How to add a Mod to the database

Mods are initially added as data in the mod category .toml files located in /momw/momw/data_seeds/by_category. Make sure to choose the correct category for the mod you're inserting, and make sure the entry is alphabetized by mod name. You will need at minimum from the mod page:

• name: The mod name verbatim from the mod's page
• author: Either an html href to the author's git account page, a django nexus_user tag for nexus users, or other link to a mod author's personal page
• date_added: The timestamp for when you added the mod to the website's database
• description: A short description for the mod. Usually lifted from the mod page for the author's own words
• url: Either the url string to the mod's page or a django nexus_mod tag for mods hosted on nexus

• tags: An array list of tags for the mod. The full list of tags can be found on the Mod Tags page. New tags can be added and the process is described in the 'How to add other details' section of this guide
• date_updated: The timestamp for when you updated the mod already existing in the website's database
• alt_to: An array list of mods this mod is an alternative to. Note: As a consequence of how the website's data is built it's vital for alternative mods to be loaded and in the database before the alt_to field will function. In other words, since mods categories - and subsequently the mods within - are loaded in alphabetical order, alternative mods listed in alt_to fields need to be listed above the current mod in some way. Typically if the field doesn't work with the current working mod you're adding this tag to, it's sufficient to instead add the current working mod as an alt_to for the other mod it's an alternative to.
• compat: A string which is either fully working, partially working, not working, or unknown. Used to describe the mod's compatibility with OpenMW.
• slug: A hyphenated string used to override long mod names into a more terse and abbreviated url slug
• picture: The url string for a hosted image if you want one to accompany the mod page
• dl_url: The url string for a direct download, when one is necessary

How to add a Mod to a Mod List

Once you add the mod to the website's database you're ready to add a mod to the mod list. You'll need to know the following information:

• Which Mod Lists are getting this mod?
• What Data Paths need to be loaded?
• What Plugins (if any) need to be loaded?
• What is the load order?
• Where can the mod be downloaded?

1. Edit data/data-path-order.yml to insert the mod's data path. Entries are listed in their overarching load order. Multiple entries need to be made for each data path. The schema assumes by default the mod's "Data Files" folder is the root folder for the downloaded archive, and any extra child directories must be listed as extra_dirs. Make sure to fill in the on_lists field to associate the data paths with the mod lists they're going into. In rare cases where there are loose mod files which need a folder not provided by the mod make sure to set the manual field to true. In other cases where certain data paths - or the mod itself - requires a development build of OpenMW make sure to set the dev_build field to true (or sometimes false if logic dictates)
2. If the mod has any plugins which need to be enabled edit data/plugin-order.yml (or data/groundcover-order.yml if the plugins are for groundcover or data/bsa-order.yml if the plugin is a bsa file) to associate each plugin that needs to be enabled with the mod lists they're going into. Entries are listed in their overarching load order. As before, if the plugin requires the development build of OpenMW make sure to set the dev_build field to true (or false if logic dictates). In rare cases where mods contain dirty records which must be cleaned make sure to set the needs_cleaning field to true. The fields is_groundcover and is_bsa should be set to true for each of those cases where applicable. Also the conflicts and depends fields should be declared for any mod conflicts or dependencies
3. If the mod has multiple files to download, previously declared manual folders, instructions specific to a certain mod list, or other important installation details, edit data/usage-notes.toml to add those instructions. Note the generic mod list slug is used here for mod list agnostic instructions where it's appropriate
4. If the mod requires any additional settings.cfg or openmw.cfg configuration, edit data/extra-cfg.toml in order to declare the configuration. By default settings declared here will be added to the openmw.cfg, but if they need to go into settings.cfg make sure to set the in_settings field to true
5. Edit data/mod-archives.json in order to provide umo with details on which files need to be downloaded. The ordering is unimportant, but separate entries need to be made for each file to be downloaded as determined by the name field. The extract_to field should contain the mod name without spaces or special characters, and additionally if any manual folders were declared earlier include those after the mod name in this field ie: NormalMapsforPremium/BannersandFlags
6. If the mod requires that files be renamed, moved, or cleaned, edit data/actions.json to add an entry for umo to use during installation
7. Edit each mod list's .toml file in data/ to officially attach the mod to the mod list. For example if you wanted to add a mod to total-overhaul, you would edit data/total-overhaul.toml
8. Finally, make sure you edit or create the latest changelog file in data/changelogs with details about the mod you added, updated, or in some cases removed.

How to add a Mod Category

To add a mod category you first need to edit momw/momw/data_seeds/mod_categories.py to add the category to the website's database. Each category will need a title, slug, and a brief description. There are various other files which need to be edited as well, but a simple search for a category slug should reveal all necessary files. Next, you'll want to create a .toml file with the name of the category to momw/momw/data_seeds/by_category and list the mods you're adding to the category in this file. Use the other category .toml files for examples.

How to add a mod list

To add a mod list you first need to edit momw/momw/data_seeds/mod_lists.py to add the mod list to the website's database. There are various other files which need to be edited as well, but a simple search for a mod list slug should reveal all necessary files. Next, you'll want to create a .toml file with the name of the mod list to momw/momw/data_seeds/data and list the sublists with each mod you're adding to the mod list. Use the other mod list .toml files for examples. You can also declare mod lists as wip (work in progress) to hide the mod list from public view until the mod list is ready for public deployment.

How to add a mod tag

To add a mod tag you need to edit momw/momw/data_seeds/mod_tags.py. All you need to provide is a name and a short description. With the tag declared you can use it in any of the category .toml files in momw/momw/data_seeds/by_category by adding the tags to the tags field for each applicable mod.

How to add new pages to the website

TODO: Explain how to add static pages and pages with dynamic features.

Maintaining the MOMW stack

TODO: Fill this in lol

MOMW Patches and MockMW

MOMW Post Processing Pack

MOMW Tools Pack

Distant Land Fixes