search

steventhorne / legendhub

Source code for the legendhub website.
https://www.legendhub.org
MIT License
3 stars 3 forks source link
hub info legendhub legendmud mud

readme

LegendHUB

A resource hub for LegendMUD.

Version v=2.5.0 License

Table of Contents

Prerequisites

This repo requires certain software in order to be deployed and run. This software will make it a lot easier to work with legendhub.

Installation

This repo contains a simple to use install process which assumes you have an HTTP server setup on that system.

Tech Stack

The following is a brief overview of the LegendHUB technical stack.

Website Server-Side Code

For the server-side code, Node.js is used alongside Express middleware using JavaScript.

This server-side code also uses compression, path, cookie-parser, and morgan as middleware.

ExpressJS is used to take care of routing requests to the route handlers as well as the API.

The API is a GraphQL API that runs in the same instance as the rest of the web server.

There is also a custom authentication middleware to handle authenticating every request.

EJS is used for view templating.

Website Client-Side Code

AngularJS v1.x is used for the client-side code. This framework is outdated and has entered LTS. This should not be a huge issue and there are alternatives.

Most of this AngularJS code is in the www/src/public/js directory under apps or controllers, though there is still some lingering code that exists in the views. See TODO List.

CSS

Bootstrap is used as the primary CSS tool. Bootstrap and custom bootstrap styles are written in SCSS.

Database

MySQL is used for the main LegendHUB database.

Services

There are additional routine maintenance and related services that run periodically outside of the web server.

These services are written in python and are found within the python/ directory.

Maintenance

Each of the following sections includes detailed instructions for maintenance of the various areas in LegendHUB.

Backups

LegendHUB automatically creates daily backups of the SQL database and drops them in database-backups Docker volume. This backup file is overwritten every day. It is recommended that you take these backups and copy them to a remote location.

There is a public and private directory in this volume. The public directory contains a backup without sensitive data, such as accounts, notifications, settings, etc.. The private directory contains a full backup of everything.

Updating the Builder

The builder is perhaps the messiest bit of code on the website. It has long been on my todo list for refactoring and cleaning up.

The reason it hasn't happened is because of how massive and fragile I view it.

Player lists are stored in localStorage on the browser. If a user clears their storage, uses a new browser, or runs into an error while using the builder, their lists are gone. Users are '''highly''' encouraged to export their lists periodically and back them up, but this advice is not always followed.

There is a system in place to catch unexpected exceptions that occur. If the user encounters one of these exceptions, the builder will no longer try to save their lists and will inform the user to refresh their browser. This should mitigate corrupt lists, though it may still be possible for other types of issues to corrupt lists, such as bad code in the saving or loading of lists. If the builder loads a list incorrectly, it will save it incorrectly as well, and lose any data that wasn't accounted for. If the code that saves lists is incorrect, it could also omit or mangle data.

Updating Stat Formulas

The function getStatTotal sums up stats and stat bonuses for each column in the builder.

There are a few sections inside of this area that handle unique scenarios, such as adding up base stats, item stats, applying item limits, apply bonus stats from other stats, apply total caps, etc. These sections should be commented and easy to find.

Within the functions called from that function, are typically switch statements that handle each stat individually, so it should be easy to find where stat formulas/item limits/caps need to be updated.

Updating Code

If any code needs to be updated, certain steps should be taken to ensure the code updates are put into effect.

In the case of any HTML or client-side JavaScript updates, the changes will be put into effect immediately. In these cases, it may be a good idea to make these changes in a development environment first, to prevent any issues from happening on the production site.

While client-side JavaScript changes can go into effect immediately, they don't always do because of browser caching. In order to force a JavaScript change to be put into effect, change the version number in the www/package.json file and restart the NodeJS application or Docker container.

Any changes to the NodeJS server-side JavaScript will not be put into effect until the NodeJS application or Docker container are restarted.

Updating CSS

LegendHUB uses [https://getbootstrap.com/docs/4.5/getting-started/introduction/ Bootstrap 4.x] to provide an easy-to-use UI framework. There has been some minor customization of this framework to meet LegendHUBs needs.

If any additional changes need to be made for custom CSS, this can be done in the css/scss/custom/_custom.scss file.

After making any changes, simply running npm run build will trigger a compile of the scss, linting of the resulting css, auto-prefixing for browser support, minification, and copying of the final files to the css directory in the web project's public files.

There are also a couple of themes that I've provided that can be found in the css/scss/custom/themes/ directory. These theme files change SCSS variables to define different properties that are used for bootstrap components and utilities.

Permissions

Certain actions on LegendHUB require permissions to complete. The following tables dictate how Members can interact with the website:

There are currently no CRUD pages that make it easy to modify Permissions and Roles. This must be done through SQL.

Currently the following permissions exist:

The Roles table defines which permissions a specific role has. This table contains an entry for each role on the website. Currently the following roles exist:

Roles can be assigned permissions by updating the RolePermissionMap table. This table is a many-to-many relationship that also includes how each role interacts with each permission. Each record contains the role and permission to be mapped, as well as whether that mapping allows for create, read, update, or delete privileges.

Members can be assigned roles by updating the MemberRoleMap table. This table is a many-to-many relationship and contains two columns: MemberId and RoleId.

Updating SQL Data

If you need to run any INSERT/UPDATE/DELETE queries in SQL, you must temporarily disable the triggers so that the update doesn't cause any notifications to be generated for users. This only needs to be done if you're modifying one of the following tables:

If this step isn't done before updating hundreds of rows, users will end up with quite a few notifications.

This can be done by running SET @DISABLE_NOTIFICATIONS = 1. This will only disable notifications for your SQL session, not for users on the website.

Adding New Areas

There are currently no CRUD pages that make it easy to modify Areas. This must be done through SQL.

The Areas table contains a list of areas in the game. This list is used to allow users to select areas for Items, Mobs, and Quests. To add a new area, simply fill out the Name and EraId for the record. The EraId column can be determined via the Eras table. The LuciferName and Era columns are deprecated and should no longer be used, though I still tend to fill out the Era column as it's pretty easy to do so.

No additional efforts need to be taken aside from including the new area in the Areas table. The website will automatically update as needed.

Adding a New Stat

This is probably the most involved aspect of LegendHUB, but is also made to be as easy as possible. (Though I'm sure there is room for improvement in this area)

The first thing that should be done is adding the stat to the Items and Items_AuditTrail table.

The second thing that should be done is updating the Items_AFTER_INSERT and Items_BEFORE_UPDATE triggers.

The third thing that should be done is adding the stat to the ItemStatInfo. The following columns are available in this table:

The final thing that should be done is restarting the docker instance. It does not need to be rebuilt. This will ensure that the NodeJS backend gets a hold of the new stat and updates the API code for it.

Type

This column defines how input fields and sorting work for the stat. The following types are valid values for this column:

The select type requires a fourth step for the new stat to function. In the www/src/public/js/apps/legendwiki-app.js file, there are two variables called selectOptions and selectShortOptions. Each of these variables needs a new property whose name must be the same as the Var column in the ItemStatInfo table.

The property should map to an array of strings. The first item in that array is the null value display. For most cases, this is an empty string. The following strings are displayed when the value is equal to the index of the string.

The selectOptions decides what should be displayed when there is plenty of room in the UI.

The selectShortOptions decides what should be displayed when there is not much room in the UI.

FilterString

This defines how the SQL will be generated for searching items when this particular filter is enabled.

For example, the Light stat is a boolean value, so the FilterString is set to = 1. This means that the generated SQL will append isLight = 1 to the WHERE clause.

As another example, the Hp Regen stat is an integer value, so the FilterString is set to > 0. This means that the generated SQL will append hpr > 0 to the WHERE clause.

The final example is for select type stats. The Weapon Type stat is a dropdown value, so the FilterString is set to = {0}. The {0} is automatically replaced with the chosen item in the dropdown from the filter modal. So any select type stats, should also have this same FilterString.

TODO List

There were a number of things I still wanted to do with LegendHUB to clean it up, improve it. These aren't necessarily major features, but things that should be noted.