Jump to content

[1.0.4] KSPAPIExtensions V1.7.5 - Utilities for shared mod use 25 Jun


swamp_ig
 Share

Recommended Posts

I've developed a package which is now being used by a fair few mods, KSPAPIExtensions or KAE for short.

I'm starting this thread to ensure that all users of KAE have somewhere to look for updates and info relevant to the code.

I'd be more than happy to accept collaborators on this mod, and additions as required.

The aims

The aim of this dll is to provide functions useful to a broad range of mods, which supplement and extend the core KSP API.

I would prefer to keep code that replaces existing functionality within their own mods, unless it's fixing a major flaw in the original API.

Including in your mod

I'm more than happy for you to use this code in your mod, but if you do so please follow these usage requirements:

  • Please inform me that you're using the DLL - this can be done by posting on this thread
  • Subscribe to this thread for updates
  • Ensure you're in the list of users below (#4) before releasing your mod
  • If required (which hopefully it won't be) you must be willing to update your mod if there's some compatibility problem
  • Include the DLL in your install in a subdirectory of GameData, not in the root, preferably alongside your own DLL.
  • Attribute me in your readme somewhere.
  • Please do not just cut and paste the code as this will cause breakages. The only exception is most of the stuff in the utils package.

The reason why I need this is that if there's an issue you're potentially not only breaking your own mod, but other people's mods too.

Hopefully all the compatibility issues are ironed out now, but there's no guarantees, so that's why I need you to follow the guidelines.

The mod has been carefully developed so that users of it don't have to release their own code in lock-step with versioning of the DLL. Old versions will either use whatever code they are compiled against, or find and use the latest version transparently when required.

For the Utils classes, most of them can be freely cut-and-pasted into your mod if you need to. But - I repeat again - don't do this with the Tweakables, or with the PartMessage service it will cause things to break.

Building with KAE

You've got a couple of options for this. You can do a git checkout of the code directly and use either visual studio to build as a dependent Visual Studio project, or the Makefile. For a good example of getting this working, see the build process for ProceduralParts or RealFuels.

Another option is to download the dll from git directly and just link against it in your project. This has the disadvantage that you won't see the documentation or code, but is easy to organize.

Licence

CC-BY-SA 3.0 Unported - with the above modifications.

Note

Swamp_ig is currently very busy. In his absence, taniwha and NathanKell are maintaining KSPAPIExtensions.

Edited by NathanKell
[1.0.4/5], v1.7.5
Link to comment
Share on other sites

I've done quite a bit of documentation of the available functions in the code itself, but here's a brief overview:

Tweakables

This package provides four extensions to the existing tweakable controls (the right click menu)

UI_FloatEdit

Tweaker for a float value. This improves the one supplied in that values can be edited with large and small increments, and a slider can be used to fine tune values. You can use the SI formats for the values displayed too (set uiFormat="S3+3", uiUnits="m" if say your float was in km (the +3) and you wanted 3 sig-figs.)

UI_ChooseOption

Choose from a range of (string) values. Optional ability to have different display to what the value is set to.

I may extend this in the future to allow the value to not be a string.

Fixed resource editor

This will automatically replace the supplied resource editor (for the VAB).

It will format resource units with SI prefixes, and allow tweaking in smaller increments than the 10% the default editor did.

It will also sent PartResourceInitialAmountChanged messages when the amount is tweaked - you can listen for these using the PartMessage service.

Improved label

The label allows you to use SI formats, automatically replaces the default.

PartMessageService

This is designed to allow inter-mod communication of when things change. For example, if your mod updates the mass of parts and other mods need to know when this changes, you can publish the message and subscribe to it.

Further details are available here.

It's really very easy to use and is as fast or faster than doing a reflection invoke.

I'd encourage everyone to use it since it means we'll have a common way of passing messages about various things changing. This will save having to explicitly code for compatibility for every mod around.

Utils

This package contains a bunch of utility methods for general use.

Debugging Utils and Physics Debugger

Can dump debugging info about game objects, types, meshes, and ordinary objects.

Can output mass, COM, ect every few physics frames with included module.

Engine Wrapper:

Wraps ModuleEngines and ModuleEnginesFX giving a unified interface.

KSPUtils

Utils for finding the relationship between parts, an improved GameScenes enum, and registration of OnUpdate methods in the editor.

If you're doing stuff in Update in the editor, especially if you're interacting with other mods, then RegisterOnUpdateEditor is your friend as it will call every module in the right order.

MathUtils:

The main function here is formatting and parsing doubles and floats with SI prefixes - will output numbers in 'engineering' notation with a fixed number of significant figures and an SI prefix on the unit if required. This is used in quite a few of the other classes - particularly the tweakables.

SystemUtils

Methods for running type version elections.

An generic ordered dictionary collection (first in, first out)

Unity Utils

A few utilities for working with unity.

Parse Utils

A few utilities for parsing Vectors and arrays of strings. Thanks to stupid_chris.

ConfigNode Utils

Utility functions for working with ConfigNodes.

Edited by swamp_ig
Link to comment
Share on other sites

Rationale for including a copy of the DLL with every mod

KAE will naturally change over time, with new versions coming out in the future.

Due to the way .net works when you compile the particular version (as in the version number) is baked into the DLL, and any other DLL compiled against that DLL then uses this version number as part of all the class references. This is a good thingtm since it means that code dependencies don't get subtly f**ed up if the DLLs get changed around from underneath your install. The downside is that you can't just replace an old DLL with a new one, you get unresolved class errors.

There's two ways to get around this: 1. (totally impractical) every user of KAE has to update their release every time a new version comes out. 2. You release with your own copy of the DLL.

If there's multiple copies of the same version then KSP is happy and just runs fine (with a few wrinkles - especially if you're using KSPAddons). If there's different versions and the code is independent, that's fine too.

Some parts of the DLL - the extended controls and the message service - need to use a shared codebase. For these classes I've made use of duck-typing (if it looks like a duck, and quacks like a duck). The old versions will detect that they're old, and proxy any method calls to the latest version of the DLL. I've done some fairly extensive testing to ensure this all works as planned, of course there's no absolute guarantees, but I think it's all good.

Edited by swamp_ig
Link to comment
Share on other sites

[table=width: 500, class: grid, align: left]

[tr]

[td]Mod[/td]

[td]Contact[/td]

[/tr]

[tr]

[td][thread=70676]Procedural Parts[/thread][/td]

[td]Swamp_Ig[/td]

[/tr]

[tr]

[td][thread=64118]Real Fuels[/thread][/td]

[td]NathanKell[/td]

[/tr]

[tr]

[td][thread=64117]Modular Fuel Tanks[/thread][/td]

[td]Taniwha[/td]

[/tr]

[tr]

[td][thread=59545]Extraplanetary Launchpads[/thread][/td]

[td]Taniwha[/td]

[/tr]

[tr]

[td][thread=80234]TweakScale - Rescale Everything[/thread][/td]

[td]Biotronic[/td]

[/tr]

[tr]

[td][thread=39512]Procedural Farings[/thread][/td]

[td]e-dog[/td]

[/tr]

[tr]

[td][thread=37707]Infernal Robotics[/thread][/td]

[td]sirkut[/td]

[/tr]

[tr]

[td][thread=65365]Infernal Robotics Model Rework[/thread][/td]

[td]ZodiusInfuser[/td]

[/tr]

[tr]

[td][thread=81981]Glow Strips[/thread][/td]

[td]Zarenor[/td]

[/tr]

[tr]

[td][thread=52042]Near Future Propulsion Pack[/thread][/td]

[td]Nertea[/td]

[/tr]

[tr]

[td][thread=88933]The Hangar[/thread][/td]

[td]allista[/td]

[/tr]

[tr]

[td][thread=92484]VuMeter[/thread][/td]

[td]PsY4[/td]

[/tr]

[/table]

Edited by swamp_ig
Link to comment
Share on other sites

You can add Infernal Robotics to the list. I'm using TweakScale and I am toying with the idea of using UI_FloatEdit for my limits. One thing I haven't checked yet with UI_FloatEdit is there an ability to not propagate a tweakable across a part that is attached symmetrically?

Link to comment
Share on other sites

Really glad to see an initiative at sharing functions useful for a wide variety of plugins. :)

I entertained the idea this was to be made possible, but couldn't do it myself lacking the needed skills.

If correctly implemented, this will result in less code with each mod, making them easier to maintain, while loading in less memory. And, I expect these functions to be of the best quality, because many more modders will see them and contribute to their improvement; therefore less possibility of bugs.

I always think at how many mods implement a part parser for their internal needs: a single parser with KAE may prove useful.

Link to comment
Share on other sites

You can add Infernal Robotics to the list. I'm using TweakScale and I am toying with the idea of using UI_FloatEdit for my limits. One thing I haven't checked yet with UI_FloatEdit is there an ability to not propagate a tweakable across a part that is attached symmetrically?

You can't do that presently, but there's no reason why that couldn't be made an option. I guess this would make more sense as an override of KSPField, but I wouldn't be overly enthusiastic about doing that.

The other thing I've been toying with with that control (although haven't needed as yet) is log-scaling - the big change arrows get replaced with "/1000" and "*1000", the small arrows are "/100" and "*100" and the slider then slides in 1 increments. This might be more sensible to do this as a separate control anyhow. Would anyone feel the pressing need for that function?

Link to comment
Share on other sites

It's actually an idea I've been toying with, and have been thinking of basing it off of KSPAPIExtensions, so maybe I should just make that and make a pull request?

Sounds like a great idea! I'm more than happy to collaborate if you like.

I'm going to be a bit Linus Tovalds in the respect that I'll be quality controlling anything that goes into the DLL, so make sure everything is well documented. (I am aware that there's a few spots here and there where my documentation could be improved)

Link to comment
Share on other sites

You can't do that presently, but there's no reason why that couldn't be made an option. I guess this would make more sense as an override of KSPField, but I wouldn't be overly enthusiastic about doing that.

The other thing I've been toying with with that control (although haven't needed as yet) is log-scaling - the big change arrows get replaced with "/1000" and "*1000", the small arrows are "/100" and "*100" and the slider then slides in 1 increments. This might be more sensible to do this as a separate control anyhow. Would anyone feel the pressing need for that function?

No need to add that to the plugin. It's not a big deal and there is already a plugin that allows you to trip symmetry within parts that solves this problem.

Link to comment
Share on other sites

Actually you could really just remove your part from the symmetry counterparts list in the counterparts during OnStart and that would break the symmetry, if that's what you wanted to do.

Link to comment
Share on other sites

Actually you could really just remove your part from the symmetry counterparts list in the counterparts during OnStart and that would break the symmetry, if that's what you wanted to do.

Never knew I could do that thanks!

Link to comment
Share on other sites

No promises - but I think that would work fine. You'll have to test it obviously.

Would be a good method for KAE - BreakSymmetry. There's always the danger of stuffing it up really isn't there since you have to make sure all the lists are fixed. Might even need to change the names of the parts too, would have to test it and see.

Link to comment
Share on other sites

After playing around with more and more mods for some hours I think there is a limit for part count I am hitting with PartCatalog. In the logs are errors pointing in this direction.

        **** Loaded PartCatalog ****

(Filename: C:/BuildAgent/work/d3d49558e4d408f4/artifacts/StandalonePlayerGenerated/UnityEngineDebug.cpp Line: 53)

ArgumentOutOfRangeException: Argument is out of range.

Parameter name: index
at System.Collections.Generic.List`1[UIPartActionFieldItem].get_Item (Int32 index) [0x00000] in <filename unknown>:0

at KSPAPIExtensions.UIPartActionsExtendedRegistration.Register () [0x00000] in <filename unknown>:0

at KSPAPIExtensions.UIPartActionsExtendedEditorRegistrationAddon.Start () [0x00000] in <filename unknown>:0

(Filename: Line: -1)

Crash!!!

Not a part count problem, but rather a bug with KSPAPIExtensions (probably not expecting the part list to be empty which it is both when filtering too much or when the catalog is initializing the filterset).

So, maybe this is a KSPAPIExtensions Problem. Any idea what is going on?

Edited by Kolago
Link to comment
Share on other sites

  • 1 month later...
I've released a minor patch to KAE. This will send hierarchy messages when doing an alt-click to copy chunks of ship in the VAB.

Very nice work on this, Swamp. Out of curiosity, how feasible would it be to also include a text field down the road?

In any case, if you have no objections I'd like to use this API in the next release of Smart Parts.

Thanks.

Link to comment
Share on other sites

This thread is quite old. Please consider starting a new thread rather than reviving this one.

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

 Share

×
×
  • Create New...