DMagic

KSPedia Creation Tutorial

81 posts in this topic

With KSP 1.1 we can now create and load our own KSPedia entries. This is great for making in-game tutorials, wikis, or manuals, as I’ve always suspected that only a small fraction of players actually use GitHub wikis, or in-depth forum manuals.

This post will go over what is needed to make KSPedia entries, how to setup your project, and how to make your pages look similar to the stock pages.

 

Software and Tools:

Required:

  • Unity – Current KSP version is using Unity 5.2.4
  • KSP Part Tools – The current package includes what is needed for generating KSPedia Asset bundles and the legacy Part Tools files

Recommended:

  • Text editor – A real text editor (like MS Word, or Open Office) is recommended; it makes catching typos, editing grammar, and saving data much easier
  • Image editor – Unless you want your pages to be entirely text you’ll want something to edit images (Photoshop or GIMP)
  • Open Source Fonts – The stock entries use two open source font sets (they may be added to the Part Tools package at some point) – Amaranth and Open Sans. (Use the small Down Arrow in the upper-right and select the .zip to download the font package)

First off, all of the basic information about how to setup your project and export a KSPedia entry comes from @Agathorn's thread. And @TriggerAu has provided lots of information about KSPedia creation and specifics about how to make stock-alike pages.

In the text below, Bolded words generally represent screen elements in Unity, such as buttons, tabs, windows, etc… Bolded and Italicized words represent the UI objects and elements and files that we are creating and manipulating.

 

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 an empty scene; delete everything in the Hierarchy Window
  • In the Main Window you’ll want to be in the #Scene Tab, in 2D mode, using regular Shaded mode.

 

Creating a Template:

It’s worth taking the time to setup a default panel prefab, something that can be copied into any project so that you don’t have to repeat the next several steps for each page. To do this we need to add a UI Panel, add some components to that, and set the Panel size. You can also save individual components as snippets that can be added to your pages; see the random notes section at the very bottom for info about saving formatted Text object snippets.

  • Add a UI panel: GameObject Tab -> UI -> Panel
  • This will add a Canvas with a child Panel, and an EventSystem – the Panel is what we are interested in
  • Right click on the Panel object and rename it something, this name is only used internally, but you should probably make it something specific to your project and something unique
  • In the Inspector Window on the right click Add Component -> Scripts -> KSPAssets.KSPedia -> Database Screen – What this does isn’t entirely clear, and you don’t need to do anything else with it, but it seems to be required
  • In the Panel’s Rect Transform Component Window set the Width to 2048 and the Height to 1536 (you can change the sizes if you want to have a taller or wider page that can be scrolled through - Thanks @jandcando)
  • Click the Anchor Preset (the box with the grey squares and red cross, or blue arrows) and select Top-Left
  • If you want a Background Image you can click the circle to the right of the Source Image field in the Inspector Window
  • See below in the Text section for information about adding Heading and Sub-Heading Text Objects to make sure that these elements are in the same place for each page
  • This can be saved as a template prefab by dragging the Panel from your Heirarchy Window to somewhere in the Assets folder in your Projects Window; it will create a .prefab file which can be dragged into any Unity project

 

08ZD6eA.png

Your setup should look something like this after you’ve created a template prefab.

 

KSPedia Asset:

We’ll come back to actually adding content later, but first we’ll go over how to setup the KSPedia asset. This involves creating the Categories and Sub-Categories for your entry, assigning pages to each Category, and determining the page order.

First we need to tell Unity which asset group our prefab belongs to.

  • In the lower-right, below the Inspector Window is the Preview Window, at the bottom of this is a selection box labeled AssetBundle
  •       Click the Box -> Select New -> Add your entry (use only lower case letters)

O49yk98.png 

 

Now we can setup the KSPedia asset through Squad’s included tool.

  • Open the KSPedia Window: KSPAssets Tab -> KSPedia

 

This will open a separate window called KSPedia Database, this is where we handle all of the Category creation, page ordering, etc...

  • Click the Create button to the right of your newly made project, then click View (ignore the Build All button along the bottom, we don’t use that at all)

yz00ZFY.png

This window has Four Tabs, an Update button for when new prefabs are added, a Save button for when you are finished, and a Back button.

  • Under the Categories Tab create a new Category, and optionally a Sub-Category, then click Create (the names used here are for internal use)
  • This will add the Category and allow you to enter a display name, which is what people will actually see in the KSPedia entry
  • Use the selection box under the Title Screen column to select the prefab for that screen
  • Use the up and down arrows along the left to change the order of Categories
  • Click View to the right of a Category or Sub-Category to go the Category Tab; here you can change the Internal Name, Title, prefab selection, or add a new Sub-Category (only for top level categories); basically the same functions as what you have in the Categories Tab (except for one that we’ll come back to)

 

 zFHcvxQ.png

A completed Categories Tab, note the Category and Sub-Category, and the Title field, which is what will be shown in-game.

 

 YYgg0ZF.png

The Category Tab for the “Other_StuffSub-Category, you can also set the prefab used for this page, change the Internal Name and the Title. Note the Screens section on the bottom; this is where we view and change the order of the third layer of pages; more on this below.

 

You can create pages on three different layers: Top level Category, Sub-Category, and Screens. Screens can be added to both Categories and Sub-Categories. One page (that is, one prefab object) is added to each Category, Sub-Category or Screen.

  • To assign a Screen to a Category or Sub-Category go to the Screens Tab
  • Any prefab that isn’t already assigned as the Title Screen of a Category or Sub-Category will show up here with the label “Undefined"
  • Click View on an “Undefinedprefab to go to the Screen Tab
  • Here you can set the Screen to a Category and Sub-Category, change the Internal Name, and the Title
  • Click the Set button; if you return to the Category Tab you will see that it now has an entry for the included Screens, change the order with the arrows along the left if you have more than one
  • After everything is setup to your liking remember to click the Save button along the top, otherwise you’ll have to do all of this over again

 

 qXugLvC.png

Here is the Screens Tab before adding the “Other Stuff” prefab to anything. Even though the Title fields are blank here, the Titles of the Categories and Sub-Categories have been set and will be shown in game.

 

gfC64Rf.png

After clicking the View button in the Screens Tab we move to the individual Screen Tab. Here we can set the Category and Title.

 

Now we can export the Asset bundle.

  • Open the Asset Compiler Window: KSPAssets Tab -> Asset Compiler
  • This window can be dragged and docked into any of the regular Unity window sections
  • Again click on the Create button for your project
  • You can view the project to see which prefabs are included and to see the .xml file, which describes the KSPedia hierarchy that the last section covered
  • Click Update if you’ve made any changes, then Build
  • This will place the asset file in in AssetBundles folder of your Unity project folder (this should be the same location as where your prefabs and the Part Tools files are located)
  • The file should have a .ksp extension, if it doesn’t you’ll need to add it
  • Place this file somewhere in KSP’s GameData folder and KSP should load up the entry and display at the end of the KSPedia contents

                                                                                        

C2PrV45.png

Here the Asset Compiler Window is docked into the section with the Project Window, Update and Build your final project from here.

 

m8gn0Y5.png

Here is the View section of the Asset Compiler Window. You can add Author Info and other Notes. If you push the Select button for the xml file it will show you its contents in the Inspector Window, be aware that long files may be truncated here.

 

Making KSPedia Pages:

Now that we know how to setup the project and make a KSPedia asset bundle, we can start actually making pages.

Some basic tips on making good pages:

  • Keep the text to a minimum; no one likes reading Power-Point slides full of text, the same applies here
  • Use images and diagrams wherever possible, adding captions and short descriptions where needed
  • Don’t over-crowd pages, just create more pages when you need them
  • Keep the focus on one element for each page, unless the page is specifically intended to be a catch-all, or “other features” kind of thing

 

Adding Text:

  • Add Text UI elements to your Panel: Right-click the Panel object in your Heirarchy Window -> UI -> Text
  • This will add a Text object as a child of the Panel, rename it to something descriptive
  • The Text Window will be added in the center of your panel, you can drag it around with your mouse and re-size it using the blue circles in the corners
  • In the Inspector Window on the right you will see the Text Component, add the actual text in the Text Box, select the Font, and change the Font Size and Font Color
  • The default Font Size appears very small because the Panel is so large, but if you make it too big it will overflow the box, you can change the Vertical and Horizontal Overflow properties to make it visible, or just make the Text object bigger

 

Some notes about fonts; from TriggerAu:

The fonts used in stock KSPedia entries are as follows; note that Unity uses pixel size for the font, so multiply the pt value by 1.25 to get the final Font Size (which is shown below in bold).

If the fonts are not included in the Part Tools package download them and put the files somewhere in your Unity Project’s Asset folder.

  • Amaranth Bold for the Headings and Subheadings:
    •       56pt – Font Size of 70, #2978ef (41,120,239 in RGB color)
    •       40pt – Font Size of 50, #2978ef (41,120,239) or #f2f2f2 (242,242,242) depending on placement
  •       Open Sans for Body font, all #f2f2f2 (242,242,242)
    •       32pt – Font Size of 40, for most
    •       32pt – Font Size of 40, bold when Paragraph Heading, then Paragraph Body is 28pt – Font Size of 35
    •       28pt – Font Size of 35, italic when Notes/Captions

 

PySS0vj.png

It’s worth adding Heading and Sub-Heading Text Objects to your Template Panel before saving it. Setup the Positions, Fonts, Font Sizes, and Colors, this will ensure that these elements are in the same location for every page. The Heading Text Object is added to the Panel and the Sub-Heading Object is added to the Heading. Keeping elements paired together like this makes it easier to move them around; play with the anchor settings to get the child objects to lock to the desired position relative to the parent object.

 

Importing Images:

To use images in our pages we first have to import them into Unity and set them up.

  • Drag any standard image file into your Unity project’s Asset folder to get started
  • Select the Image (you can select and import multiple images at the same time) in the Unity Project Window
  • In the Inspector Window change the Texture Type to “Sprite (2D and UI)”, uncheck Generate Mip Maps and click Apply

XGf3JB8.png

 

Adding Images:

To use our imported images we need to add an Image UI Object to out Panel.

  • Right-click the Panel -> UI -> Image
  • Move and re-size the object the same as with the Text Object
  • For the final prefab page you should only have a single Image Object, with a transparent background, covering the entire page
  • Make a 2048*1536, transparent image in your image editor, then paste your images onto the larger image and move them into place

 

Positioning individual images within a larger image is difficult to do without lots of trial and error. I find it’s best to import the individual images first, then set them at the desired size and positions. After setting things up in Unity you can get the size and position information and use that to create your final image.

To add an image, first create an Image Object as describe above.

  • Select one of the imported files as the Sprite Image for your Image Object
  • Hold Shift when re-sizing the Image to maintain the aspect ratio
  • Once you have the Image where you want it you can read the size information from the Rect Transform Width and Height Boxes
  • To get the position of the center of the Image you’ll need to change the Anchor Preset to Top-Left
  • The Rect Transform Pos X Box will give the number of pixels from the left edge to the center of the Image
  • The Pos Y Box will give the number of pixels below the top edge
  • Use this information to re-size and place your image in the proper location in your image editor
  • Also be aware that most stock KSPedia screenshot images have a white border around the edge, this is roughly 5 to 7 pixels wide
  • Once you have a single, 2048*1536, transparent image file, import this into Unity and set it as the Sprite Image for the Panel’s one Image Object

 

6s5cgLK.png

Read the image size and position information from the Rect Transform Component. Use this for setting up the final image in your image editor.

 

Here are some examples of a more complex project.

QQVLKkI.png

The Categories Tab includes a top level category and several sub-categories, each with several screens.

 

pVByBvn.png

Note how all of the panels in this project are placed under the same canvas object in the Hierarchy Window. When working on multiple panels you can disable all but the panel you are working on by unchecking the box at the very top of the Inspector Window (the one to the left of the prefab title). Be very careful when building your final project to make sure that none of your actual prefab files are disabled; the files (found in the Project Window) can be enabled or disabled independently of the objects in the Hierarchy Window. If the files are disabled when you build the project then those screens will appear blank in-game.

The prefab and image files for all of the SCANsat pages can be found on the GitHub repo.

 

 A few random notes here:

  • Squad KSPedia pages appear to all be built as separate files; I don't know how this works or if there is some benefit to it, but I've been working with a single file that contains all pages and it seems to work fine
  • There seems to be several methods in the KSPedia classes that deal with merging and replacing entries
    • This might imply that it is possible to replace or add to existing entries; this is entirely speculation on my part
  • I'll add some information later about getting screenshots of parts, vessels, or planets without any background
    • For parts I've been using a big green screen panel to attach my parts to, then removing that background in Photoshop
    • Something similar can be done to remove the mostly black space background, or you could use Texture Replacer to completely replace the SkyBox with a solid color image
  • When you go back after building the project to edit text elements you need to remove all of the existing prefab files for that panel
    • Delete the prefab file - Do Not delete the actual object in the hierarchy, unless you want to start over
    • Update the KSPedia Asset after deleting the prefab and update the Asset Compiler
    • The text information seems to be stored directly in the xml file, and won't get properly updated unless you clear out the existing information
  • You can save snippets with any objects from your project's hierarchy, not just completed or default Panels. For instance, you can create Text object groups with the font, size, color, and layout already setup.
    • You can see below how different paragraph-header combinations can be created, as well as formatted text boxes, and the red note text boxes
    • This saves a lot of time when creating entries with lots of text, since you would otherwise need to format every new Text object
    • Add these to your pages by simply dragging them into the desired Panel.

YbE6iFM.png

 

If anyone has more to add, or corrections to make, please let me know.

Edited by DMagic
Remove dependency warning
27 people like this

Share this post


Link to post
Share on other sites

thank you for this topic. 

Edited by Apollo13

Share this post


Link to post
Share on other sites

Wow you took this so much farther than I did.  Awesome job!

Share this post


Link to post
Share on other sites

Thanks for taking the time to share this man!

Share this post


Link to post
Share on other sites

I nominate this to be pinned! Great work. It is not as straight forward an I'd hoped, but good to know!

2 people like this

Share this post


Link to post
Share on other sites

Once you get familiar with the work flow and a working template it's actually not that difficult.

You can see the final result in Unity, so there's really no need to actually load up KSP until the very end.

Preparing the actual content is what ends up taking most of the time and effort.

1 person likes this

Share this post


Link to post
Share on other sites

I will certainly give a shot for my Probes+ mod. Even if it is just a quick overview page

Share this post


Link to post
Share on other sites

Pressing "build" on the Asset Compiler window crashes Unity and gives me a Microsoft Visual C++ Runtime Library runtime error. I'm running Unity 5.2.4. Do I need to use a different version?

EDIT

Here is a screenshot:

y637mk2.png?1

 

I'm trying to make a small KSPedia page that just has the Delta V subway map made by Kowgan into the KSPedia. So the background image is just a stock background image with the delta v map edited onto it

EDIT 2

When I re-open the unity scene after it crashes, lots of scripts in multiple gameObjects are broken. They say "The associated script cannot be loaded. Please fix any compile errors and assign a valid script." This affects scripts in the Canvas object, the EventSystem object, and all Image objects.

Edited by jandcando

Share this post


Link to post
Share on other sites

@jandcando I've problems with the scripts getting messed up, I think I was trying to transfer files between different computers. 

I basically had to scrap that panel and make a new one. You should probably be able to copy any Image and Text components, but the panel will need to be replaced with a new one or a template. You might also want to delete the .xml file that was generated by the KSPedia tool; there should be an XML folder somewhere in your Assets folder.

I'm not sure why it's crashing (I've always had problems with Unity stability, in 4.x more than 5.x, though), but I can see that your panel doesn't look right. It's missing the Image component in the Inspector Window.

Share this post


Link to post
Share on other sites

Alright, I'm trying again with a totally blank Unity project.

Here I am so far:

zbdx0Wi.png

Well, it worked this time. I'm guessing this is all because my other Unity project has lots of old stuff that wasn't properly brought to the new Unity version or something... Starting fresh is always nice to do every now and then.

 

1 person likes this

Share this post


Link to post
Share on other sites

I'm starting to think that it's worth creating a KSPedia creation made up of other people's contributions like this. So that, rather than having a bunch of one or two page entries we can have a single entry, or just a couple, with lots of sub-categories and pages. 

The tutorials forum is filled with stuff that could make great KSPedia additions.

I'll see about making a new thread to collect all of the KSPedia entries and maybe start some kind of unified collection.

Share this post


Link to post
Share on other sites
On 4/28/2016 at 3:47 PM, jandcando said:

Alright, I'm trying again with a totally blank Unity project.

Here I am so far:

zbdx0Wi.png

Well, it worked this time. I'm guessing this is all because my other Unity project has lots of old stuff that wasn't properly brought to the new Unity version or something... Starting fresh is always nice to do every now and then.

 

Looks like you are working on the same thing I was gonna try and do lol.

@DMagic can the screen be made taller? I see in game there is a scroll bar and something like the delta v map would look better taking up the whole screen and being able to scroll. 

  • In the Panel’s Rect Transform Component Window set the Width to 2048 and the Height to 1536
    I figure that line, the Height is where it would be changed, but will the game accept it?
Edited by PortableGoogle

Share this post


Link to post
Share on other sites
1 hour ago, PortableGoogle said:

Looks like you are working on the same thing I was gonna try and do lol.

@DMagic can the screen be made taller? I see in game there is a scroll bar and something like the delta v map would look better taking up the whole screen and being able to scroll. 

  • In the Panel’s Rect Transform Component Window set the Width to 2048 and the Height to 1536
    I figure that line, the Height is where it would be changed, but will the game accept it?

I'm trying this now, since it was unreadable in the game when I tried it. I've set width to 2048 and height to 1962 to accommodate the full height of the map.

It works! I can read the map now, and the scroll bar magically put itself where it needed to be.

Here is the .ksp file if anyone wants to have it (Dropbox link): https://www.dropbox.com/s/z3p6kjrgj6zt55n/deltavmap.ksp?dl=0

6 hours ago, DMagic said:

I'm starting to think that it's worth creating a KSPedia creation made up of other people's contributions like this. So that, rather than having a bunch of one or two page entries we can have a single entry, or just a couple, with lots of sub-categories and pages. 

The tutorials forum is filled with stuff that could make great KSPedia additions.

I'll see about making a new thread to collect all of the KSPedia entries and maybe start some kind of unified collection.

I really like that idea. I was thinking about starting a sort of reference-based mod myself filled with KSPedia entries. Stuff like where exactly is the cut-off like between "in space high" vs "in space low" for all the planets, and science multipliers. The kinds important of stuff you usually have to make a trip to the KSP wiki to find.

Edited by jandcando
2 people like this

Share this post


Link to post
Share on other sites
2 minutes ago, jandcando said:

I'm trying this now, since it was unreadable in the game when I tried it. I've set width to 2048 and height to 1962 to accommodate the full height of the map.

It works! I can read the map now, and the scroll bar magically put itself where it needed to be.

Here is the .ksp file if anyone wants to have it (Dropbox link): https://www.dropbox.com/s/z3p6kjrgj6zt55n/deltavmap.ksp?dl=0

do i just put that file in my gamedata folder? and awesome on it scrolling. Gonna work on learning this tomorrow and maybe see about helping contribute to a community KSpedia update or whatever you want to call it.

Share this post


Link to post
Share on other sites
Just now, PortableGoogle said:

do i just put that file in my gamedata folder? and awesome on it scrolling. Gonna work on learning this tomorrow and maybe see about helping contribute to a community KSpedia update or whatever you want to call it.

Yep, it just goes into your GameData folder. You can make a folder for it if you want, it doesn't really matter as long as it is in anywhere in GameData.

Share this post


Link to post
Share on other sites
Just now, jandcando said:

Yep, it just goes into your GameData folder. You can make a folder for it if you want, it doesn't really matter as long as it is in anywhere in GameData.

thanks, time to get this rocket up and go to bed lol

Share this post


Link to post
Share on other sites

Amazing and easy-to-follow tutorial even for someone like me who's never touched unity. Thanks.

Share this post


Link to post
Share on other sites

File sizes seem to be getting pretty large even with only a few pages, at 4 pages so far and the asset bundle is already at 5MB. Is this normal?

@DMagic, paging! :D

Share this post


Link to post
Share on other sites

@Poodmund Are you using a single large image per page? When I was making pages that contained multiple images the file size was much larger.

With SCANsat I have 17 pages, all of them with a single, panel-sized image (plus the blueprint background, the file size for which is around 20kb), and it comes out to 3.8MB. The image files range from less than 500kb to around 2MB; all of them are .png files.

If your images have little to no transparent space they might come out a bit bigger, but I think there are several stock pages with skybox backgrounds, and all but one Squad KSPedia files come out at less than 150kb (I don't know what the deal is with the single 1.5MB page for science transmission).

Also, all of my prefab files and images are on the SCANsat GitHub repo.

Edited by DMagic

Share this post


Link to post
Share on other sites

Ah I seeee.... so reusing common assets actually does work when the bundle is exported. I feel dumb now.

Share this post


Link to post
Share on other sites

Yeah. Making the skybox the background image and leaving most of the main image blank would probably cut down on size a lot.

 

It seems like there is either something wrong with how I am generating KSPedia asset bundles, or a bug with the asset loader, because any time three or more additional KSPedia entries are installed it breaks the system.

So... I guess maybe we shouldn't make KSPedia entries. At least until someone can figure out if there is a way around this problem. ;.; 

Edited by DMagic

Share this post


Link to post
Share on other sites
2 hours ago, DMagic said:

Yeah. Making the skybox the background image and leaving most of the main image blank would probably cut down on size a lot.

Well each page showcases a different planet/moon so the different textures are essential. It seems mad that with 5 panels that I have mocked up, if you set the background of the panels to none, export the bundle, 150kb. Assign the 5 images to the backgrounds of the panels, export the bundle, 8.3mb. However, the sum total size of the 5 images as .pngs is 6.8mb. Its as so anti-compression is occurring. :(

Share this post


Link to post
Share on other sites

@Poodmund Are you assigning the images to the Panel's background image, or to a separate Image UI object? I'm not sure if it makes any difference.

Are all of the pages similar to what you posted in the OPM thread? What you can do is make a skybox image to use as the background, then cut out the planet images and leave the rest of the space transparent.

If you have Texture Replacer you could try replacing the sky box with a flat black (or maybe green) texture. That would make it easier to crop out the background from the planet images, though it's not really that hard to remove the background from spherical planets using the regular skybox.

That way the Asset Compiler would presumably be able to save space by only linking to the background once.

Share this post


Link to post
Share on other sites
18 hours ago, DMagic said:

@Poodmund Are you assigning the images to the Panel's background image, or to a separate Image UI object? I'm not sure if it makes any difference.

I have tried both of these and it made minimal difference.

18 hours ago, DMagic said:

Are all of the pages similar to what you posted in the OPM thread? What you can do is make a skybox image to use as the background, then cut out the planet images and leave the rest of the space transparent.

If you have Texture Replacer you could try replacing the sky box with a flat black (or maybe green) texture. That would make it easier to crop out the background from the planet images, though it's not really that hard to remove the background from spherical planets using the regular skybox.

That way the Asset Compiler would presumably be able to save space by only linking to the background once.

I have also tried this method. Used a Skybox image as a common asset and then added in all the texture elements separately for each panel and it got it down to 6mb for the 5 panels.

I think the compiler may just be badly optimised for image assets.

EDIT: Paging @TriggerAu for input regarding KSPedia asset bundle file size with respect to the pages that contain image-heavy content i.e. Planet pages?

 

Edited by Poodmund

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now