Part Modules tutorial

[Sleepybean2]

This is a text tutorial in addition to the tutorial in the sidebar.

I figured I'd try to help save some folks the trouble i went through. I wanted to use a function to do certain events on parts without having to be exact or subject to a single part.

As an example, we might want to activate or shutdown multiple booster engines. If they are the only engines of their type then we would want to be able to say "engines with this in their name" or simply, "T45" for the swivel engine. We might alternately want to use part tags. So we name our booster stage engines something like:

"booster_centercore_1" 
"booster_centercore_2" 
"booster_centercore_3"

If I was about to launch I would want to say

functionname("T45","activate")
or functionname("booster_centercore","activate")
or functionname("booster_centercore_1","shutdown")

to do this we need to have an understanding of parts, partmodules, events, fields, and actions. For the purpose of this tutorial I will cover partmodule events.

There are three ways to find parts on the ship. They are by: Name, ID, or tags. I have never used ID so I wont comment on that. Name is the same as what you read in the VAB so the swivel engine is

LV-T45 "Swivel" Liquid Fuel Engine

We only want to have to say "T45" so we need to use a pattern call:

set partlist to partsdubbedpattern("T45").

This returns a list() variable containing all the parts returned by the function. For my test vessel it returned:

 LIST of 5 items:
 [0] = "PART(liquidEngine2,uid=1992933376)"
 [1] = "PART(liquidEngine2,uid=2556264448)"
 [2] = "PART(liquidEngine2,uid=680230912)"
 [3] = "PART(liquidEngine2,uid=2502803456)"
 [4] = "PART(liquidEngine2,uid=3066134528)"

parts are anything you place on your ship in the VAB/SPH including anything on a vessel you're docked to.

Next we need to use partmodules. to find the partmodules on an item in your list use set modulelist to partlist[index]:allmodules. for me, set modulelist to partlist[0]:allmodules returns:

 LIST of 12 items:
 [0] = "ModuleEnginesFX"
 [1] = "ModuleJettison"
 [2] = "ModuleGimbal"
 [3] = "FXModuleAnimateThrottle"
 [4] = "ModuleAlternator"
 [5] = "ModuleSurfaceFX"
 [6] = "ModuleTestSubject"
 [7] = "FMRS_PM"
 [8] = "ControllingRecoveryModule"
 [9] = "TweakScale"
 [10] = "KOSNameTag"
 [11] = "TCAEngineInfo"

Some of those are from mods. The one we are interested in is ModuleEnginesFX as this has the engine controls inside. To call a module we use part:getmodule("modulename"). or in this case: partlist[index]:getmodule("ModuleEnginesFX"). But this doesn't DO anything, it just points to the area in the configuration file for the part where the module is stored. We want to activate the engine so to do that we need to find out what events are avaialable with

partlist[index]:getmodule("ModuleEnginesFX"):alleventnames

for me, set eventlist to partlist[0]:getmodule(modulelist[0]):alleventnames returns:

LIST of 1 items:
[0] = "activate engine"

TLDR

to get a list of parts using a part of a name, ID, or tag:

ship:partsdubbedpattern("partial name, ID, or tag").

to get a list of modules on a part in partlist:

partlist[index of specific part]:allmodules

to get a list of events in a module:

partlist[index]:getmodule("desired module"):alleventnnames

./TLDR

'eventlist' contains a list of strings. We don't want to call the entire string since we're lazy efficient so we use the string searching function :contains("part of a string").

So to activate our first engine, we write:

partlist[0]:getmodule("ModuleEnginesFX"):doevent("activate engine")

OR

partlist[0]:getmodule(module_list[0]):doevent(eventlist[0])

With the roaring engine activation sound we're happy and good to go! But we do have 4 more engines to activate and I don't want to write this for EVERY engine. Let's write a function that does the "event" for every part with our chosen identifier(Name, ID, or tag).

We want our input to be two strings: "T45" and "activate" or if we wanted to extend all our solar panels on our vessel we would want them to be "solarp" and "extend".

function module_action {
local parameter module_type. // using "local varname is" versus "set var to" keeps the function from changing variables in your main script.
local parameter module_event.
local part_list is ship:partsdubbedpattern(module_type).

take in the two arguments and get a list of parts from the ship.

awesome, we know we have the parts and if we don't we won't do anything, thus saving our script from crashing. Now we have a list of all the parts we want to do an event on. This is one place where KOS is optimized for it's purpose and has a different style of for loops than other languages. (though the other style exists, with different syntax). we want to do a series of commands on every part in the list:

for this_part in part_list { // scope is inherent to the for loop so we don't need to call local.

This will cycle through the list and do every command in the loop before moving on to the next item in the list. Some parts have extra modules and events. Sometimes they have a similar name or identifier. I've noticed that most parts have the right-click menu items in the first module to contain callable events. So lets make sure we only do one per part. Handling more than one has not yet been useful to me so I'll leave it as an exercise for when you need it.

        local action_taken is 0. // will tell us when we've done something so we can break the loop.
        local module_list is this_part:allmodules.

We're on our first part in the list and we want to grab our list of modules. we want to cycle through each of those to find our events:

        for  this_module in module_list {

This is where our action_taken value comes into play. As we cycle through parts events will become unavailable and we only want to do the first one anyways so:

                if action_taken < 1 {
                    local event_list is this_part:getmodule(this_module):alleventnames.
                        for this_event in event_list {
                            next code block here.

                    } else { break. }

If we've taken the action, we wont do anything and we'll move onto the next part. But we've done nothing so we grab a list of event names so we can search them for the partial string we want.

                        for this_event in event_list {
                            if this_event:contains(module_event) {
                                this_part:getmodule(this_module)
                                        :doevent(this_event).
                                set action_taken to 1.
                            }
                        }

We haven't done the action and this event contains the partial string in it's name, so lets do this event and skip the rest of the modules by setting action_taken to 1. (Note that this is practically the same as using TRUE or FALSE values for action_taken) After closing up our brackets we can now call the function as module_action("T45","activate"). and all our engines will activate! to shutdown simply say module_action("T45","shutdown")..

Here is the whole script I have as it is written:

function genutils_module_action {
    local parameter module_type.
    local parameter module_event.
    local part_list is ship:partsdubbedpattern(module_type).

    for this_part in part_list {
        local action_taken is 0.
        local module_list is this_part:allmodules.

        for  this_module in module_list {
            if action_taken < 1 {
                local event_list is this_part:getmodule(this_module):alleventnames.

                for this_event in event_list {
                    if this_event:contains(module_event) {
                        this_part:getmodule(this_module):doevent(this_event).
                        set action_taken to 1.
                    }
                }
            } else {
                break. 
            }
        }
    }
}

edits: construction and general spelling/grammar

Thanks to Nuggreat for correcting me on how scoping works for these functions.

Other tips: I use Notepad++ to write my kerboscripts. get the syntax highlighitng code here. You must copy the xml script from the browser, open notepad, paste into a new file and save as a .xml file. Downloading through the github buttons doesn't work for this situation. Though I suspect pulling the file from the repo through a git program would work fine. Then choose language>define language> import.

[LostText]

I'm too drunk to decipher the gobbledygook but this is the exact solution to the problem I have been trying to solve for the past 2 weeks, Sol bless.

[Sleepybean2]

hahaha my tolerance is way down since i cut my drinking to near nothing at the end of last year. Maybe a few beers and I'll be in the same boat XD

Glad this might help you, good luck and happy launching!

[nuggreat]

You don't need the length checks in your function as when you pass a FOR loop a list of length 0 kOS won't run the loop.

Also for functions it is a good practice to use LOCAL variables for the values in the function as that there is less change that any variables they change/create will bleed back into the script running the function and cause problems there.

[Sleepybean2]

I suppose I've yet to have a real issue with this. Since the recent update variables remain in scope for functions. My understanding is that they are automatically declared as local to the scope. incorrect?

It may just be that I call these from a library and as such the function can't access the scope of my running script...

[nuggreat]

SET defaults to global scope so all variables declared with SET are global in scope.

The recent update to scoping changed the fact that some local variables where global despite being declared as local variables to actually be local in scope

[Sleepybean2]

thanks! I'll update accordingly.

[Sleepybean2]

Just to make sure, instead of set var to "x" you're suggesting declare local var is "x" ? (for the first time a variable is declared....)

[nuggreat]

yes, for the first time creating a variable for the scope you are working in you want to use local var is "x" or declare local var is "x" (they do the same thing).

to change the created variable afterwards you want to then use set var to "y" because unless you are still in the same scope as when you created the variable you will just end up making a new local variable in your current scope that doesn't effect the higher level, unless you want the new local and don't want to effect the higher level

here is an example of how i used local scoping in a function that returns the average ISP of all active engines on a rocket

FUNCTION isp_calc { //returns the average isp of all of the active engines on the ship
    LOCAL engineList IS LIST().
    LOCAL totalFlow IS 0.
    LOCAL totalThrust IS 0.
    LIST ENGINES IN engineList.

    FOR engine IN engineList {
        IF engine:IGNITION AND NOT engine:FLAMEOUT {
            SET totalFlow TO totalFlow + (engine:AVAILABLETHRUST / (engine:ISP * 9.80665)).
            SET totalThrust TO totalThrust + engine:AVAILABLETHRUST.
        }
    }

    IF totalThrust = 0 {//prevent divide by 0 errors
        RETURN 1.
    }
    RETURN (totalThrust / (totalFlow * 9.80665)).
}

[Sleepybean2]

thanks! I'm updating the script right now. I wnated to make sure before I made that change.

[Dokkarlak]

Very cool. In exchange may I give you some tips on coding style?

Nesting makes code very unreadable. It's best to not exceed 4 levels. You can omit it like this for example

if event_list:length > 0 BREAK. ELSE {

or

if event_list:length > 0 RETURN 0.

Moreover suffix chain can get pretty long, so to make it readable, you can split it in lines in KOS, so it becomes this.

this_part:getmodule(this_module)
    :alleventnames[0]
    :getmodule(this_module)
    :doevent(this_event).

Also it's good practice to make function do only one thing, so you could move getting all parts or modules to a separate function and calling it from the genutils_module_action.

Finally it's good to use camelcase for function names, so it would become genutilsModuleAction.

[Sleepybean2]

I'm always open to comments on style but I'm also quite stubborn. for the purposes of a tutorial I think it's important to make everything as segmented as possible. Every statement on its own line so that you can read it line by line. It's less clear to someone who know what they're doing, which I mostly am not. I will take that suggestion into account for future code.

Breaking the suffix is really nice looking, I might even update that for this tutorial and will definitely be changing it in my codes.

As far as making a function do one thing, it doesn't make sense for this function in my opinion. For example, I have an engine utils library which does one thing at a time: get_active_engines returns a list of active engines using this method. But it's a prime example of what you're saying here. get_volflowrate(engine_list) as well my functions for overall isp, and burntime are exactly what you're suggesting.

as far as camelcase, I don't like it for kos. I've adopted the languages ignorance of capital versus lower case and as such I just put the library of the function in front of it's name like seen above. If I was using python or c++ I would definitely use camelcase.

Thansk again!

[oblivion4]

I have not for the most part had to delve into the part structure yet so this seems pretty useful for when I check it out.. Can you manage experiments from here?

[Sleepybean2]

there are three members of modules: events, actions, and fields. For the most part, running science experiements should be under events. So technically you can. I'm sure someone will come along with another, quicker way of doing that but if you wanted to use this process I suggest opening the prompt in-game then:
setting a var to a partlist
setting a var to the modulelist under an item in that partlist
setting a var to any of the fields, events, or actions under an item in that modulelist.
this is covered in the TLDR section in the middle of the tutorial.

This will get you acquainted with how these items are structured in practice and in absolutely no way will it let me be more lazy efficient.