GUI Tutorial Series

[Abion47]

Lesson Zero

Welcome to my tutorial series on how to create spectacular terminal GUIs in SOMA. I'm striving to make this tutorial as easy to follow as possible, so I won't assume any previous experience with the ImGui system. I do, however, assume that you have already familiarized yourself with the general modding toolkit in SOMA. This tutorial will also largely take place in the script-side of things, so I expect that you know how to set up a SOMA workspace in CodeLite, if you have not already done so. (Here is a refresher for those that don't.)

If at any point you get confused about something during the course of the series, each tutorial will have downloadable files that comes with it. These files will contain the map as it should be at the start of the tutorial, as well as once the tutorial has been completed.

Now, the best place for any tutorial series to start is at the beginning, so this first tutorial will be on how to create a terminal on your map and prepare it for GUI scripting.

Table of Contents
The Basics

• Lesson Zero - Setting up your terminal >You Are Here<
  
• Hello, End of the World - Labels and Label Data
  
• Your Friendly Infomercial - TextFrames and Images
  
• Mind Your Language - Lang Files
  
• Who's Got The Button - Buttons and Interactivity
  

Getting More Advanced

• Get To The Back Of The Line - Background Graphics and Z-Order
  
• The Well Oiled Machine - ImGui State Variables
  
• A Regular Grab Bag - Scroll Bars, Check Boxes, and Alternate Button Types
  
• She Goes In And Out, And In, And Out... - Interfacing With Other Entities
  
• Grouping and Layout (WIP)
  

Using SOMA's Built-In GUI Styles

• StationGui (WIP)
  
• UrbanGui (WIP)
  
• Playing Audio (WIP)
  

Going Beyond Terminals

• Setting Up a User Module (WIP)
  
• Basic Heads-Up Display (WIP)
  
• Target Info Module (WIP)
  
• Player HUD Menu System (WIP)
  

Tutorial Requirements

For this tutorial, you will need the following:

• A map with three things: a PlayerStartArea, a basic plane (of any material) for the player to stand on, and a light source with which to see.
  
• A CodeLite workspace setup, linked to your map's script file.
  

Tutorial Source Files

Initial File
Completed File

The Tutorial Itself

First, place a terminal entity onto your world. It can be anywhere, really, as long it's in a place that the player will be able to easily see it.

The type of terminal doesn't particularly matter either, but the large computer panel terminal is nice and big, so it will be an ideal choice. Be warned, there are several entities that are associated with a large computer panel, so make sure you get the one named "computer_panel_large_GUI". (You'll know it's the right one if you select it and see a Terminal section under the Entity tab.)



Now open the Terminal section up. From here, you will see a number of text boxes, check boxes, and number boxes - just a lot of boxes, really. For now, though, the only one we will be worrying ourselves with is the box at the top labelled "OnGuiFunction".



This box will hold the name of the callback function that will be handling all the GUI drawing of our terminal. Strictly speaking, you can call it whatever you want, but good practice is to call it the name of your terminal entity followed by "_OnGui".



That's all we need to do in the Level Editor for now, but before we leave, we are going to want to click the button under the text box marked "Copy". What this does is it copies the relevant code for your function into your clipblard, so you don't have to worry about remembering exactly what you need to type into your script file. Don't forget to save at this point!

Now let's head over to our script file. If your map is freshly made, your script file should be full of all the default code from when the file was generated. Scroll all the way down to the bottom of the file, and you will see a section marked out specifically for terminals.

You should still have the code in your clipboard from before, so go ahead and paste it under the section marked for your terminal functions. (If you've lost the code from before, you can always go back to the Level Editor and copy it again.)



After a little bit of formatting, your code should look like the above picture.

What you are looking at is the default callback function for a terminal's OnGui event. The first parameter is a string called "asEntityName", which will hold the name of the terminal entity that is invoking this function. Unless you want to have more than one terminal referencing the same function, you generally don't need to worry about this parameter.

The second parameter is a float called "afTimeStep". This parameter holds the length of time that has passed since the last time OnGui was called. This is useful to have if you will ever be creating terminal GUIs that deal with animated elements, such as the waveform terminal in the pilot seat room in Omicron, but otherwise you probably won't have to bother much here either.

And that's it, really. As of this point, you now have a static terminal that does absolutely nothing. After you've finished celebrating, we can move on to the next tutorial, in which we will get our terminal to do some basic stuff.