This is a scripting guide for MWSE by Yacoby. Permission was granted by Yacoby to put the guide here on this wiki.
The original PDF version is available for download at these links.
ForwardEdit
This guide was written for the purpose of getting people to start scripting with Morrowind Script Extender. It is a wonderful thing, but it can seem hard to make the first leap. I hope people who read this find it easier to make that leap.
This isn't finished. It is nowhere near finished, so if anyone has anything that they would consider adding, just drop me a note.
I would like to thank the MWSE development team, for writing MWSE, and especially Fliggerty, for the feedback and scripts he provided.
Happy Scripting
~Yacoby
IntroductionEdit
What is MWSE?Edit
Morrowind Script Extender (MWSE for short) does what is says on the tin. It extends the number of functions available for use by modders.
For example, using the default scripting language, there is no way to change an objects name. However, if we add MWSE into the mix, all you have to do is use the xSetName function.
It makes things possible that are impossible or very hard with the vanilla scripting engine.
MWSE doesn't require a fast computer to run, in fact, when running MWSE on my old computer (1.6 GHz CPU, 16Mb Gefore4 MX Graphics card, 256Mb of RAM) I didn't notice any drop in my frames per second when running MWSE.
How do I run MWSE?Edit
To allow MWSE functions and mods to work, you need to have MWSE running in the background while you run Morrowind.
The most recent version of MWSE can be downloaded from here:
http://sourceforge.net/projects/mwse
With the most current version of MWSE, (0.9.4a) you need to run MWSE Launcher.exe to run MWSE. However, as things change, always check the readme included with your version of MWSE.
How do I start scripting with MWSE?Edit
The first thing you need to know is how to write basic Morrowind scripts. This document assumes that you at least know what if blocks are.
If you don't know how to script yet, I suggest you look at Morrowind Scripting for Dummies, which can be found at places like
[1]
Make sure you get version 8 or version 9. Unfortunately, you can still find version 5 on a lot of places.
When you make a MWSE mod, you can do it in exactly the same way as you would a normal mod. There is, however, one thing that you cannot do, and that is compile scripts using MWSE functions in the Construction Set (CS).
This means that we need to use another editor called MWEdit to write MWSE scripts. Although MWEdit is far better than the CS in some respects, it cannot edit cells, and I wouldn't advise writing dialog with it.
This means that in most cases, you will still need to use the CS, as well as MWEdit, to make your mod, so to make sure I get my point across:
You can edit a MWSE mod in the CS, as long as you don't edit any scripts containing MWSE functions.
MWEdit can be downloaded from here:
http://sourceforge.net/projects/mwedit
Installing MWEdit is an easy matter. All you need to do is extract the files to a location of your choice and run MWEdit.exe
As soon as you start MWEdit, you will notice that the layout is far different from the CS, but once you get used to it, you will wish the CS had MWEdits layout. Trust me on this.
FAQEdit
(By Fliggerty, edited by Yacoby)
- Is it stable? - MWSE itself is quite stable. Many people claim that they experience fewer CTDs while using MWSE. However, as with anything involved with Morrowind, it seems that depending on your hardware/software configuration, it may not run very well.
- Does it eat resources? - While playing the game, MWSE.exe rarely uses up to 4% of the CPU. The most memory I have ever seen it use is 1.6Mb. Upon initial load, before Morrowind starts, it is not uncommon to see it momentarily use 100% of the CPU.
- Can it work with other external programs? - Yes, in most cases. MGE has a built-in version of MWSE that is equivalent to v0.9.2 or 0.9.3 (Depending on which version of MGE you use). MWSE and MWE are also compatible. However, some people have reported that they will not run together at all. This seems to be system dependent. There are also no known issues using both MWSE and the FPS Optimizer.
- If so, how to configure?
- MWE: If you use MWE to autolaunch Morrowind, change the path in "Autolaunch Morrowind" to point to MWSE Launcher.exe rather than Morrowind Launcher.exe.
- FPS Opt: No configuration required.
- MGE 3.0.3: MWSE 0.9.4a is incompatible with MGE 3.0.3. If you want to use MGE mods, use MGEs internal version (0.9.2)
- MGE 3.3.2: MWSE 0.9.4a is incompatible with MGE 3.0.3. If you want to use MGE mods, use MGEs internal version (0.9.3)
- MWE: If you use MWE to autolaunch Morrowind, change the path in "Autolaunch Morrowind" to point to MWSE Launcher.exe rather than Morrowind Launcher.exe.
- Are there longer loading times and/or reduced fps? - There are often longer loading times. MWSE scans all scripts when loading the game. This is necessary to determine which scripts contain MWSE functions. Depending on how script-intensive your mods are, this delay may be rather long. As with any mod, if it runs a lot of scripts, an MWSE mod may cause an FPS hit. But any such effect from MWSE itself is not noticeable.
- Is there spyware? - No. There is no code that will intentionally do anything harmful to your computer. If you don't trust me, you can download the source and see for yourself.
- I can't install it! - Extract MWSE anywhere, it doesn't need to be in the Morrowind directory.
- Why isn't it working? - Ensure that you are running Bloodmoon v1.6.1820 (If you use GOTY, you don't need to patch it). You can get the patch here: http://www.elderscrolls.com/downloads/updates_patches.htm. Make sure you have the latest version of MWSE.
- Will it work with a no-cd patch? - Yes. It seems you have to have the proper one though. I use this one: http://www.gameburnworld.com/dl/dl.php?file=MorrowindBloodmoonv1.6.1820NoCDFixedexeEng.rar
Quickstart GuideEdit
Happy to jump in, ignoring the tutorials? This is the section for you. As much information packed into as little text as possible. When you have read this, you will need to look over the function list to get an idea of what functions are possible.
VariablesEdit
Types of MWSE VariablesEdit
The MWSE functions make use of two new variable types, string and reference. Both are actually declared in the scripts using the "long" type.
The ref, reference, variables provide a way to keep track of specific objects in the game world. They are most commonly used on the left side of the -> operator with other functions (new or old) to affect that object.
Long temp
Long var
Setx var to xGetRef, "Player"
;the variable var is now a ref, pointing to the player
Var->xItem, "Gold_001", 2
Setx var to xStringBuild, "Happy"
;the variable var is now a string
Setx temp to xStringComapre, var, "Sad"
If ( temp == 0 )
Messagebox, "Someone is sad"
endif
All string and ref information is lost when Morrowind is closed.
Using setxEdit
Unfortunately, the new functions can't be easily integrated with the standard script functions and commands. A 'setx' command is provided as a substitute for 'set' when you are using a new function. You can only put one function or one string value on the right side of 'setx' but it does allow more than one variable on the left for functions like 'xInventory' that return multiple values.
The MWEdit compiler doesn't do any error checking on the number of variables on the left hand side, so don't get it wrong.
A normal Morrowind function using set
Set health to GetHealth
A MWSE function using setx
Setx pcCell to xPCCellID
Multiple returns using setx
setx invitem,invcount,invref to pcref->xInventory
Testing ConditionsEdit
Ifx, Whilex conditionsEdit
The standard Morrowind script if and while commands do not work when the body of the block contains extended commands, instead use ifx and whilex.
The ifx and whilex do not currently support a full syntax, it doesn't compile if a function is used in the ifx statement itself
Ifx ( getHealth ) ;bad
Float tmp
Set tmp to getHealth
Ifx ( tmp ) ;good
The ifx/whilex block will be performed if the value is not zero. You can use 'else' with 'ifx' but not 'elseif' and there isn't an 'elseifx'.
If you have a multiple stage if/elseif section it's frequently possible to isolate the new functions to only one or two sections, so check all of the others first then use statements like the following.
| Old Version | New Version |
|---|---|
if ( state == 5 )
else
endif |
set temp to ( state - 5 ) ifx ( temp )
else
endif |
It's OK to leave the first section blank, so this also works:
| Old Version | New Version |
|---|---|
if ( state == 5 )
endif |
set temp to ( state - 5 ) ifx ( temp )
endif |
This makes some scripts very messy. If you have a lot of if statements that results in a single block of code either being executed or skipped, sometimes it is easier to do something like this, rather than a load of complex ifx blocks.
Set temp to 0
if ( player->getHealth > 0 )
if ( state == 5 )
if ( player->getLevel == 25 )
Set temp to 1
endif
endif
endif
ifx ( temp )
;do extended functions here
endif
Also be careful with reference variables.
long NPCref
short state
Setx NPCref to xFirstNPC
if ( state != 0 )
NPCref->startscript myscript ; this will not work
endif
ifx ( state )
NPCref->startscript myscript ; this will work
endif
Data LossEdit
When you exit and reload Morrowind, all string and ref variables become invalid.
Tutorial OneEdit
Open up MWEdit, and click OK to the warning screen that comes up. Don't disregard what it says though; it is always worth backing up a plugin once every few days.
Press the "New" button (The one that looks like a white piece of paper).
Scroll down the left hand list box till you find an item that says "Script". Click on it. Now in the larger right hand box, right click and press "Add New" and a new script dialog should come up.
We are going to write a small script that will tell the player what cell he or she is in.
Start the script
Begin My_First_MWSE_Script End My_First_MWSE_Script
The first thing we need to do is find and store the cell that the player is in. So we look at the MWSE function reference (at the end of this document) and find:
cellid (string): xPCCellID
- Returns a string containing the name of the current cell.
Which all looks rather confusing.
- cellid is what is returned, basically the name of the cell the player is in
- (string) is the type of the object that is retuned.
- xPCCellID is the function name
So what is a string I hear you say. A string is a collection of characters; "Hello World!", "I am 354 years old" and "a" are all examples of strings. A string must always be surrounded by quotes.
MWSE cheats a bit with strings, rather than have a new String variable type, it uses the Long variable type.
So next thing we need to do is add the variable to hold the players cell.
Begin My_First_MWSE_Script ; stores the cell the player is in Long playersCell End My_First_MWSE_Script
Then, we need to set the variable to the players cell.
One important thing about MWSE functions is that rather than use the set function, you need to use the setx function.
So with a normal function, you would use set:
Set myHealth to getHealth
With a MWSE function, you would use setx:
Setx myCell to xPCCellID
Bearing this in mind, we will store the player's cell in the "playersCell" variable:
Begin My_First_MWSE_Script ; stores the cell the player is in Long playersCell ; make the variable hold the players cell Setx playersCell to xPCCellID End My_First_MWSE_Script
Now, you may have noticed that this doesn't actual do anything, so we need to output the players cell using the messageBox function.
Unfortunately, you cannot output MWSE strings in normal messageboxs, but luckily there is a fix, xMessageFix to be precise. If we look at xMessageFix in the MWSE function reference, we find quite a lot of information. However, not that much of it is useful here, as all we want to do is display a string, not use choices.
Take a look at the xStringBuild function, you will see that the arguments are exactly the same as xMessageFix, for the purpose of formatting messages; xMessageFix and xStringBuild are exactly the same.
The most important thing to remember about xMessageFix is that it must be followed by a messagebox, and the length of the message in the messagebox must be longer than the length of the message in xMessageFix
xMessageFix message_format (string), ...
The first argument for the xMessageFix function is the message format, the second, third, forth are the variables defined in the message_format argument. (They can also be choices.)
What we want to do is display "You are in CellName" in a messagebox.
%s is used by the xMessageFix function to insert a string into a message. As we have two strings, we would use two %s in the format argument:
xMessageFix, "%s%s", "You are in ", playersCell Messagebox, "ThisJustFillsTheMessageboxUpWithRandomJunk.ThisWillBeReplaced"
However, there is a slightly tidier way of doing things, as we don't just have to put references to strings in the format box:
xMessageFix, "You are in %s", playersCell Messagebox, "ThisJustFillsTheMessageboxUpWithRandomJunk.ThisWillBeReplaced"
So integrating this into the main script, and we get:
Begin My_First_MWSE_Script ; stores the cell the player is in Long playersCell ; make the variable hold the players cell Setx playersCell to xPCCellID ; tell the player what cell he or she is in xMessageFix, "You are in %s", playersCell Messagebox, "abcdefghijklmnopqrstuvqxyz0123456789abcdefghijk" End My_First_MWSE_Script
You may have noticed that the script will just contiusly output the message, so after the messagebox, we need to stop the script:
Begin My_First_MWSE_Script ; stores the cell the player is in Long playersCell ; make the variable hold the players cell Setx playersCell to xPCCellID ; tell the player what cell he or she is in xMessageFix, "You are in %s", playersCell Messagebox, "abcdefghijklmnopqrstuvqxyz0123456789abcdefghijk" stopScript, My_First_MWSE_Script End My_First_MWSE_Script
Now press the compile button in the script editor. It should compile without any errors. If you get an error about "My_First_MWSE_Script" being an invalid object, you need to save the script so that it exists in the esp, open it again and then try and compile it.
Now give the script a test in game (don't forget to start MWSE as well).
Tutorial TwoEdit
In this next script, we are going to make a script that when you look at an NPC, it will shrink it, and when you look at a creature it will make it grow in size.
The first thing we need to do is get the target of what the player is looking at:
Begin rescale_script Long pcTarget End rescale_script
The function xGetPCTarget returns the id of the object that the player is looking at. It will only get the target of objects where the name box shows up, so it doesn't work getting the target of things that are in combat with you.
If there is no target, it will return 0:
Begin rescale_script
Long pcTarget
Setx pcTarget to xGetPCTarget
if ( pcTarget == 0 ) ; nothing targeted
Return
Endif
End rescale_script
The variable pcTarget now holds a reference to the players target. So with extended functions, we can use the -> operator and the variable.
Next we need to work out what type of object the player is looking at. For this we need to use the xRefType function. xRefType returns a different set of numbers depending on the object type. If the object is a creature, it returns 1095062083, and if it is an NPC, it returns 1598246990.
To hold the number we are going to create a new variable called temp, which we will use to store the number. We will also create a variable to say if it is a creature or not, because this variable will be 0 or 1, we can use it very easily with the ifx command:
Begin rescale_script
Long pcTarget
Setx pcTarget to xGetPCTarget
if ( pcTarget == 0 ) ; nothing targeted
Return
Endif
Long temp
Setx temp to pcTarget->xRefType
Short isNPC
if ( temp == 1598246990 ) ; it is an NPC
Set isNPC to 1
Elseif ( temp == 1598246990 ) ; it is a creature
Set isNPC to 0
Else ; we don't want to rescale other objects, so return
Return
Endif
End rescale_script
So, to recap, we now have a variable that tells us if it is a creature or a NPC. If it is anything else, we have used the return function so it won't be executing this part of the script. We also have a variable holding a reference to the object the player is looking at.
What we next need to check is the object hasn't already been scaled. (Changing the scale of an object is a very expensive operation for the game engine to do).
Unfortunately, we cannot use the -> operator with a ref variable and a standard function (any function that doesn't use setx):
Set temp to pcTarget->getScale ; Doesn't Work
Fortunately there is a workaround; xSetRef. xSetRef makes the next function called apply to the ref argument given to xSetRef.
This code:
xSetRef, pcTarget
set temp to getScale
Does exactly the same thing as this code does:
Set temp to pcTarget->getScale
Except it works.
So we need to add what we have learnt into the script:
Begin rescale_script
Long pcTarget
Setx pcTarget to xGetPCTarget
If ( pcTarget == 0 ) ; nothing targeted
Return
Endif
Long temp
Setx temp to pcTarget->xRefType
Short isNPC
If ( temp == 1598246990 ) ; it is an NPC
Set isNPC to 1
Elseif ( temp == 1598246990 ) ; it is a creature
Set isNPC to 0
Else ; we don't want to rescale other objects, so return
Return
Endif
; get the scale
xSetRef, pcTarget
set temp to getScale
; if the scale is not 1, it has already been changed, so we don't need to change it again
if ( temp != 1 )
return
endif
End rescale_script
At this point in the script, we know we need to rescale the object, but we need to decide if we need to increase the size (for creatures) or decrease the size (NPCs).
Unfortunately, you cannot use extended functions within normal if blocks, you have to use the new ifx blocks. The ifx blocks have several disadvantages, the main one being that they don't do any of the more complex checking that the normal if blocks have. It will execute the block if the value in the ifx is true (anything other than 0), other wise it skips it.
There is more about ifx and whilex MWSE Quickstart guide.
As we have a variable that holds whether it is an NPC or not in a single 1 or 0 variable, it will be very easy to implement:
Begin rescale_script
Long pcTarget
Setx pcTarget to xGetPCTarget
If ( pcTarget == 0 ) ; nothing targeted
Return
Endif
Long temp
Setx temp to pcTarget->xRefType
Short isNPC
If ( temp == 1598246990 ) ; it is an NPC
Set isNPC to 1
Elseif ( temp == 1598246990 ) ; it is a creature
Set isNPC to 0
Else ; we don't want to rescale other objects, so return
Return
Endif
; get the scale
xSetRef, pcTarget
set temp to getScale
; if the scale is not 1, it has already been changed, so we don't need to change it again
if ( temp != 1 )
return
endif
ifx ( isNPC )
xSetRef, pcTarget
setScale, 0.5
else ; it is not an NPC, so it must be a creature
xSetRef, pcTarget
setScale, 1.5
endif
End rescale_script
The last thing we need to do is add some simple optimization. As this script will not need to be run when there are is a menu open, we can make it skip executing the script when there is a menu open by adding this to the top of the script:
If ( MenuMode )
Return
Endif
Tips and TricksEdit
Storing Cell/Position DataEdit
As you know, all string data is lost when Morrowind stops running. If you want to store a cell ID, how do you do it?
If you know how many positions need to be stored, one solution is to use disabled NPCs or Creatures. Place them in the position that you need to be stored. You can later retrieve the information via xGetRef, then using getPos, and xMyCellID.
Pros:
The data is stored in the save, so it is unique to that save.
Cons:
You have to know how many positions need to be stored, and create an NPC for every position.
Another method is to write the data to another file. You could, in theory, store an infinite number of locations. However, the problem comes making sure the data is unique to every save. You could just include the PC name in the file name, but then what would happen if you had to players with the same name? When you went back to a previous save? You would have to include enough unique data in the file name that the file name was unique. You could, for example, use the cell name and the players name, and rewrite the data every time the player changed cell.
Pros:
Can store an unlimited amount of data.
Cons:
You need to use a lot of information from the player to make sure the file is unique. As there is no delete function the MWSE directory may end up getting full of unneeded files.
Sending Data to other applications (Programmers only)Edit
(By CDCooley)
// 2005-07-13 CDC This is a very simplistic example for creating a named pipe.
// The MSDN documention for CreateNamedPipe gives a multi-threaded demonstration.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <windows.h>
#define BUFSIZE 4096
int main(){
HANDLE pipe;
DWORD size, i;
CHAR buffer[BUFSIZE+1];
//From Morrowind, this pipe is called demo1
pipe = CreateNamedPipe("\\\\.\\pipe\\MWSEdemo1",
PIPE_ACCESS_DUPLEX, PIPE_TYPE_MESSAGE |
PIPE_READMODE_MESSAGE | PIPE_WAIT,
PIPE_UNLIMITED_INSTANCES, BUFSIZE, BUFSIZE, 20000, NULL);
while ( (pipe != INVALID_HANDLE_VALUE) &&
( ConnectNamedPipe(pipe, NULL) ||
(GetLastError() == ERROR_PIPE_CONNECTED) ) ){
// A simple echo server
while (true){
if (!ReadFile( pipe, buffer, BUFSIZE, &size, NULL) || (size == 0) ) break;
buffer[size] = 0; // ensure it's null terminated in case it's a string
printf("Request as float=%f as long=%d as string=%s\n",*((float*)buffer),*((long*)buffer), buffer) && fflush(stdout);
if ( !WriteFile(pipe, buffer, size, &i, NULL)
|| (i != size) ) break;
}
FlushFileBuffers(pipe);
DisconnectNamedPipe(pipe);
}
CloseHandle(pipe);
return 0;
}
begin mwse_pipeexample
long count
long numread
float sent
float received
if ( MenuMode == 1 )
return
endif
ifx ( count )
xFileWriteFloat "|demo1" sent
set received to 0.0
setx numread received to xFileReadFloat "|demo1" 1
if ( numread < 1 )
MessageBox "I sent %f, but the server didn't respond! Maybe it's just slow. Or maybe it's not running." sent "OK"
else
MessageBox "I sent %f and received %f." sent received "OK"
endif
set sent to ( sent * sent )
set count to ( count - 1 )
if ( count == 0 )
StopScript mwse_pipeexample
endif
else
set sent to 3.14159
set count to 5
endif
end
MWSE Function ReferenceEdit
-
- Main article: Functions
MWSE adds a total of 98 new functions to Morrowind's scripting language. These range from wrappers, to brand new functions, from adding new mathematical functions, to adding file I/O.