Tour of the repository

This page covers the layout of the project repository, where to look for things, and where the various build steps put things.

Top level

The top of the project repository contains the usual suspects: readme, package.json and yarn.lock for node tooling, gulpfile.js to define the build process etc, .gitignore. It also contains a legacy Makefile from earlier days in the project. You can probably safely ignore this now.

The src, test, and LICENSES folders are what they say on the tin. static contains static content for the application. Notably the data files for all the monster information. There is also a normalise stylesheet, and various versions of the Manticore image. Earlier in the project some build process stuffed its output here too. Some old build targets may still do (notably less compilation).

Once you run gulp you will also get two additional folders: build and dist.

build

This directory contains the build output of compiler tasks, specifically the typescript compiler. There are two groups of outputs: javascript (js subfolder) and types. The javascript is the individual source files pre-bundling.

The types here are specifically for the common library project, and are used as a ambient `/// reference in the various other typescript codebases.

dist

This is the hive of file that will form the final application. It brings together all the scripts, styles, static resource, the html file, and the application cache manifest.

The src hive.

This collection of files is organised at the top level by resource type: javascript, typescript, less, and html. The html folder is simply the index.html used for the app and is completely static. less is the stylesheets and compiled using the gulp styles target. js is static javascript used in the project and not managed by yarn. Previously this included vendored version react and react-dom but these are now managed by yarn.

The ts hive is organised across three groups of build targets:

• common – this is the shared code used by the app and workers. This is primarily the common types, and functions used on both sides of worker boundaries. It is compiled into a stand alone javascript file so that the different entry point targets and reference it themselves without needing to statically link it into each target. Because common is a dependancy of app it is conservative about which javascript features it can target.
• app – this is the front end user interface and application entry point that is loaded by the index.html file. It depends upon React and contains all the tsx components for the UI. It also creates the data access worker and the generation process workers. Due to being the entry point into the project this codebase is conservative about which javascript features it can depend upon.
• workers — This sub hive is currently a bit of a mess. All the workers currently live here as top level scripts, and then call into common and their own library code. Eventually these will be split out into a hive per worker, with code from common that is not actually common being moved here too. Workers have the luxury of being able to be loaded based on runtime capability so the generation process currently is compiled as both an ES6 – and can use generators natively – and as a fallback version targeting ES5 and using downlevel iteration.

The test for whether generators are available is in app/manticore.ts and simply does the following:

// Some browsers dont support generators. This test is a little gross but it 
// does allow us to switch implementations.
const GENERATORS_AVAILABLE = (() => {
    try {
        eval ("(function*(){})");
        return true;
    }
    catch (e) {
        return false;
    }
})();

Note: this should be only use of eval in the project.