Modder Guide - KSPSnark/IndicatorLights GitHub Wiki

Overview: How it works

All "lighting" in IndicatorLights involves manipulating the emissive color of a material in a model. (There's no actual light involved: none of the "lights" actually illuminates anything. They just glow.)

At minimum, for an IndicatorLight to work, there have to be three components in the system:

  • A mesh in the part's model, which has an emissive material.
    • This might be a "native" piece of the part itself, or it could be an "extra" mesh added via ModuleManager config.
  • A ModuleControllableEmissive, which holds on to a reference to the mesh, and adjusts its emissive color when told to.
  • A ModuleEmissiveController, which is the driver that tells the ModuleControllableEmissive what to do.

diagram

ModuleEmissiveController is an abstract class which serves as the parent of a variety of specific controller types, which do different types of control.

Generally, what the controller does is:

  1. Take some sort of input from the ship. Typically, a property of some other module on the part.
  2. Make a decision based on that.
  3. Produce an output color, which it then sends to the ModuleControllableEmissive.

The above diagram is just the simplest case. Actually, it's possible to get fancier:

  • One ModuleControllableEmissive can trigger multiple meshes.
  • One ModuleEmissiveController can direct multiple ModuleControllableEmissives.
  • The output from one controller can be used as the input to another controller.
  • ...or as the input to multiple controllers.
  • A controller might accept multiple inputs from other controllers.

...This allows using config to set up a complex "circuit diagram" to wire together many controllers and emissives in a chain, which lets you build up arbitrarily complex behaviors:

diagram

So how do I add indicator lights to a part and get the behavior that I want?

  1. Make sure that the part has at least one mesh on it with an emissive material (either "native" or added via ModuleManager).
  2. In your config file, add a ModuleControllableEmissive that points at the mesh.
  3. In your config file, add some controller type (a subclass of ModuleEmissiveController), point it at the ModuleControllableEmissive, and add any additional config settings that the particular controller class requires.

That's it!

The following pages go into detail about just how to do the above steps, with examples:

Debugging your config

If you put together some config and get the syntax wrong (for example, invalid ColorSource syntax), the mod has a debug feature to help you.

There's a particular color pattern that means "ERROR". It's a continuous flashing pattern on a 1200-millisecond cycle that goes "red-green-blue-off, red-green-blue-off". If you ever see that pattern, it means IndicatorLights is unhappy with something that it found in config. If that happens, check the log file: you should find a warning message there, starting with "[IndicatorLights]", that should tell you exactly what the problem is.

A note to plug-in authors

My intended target audience in these pages, thus far, is modders who are not plug-in authors-- that is, who are simply using .cfg files to add or modify parts, rather than writing actual C# plug-in code to implement new controllers.

So you won't currently find any information in this wiki about how to write a new controller.

The main reason for this omission is that I've gotten a lot of interest from the former category of modder, and haven't heard anything from the latter, so I simply didn't bother to document the programmatic interface.

If you're interested in writing plug-in code to work with IndicatorLights directly, please post in the IndicatorLights forum thread to let me know!