rychard/gnomeserver

Integrated Web Server for Gnomoria

GnomeServer

This is essentially a port/rewrite of an existing mod for Cities: Skylines.

That repository can be found at Rychard/CityWebServer.

Notice

While Gnomoria does allow modding of the game, the scope of what can be modified is extremely limited, and as far as I can tell doesn't allow for the execution of arbitrary bits of code. Consequently, the only way I was able to make this work was by modifying the game's executable.

To perform such a modification, there exists a library (Mono.Cecil), which is an extremely powerful library that facilitates this process. This was my first attempt at using this library, and while I was largely successful in my efforts, I have no idea how likely it is that my assembly modification code will work as-is upon the game's next update.

Installation

Server

1. Locate your Gnomoria installation directory.

   • Example: C:\Program Files (x86)\Steam\SteamApps\Common\Gnomoria

2. Copy the following files from your Gnomoria installation directory to the Assemblies directory located in the root of this repository:

   • Gnomoria.exe
   • gnomorialib.dll
   • irrKlang.NET4.dll
   • SevenZipSharp.dll

3. Build the GnomeServer solution located in this repository using Visual Studio 2015 (it's free).

4. Copy the files below to your Gnomoria installation directory:

• GnomoriaInjection\bin\x86\Debug\GnomeServer.dll
• GnomoriaInjection\bin\x86\Debug\GnomoriaInjection.dll
• GnomoriaInjection\bin\x86\Debug\Newtonsoft.Json.dll
• GnomoriaInjection\bin\x86\Debug\TypeLite.dll
• GnomoriaInjection\bin\x86\Debug\GnomeServer.pdb (Optional)
• GnomoriaInjection\bin\x86\Debug\GnomoriaInjection.pdb (Optional)

5. Download LinqPad and use it to run the inject.linq script located in the Injector directory.

   • It's likely that you'll need to edit the first path in that script to point to your Gnomoria installation path.
   • This script will create a file called GnomoriaInjected.exe in your Gnomoria installation path.
   • At the time of writing, this is verified to work on the latest in-dev release from Steam, which is v0.9.18 RC31.
   • This may also work for the current stable version of the game on Steam (and perhaps the DRM-free version from Humble Bundle, which I also own, but haven't tested personally).

6. Double-click the GnomoriaInjected.exe file in your Gnomoria installation directory to start the game.

Website

The server is designed to be flexible, so that anyone can build a website that will be hosted by the game. The server will host anything in the following directory:

C:\Users\<username>\Documents\My Games\Gnomoria\wwwroot

If any of the following conditions are met, accessing the server will display a "debug mode" page, which displays a list of controllers and their priorities:

• The directory listed above does not exist.
• The directory listed above is empty.
• A request is made for the root-level directory (/), but an index.html file does not exist.
  • This filename is not editable via the configuration file.
  • Refer to the IntegratedWebServer.ServiceRoot method to modify this.

This "feature" allows you to to verify that all request handlers (controllers) have been correctly registered with the server.

In this repository, there exists a project named GnomeApp. This is a website that I've put together during the development of the server. If you wish to use this website, you'll need to build and deploy it independently of the server. If you're developing your own website, these steps are not required.

Note: Building this project requires you to have TypeScript 1.6.

1. In the Solution Explorer, right click on the GnomeApp\app\models\Interfaces.tt file, and click Run Custom Tool.

• You must build the GnomeServer project prior to performing this step, as it uses the build artifacts from that project.

• Failure to perform this step will result in the following compiler warning:

  ```text
  A custom tool 'TextTemplatingFileGenerator' is associated with file 'app\models\Interfaces.tt', but the output of the custom tool was not found in the project.  You may try re-running the custom tool by right-clicking on the file in the Solution Explorer and choosing Run Custom Tool.
  ```
  

2. In the Solution Explorer, right click the on the GnomeApp project and select Publish.
3. Use the following options:

• Publish method: File System
• Target location: C:\Users\<username>\Documents\My Games\Gnomoria\wwwroot
• Configuration: Release

3. Once this is done, ensure that the C:\Users\<username>\Documents\My Games\Gnomoria\wwwroot directory exists.

Advanced Server Configuration

By default, the game hosts a web server that listens for requests at http://localhost:8081/

This address can be configured by editing the server's configuration:

• Install the mod normally.
• Launch GnomoriaInjected.exe at least once.
• Close the game.
• Locate the GnomeServer.json file. It is located in the same directory as your saved games.
• Editing the file should be simple enough, but here's a quick sample to illustrate:

[
  {
    "Key": "webServerHost1",
    "Value": "http://<HostName>:<PortNumber>/",
    "Type": "string"
  }
]

Projects

GnomeServer

This project compiles into a single dll (GnomeServer.dll). The GnomoriaInjection project has a reference to this project, allowing it to access and spin up an instance of the appropriate code that runs in the same AppDomain as the game itself. Because of this, this assembly has access to the entirety of the game's assembly at runtime, which allows the developer to control large portions of the game's logic.

It's worth noting that this project leverages what is very much a very rudimentary web-server. While it implements a very respectable amount of features, there's still an immense distance between the one used here and, say, IIS. Because it was originally written for a game written in Unity3D (which runs under Mono), I had to work within the limitations imposed by that platform. Seeing as how Gnomoria uses XNA (using .NET 4.0) these limitations don't necessarily apply, and I could have dropped in an ASP.NET Self-Host platform. That said, I chose not to simply because I would be unable to use the latest version, since that platform has long-since moved forward to more recent releases of the .NET framework.

Despite these "limitations", one of my design goals was to reduce the most tedious part of working with the previous version of the web server used for the Cities: Skylines mod: the creation of new endpoints. During my "9 to 5" I do a lot of work using the latest-and-greatest versions of ASP.NET MVC/WebAPI and one of the most missed parts of that is Attribute Routing.

Seeing as how the ASP.NET team has recently open-sourced the code for this project, I briefly considered pulling out some of the relevant bits and pieces for use in this project. That idea was short-lived, as I came to my senses and realized that this code is very feature-rich, and this comes at the cost of some rather lengthy code. Instead of grabbing a few dozen files and spending countless hours trying to get it to work with this project, I decided to implement my own (admittedly very limited) version of this feature. It should feel somewhat similar to those familiar with the official solution, but there are some remaining issues with it and it's certainly not what I'd call a "complete" product.

GnomoriaInjection

This project compiles into a single dll (GnomoriaInjection.dll) that acts as the receiving end of the hook. At some point after the game's executable is launched, a call is made to the getter of the GnomanEmpire.Instance property. This seems to be a reliable location to inject code into the game, though care must be taken to ensure that code is not injected multiple times, as this property is accessed quite frequently throughout the normal execution of the game.

GnomeApp

The server does include a website by default, but the built-in site is extremely rudimentary and largely useless for anything other than development of the server itself.

Because the utility of the server is largely dependent upon the existence of a website to host, this project exists to provide a working model of a website that exposes much of the functionality exposed by the server.

This project is a JavaScript SPA (Single-Page Application), the bulk of which is written in TypeScript. This is subsequently transpiled into JavaScript, where it leverages a variety of JavaScript libraries, such as Durandal, Knockout, RequireJS, and jQuery.

Also contained in this project are TypeScript interfaces that are generated dynamically from C# class definitions in the GnomeServer project. This is accomplished through the very useful TypeLite library.

Questions?

Create an issue on this repository and I'll see what I can do to help.

Attribution

The design of GnomeApp is based on the "Dream" template from WebThemez

gnomeserver's Issues

Add License

I just realized that I don't have a LICENSE file in this repository.

As a note (both to myself, as well as anyone else), the code in this repository will be placed under the MIT license:

Copyright (c) 2015 Joshua Shearer

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Edit Neighboring Kingdoms

The API should allow neighboring kingdoms to be edited and written back into the game.

The following is an incomplete list of things necessary for this:

• Name
• SubType
  • Is this the same as the SubType defined in faction.xml?
    • Merchant City-State
    • Goblin Kingdom
    • Mining Colony
    • Lumber Camp
    • Agricultural Settlement

Perhaps just as importantly, this functionality should be made available within the web application.

From Roest (@rschurade) on the Gnomoria Forums: http://forums.gnomoria.com/index.php?topic=8123.msg61495#msg61495

Also mentioned here:

• Change neighboring kingdoms?
• [Request] Edit / Change Merchant City / Trade Kinddom

Spawn/Kill Enemies

The API should allow various operations on the enemies in the game.

The following is an incomplete list of things necessary for this:

• Spawning Enemies
• Killing Enemies

Perhaps just as importantly, this functionality should be made available within the web application.

From Roest (@rschurade) on the Gnomoria Forums: http://forums.gnomoria.com/index.php?topic=8123.msg61495#msg61495

Configuration and Log files should be stored in directory specified in Game.ini

Gnomoria allows users to customize the location of their save games via the presence of a Game.ini file in the same directly as Gnomoria.exe.

When a path is correctly configured in this file, the game will use that directory for all game saves. Mods should respect this configuration value as well.

Convention-based endpoint resolution by HTTP method

I should be able to define multiple routes with the same path, so long as each route has only a single endpoint for each HTTP method (GET, POST, PUT, DELETE).

Allow editing of Gnomes

The API should allow the data for Gnomes to be edited and written back into the game.

The following is an incomplete list of things necessary for this:

• Name
• Profession
• Skill Levels
• Health (Replace missing limbs, etc)

Perhaps just as importantly, this functionality should be made available within the web application.

From Roest (@rschurade) on the Gnomoria Forums: http://forums.gnomoria.com/index.php?topic=8123.msg61495#msg61495

Spawn/Edit Items

The API should allow for the ability to manipulate the items on the map or in stockpiles.

The following is an incomplete list of things necessary for this:

• Stockpile Operations
  • Show all stockpiles
  • List of items in stockpile (show global counts for reference?)
    • e.g. Strawberry Seeds: 100 (12345 Total)
  • List of items that each stockpile accepts
    • Edit which items are accepted at the stockpiles?
  • Visualization (Graph showing connections between stockpiles; push/pull relations)
• Spawn additional items
  • Note that spawning liquids will require barrels to hold them.
  • Directly into a stockpile?
  • At a specific location?

Perhaps just as importantly, this functionality should be made available within the web application.

From Roest (@rschurade) on the Gnomoria Forums: http://forums.gnomoria.com/index.php?topic=8123.msg61495#msg61495

Provide thread-safe access of Gnomoria objects

Throughout development, I've encountered only a handful of crashes that were the direct result of accessing objects across thread boundaries.

Modifying existing objects seems to be safe (in practice, but this is not an acceptable excuse), but creating or removing items that exist as part of a collection can easily cause Gnomoria to crash if those collections are enumerated frequently, or if enumeration within the Gnomoria process takes an extended period of time to complete. The issue is unlikely to occur in reverse, as the web server itself is only executing code against Gnomoria when a request is received, and the Try/Catch blocks that surround the invocation of this code would capture any exceptions thrown in this scenario. The server would send the error as the body of the response, but the Gnomoria process is unlikely to be impacted.

A common scenario that can reliably result in a crash of the Gnomoria process involves the addition/creation of new Character objects. The collection that keeps track of these references is regularly enumerated across many of the game's Update methods, and modifying this from the web server thread (while Gnomoria is enumerating the collection) would throw an exception.

Note: For the uninformed, modifying a collection while it is being enumerated will cause the following exception to be thrown:

System.InvalidOperationException was unhandled
  Message="Collection was modified; enumeration operation may not execute."
  Source="mscorlib"
  StackTrace:
       at System.ThrowHelper.ThrowInvalidOperationException(...)
       at System.Collections.Generic.List`1.Enumerator.MoveNext()

During the execution of the GnomoriaInjection.Inject.Hook method, we have access to the game's primary thread, and can create a dispatcher at this point, but this does nothing to provide us with the thread-safety we need. Since this method is invoked any time the GnomanEmpire.Instance property is accessed, Gnomoria could be directly in the middle of enumerating one of these collections.

Instead, it might be wise to instead use a second hook that is invoked at the end of one of the game's many Update methods. The master Update loop should be safe to hook into, since I can't imagine a scenario that involves a collection being enumerated at this time.

Convention-based endpoint resolution should consider QueryString parameters

When resolving an endpoint, the parameters are not considered at all. Only after a endpoint is resolved are the QueryString parameters accessed, at which point we are unable to redirect the invocation.

Here are some notes regarding this:

• Endpoint resolution should consider the parameters of a method.
• At minimum, we must consider parameters that are required.
• Considering the Type of parameter would introduce a lot of complexity, as it would lead to the suggestion of supporting complex-type binding. For now, let's keep it simple.
• Like ASP.NET, throw exceptions when resolution fails.

Update README | Build: Cannot find namespace 'GnomeServer'. GnomeApp

When trying to build the master branch, there is a lot of errors. Could this be because the Gnomoria RC version has gone up a few?

Severity    Code    Description Project File    Line
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    32
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\gnome\index.ts  16
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\gnome\index.ts  16
Error       Build: Statements are not allowed in ambient contexts.  GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\Interfaces.d.ts  1
Error       Build: Cannot find name 'ErrorGeneratingOutput'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\Interfaces.d.ts  1
Error   TS1036  Statements are not allowed in ambient contexts. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\Interfaces.d.ts  1
Error   TS2304  Cannot find name 'ErrorGeneratingOutput'.   GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\Interfaces.d.ts  1
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    2
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    2
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    6
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    6
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    10
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    10
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    14
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    14
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    27
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    27
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    28
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    28
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    29
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    29
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    30
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    30
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    31
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    31
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    32
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    61
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    61
Error       Build: Cannot find namespace 'GnomeServer'. GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    62
Error   TS2503  Cannot find namespace 'GnomeServer'.    GnomeApp    C:\Users\Temeez\Desktop\GnomeServer-master\GnomeApp\app\models\models.ts    62

Compile instructions are sparse. They dont mention which version of visual studio is required.

It would help to note compiling is known functional with visual studio 2015. I tested with 2015 community edition and it worked. It didnt work with Visual studio 2008 express or 2012.

Add Newtonsoft.Json requirement to the README

Hey!

There doesn't seem to no mention about the Newtonsoft.Json framework which the project needs to be installed in the README Installation part. Might want to add that at some point :)

Secondly: Awesome job! It is nice to see that the [Game X]Server idea didn't stop to Cities Skylines.

Failed to resolve assembly: 'gnomorialib, Version=0.9.18.0, Culture=neutral, PublicKeyToken=null'

Using the 0.1 release, after changing the path to my game, i receive this error

Separate Skills for Production and Combat

Currently, all the skills are exposed in one group that doesn't differentiate between production skills and combat skills, which can be misleading since (to my knowledge) Professions don't include combat skills in the list of skills which they "allow", which causes those skills to appear as though they are unused by any profession.

Skills should be exposed via the API separately for production skills and Combat skills.

From Roest (@rschurade) on the Gnomoria Forums: http://forums.gnomoria.com/index.php?topic=8123.msg61495#msg61495