[Guide] Programmable Block - C# 102.5 for Space Engineers - Reading Documentation

Hey All,

I've had a request from a few people to go over how to read some of the stuff posted here and on Reddit. If you haven't read Programming 101 and Programming 102, please do so. This guide assumes you know what all these types are already, and is not going to stop to explain what an "int" or "inheritance" is.

First, let's start with what I call "MSDN syntax." Basically, MSDN is Microsoft Developers Network. C# was originally developed by Microsoft to use their .Net framework to its fullest extent. When reading MSDN guides or Cuber's API dump you'll see several icons in the documentation, all based on Microsoft's Intellisense technology found in Visual Studio:

Image Source: https://www.vidgenuity.com/wp-content/uploads/intellisense_icons.jpg (vidgenuity.com main page was offline when this guide was created.)

So using this, we know what each thing means.

If we look at the following page:

https://msdn.microsoft.com/en-us/library/system.windows.controls.textbox%28v=vs.110%29.aspx

You'll see a TON of these things listed. This is for windows programming-- don't worry about the class or its use, we are just looking at the icons so we can read through it and see what each section and icon means.

First: Syntax. This box shows how something is used in the code. Note that it doesn't tell you when to use it-- things tend to be used as needed, and the document can't possibly list every use case. You will know the when as you gain experience.

Code:

[ContentPropertyAttribute("Text")]
[LocalizabilityAttribute(LocalizationCategory.Text)]
[COLOR= #3366ff]public class[/COLOR] TextBox : TextBoxBase, IAddChild

This shows how the code was implemented. In this case, you can ignore the first two lines (it isn't relevant to C# in reference to Space Engineers). This tells you that it is a public class named TextBox that inherits from TextBoxBase and IAddChild.

Let's compare with a non-class "syntax" box:

See the big difference here? It still tells you how it was initialized, but it also helpfully prints out each parameter individually and informs you of what type of parameter it is and its description.

Constructors: This lists all the valid constructors for a class.

So, we see the icon, the name of the constructor, and it tells you how it is used. Click the name to see a more detailed breakdown of the constructor.

Properties: This lists all the accessible properties. Each property can be clicked on to see more information about the property. It also informs you of any inheritance.

Methods: This shows you what methods are accessible, and the icon indicates if it is private/public/protected. This also gives a description of what each method does.

Events: These likely won't be used in SE Coding, but I'll include it here for thoroughness:

Fields: Variables declared in the class itself. Anything with a big red S icon means it is a static field, which is something not currently implemented in Space Engineers.

So, now that we've looked at a proper MSDN document, let's take a look at one of Cuber's DLL dumps.

Not so different, right? The main piece of information lacking is the "description" field for each entry (other than where it inherited from).

Reading Templates
This is something specifically requested that I go over. Some of the syntax entries are a bit... convoluted for non-programmers, which is completely understandable. Let's take a look at GetBlocksOfType.

Code:

void GetBlocksOfType<T>(List<IMyTerminalBlock> blocks, Func<IMyTerminalBlock, bool> collect = null);

Ok, let's start with the obvious.

Code:

void GetBlocksOfType

This says we have a method of type void named GetBlocksOfType.

Code:

<T>

This indicates that the method we have is a template. This means that this method is a generic method. What is a generic method? A method that can take any type passed into it without having to have a separate overload for each case. This is not the same as overloading parameters, and should not be used in place of overloaded method definitions. The scope of this document will not show you how to make or use generic methods.

Code:

Func<IMyTerminalBlock, bool> collect = null

This is passing a method as a parameter. Why, yes, you can do that. Notice that "collect = null" part? Well, if we were to rewrite the method definition as taking the actual method rather than having to put the func<> bit in:

Code:

GetBlocksOfType<T>(List<IMyTerminalBlock>, collect(IMyTerminalBlock,bool) = null))

What's that = null part? Well, I haven't explained it yet, but basically... you can make parameters optional by specifying default values. In this case, it says the return result of collect is null. Since we never use a collect() method (and we don't really even know what it is supposed to return), we never bother talking about that option or using it. So, if we were to write this code in the game and assume it was a mandatory to put that value in, our code would look more like:

Code:

GridTerminalSystem.GetBlocksOfType<IMyBeacon>(beacon, collect(block,true));

So, to make it easier for everyone? If you see "Func<> = null" in the documentation anywhere, don't worry about it.

Glossary
protected - A keyword that functions like public and private. It allows access to it from its derived class instances (inherited classes).
Event - A special method that fires every time a specific thing happens. If these were allowed in Space Engineers, you could create code that would subscribe to them, and therefore react when something happened (like, say, a door opened).
generic method - These are used when you want to do things to classes or other objects and the way you handle it will not change no matter what is passed into the method. This is not the same as overloading the method to handle different data types, since that allows you to change the code to handle different data type parameters in different ways.

 

Just to expand a little on "void"... You might have covered this in the other "chapters", but here goes.

When a method (or function) is declared like:

Code:

private void someFunctionOrMethodName(...)

or:

Code:

public void someFunctionOrMethodName(...)

or just:

Code:

void someFunctionOrMethodName(...)

it means that the method/function doesn't return anything.

So in something like:

Code:

IMyShipMergeBlock merge = (IMyShipMergeBlock)GridTerminalSystem.GetBlockWithName(...)

the GetBlockWithName method of the GridTerminalSystem object returns something, so it is not declared as void.

But in:

Code:

merge.GetActionWithName("OnOff_Off").Apply(merge);

The Apply method of the Action "OnOff_Off" of the "merge" block does not return anything, so it is declared "void".

Bottom line, if your method/function does something and returns a result (either something that you want to return, like an object, or if it returns something to indicate status, like success or failure) you have to declare your method/function like so:

Code:

public theTypeItReturns methodOrFunctionName(someParameterType params...)

If it doesn't return anything (just does something and returns), you declare it void.

Aside from all the SE objects that you can return (along with any C# object that you might create), these are the data types that are built-in to C#:

https://msdn.microsoft.com/en-us/library/cs7y5x0x%28v=vs.90%29.aspx

 

I get some nostalgic feelings if i see this old school VS icons

 

I never thought I would see the day that I literally mix work with pleasure. I have been developing in C# for years and this is exciting

 

Anybody know how to make the script wait? System.Threading.Thread.Sleep() is not allowed

I am using a while loop but it executes at lightning speed then I think after 1 second it just stops executing. or it bricks it self because my output stop updating until I edit and remember again.

 

Why does it need to wait?

 

save state and wait next run.
while your script is working nothing changed in the world.

 

Yea I figured it out now. I need to use a timer block to repeat the run every x seconds. That is all I needed. Now I also uncovered the workshop has tons of scripts and I see how things are being done.

Very limited though. I thouhgt we could access base clasess like GetChildren .I want to traverse the blocks and find specific items but I dont think that is the inteneted use. The script blocks the IMyEntity usage.. which is a bit rubbish.

 

you can find specific items by type or by name.
or just get all terminal blocks(same as K-menu)