'S' update as of 4/12/11

New releases and general discussions.

Post » Thu Oct 08, 2009 12:33 am

Hello fellow scirra members.
I am preparing for the alpha release of the 'S' plugin.
The purpose of this thread will be to explain what the S plugin actually is, and to serve as an on-going tutorial. The exact order of the tutorials hasn't been decided, so feel free to weigh in on what needs teaching, and I will try to plan out the next tutorial based on demand. This first tutorial will primarily explain the theory and purpose of S, and only briefly introduce some of the syntax. Future tutorials will give more concrete examples, and eventually walk through the creation of more complex projects. The plugin itself will not be released until the 2nd or 3rd tutorial, as it essentially useless without some background information.

For starters though, we will look into what the S plugin is, and what it can be used for.
[color=#FF0000:17pu5r54]click here to download the previous version of s (until I update the tutorials, use this for the everything before the level editor tutorial)[/color:17pu5r54][size=85:17pu5r54]

[color=#FF0000:17pu5r54]click here to get the newest version, use this for the level editor on. I know this is messy. I will update the earlier tutorials when I get a chance[/color:17pu5r54][size=85]
extract the rar into your construct folder.[/size:17pu5r54]

This symbol will be at the beginning of each tutorial in this thread so you can easily find them and go back to them.

S stands for superstructure, or systemplus. it is shortened to 's' to require the minimum amount of typing when invoking expressions. also, s happens to be the first letter in two of it's major functions.

We will first go over what a superstructure is.

A superstructure is a named container which can contain named arrays of 5 different types of data. Strings, Numbers, Objects, Object Types, and other superstructures.

in s you can create variables of any of the following types:
[list:17pu5r54][*:17pu5r54]strings - store text, like names of characters or items, players, or dialogue.[/*:m:17pu5r54]
[*:17pu5r54]numbers - store floating point or integer values, like hitpoints, or x and y positions[/*:m:17pu5r54]
[*:17pu5r54]objects - store references to construct objects. a construct object would be like the player sprite in your game, or a text object on the top of the screen that displays the current score. You can use these references to gather information from objects, and to control objects. For instance, you can find out the x and y coordinate of an object, or pick an object so you can change it's position. This is only a reference, however, not the object itself, so more than one object variable can refer to the same object, and destroying an object variable or reassigning it to another object doesn't affect the object itself.[/*:m:17pu5r54]
[*:17pu5r54]objecttypes - stores a reference to construct object types. while an object variable refers to an actual object, the object type variable refers to the type of an object as distinct from an actual instance of that object. If you destroy a sprite at start of layout, even though there are no sprites you can create an object of type sprite. You can check if there were any collisions with an object of type sprite, even if there on are sprites on your layout. ObjectType variables can be used anyway you'd normally use a dropdown box to select a type in construct, like creating a new object, or checking for collisions.[/*:m:17pu5r54][/list:u:17pu5r54]

with s you can create any number of named variables of any of these types. such as a number called "hitpoints", or a string called "name", an object reference called "currenttarget", or an objecttype reference called "enemyspecies"
remember that these are all variables, so any value, including the object and objecttype variables can be changed at any time.

most of us our familiar with the idea of a string or number variable and their various uses. So let's explore the possible uses of objects and objecttypes.
I will only give one possible scenario for each for now, but their possible uses are as diverse as strings and numbers, if not more so. One could create a "currenttarget" object variable that could be used to store the current target for an ai enemy for instance. the enemy could be made to chase this object, you could pick this particular object and check for collisions, you could change targets arbitrarily, or you could recall this object at any time, even if it is not in any particular pickable situation.

one example of a usage for an objtype variable is to store the type of a currently equipped throwable weapon.
one could make an objecttype variable "throwweapon"
when it was time to throw a grenade, a boomerang, a bomb, or a knife, you could use the same code to Create New Object, and just insert the variable type in place of a particular type. it wouldn't matter if they were all of the same type (like a sprite, or an xaudio2 object, or what behaviors they had applied to them, etc. You could use one single action to spawn whichever type was stored in an objecttype variable

there are many other scenarios where these new types of variable could be useful, but we'll move on to specific application after we've covered all of the basics.

next we will explore the concept of arrays:
in s, when you create a single variable, you are actually creating a container for that variable type.
The container consists of a name, a default value, the variable itself. for instance:

so here we have a string container called "username" with a default value of "player", and the actual string value stored in the variable. However, each named container in 's' can contain any number of values referenced by numerical index:

they can be accessed and treated as single values. if you specify no index, the first value is accessed. if you try to access an index greater than the size of the array, the default value is returned. Also if try to set the 30th value of your array, without having 1 through 29 added yet, 1 through 29 will be created and set to the default. Remember, it is perfectly acceptable to create a string container to hold a single value. the concept of an array only comes in if you need that container to hold more than one value.

You can create arrays of strings, numbers, objects, objecttypes, and supers.
Now to explain the super, or superstructure.
a superstructure is a data structure that can hold any number of any of these named array containers, including named containers for arrays of supers:

a super is designed to as a completely customizable conceptual object. You can organize data an objects in a meaningful way. The entire collection of containers and data structures you create is actually contained in one 'master' super.

for example:
one my conceive of something called a "party"(a super), which has a "name" (string), a "rating" (number), and contains an array of "party members" (array of supers). Each "party member" has "hitpoints"(number), a "name"(string), an "inventory"(array of object types),"armor"(super), and a "weapon"(super). Each "weapon" consists of "strength"(number), "name"(string),and a "sprite"(object).

S uses a special array notation to navigate and access your structures
it is necessary to understand this notation before moving on to actions, and expressions

this is an empty address

the address of the "party" super in the above example

the address of the "name" string of the "party"

[code:17pu5r54]{"party","party member"}[/code:17pu5r54]
the address of the first "party member" in "party"

[code:17pu5r54]{"party","party member",0}[/code:17pu5r54]
this statement is equivalent to the statement above, any time you include a number in the array it refers to the index of the previous address component. This is a 0 index, so it begins on 0 instead of 1. 0 is assumed if an index is not provided, in this way, you can address singular variables the same as arrays (remember single variables are just arrays that contain only one member)

[code:17pu5r54]{"party","party member",3,"inventory",5}[/code:17pu5r54]
would refer to the 5th item in the "inventory" of the 3rd "party member" in "party"

In the next lesson, we will see an simple CAP example of how superstructures, and other arrays can be created and accessed. I will also release the plugin itself. Unfortunately I'm out of time for today, but tomorrow I will go over several examples of the applications of the superstructure system. Once the basic syntax and workflow are understood, it will be possible to easily create projects that would once have been extremely convoluted, and difficult to organize with traditional events and picking. A few simple examples would be the creation of a 3d object editor, or an AI that can prioritize tasks and targets.

I hope you all will forgive me for the mostly theoretical post. I had anticipated getting far enough to actually release the plugin itself. Unfortunately, I've run out of time and I must get to bed soon. Please bear with me long enough to see what this thing can do :)
see you tomorrow
Spriter Dev
Posts: 3,224
Reputation: 16,254

Post » Thu Oct 08, 2009 12:50 am

'S' is the best thing since sliced bread. Read my excitement.
Posts: 1,197
Reputation: 5,620

Post » Thu Oct 08, 2009 1:00 am

awesome, looking forward to seeing more.
Posts: 1,763
Reputation: 18,772

Post » Thu Oct 08, 2009 10:38 am

A little encouragement:

Posts: 1,910
Reputation: 13,155

Post » Thu Oct 08, 2009 10:52 am

amazing :D
Posts: 448
Reputation: 2,546

Post » Thu Oct 08, 2009 12:25 pm

Pretty awesome presentation Mr.Lucid. A+
Posts: 473
Reputation: 4,569

Post » Thu Oct 08, 2009 3:13 pm

cool dude
Posts: 622
Reputation: 3,186

Post » Thu Oct 08, 2009 6:22 pm

Sounds like construct is heading towards the realm of object-oriented programming! (Well, actually there's no methods in the containers, so I guess it isn't object-oriented. But... heck. That's still awesome.)
Posts: 263
Reputation: 2,201

Post » Fri Oct 09, 2009 12:01 am

[quote="Drasa":rv6ylv5l]Sounds like construct is heading towards the realm of object-oriented programming[/quote:rv6ylv5l]

I was thinking the same thing as well. I've been wishing for awhile for that kind of capability.. so this is just downright incredible. Can't wait to see some examples and get the plugin!
Posts: 835
Reputation: 5,313

Post » Fri Oct 09, 2009 3:28 am

thanks for all the kind words and encouragement, everyone.
I will eventually consolidate and clean up all these tutorials into a single pdf help file.

I don't have as much time as I originally intended to write tutorials today, however, I did have a chance to share the alpha with a few people in chat and get initial impressions on what was most confusing, and what things needed special emphasis. Today's tutorial will be extremely basic. Basically a "hello world" program, and I will try to release at least one tutorial a day. Please feel free to ask questions, especially about "why isn't this working", and I will do my best to answer them throughout the day, and perhaps integrate any remaining questions in the next days tutorial.
keep in mind this plugin is in the alpha stage. Though I will follow basic steps to allow backward compatibility with previous versions, s will be updated on a sometimes daily basis, and advancing development will take priority over maintaining compatibility with caps created with alpha versions. Please do not begin any major projects that require this plugin until a non alpha/beta release.

first. download s:
[color=#FF0000:2wyojpq2]click here to start download[/color:2wyojpq2]
extract the rar into your construct folder.

[list:2wyojpq2][*:2wyojpq2]Start a new project, and add one text object, and the s object.[/*:m:2wyojpq2]
[*:2wyojpq2]Add an At Start of Layout condition.[/*:m:2wyojpq2]
[*:2wyojpq2]With s, add an Add Array action
[*:2wyojpq2]For the name of the array choose "words".[/*:m:2wyojpq2]
[*:2wyojpq2]Skip over within which super for now (leave it as {""}[/*:m:2wyojpq2]
[*:2wyojpq2]For the type choose String[/*:m:2wyojpq2]
[*:2wyojpq2]For the default, choose "default!!!" or anything else you're happy with[/*:m:2wyojpq2]
[*:2wyojpq2]The last option is only relevant when creating super arrays. we will come back to this in a later lesson.[/*:m:2wyojpq2][/list:u:2wyojpq2]
You have now created an empty string container named "words" with a default value of "default!!!" (or whatever you chose as your default)
[list:2wyojpq2][*:2wyojpq2]Make a Set Text Event with your text object, and double click the s object to get a list of expressions. choose Get String[/*:m:2wyojpq2]
[*:2wyojpq2]Set Text to s.s({"words"})
do not omit the curly brackets {}, this is the number one cause of crashes amongst both myself and the test group earlier today. s.s({"words"}), not s.s("words").
[*:2wyojpq2]Run your cap[/*:m:2wyojpq2][/list:u:2wyojpq2]
if all went well your text should be set to the default value you chose, since your string has not been set to anything yet.

now let's take a look at the expression first we have s.s
every expression in s is abbreviated to as few letters as possible
to retrieve a value of each of the types the expressions are:
[list:2wyojpq2][*:2wyojpq2]s for a string value[/*:m:2wyojpq2]
[*:2wyojpq2]n for a numeric value[/*:m:2wyojpq2]
[*:2wyojpq2]o for an object variable's type[/*:m:2wyojpq2]
[*:2wyojpq2]ot for an objecttype variable[/*:m:2wyojpq2][/list:u:2wyojpq2]
fairly straightforward to remember, and you can always double click the object if you forget.

inside the Get String expression you had {"words"}
in the last lesson we saw several examples of addresses.
this is a simple address, and fairly straightforward.
we will reexplore the syntax of addresses in greater detail in later lessons

for now, lets change our cap a little and make it a true hello world example.
between the action to create the string array, and before you set the text

[list:2wyojpq2][*:2wyojpq2]add an action with s to Add/Overwrite String in Array
[*:2wyojpq2]for the String to Add, choose a string. Try "hello world!"[/*:m:2wyojpq2]
[*:2wyojpq2]for Within which Array choose {"words"}. and don't forget the curly brackets![/*:m:2wyojpq2]
[*:2wyojpq2]for How To Add Choose Insert[/*:m:2wyojpq2]
[*:2wyojpq2]Add/Overwrite where can be left as "end"[/*:m:2wyojpq2][/list:u:2wyojpq2]

Now run cap again.
you should now see that ever so satisfying "hello world!" message.
This means your string container is not empty anymore.
it contains a single string value. Remember though that all containers can hold more than one value if necessary.

return to your cap, and copy/paste the Add/Overwrite String in Array action so you have 2 of them in a row
in the second one however, change the message to "Goodbye World!"
you now have two values in your "words" array

if you run your cap again, it should be no different than the first time.
you will get the value stored at 0 in your array
when you do not specify an index in your address ( {"words"} ):

0 is assumed
you could achieve the same result by changing it to {"words",0}
if you would like to access your goodbye message
set the text to {"words",1}.
try this and run the cap again.

try changing it to {"words",5} and running the cap again
unless you added extra strings yourself, you should get the default value.
any time you try to access an array location that is higher than the size of the array, you will get the default value.

I will introduce briefly some related concepts before closing today's lesson.
The first is the difference between overwrite, and insert.
overwrite does just that, it overwrites the current value at the index specified
insert adds the specified value, and if there is another value already at that index, the old value is pushed forward
so if you had two string values in {"words"}:
[list=0:2wyojpq2][size=50:2wyojpq2]0[/size:2wyojpq2]" beginning"
and you overwrote index 1 in ({"words"}) with the string "middle"
you would still have two string values, but the second would be overwritten with the new value:
and you inserted at index 1 ({"words"}) with "middle"
you would now have:

if you would like to try these in your cap, change the last value in the Add/Overwrite String in Array action from "end" to the numerical index you'd like

when attempting overwriting or inserting at a location higher than the highest index of the array, the array will increase in size, and any intermediate spaces will be filled with the default value, so if your default string was "nothing to see here" and you started with the array:
and you inserted the value "way up there" at index 7 in {"words"}, you would end up with
[size=50:2wyojpq2]2[/size:2wyojpq2]"nothing to see here"
[size=50:2wyojpq2]3[/size:2wyojpq2]"nothing to see here"
[size=50:2wyojpq2]4[/size:2wyojpq2]"nothing to see here"
[size=50:2wyojpq2]5[/size:2wyojpq2]"nothing to see here"
[size=50:2wyojpq2]6[/size:2wyojpq2]"nothing to see here"
[size=50:2wyojpq2]7[/size:2wyojpq2]"way up there"

The last item for today is the "end" string value for the index you saw in the Add/Overwrite String in Array action
open your cap, and double click one of those actions.

the last setting in this action is Add/Overwrite where
it is defaulted to "end". This is the only valid string to insert here. normally you put numerical index values here. "end" is a convenient way of specifying the end of an array without having to retrieve it's size. if you choose to insert at "end", the item will be inserted after the last value in the array, if you overwrite at "end" the item will overwrite the last value in the array.

please feel free to experiment, especially repeating some of this lesson with numbers instead of strings. if you experiment too much you're bound to crash the plugin. :) it is not unstable, but as you can see thus far, it has a very specific syntax. please ask any questions you have. and stay tuned. After we get through the basics, we will begin to explore some of the things you can do with s, and the new level of power and organization it brings to construct.
Spriter Dev
Posts: 3,224
Reputation: 16,254


Return to Construct Classic Discussion

Who is online

Users browsing this forum: No registered users and 3 guests