Open Resource System (ORS) - Mod Resource API - version 1.4.2

[Fractal_UK]

Open Resource System (ORS) - Mod Resource API - version 1.4.2

What is the Open Resource System?

ORS is designed to provide a framework for mods to create resources in KSP with minimal effort. It includes pre-written part modules that you can use for resource scanning and resource extraction directly just by creating .cfg files or you can use a reference to the ORS .dll file in your own plugin code.

How does it work?

The basic idea of ORS is to seperate resources into tree types:

Atmospheric Resources

Atmospheric resources are resources that are found, simply enough, in the atmospheres of planets. These resources can be collectable or they can be specified solely for interest, i.e. detected with scanners but not collected. ORS defines the atmosphere for each planet and the idea is that modders modify these definitions using ModuleManager. Atmospheric resource definitions look like this:

ATMOSPHERIC_RESOURCE_DEFINITION
{
	name = KerbinOxygen
	guiName = Oxygen
	celestialBodyName = Kerbin
	resourceName = Oxidizer
	abundance = 0.20946
}

The resourceName definition is optional, this determines whether a particular "in game" resource can be collected from the atmosphere.

Oceanic Resources

Oceanic resources are much like Atmospheric resources and ORS also defines default values for every body in the Kerbin system, which again, are designed to be updated using ModuleManager or extended. They look like this:

OCEANIC_RESOURCE_DEFINITION
{
	name = KerbinWater
	guiName = Water
	celestialBodyName = Kerbin
	abundance = 0.9666
}

Again, the resourceName definition (see the atmosphere node example) is optional. Unlike in the atmosphere node, it isn't shown in this one because there are no resources in the stock game that can be collected directly from the ocean without some kind of processing.

Resource Packs

Atmospheric and Oceanic resources, since they are based on concentrations need to be consistent, otherwise values could add up to more 100% or different mods could report different values and that might be very confusing to the player! As such, ORS will allow the player to load in only one atmospheric and oceanic resource pack at a time.

Atmospheric and Oceanic packs enclose the ATMOSPHERIC_RESOURCE_DEFINITION and OCEANIC_RESOURCE_DEFINITION blocks as follows:

ATMOSPHERIC_RESOURCE_PACK_DEFINITION
{
    name = ExampleAtmosphericPack
    ATMOSPHERIC_RESOURCE_DEFINITION
    {
	name = EveCarbonDioxide
	guiName = Carbon Dioxide
	celestialBodyName = Eve
	abundance = 0.6217
    }
    ATMOSPHERIC_RESOURCE_DEFINITION
    {
	name = EveNitrogen
	guiName = Nitrogen
	celestialBodyName = Eve
	abundance = 0.3654
    }

    ....

}

OCEANIC_RESOURCE_PACK_DEFINITION
{
    name = ExampleOceanicPack
    OCEANIC_RESOURCE_DEFINITION
    {
	name = EveWater
	guiName = Water
	celestialBodyName = Eve
	abundance = 0.9783
    }
    OCEANIC_RESOURCE_DEFINITION
    {
	name = EveSodium
	guiName = Sodium
	celestialBodyName = Eve
	abundance = 0.0094
    }

    ...

}

It is best practise to place these nodes inside cfg files inside the ORSResourcePack directory and make it clear to the user that they should remove any existing ORSResourcePack before installing yours.

Crustal Resources

Crustal resources are the most complicated and are not defined by default. These define a resource map created by an image file that determines the abudnance of the element across the surface of each planet. This is an example of a node from KSP Interstellar.

PLANETARY_RESOURCE_DEFINITION
{
	name = Thorium
	celestialBodyName = Kerbin
	resourceName = ThF4
	mapUrl = WarpPlugin/PlanetResourceData/kerbin_thorium
	resourceScale = LOG_SCALE
	scaleFactor = 1.0311580936394657748190008944693
	scaleMultiplier = 4
	displayTexture = WarpPlugin/thorium_resource_point
	displayThreshold = 0.001
}

The mapUrl parameter determines the path to the (greyscale) image that definies the resources across Kerbin's surface.

The resourceScale parameter can be LOG_SCALE or LINEAR_SCALE. Using greyscale only gives you 255 different possible values so using LOG_SCALE allows you to achieve a much bigger variation over the range.

The scaleFactor parameter is only applicable when using LOG_SCALE. Resource value is equal to scaleFactor^(pixel greyscale value)/1000000 (i.e. the number is in ppm).

The scaleMultiplier parameter is a final simple multiplication to change the resource value, making the final resource valuel scaleMultiplier * scaleFactor^(pixel greyscale value)/1000000 for LOG_SCALE or (pixel greyscale value)/255 * scaleMultiplier for LINEAR_SCALE.

Note: The final resource value should always be between 0 and 1.

The displayTexture parameter will allow a textured sphere with the specified texture to be displayed at locations of high abundance of a particular resource, allowing your players to spot resources using a scanner from orbit both on the game display and in the map view.

The displayThreshold parameter determines the abundance of the resource you need in order to trigger the spot being detected as a high abundance area.

Note: Do not overuse these options, you should have perhaps 0-100 high abundance areas per planet, no more.

Examples

kerbin_thorium.png

thorium_resource_point.png

Okay, how do I scan for resources?

You can hook into the system to scan for resources by using the ORSResourceScanner part module. Let's say I wanted to scan for the Thorium above, I would make a part with this PartModule

MODULE
{
	name = ORSResourceScanner
	resourceName = Thorium
	mapViewAvailable = true
}

This module simply says that it is scanning for the Thorium resource and that you should be able to see high concentrations of Thorium marked in game. The part will also show you the percentage/ppm concentration in the soil below.

So far so good, how do I make it possible to extract resources?

Let's continue to use Thorium as an example, the module for resource extraction is a little more complicated than the others but it's still really rather simple. This is what the thorium mining module in Interstellar looks like this but this has some special features such as using the Megajoule resource manager to draw power.

MODULE
{
	name = ORSModuleResourceExtraction
	powerConsumptionLand = 10
	powerConsumptionOcean = 0.001
	extractionRateLandPerTon = 0.009259259259
	extractionRateOceanPerTon = 0.0001
	resourceName = ThF4
	unitName = Thorium Miner
	extractActionName = Mine Thorium
	stopActionName = Stop Thorium Mining
	resourceManaged = True
	resourceToUse = Megajoules
}

Most people probably aren't going to want to make use of those extra features so they might modify the item like this (changes highlighted in bold). The changes to powerConsumption and extraction rate are to make things more friendly to stock power levels.

MODULE
{
	name = ORSModuleResourceExtraction
	powerConsumptionLand = [B]100[/B]
	powerConsumptionOcean = 0.001
	extractionRateLandPerTon = [B]0.00009259259259[/B]
	extractionRateOceanPerTon = 0.0001
	resourceName = ThF4
	unitName = Thorium Miner
	extractActionName = Mine Thorium
	stopActionName = Stop Thorium Mining
	resourceManaged = [B]False[/B]
	resourceToUse = [B]ElectricCharge[/B]
}

I'm a modder and I'm worried about distributing other people's code with my plugin in case an update breaks something, can you help me?

Yes I can. In order to guarantee that your mod will continue to work even when this plugin is updated, this mod will be distributed with a number of .dll files. The current standard version OpenResourceSystem.dll and the current version specific .dll file - i.e. the first version will have OpenResourceSystem.dll and OpenResourceSystem_1_0_0.dll. If you must guarantee compatibility for players of your mod, you should compile your own mod using the most recent version specific copy of the plugin.

You should then distribute your mod with a copy of OpenResourceSystem containing the version specific .dll you are currently referencing i.e. "OpenResourceSystem_1_0_0.dll" but NOT the default OpenResourceSystem.dll. You should then alter your reference to use a specific alias rather than "global", e.g. "ORSv1_4" for OpenResourceSystem_1_4_0.dll and use extern alias to reference your specific version. This ensures that newer versions of the plugin will never accidently replace old versions, at worst any .dll can only be replaced be a .dll of the same version number (which doesn't matter).

You can make "safe" copies of the above files simply by inheriting from the above class. So, in the case of Interstellar, to make use of this system, I might create a .cs file called FNResourceScanner.cs file which looked liked this

extern alias ORSv1_4;

using System;
using ORSv1_4::OpenResourceSystem;

namespace FNPlugin {
    class FNResourceScanner : ORSResourceScanner {

    }
}

and references OpenResourceSystem_1_4_0.dll. That way, if I later release OpenResourceSystem version 1.5 (or whichever version comes next), it doesn't matter - OpenResourceSystem_1_4_0.dll will still be there and my plugin is safe. I can then update to OpenResourceSystem_1_5_0.dll at my own leisure without worrying about my mod breaking.

I'm looking for a resource system, something like the original proposed stock system, will this mod give me that?

No. This mod is all behind the scenes stuff designed to make it easy for modders to add those kind of resource systems and to provide a common backend, so that parts from one mod will work with resources in other mods, etc. If you're looking for mods that actually add resources, this resource system is all based off work done originally for KSP Interstellar. Interstellar is a large and heavy footprint mod for people to rely upon for their own resource systems, so I decided to seperate out the resource components and make them available to everyone under a permissive license. Kethane is also a popular but unrelated resource mod.

Download

Source

License

Edited September 24, 2014 by Fractal_UK

[N3X15]

Oh my.~

I still have a Jenkins server, if you'd like to set up continuous integration or put up nightlies.

[GeoPhizzix]

Ahh, nothing like the smell of mineral exploration in the morning. I like the sound of this, definitely going to give it a try. Thank you for your time and sharing it with us!

[Ratzap]

Ah good, you did decide to do it. I was getting round to PMing you again to see if you were going to or not before starting myself.

Now we can all stop reinventing the wheel and polish one resource system up.

Edited January 2, 2014 by Ratzap

[Fractal_UK]

Ah good, you did decide to do it. I was getting round to PMing you again to see if you were going to or not before starting myself.

Now we can all stop reinventing the wheel and polish one resource system up.

It took me a while to test the system to make sure the setup that I imagined was actually practical. The test case was rewriting large parts of Interstellar to hook into this rather than containing the code internally - by doing that, I've proved that it is viable for other mods to hook into this in the same way.

Of course, you don't actually need to reference the dll directly, you can just make use of the internal PartModules with .cfg files but I've learnt from similar discussion about ModuleManager that a lot of modders really want to guarantee version safety (and I don't blame them).

Oh my.~

I still have a Jenkins server, if you'd like to set up continuous integration or put up nightlies.

Thanks for the offer, I guess I'll wait and see how this takes off and whether it is something that attracts lots of willing contributors.

[deadshot462]

Looking forward to seeing what people come up with this.

[Fraz86]

This looks great! Do you plan to incorporate orbital resources as well (e.g., like antimatter in KSPI)?

[jordanjay29]

I love these helper mods, it really shows that there's a vibrant, healthy modding community here. We need a directory of Mods for Modders for reference.

[CaptRobau]

Could you put up a small example mod or screenshots? I have a hard time making it work, which isn't helped by not knowing what everything should look like.

[Shad0wCatcher]

@ Fractal Congrats on the release; here's hoping it really catches on and we can have one unified "resource" directory soon for folks to tap into versus everyone reinventing the wheel as Ratzap rather eloquently put it.

[Majiir]

Fractal_UK, could you expand on the distribution and versioning scheme? Is OpenResourceSystem.dll some sort of version picker? What kind of file structure do you recommend (i.e. should API users include DLLs in their own GameData folders)? Is there any shared functionality (like caching or a UI) that will be duplicated if mods distribute their own DLLs?

Now we can all stop reinventing the wheel and polish one resource system up.

In what way is this not reinventing the wheel, and what previous projects have been reinventing the wheel?

[Fractal_UK]

Fractal_UK, could you expand on the distribution and versioning scheme? Is OpenResourceSystem.dll some sort of version picker? What kind of file structure do you recommend (i.e. should API users include DLLs in their own GameData folders)? Is there any shared functionality (like caching or a UI) that will be duplicated if mods distribute their own DLLs?

There shouldn't be any need to include the dll in the mod's own folder but equally there is no problem with putting it there. No code is actually executed on loading by any of the plugins, it's all triggered by Part Modules so the idea is that the OpenResourceSystem directory can contain a version archive, that way if you have two mods, mod A and mod B where mod A uses OpenResourceSystem_1_0_0.dll and mod B uses OpenResourceSystem_2_2_0.dll, both mods will still have access to the code that they themselves want to use. The only thing I need to do is maintain cfg file compatibility between releases.

Thus, mod A can include its release containing OpenResourceSystem/Plugins/OpenResourceSystem_1_0_0.dll, Mod B can include a release containing OpenResourceSystem/Plugins/OpenResourceSystem_2_2_0.dll, and neither will conflict with each other or the standard OpenResourceSystem.dll. Critically, when players install new mods the only files that might get overwritten are copies of the same version of the dll - and that should not matter at all.

OpenResourceSystem.dll is merely the default, up to date copy, which should only be distributed from here - any mods hooking in should use the appropriate version specific DLL. This default one should also be loaded first allowing mods using only .cfg files associated with this to use the most up to date version of the plugin.

There is no UI crossover involved, data is obviously duplicated if you have many different versions running at the same time but each version will be retreiving data from the same source .cfg files so doing this shouldn't cause any strange results.

This looks great! Do you plan to incorporate orbital resources as well (e.g., like antimatter in KSPI)?

I guess I could do, I am not sure how many resources other resources would fit well into this category but it could be done.

Edited January 3, 2014 by Fractal_UK

[Shad0wCatcher]

I suppose Nebula mining (future-proofing essentially) would be done orbitally; same with planetary rings (someone makes one that can be interacted with).

[FenrirWolf]

In what way is this not reinventing the wheel, and what previous projects have been reinventing the wheel?

In that other people can hook into this iteration of the wheel instead of making a other one later.

[CaptRobau]

I guess I could do, I am not sure how many resources other resources would fit well into this category but it could be done.

Bussard Ramjet here we come.

[sarbian]

I don't understand the version system either. How does KSP know which version of the PartModule to use ? With 2+ DLL defining the same PartModule I think it will only use one version for all mods ( first or last ?)

Or I need more coffee.

[Fractal_UK]

I don't understand the version system either. How does KSP know which version of the PartModule to use ? With 2+ DLL defining the same PartModule I think it will only use one version for all mods ( first or last ?)

Or I need more coffee.

KSP will always use the first version loaded for PartModules defined directly, which should always be the latest version - OpenResourceSystem.dll. Mods that require a version independent copy should reference the version specific copy of the dll (OpenResourceSystem_1_0_0.dll at present) and create new classes that inherit from these.

In your case, if you want a scanner, you might make:

using System;
using OpenResourceSystem;

namespace SarbianMod{
    class SarbianResourceScanner : ORSResourceScanner {
    }
}

Then in your part.cfg you use

MODULE
{
	name = SarbianResourceScanner
	resourceName = Thorium
	mapViewAvailable = true
}

SarbianResourceScanner is now tied to the version specific copy of the .dll that you want to use for your own mod, whereas ORSResourceScanner is tied to the most up to date copy.

[sarbian]

Ok, I get it now. Something still sound a bit too complex but I need to think more.

[Ratzap]

In what way is this not reinventing the wheel, and what previous projects have been reinventing the wheel?

Kethane is the best known resource system but it's restricted by the license. Every mod which wanted to do something with resources (extraplanetary and orbital come to mind) had to either attempt to fit in with your restrictions (the recent arguments in the EL thread are an example) or go it alone - a very daunting prospect. So people who might want to do something but don't want to have to write their own system or give it all to you and hope you agree can now do what they want.

So I suppose it is a reinvention but it's the first free and open system, which is what KSP needs. It's basic infrastructure for other people to build mods without needing to do more than add some config files. Use the same models, same parts, same GUI - nice and consistent for players.

[wasmic]

So this is like the MinecraftForge OreDictionary? Sweeeeet.

[regex]

I'm curious as to why this ships with its own resources defined? One of the drawbacks of extending Kethane's functions is that you always had to have Kethane. While your license doesn't prevent me from yanking them out, I'm not sure why it isn't left up to the mod author to define their own resources (unless it is to reserve those names for KSPI?) I can understand them being included as an illustration of how to use the mod but are they needed? Do those resources show if you don't have a proper scanner, just sitting in the background?

Maybe I'm just ignorant of the functionality because I don't use KSPI...

Anyway, great work Fractal_UK, I see some good things on the horizon from this.

[Fractal_UK]

I'm curious as to why this ships with its own resources defined? One of the drawbacks of extending Kethane's functions is that you always had to have Kethane. While your license doesn't prevent me from yanking them out, I'm not sure why it isn't left up to the mod author to define their own resources (unless it is to reserve those names for KSPI?) I can understand them being included as an illustration of how to use the mod but are they needed? Do those resources show if you don't have a proper scanner, just sitting in the background?

Maybe I'm just ignorant of the functionality because I don't use KSPI...

Anyway, great work Fractal_UK, I see some good things on the horizon from this.

The idea of having a predefined set of oceanic and atmospheric resources is basically to ensure a good player experience, everything is designed to work from percentage abundances. It wouldn't really make much sense and wouldn't provide a good experience for players if the atmosphere or ocean ended up having resources that totalled up to 856% or something. I provide a set of defaults not to prevent changes but rather to try and define a range in which changes should be made.

[Dred_furst]

Wouldn't it be better to provide that in an example project if you are providing examples?

I'm looking into how to expand this, do you have any sort of roadmap for it currently? or any design documentation to boost development?

and finally re: project setup, what IDE are you using to develop this? Monodevelop or Visual studio? It appears to be missing the SLN file for the csproj file as well as having some weird dependencies in visual studio. (And inversely, KSPI is missing the csproj file for FNPlugin).

[regex]

The idea of having a predefined set of oceanic and atmospheric resources is basically to ensure a good player experience, everything is designed to work from percentage abundances. It wouldn't really make much sense and wouldn't provide a good experience for players if the atmosphere or ocean ended up having resources that totalled up to 856% or something. I provide a set of defaults not to prevent changes but rather to try and define a range in which changes should be made.

I would argue that it's up to the mod author to ensure a good player experience and to define what resources their mod provides/needs. What if they have differing ideas regarding the composition of Eve's oceans or Laythe's atmosphere? Now if they change those values using ModuleManager they're altering the experience for every other mod rather than adding what they need. Does KSPI use these defaults? I guess I'm just a bit puzzled about how this is "open" when there are defaults defined and changing them could affect the experience of other mods rather than building upon them.

[Fractal_UK]

I would argue that it's up to the mod author to ensure a good player experience and to define what resources their mod provides/needs. What if they have differing ideas regarding the composition of Eve's oceans or Laythe's atmosphere? Now if they change those values using ModuleManager they're altering the experience for every other mod rather than adding what they need. Does KSPI use these defaults? I guess I'm just a bit puzzled about how this is "open" when there are defaults defined and changing them could affect the experience of other mods rather than building upon them.

Remember that the definitions are going to be shared by all mods, that is the point of integrating into a single resource system, additionally multiple definitions are generally bad - that means if there are no defaults but four or five seperate mods want to use this to define the ocean as containing water (not an unreasonable thing to want) you immediately have five duplicate definitions and the whole thing becomes a mess. It is much much safer for atmospheric and oceanic resources to define defaults and edit them with ModuleManager.

Once I release the next update KSPI will use MM .cfgs to edit some resources into these existing definitions.

It may also be possible to add some kind of masking system so that certain mods can hide certain resources from others if they need to do something funny or create duplicates for some reason.

Planetary resource definitions are a bit different and no defaults are defined there.