I feel its best to learn the CS Scripting language by looking through pre-existing scripts, seeing how things work, and learning the ins and outs. But some of the basics of scripting may not be evident from that approach. So for the purpose of this tutorial, I decided to simply touch on the basics, and try to keep things simple.
1.) A scriptname: this names your script. Every script MUST have this at the top.
scriptname MyScript
or, it can be shortened to:
scn MyScript
2.) The declaration of variables that will be used: Creates a place in memory for storage of things that you need to store. There are three types that are used:
Variable types:
short myShortVar
float myFloatVar
ref myRefVar
'Short' variables are used to hold integers. (Examples: 5 or -685)
'Float' variables are used to hold Reals. (Examples: 54.43 or -585.324)
'Ref' (short for Reference) variables are used to hold a pointer to a reference. That is to say, a specific 'object' that has been placed in the game somewhere, NOT an object that can be found in the Object window. When an object is placed in the Render window, what you see is a reference to the object, not the object itself. If that's confusing, just think of it as a copy of the original.
'long' variables are also possible, but [url=http://cs.elderscrolls.com/constwiki/index.php/Variable_types:_longint]this page[/url] in the CS Wiki suggests that there's no practical difference between a long and a float in OB scripting, and I've not seen it used in any OB scripts anyways.
3.) The blocks: only very special scripts do NOT need a block; particularly ones that are only creating a variable for use by something else.
Syntax:
begin GameMode
end
Blocks always start with a 'begin' statement and an 'end' statement. After the 'begin' statement, is the condition, which is checked to see whether or not the code within the block should execute or not. For instance, 'GameMode' executes every time the script is running and there is no menu open, hence, in the actual "Game." There are several block types, including 'OnActivate' 'OnEquip' and 'MenuMode', as well as several others (OnActivate executes when the object it is attached to is activated. OnEquip executes when the object it is attached to is equipped. MenuMode executes while any menu is open). A script can have several blocktypes; that way, it can execute different blocks of code for different situations.
Inside of block statements, which are the "meat" of any script (the part that actually does things), a number of things can occur:
Assigning a value to a variable: This is a simple concept. Supposing you have a variable, then you probably want to store a value in it.
Supposing that I have the variable x, and I assign it the value of 5, then: 4 + x = 9.
Syntax:
set MyShortVariable to 5
set MyFloatVariable to 5.64
set MyRefVariable to MyRefObj
If statements: these are condition checkers. Its the same principal as "If it is sunny, I will go for a walk" except it checks one variable against another. (ie if MyVar > 5; if x == y). If the condition is true, then the code between the if and the endif will run.
If there is an 'else' statement between if and the endif, then it acts as the if's endif, and the code between the else and the endif will run when the if condition is false.
If there is an elseif statement between the if and the endif, then it acts as both an if and an else: it will only execute its code if the previous if (and any previous elseif's) are false, AND its condition is true.
Therefore, for an if block, you can only have 1 if, any number of elseif's, 1 else, and 1 endif.
Syntax:
if
elseif
else
endif
Function Calls: Most functions are self explanatory. Things such as GetDistance or EquipItem are pretty much English, at least more so than you'll find on some forums. Many functions return a number, for use in the script. These numbers can be stored in a variable, or used directly in an if statement.
Syntax
if getDistance player < 500
Message "You are getting close"
endif
set MyFloatVar to GetDistance player
Functions use the object that the script is attached to, unless it is given another reference as its 'caller'. To do this, you simply type the reference you want to call the function from, add a period (.) to it, and then type the function. That means that:
Syntax:
AddItem AgneteKey 1
will add that key to the calling object's inventory (the one the script is attached to). BUT:
Syntax:
player.AddItem AgneteKey 1
will add that key to the player's inventory.
[url=http://cs.elderscrolls.com/constwiki/index.php/Category:Functions]There are several different functions.[/url] However, the trick to functions is not knowing every single one, but knowing where to find out which one to use in certain situations. To that end, [url=http://cs.elderscrolls.com/constwiki/index.php/Category:Function_Types]this page[/url] is exceptionally useful.
I hope this will be useful to someone.
Tutorial by PoHa!
[TUTORIAL] Oblivion Scripting
Moderators: Haplo, Lead Developers