Search the Community

Newer versions of KSP support Unity’s updated UI system (technically available since KSP 1.0, but only really practical since 1.1), which is a major improvement over the old OnGUI system. Rather than rebuilding the UI every frame using the esoteric GUILayout and GUI system, the new Unity UI is built using standard Unity objects and hierarchies. This significantly improves performance, reduces the garbage created, and allows for some fancy effects that weren’t practical with OnGUI. The only problem is that building the new UI entirely through code is extremely tricky, to the point of being impractical in all but the simplest cases. So there are basically two options for using the new UI. One is built into KSP and is perfect for creating relatively simple windows that don’t require much customization. This is the PopupDialog system, it uses notations similar to the old GUILayout system, but generates a new Unity UI object. There is a thread with more details on PopupDialogs and some examples. The other option is to build your UI in the Unity editor, export it as an AssetBundle, and load it into KSP. There are also two options for how to handle this. You can create the UI in Unity without importing any assemblies into the Unity editor. When you load this UI into KSP you will need to manually hook up all of the elements through code. Things like the function called by a button, or the string of a text element will all have to be manually assigned. This is OK for simpler UIs, but can become prohibitively tedious for more complex UIs. Sarbian’s GC Monitor is an example of this type of UI. For a more complex UI it can be simpler to import an assembly directly into the Unity editor, allowing you to set button, or toggle listeners, and to store references to UI elements where needed. The only problem here is that you cannot import an assembly that refers to KSP’s Assembly-CSharp.dll, the primary KSP assembly. This means that any mod using a Unity UI will need two assemblies, one to handle the KSP side of things, and another that can be imported into Unity and will handle the UI side of things. The KSP assembly can keep a reference to the UI assembly, but the UI assembly can’t refer to the KSP assembly, since that will refer to Assembly-CSharp (this would create a kind of nested Unity project in the code, which Unity won't accept). This means that communication between the two assemblies will be difficult. It's worth noting here, that while you can't import any references to the KSP assembly in your Unity project, nothing is preventing you from adding that reference to your code outside of Unity. If you are careful you can setup your code in such a way that only a single assembly is needed. This would require either doing all of the Unity UI work before hooking things up to KSP, or just walling off anything that refers to KSP code into separate classes that could be disabled when you need to import the assembly into Unity. This tutorial doesn't cover this option, but this is another option that you can use and could get around some of the complicated interface-based techniques discussed below. But before we get to that we can go over some of the basics of Unity UI creation (generic UI creation is also broadly similar to KSPedia creation, which is covered in its own tutorial). I won’t go into too much detail, since there are a number of very thorough tutorials and examples available. Check out some of these; pay particular attention to the RectTransform as that is the core positioning component of all UI elements, and it can be quite tricky to get a handle on. Using Basic Orbit as an example project we’ll go over several different areas of UI creation, starting with making a simple, static window, one that can’t be re-sized and has a fixed amount of UI elements. I’ll be using the same formatting as in the KSPedia tutorial, with Unity Editor screen elements Bolded and UI objects and elements Bolded and Italicized. The code for Basic Orbit is available on GitHub. Much of the methods used here come from Kerbal Engineer Redux (which uses the Unity UI only for its toolbar button), its source and Unity project can be found on its GitHub page. This is the window we’ll be creating and hooking up to KSP today. It controls the visibility and some options for other screen objects. Section 1: Software and Tools: Required: Unity – Current KSP version (1.9.1) is using Unity 2019.2.2f1 KSP Part Tools – The current package includes what is needed for generating Asset Bundles and the legacy Part Tools files It should be noted that anyone familiar with Unity who can write their own asset bundle script doesn't need to worry about the Part Tools, just write the script for building an asset bundle and you can use the version of Unity that matches KSP If you do so make sure that any scripts you add to the project are placed in a folder called Editor somewhere within your Unity project's Assets folder To start with we need a new Unity project (I’m using Unity 5.2.4f1, since this is the version supported by the KSP Part Tools - KSP 1.4.x uses Unity 2017, but earlier versions should still work; KSP 1.8 and above uses Unity 2019.2). I would suggest making a separate project folder for each UI, you can create a new project in the Unity startup window, you can then copy the KSP Part Tools files into that project’s Asset folder, or just import them into Unity in the normal way. We only need the Part Tools for the Asset Compiler function, which we’ll get to later. Unity Project Setup: The first step is to install Unity and add the Part Tools package. Once Unity is installed open it and create a project for KSP (there are probably other tutorials that cover setting up Unity in more detail; that isn’t really covered here). Go to the Assets Tab along the top -> Import Package -> Custom Package -> Select the PartTools_AssetBundles.unitypackage file This will load all of the bits necessary for KSPedia creation Now you want a new scene; the Hierarchy Window should only have the Camera, which we want because it allows us to view the UI as it will be in-game In the Main Window you’ll want to be in the #Scene Tab, in 2D mode, using regular Shaded mode Section 2: Creating the UI: All Unity UI windows must be the child of a Canvas element, so we’ll need to add one here. In general, we don’t need to export this Canvas, since our UI can be added directly to one of KSP’s Canvases, but we need it in the editor to actually see anything we create. Add a Canvas: GameObject Tab -> UI -> Canvas This adds the Canvas element and the EventSystem The default properties should be fine, you’ll want to set Pixel Perfect on, since most KSP canvas’ seem to use this, it simply makes sure that all UI elements are snapped to pixel edges Render Mode should be on Screen Space – Overlay, this is for basic UI styles, a simple window on the screen To this Canvas we then add a Panel: Right-click on the Canvas -> UI sub-folder -> Panel The Panel is the basic window object, this is where we add buttons, labels, images, and so on The Panel has a RectTransform, a Canvas Renderer, and an Image element The RectTransform controls the window size and position The Canvas Renderer is a required component for any UI element that will actually be drawn on-screen The Image is the window background image By default, the Panel is the same size as the Canvas and uses the Stretch Anchor, meaning it will always stretch to the size of the Canvas, we obviously don’t want this Click on the Anchor image (the blue arrows, or red lines) in the RectTransform element and select the Middle-Center Option, with red lines crossing in the center You may end up wanting the Anchor to be Top-Left and the Pivot to be 0, 1, but you can leave them as they are for now This will set the Anchor to the center of the Panel, and will change the available RectTransform Fields, we can now directly set the size of the Panel, and they will be fixed Once we set the Panel size it will look like this: The Pivot (blue circle) and Anchor (white arrows) are in the center and the borders are marked in the corners with the blue dots Adding Elements to the Window: We’ll go over the background images used for the window, and more complex anchoring and pivot functions later, but for now, we can start adding the UI elements to this simple window. Basic UI elements can be added by right-clicking on any object in the Hierarchy Window and selecting a UI object The Add Component button can be used to add those same elements, or any other Unity object or script To start with we’ll add a few Text labels and some Toggles that look like buttons For Text elements just right-click the Panel and select a Text object under the UI tab To position the element we can drag it to the desired location, it should snap to the center line The width and height can be changed by dragging the edges, or by changing their values in the RectTransform properties Dragging the edges will make the element un-centered, whereas editing the height and width in the RectTransform will adjust the element’s size based on its pivot position (centered by default) Since this window is fixed we don’t need to worry about the anchor position, but if you want to make sure that an element stays at the top of the window you can change the anchor to Top-Center, or Top-Right if you want it stay in that corner, this can help when making a UI if you are frequently adjusting the window size For fixed Text elements we can just type in the Text Field whatever we want, for dynamic elements (which are set by something in-game) we’ll cover them later The Text properties: size, style, alignment, color, etc… can all be adjusted in the Text element’s properties A quick note about hierarchy and draw order here: Elements lower in the hierarchy are always drawn above higher elements This means that child elements are drawn over their parents, and siblings are drawn in order from last to first, with last on top Now to add some Toggle Buttons, since this a group of three related Toggles we can put them all under one parent object Right-Click on the Panel and select Create Empty, this will add a simple RectTransform with no UI elements We can adjust its position, size and anchor so that it can hold the Toggles and be fixed relative to the top of the window Now add a Toggle element directly to the new empty object (all Unity objects can be renamed by double-clicking on the in the Hierarchy window) Unity doesn’t have native Toggle Buttons, so the element created here is a standard toggle with a label and checkbox We can adjust these elements to work as a Toggle Button just by changing their size and positions (and some code that we’ll get to later) We need to go from this: To this (yes it looks odd, but we’ll get to specifics in a bit): Creating a Toggle Button and Adjusting the RectTransform: To make what we need we basically only have to adjust the RectTransform component for each UI element in the Toggle element. The Toggle itself is made up of a Toggle Script, which controls actually activating and deactivating it, the Background Image, which by default is the empty checkbox, the Checkmark Image, which is only shown when the Toggle is put into the “on” state, and a Text Label. We want this Toggle to look like a standard KSP button, so the images should fill the entire object and the text should be centered The Background Image will be set to standard KSP button styles (the regular button, a brighter button for when the mouse is over the element, and a darker button for when the mouse is actually clicking on it) and the Checkmark Image will be set to the darker, pressed KSP button; since the Checkmark Image is drawn over the Background Image, it will hide the standard button images when the Toggle is on To do this we need to adjust the Background and Checkmark Image RectTransforms to fill the entire object We set the Anchor to Stretch-Stretch (four blue arrows), this will make the element stretch to fit the size of its parent, it also replaces the size and position fields with offsets, so if we want an element to stretch with its parent, but always have 10 pixel borders around the edge, we can set each field to 10, here we want them all set to 0, the same size as its parent We do the same with the Checkmark Image For the Label, we generally want some padding around the edges, and the text should be changed to centered alignment We’ll get into actually assigning images to these elements later on, for now these are all using the default Unity UI element sprites (which can be seen in KSP in the debug window and a few other places) We can also replace the Text label with an Image element, this will simply draw an icon over the Toggle Button rather that a label Images can be imported into Unity by simply copying them into a folder in the Unity Project’s Asset folder, or by dragging them directly into the Unity Editor’s Project Window Images should be imported as Sprite (2D and UI) and the Generate Mip Maps toggle should be off Filling in the other UI elements: I’m not going to go over how to add all of the different UI elements. There are numerous UI tutorials that thoroughly cover different element types; sliders, standard buttons, and text labels are all fairly straightforward to add. For static windows it isn’t too complicated, the RectTransform can get quite complicated, but the best way to understand it is to simply play around with it and change values to see what happens. More complicated UI layouts, and variable size windows will be covered later on. Exporting the Asset Bundle: To load anything into KSP we’ll need to actually export all of our prefabs as an AssetBundle using the Asset Compiler from the KSP Part Tools. The method for this is similar to that described in the KSPedia tutorial, just without the KSPedia Database steps. Drag any prefabs into the Assets folder in your Project Window (this would be the Panel that we added to the Canvas at the start for our window) Set the AssetBundle name in the Properties Panel in the lower right Then open or go to the Asset Compiler window -> Create (for your bundle) -> Update -> Build This will export a file into the AssetBundles folder in your Unity Project, it should have the .ksp file extension Section 3: Hooking up the UI: Now to get to the fun part. By making use of the Unity Editor we can assign methods to all of the toggles and buttons, store references to text elements so they can be updated later, spawn new windows, and much more. To do this we need to make a new assembly that can be imported into the Unity Editor. Any MonoBehaviours defined in this assembly can then be added as scripts to our UI objects. These can be scripts that control specific behaviors, like switching text colors when mousing-over an element, or that control the various window functions. I’ll be referring to the assembly that is imported into the Unity editor as the Unity Assembly, and the assembly that uses KSP code as the KSP Assembly. Unity Assembly: We create our Unity Assembly the same as any other, it should use .Net 3.5, but it should only add references to UnityEngine and UnityEngine.UI, it should not have any references to KSP assemblies. For our KSP Assembly we create that as always, and we add a reference to our new Unity Assembly. This means that the KSP Assembly can call any public methods from the Unity Assembly, modify any public fields, and implement interfaces. But the Unity Assembly can’t directly communicate with the upstream KSP Assembly, or directly use any KSP code. There are a few ways around this, we could use some sort of listener and events system to trigger methods in the KSP Assembly or use interfaces in the Unity Assembly. We’ll be using the interface method. To simplify importing your assembly into Unity you might want to add a post-build event to your VS project that copies the assembly into the Unity folder: copy /y "$(TargetPath)" "C:\YourUnityProjectFolder\Assets\Plugins\" Creating Scripts for Unity: Any class that inherits from a Unity MonoBehaviour can be imported into Unity and added as a component to any other Unity object. To import an assembly into the Unity Editor just drag the .dll into your Unity project’s Asset folder, there should be a separate Plugins folder Once it is imported you can add the script to any Unity object: Add Component -> Scripts -> Your.Assembly.NameSpace -> YourScript Now the script is added to that object and a new instance will be instantiated whenever that object, or its parent object is created These scripts can accomplish several things They can store references to elements of the UI that need to modified by the script They can add behaviors to elements, such as controlling text color, or for replacing standard Unity Text elements with KSP’s new vector font Text Mesh Pro elements They can be used to assign listeners to buttons, toggles, sliders, etc… For the simple window that we’ve already created we have a Text element that needs to be updated in-game (the little mod version label), and several toggles. Because we want to set the initial state of some of these toggles (one controls whether a separate window is open or closed, so if it’s already open that toggle should be set to the on state), and because we want some of the toggles to affect others, we need to store references to the Toggle elements. And we need to assign listeners to the Toggle scripts. Any field with Primitive Types, or Unity Object Types can be set in the script then assigned to in the Unity Editor Storing these fields allows for easy access in the script using UnityEngine; using UnityEngine.UI; namespace BasicOrbit.Unity.Unity { [RequireComponent(typeof(RectTransform))] public class BasicOrbit_Example : MonoBehaviour { [SerializeField] private Toggle m_OrbitToggle = null; [SerializeField] private Toggle m_OrbitDragToggle = null; [SerializeField] private Toggle m_OrbitSettingsToggle = null; [SerializeField] private Text m_VersionText = null; } } Note the RequireComponent attribute at the top, this simply means that the specified types must also be present on the same GameObject All UI elements that actually draw something on the screen (images, text, etc…) require a CanvasRenderer, for example If that component isn’t present on the object it will be added when you add the script Public fields will automatically be added to the script’s Inspector tab You can set attach the [NonSerialized] attribute to public fields to prevent them from being shown in the editor or serialized Private fields can be added by attaching the [SerializeField] attribute (unity chops off the m_ part of the field's name in the Inspector window) These fields can be filled in by simply dragging the desired elements into their respective fields, or by selecting the little circle to right of the field and selecting the element from a list of all valid elements in the project, or by filling in the desired value for primitive types Now we can access these fields from any instance of the script, though it is still a good idea to check if they are null, in case of errors made when setting up the UI, or exporting your prefabs To access or update these properties we just use these references public void updateVersionText(string newText) { if (m_VersionText != null) m_VersionText.text = newText; } public void setInitialToggle(bool isOn) { if (m_OrbitToggle != null) m_OrbitToggle.isOn = isOn; } One thing to note about setting Toggle states like this, whenever you change a Toggle’s isOn field, it will trigger that Toggle’s Listener Events, so anything you or anyone else has attached to this Toggle will be triggered. One way of getting around this is to have a Bool set to False while you are doing the initial setup. Then set your Toggle Listener to not do anything when the Loaded Flag is False, after the setup is complete you can set the Flag to True. Now to add listeners to Toggles and Buttons. The Unity UI attaches listeners to Unity Events triggered by a Button, Toggle, Slider, etc… Any public method that meets the requirement of that particular event can be added as a listener. public void OrbitPanelToggle(bool isOn) { if (!loaded) return; if (m_OrbitToggle == null) return; //Turn on Orbit Panel } public void OrbitDragToggle(bool isOn) { if (m_OrbitDragToggle == null) return; //Turn on Orbit Panel drag state } public void OrbitSettingsToggle(bool isOn) { if (m_OrbitSettingsToggle == null) return; //Spawn Orbit Panel settings window } public void myButtonListener() { //Methods with no arguments can be added to any button or to any other element if the argument does not need to be specified } public void mySliderAlpha(float alpha) { if (!loaded) return; if (m_AlphaText != null) m_AlphaText.text = alpha.ToString("P0"); //Change panel background alpha } Inside the Inspector tab for any Unity element with a Unity Event there is a section for adding listeners, you can add more by selecting the plus button on the bottom. Add a listener by first selecting an object for the little box below the “Runtime Only” box This will be the object that contains the script which has your listener You can either drag the object into the box, or select it from the list using the little circle In this case we select the parent Panel object, which has our example script The specific method is then selected in the box on the right This box has a list of all components attached to the selected object Select the Example script which will then show a list of all public methods that can be chosen Now we can just basically repeat these steps wherever needed. If you need access to an object somewhere, just add a reference to it in your script and assign it in the editor. If you need more listeners, just add them. More complicated behaviors will be explained later. One thing to note about Buttons, Toggles, etc, is the Transition and Navigation elements in their Inspector tabs. Transition refers to how the element behaves in its different states Sprite Swap transitions mean that different sprites are used for the normal state, when the mouse is over the object, or for when the mouse is clicking on the object Color Tint just adjusts the color tint for the attached Image element in those same states Animation uses Unity Animations to design more complex behaviors This is something that will be covered more later, but KSP generally uses Sprite Swap transitions, and for this example these states will all be setup in-game Navigation refers to keyboard navigation and is generally something that should be deactivated When you click on an object it will become the “active” object until you click somewhere else unless Navigation is disabled This means that the element will remain in the Highlighted state Section 4: Assembly Communication: Now that we have our UI hooked up to the Unity Assembly we need to get it communicating with the KSP assembly. There are probably several ways of handling this, but I’ve been using Interfaces in the Unity Assembly to handle it. The basic idea is to create one or more interfaces with the methods and fields needed to send information between the two assemblies, then we add those interfaces to objects in our KSP Assembly. This basically serves two purposes, the interface us used to set the initial state of the UI when it is created, using information from KSP, this could be persistent data, or just anything that can be altered at run time, like the name of a vessel. And it allows for the UI elements to make changes on the KSP side, by setting persistent data, or triggering a KSP-related function. In our last example we had a window with several Toggle elements, a Text field, and a method for the alpha Slider, so the interface contains what is needed to setup those elements, and to transfer data to the KSP Assembly for persistent storage. namespace BasicOrbit.Unity.Interface { public interface IExample { string Version { get; } bool ShowOrbit { get; set; } float Alpha { get; set; } } } The Version string is read-only, since the UI does nothing to alter it The Show Orbit bool is read to set the initial state, but can also be set by the UI when clicking on the Toggle The Alpha float is also used to set the initial state, and needs to be updated when changing the Slider value So now we can set the UI’s initial state by implementing our interface on an object in the KSP Assembly and calling the Setup method. private IExample exampleInterface; public void setInitialState(IExample example) { if (example == null) return; exampleInterface = example; if (m_VersionText != null) m_VersionText.text = example.Version; if (m_OrbitToggle != null) m_OrbitToggle.isOn = example.ShowOrbit; if (m_AlphaSlider != null) m_AlphaSlider.value = example.Alpha; if (m_AlphaText != null) m_AlphaText.text = example.Alpha.ToString("P0"); loaded = true; } public void OrbitPanelToggle(bool isOn) { if (!loaded) return; if (m_OrbitToggle == null) return; if (exampleInterface != null) exampleInterface.ShowOrbit = isOn; //Turn on Orbit Panel } public void mySliderAlpha(float alpha) { if (!loaded) return; if (exampleInterface != null) exampleInterface.Alpha = alpha; if (m_AlphaText != null) m_AlphaText.text = alpha.ToString("P0"); //Set panel background transparency } Note that we store a reference to the interface for use by the listener methods Make sure to set the Loaded Flag to true if needed The code for actually turning on the separate panel, or changing the background image’s alpha channel can all be handled within the Unity Assembly Section 5: Turning it On: Now we have to be able to actually turn on the UI. To do this we need a reference to the UI Prefab and a button somewhere to trigger the UI. We can let KSP load the AssetBundle that was exported from Unity, anything with a .ksp file extension should be loaded, or we can load it ourselves (KSP won’t load it twice, so there is no duplication of resources doing it this way; you can also just remove the .ksp extension to hide it from KSP’s asset loader). I’ve been loading it myself, it works find, and it allows me to open it immediately upon starting KSP. If we need to process or update all of the prefabs it can be useful to load in all of the prefabs, but to generate a window all you really need is the primary prefab (anything that will be created directly by the KSP Assembly). We can store prefabs as references in our Unity scripts by adding a serializable GameObject. A simple KSPAddon can be used to manually load and store a reference to the prefab: [KSPAddon(KSPAddon.Startup.Instantly, true)] public class BasicOrbitLoader : MonoBehaviour { private static GameObject panelPrefab; public static GameObject PanelPrefab { get { return panelPrefab; } } private void Awake() { string path = KSPUtil.ApplicationRootPath + "GameData/YourMod/PrefabFolder"; AssetBundle prefabs = AssetBundle.LoadFromFile(path + "/your_bundle_name"); panelPrefab = prefabs.LoadAsset("Your_Prefab_Name") as GameObject; } } Then we need an object that implements our interface; this can get its data from a persistent settings file, or a scenario module, from in-game data, or any other suitable source: [KSPAddon(KSPAddon.Startup.Flight, false)] public class BasicExample : MonoBehaviour, IExample { private string _version; private static BasicExample instance = null; public static BasicExample Instance { get { return instance; } } private void Awake() { instance = this; _version = "Assembly Info Version"; } public string Version { get { return _version; } } public bool ShowOrbit { get { return BasicSettings.Instance.showOrbitPanel; } set { BasicSettings.Instance.showOrbitPanel = value; } } public float Alpha { get { return BasicSettings.Instance.panelAlpha; } set { BasicSettings.Instance.panelAlpha = value; } } } To open the window we just need to setup a toolbar button as normal and use the Open function to start the UI: BasicOrbit_Example window; private void Open() { if (BasicOrbitLoader.PanelPrefab == null) return; GameObject obj = Instantiate(BasicOrbitLoader.ToolbarPrefab, GetAnchor(), Quaternion.identity) as GameObject; if (obj == null) return; obj.transform.SetParent(MainCanvasUtil.MainCanvas.transform); window = obj.GetComponent<BasicOrbit_Example>(); if (window == null) return; window.setInitialState(BasicExample.Instance); } The arguments in the Instantiate method are used to set the window’s position and rotation The rotation is set to zero Here the position is set using the Toolbar Button’s GetAnchor method There are several canvases that could be used, but in general the MainCanvas will probably be best We can get a reference to the UI script since it is attached to the newly instantiated object The window can be closed by either hiding it or destroying it You can hide the window by setting its gameObject.SetActive(false) This can be used if the window has a complicated initial setup and you don’t want to keep repeating that This should be enough to get a basic window into KSP. Future sections will go over dynamic UI generation and UI layouts elements, specific UI features, KSP-style UI elements, and using TextMeshPro for all text elements. They should also, hopefully, be much shorter, since they won’t have to cover so much information. If you want to setup your UI with the legacy Unity GUI style elements, they are available for free on the Asset Store. You will need to import them into Unity and use the Sprite Editor to set the Splicing lines properly (so that the images stretch to fit whatever size is needed). After that you can simply drag the sprites into your Image elements wherever needed.