This describes how to run the project on a locahost only.
Also explains the compilation process

This is sub-layout for documentation pages

Top

The required platform is linux

Using the url you got to the git repository, you will neeed to download (clone) 2 projects.
The first one is the website (needed for the sql dumps), and the second one is the game server itself.

    git clone url/darknessorlightnodejs.git
    git clone url/darknessorlightwebsite.git
  

Please, be advised, that this can take hours, maybe even days to complete, due to the large resource files

3.1 Compulsory

The following programs are needed in order to run the project.

• web server (I used apache2)
• MYSQL database (I used mysql)
• Bash filters (sed, tr, awk, find ...)
• npm
• nodeJS
• typescript

3.1.1 Npm

Npm is package manager. It allows you to install packages for NodeJS, and also run predefined scripts. It uses package.json file.

        sudo apt-get install npm
  

3.1.2 NodeJs

NodeJS is javascript server.

        sudo apt-get install nodejs
  

3.1.3 Typescript

Typescript is a language for application-scale JavaScript. It allows to use classes, abstract classes, inheritance etc. It provides compile time code check. Can be installed using npm:

      npm install -g typescript
    

The point is, that in pure javascript, having class:

     class A
     {
        constructor()
        {
          console.log(this.variable);
        }
     }
    

Now this code executes fine, and there are no errors. The point is, that accessing undefined variable gives value 'undefined'

This makes it extremelly difficult to develop huge projects, as any typo can result in bad behavior. Moreover, in pure javascript, variables do not have type, so you can assign anything as a value. And more issues.
This all is, however, solved with typescript

3.2 For being able to write code and develop

The following programs are needed in order to be able to work on the project. (you can skip this, if you only want to run the project)

• sass

3.2.1 sass

Instructions about how to install sass can be found here

You will need to import sql dump to your local sql database.

Please, do not run the project on the real database, because the table structure / game code might not be compatible with the current cloned game version.

Navigate to the directory with sql dumps:

    cd ./darknessorlight/dbsBackup
  

Navigate to the directory with the most recent date

    cd ./[most recent date]
  

Import the dump

    mysql -u user -p
    sql > source ./_glaser_cz01.sql
  

Note: The dumps already have stripped out the definer, so the stored procedures and triggers will work under any user

You need to define in sources the username and password for connecting to the sql database.
In order to do that, open file ./src/server.ts and scroll all the way down, until you see following lines:

  ConsoleLogger.logWaitForCompletionEvent("Connecting to database");
  if (USE_LOCALHOST)
    dbs.connect("localhost", "usernameHere", "passwordHere", functionCallBack);
  else
    dbs.connect("remoteSQL.com", "usernameHere", "passwordHere", functionCallBack);

Obviously, fill in the appropriate username and password for your local database

lastly, force the server to use localhost(if not already) by modifying the same ./src/server.ts file:

    gedit ./server.ts
    #here, change variable value to true on this line:
    #var USE_LOCALHOST: boolean = true;

So, considering that you have the both projects downloaded, and the appropriate software installed, you need to compile the game server, as the build directory is not a part of the git repo.
This will show sorely the commands on how to do it.
The detailed explanation (in case you would wonder how the script works...) can be found here

6.1 Available scripts

Here is summary of all available scripts for compilation / running the game / testing

Script name	Description
./compile.sh	Compiles server-side code
./copyJsons.sh	Copies server-side JSONS (map jsons for example) into the build directory
./compileClient.sh slow and memory consuming!	Copiles client-side .ts code (along with all necessary substitutions explained above), and copies all html / css / js and all client side assets to the build directory
./copyClientSideResources.sh	Copies all html / css / js and all client side assets to the build directory. Does not compile any code what so ever
./runTests.sh	Allows to run specific tests (online / offline / sql) or benchmarks. Use -h for help
./cleanCompileTempFiles.sh run this ONLY on files inside BUILD directory!	Irreversibly deletes all files that are not neeed for final project runtime. This includes (but is not only limited to): *.scss, *.ts.md5 *.ts.bak *.ts *.css.map files. Also minifies *.json files

6.2 Example on how to compile the project

This describes the necessary commands for compiling the project

Navigate to the src folder

    cd darknessorlightnodejs/src

Compile the server

    ./compile.sh  #this will take serious amount of time

Compile the client

    ./compileClient.sh

Run the game server

    npm run node

You can navigate to the game in your browser at http://127.0.0.1:8080

6.3 Cleaning the project

Cleaning is process of recompiling entire project again. (as is normal compiling, only changed files are compiled)

Delete the build directory (do not worry, it is tested, and compiling process will create new directory and all wil work!)

  rm -r ./build

Compile the server (this can take even hours to complete)

  ./compile.sh

Compile the client

  ./compileClient.sh

Server and client are now fully functional. You can run server.

  npm run node

6.3.1 When it is needed to clean the project?

A rule of thump is: When you move a source file somewhere else, then you need to rebuild. This applies to source code on server only: if you move a source file on a client side to different directory, then you only need to run ./compileClient.sh

7.1 Server side

In order to run the tests on a server side, you must have already compiled the code using the ./compile.sh command.
Then, all you have to do is execute

  ./runTests.sh --all

Which will run all the tests available (for the server side only).
For printing help, you can execute simply

  ./runTests.sh

7.1.1 Adding a new test

In order to add a new test to the project, here is what you have to do:
Navigate to the test directory (preferrably, do it in IDE, not in console...)

  cd ./src/test

Here, you see 3 main directories:
offline - contains tests that do not require connection to the sql database, nor do any requests to the server API
online - contains tests, that require downloading JSON files or any external data from the darkness or light website. This is done using localhost. sql - contains tests that do require sql connection, and are operating above sql database.
Note: these tests are unbelieveably ugly code, because it is a hell to make such a test work, and even simple test case results in hundreds of lines of a code. But all in all, better some tests, than no tests...

To add any test, (let's consider an offline test), create a relevant file in the ./offline directory, along with the directory structure, such as

    mkdir ./src/test/offline/app/model/character/MonsterHydraTest.ts
  

Where the original tested file is in

    ls ./src/app/model/character/MonsterHydra.ts
  

From here, you see the conventions

• Keep the directory path same, with exception that tests are in ./src/test
• The test file's name is NameTest.ts, where Name.ts is the name of the tested file

So, just copy paste any existing *Test.ts file, you find around in that directory, and from there just edit it to make a test case for the new class

7.2 Client side

Client side tests are unfortunatelly more compicated, and it was a nightmare to make them work.
Keeping that in mind, the code is not beautiful and the structure is quite complicated...

The point of client-side tests in to test any code, which is on client side only, which is not affected by ./compile.sh
To run the client-side tests, we first need to compile them by calling

  ./compileClientTests.sh

To run the tests, we need to run the server first

  npm run node

and then access in web browser

   http://127.0.0.1:8080/test

Which will run the tests on the client-side code

7.2.1 Adding a new test

In order to add a new test to the client side, here is what you need to do.
Suppose, that we have a file

    src/app/view/assets/js/forms/TextInput.ts
  

Which we want to test.

• we create the actual test file in

          src/app/view/assets/js/test/forms/TextInputTest.js
        

  This can be done (and should be done) by copy-pasting existing test file you find there around.
• We add a reference to the compiled tester file, by opening a file

          src/app/view/assets/js/test/tester.ts
        

  and adding

          ///<reference path="../forms/TextInput.ts" />
        

• Open file

          src/app/view/html/test.ejs
        

  and add

          <script src="assets/js/test/forms/TextInputTest.js"></script>
        

Then, you need to compile the tests again by running ./compileClientTests.sh
Note: I would rather recompile the client aswell (./compileClient.sh) to make sure the .ejs file will get copied to the build directory.