ShockEd: An Introduction to Scripts

[6633eda994952Nameless Voice]

Tags: °SS2 °tutorialAn Introduction to Scripts
A script in Dark is a piece of code that is placed on an object to do something when certain things happen to that object.
Scripts are stored in script modules (.osm files), which are basically a library of classes and functions written in C++ and compiled into a dynamic-linked library (.dll). You need to load the script module file into your mission (using the script_load command) before you can use any of the scripts that it contains. All players must also have this script module for the scripts to work. You can either include the script module in your misssion .zip, or instruct players that they need to have it installed in order to play the mission.

Scripts are placed on objects via the S->Scripts property.

Scripts are basically event handlers for events created by the game or by other scripts. Event handling in Dark works by means of script messages – special messages that are sent to objects by the engine when certain events occur. An example of this would be the FrobWorldEnd message, which is sent to an object when the player frobs that object in the world*.

Whenever an object receives a script message, it is passed to each script on the object in turn, starting from the script named in the Script 0 box on the object, then on through to Script 3, and then – unless the Don’t Inherit flag is set – it will go backwards up the inheritance tree until it reaches the base Object (-1), or encounters a script property that does have the Don’t Inherit flag set.
Each of these scripts can then react to this message in whatever way they wish.

The Dark Engine exposes a set of functions that scripts are able to use to interact with the game world, such as retrieving or setting properties, creating and destroying objects or links, sending script messages, starting timers, and so on. While most of these systems are fairly versatile, the scripts are still limited in that they can only interact with the game world via the systems that Dark exposes for them. While custom scripts can do anything and everything that the standard scripts do, bear in mind that in some cases the engine may only allow them to do the exact same thing, rather than to do it slightly differently. An example of this would be the bow-drawing function. Basically, the arrow script tells the engine "Bring out the bow and use this object as an arrow". A script couldn’t, for example, create its own type of weapon (say, a crossbow) for the arrow to be equipped in, since the engine handles the entire process of player arm creation and bow control. All the script can do is to tell it to equip an arrow.
Of course, scripts can also do anything else you would expect a program to be able to do, such as perform calculations and logic on property values and then modifying them as a result.

A very important point is that scripts can send messages to other objects. For example, the StdButton script will send the message TurnOn down its SwitchLink links to any linked object. A lot of the standard scripts will respond to the TurnOn message by activating themselves – for example, a door (StdDoor) will open, a light (AnimLight) will turn on, and an emittertrap (TrapTweqEmit) will fire. Many of these scripts will also respond to the TurnOff message by deactivating.
There is no special meaning to these two messages (TurnOn and TurnOff) – rather, they are a standard interface that was used by Looking Glass when the made the scripts. Technically, the messages could as easily have been named Bob and James, and as long as all the scripts were written to work with these messages instead, it would have made no difference (though it would have been very messy and unintuitive). A script can use whatever script messages it pleases, though there will also need to be a script listening for that message (it can be the same script) for it to be useful.

The SwitchLink link flavour also has no special meaning in the engine, other than that it is the standard method for a triggering script (like a button) to send messages to other objects. The Thief version of Dark uses the flavour ControlDevice instead of SwitchLink, and it makes no difference. However, while you can use any name you please as script messages, you can’t add new link flavours to Dark – you are limited to the ones that are hard-coded into DromEd.

With a fair number of my scripts (the ‘NVTrap’ and ‘NVTrigger’ scripts), I have allowed you to choose which messages they should listen for and send, and where to send them to, via Objlist Args parameters. While most of them default to the standard ‘TurnOn/TurnOff via SwitchLink’ system, you can use whatever messages or destinations you like. An example of this would be to have my NVOnscreenText script set up to trigger when the player frobs its object, by setting it to listen for FrobWorldEnd (for this script, this would be done by adding NVOnscreenTextOn="FrobWorldEnd" to its Objlist Args property). Another example might be to have my NVTrigQVar script send a Toggle message to objects down Owns links instead of TurnOn down SwitchLink links (in this case, NVTrigQVarTOn="Toggle"; NVTrigQVarTDest="&Owns").

The concept of objlist args parameters could probably use some explanation.
(You will also find these referred to as "Design Note parameters", as that is the property used in the Thief version of DromEd.)
Since it is obviously useful for the mission designer to be able to control the scripts on an object, rather than the scriptwriter having to rewrite them for every situation, the scripts need some DromEd property which the designer can use to configure them. Most of the properties in Dark already have a purpose, but the Script->Objlist Args doesn’t really have one, plus it’s a very long field that can store a lot of text (was it 65536 characters?). As such, it is an ideal place for scripts to store their extra configuration settings. Settings are written as parameters separated by semicolons, in the following format:

Code: [Select]

ParameterName1=Value2;
Where ParameterName is the name of the parameter that the script uses (and is dependant on each script), and Value is the value that the designer wants to set the parameter to. There does not need to be a semicolon after the last parameter.
It is important to note that strings (text values) must be enclosed in double-quotes, like this:

Code: [Select]

TextParameter="Some text"
Numerical values should not include these quotes:

Code: [Select]

NumericalParameter=5

Many of the messages that are sent to objects by the game engine have extra information associated with them. For example, the FrobWorldEnd message gives the object id of the frobber, the Alertness message gives the level of alertness that the AI has reached and the previous level of alertness the AI had before, and so on. Scripts can use this information if they wish.



* (Technically, the object must have Script set in the World Action section of its Engine Features->Frob Info property for this message to be sent. Also, if the player holds down the Frob button on the object, the message is only sent when the button is released. The game also sends FrobWorldBegin when the player first begins frobbing the object.)

[6633eda994d2eEnchantermon]

Nice tutorial.

[6633eda994e4eZygo]

NV, you may want to note the Editor-> Design Note to Script->Objlist arg switch for SS2 above.

[6633eda994f34Nameless Voice]

Good point.  I thought I'd done that already.

[6633eda99508eZylonBane]

It is possible to create a crossbow by using custom models and motions though, yes?

[6633eda9951a0Nameless Voice]

That's a bit out of nowhere, but yes.  Especially so in SS2 with its guns, where you can use simple jointed gun objects instead of having to worry with meshes and motions.

[6633eda99527eZylonBane]

Well, you use a crossbow above as an example of something you can't do.

[6633eda995385Nameless Voice]

Oh, so I do.
Yes, that tutorial was obviously written for Thief 2.

I'll see if I can think of a more SS2-oriented example.

[6633eda995483Zygo]

I'd say the crossbow example is fine really, the animation system in SS2 is still too limited to be able to make one even if more simple things are practical. I don't think you can even get anything other than straight translation to work using the built in system.

[6633eda995592Nameless Voice]

The example of equipping a bow arm doesn't make sense, though.  There's no bow in SS2.

You can make an object with rotating joints, though.  Not a mesh, just a simple object with IK joints.

[6633eda995683Zygo]

You have to use 'trickery' to get rotation working for an "in hand" object though, yes? The  Gun Anim Post/Pre (built in system) works only with translations like the slider for the pistol/ pump for the shotgun?

[6633eda995750Nameless Voice]

Yes.

[6633eda995828lostone1993]

any chance you can open up the scripts in a program like visual basic express, to have a look ?

[6633eda99592aZylonBane]

F*** me, seriously? You bump a nearly two-year-old thread to offer up your genius suggestion to apply smegging VISUAL BASIC to this?

[6633eda995ab8Kolya]

We intentionally have no thread necromancy warning here, because threads like this should always stay open for questions, etc.

lostone, if you read the start of the first post, NV said that the scripts are written in C++ and compiled into DLLs. So Visual Basic Express won't help you here. Basically you'll need the source of a script to see what it does.

[6633eda995bd5StaticZ]

Hi very intersting article. But are any code examples? All i can see is single fuction ScriptModuleInit in export section. What type of decloration must be stdcall\cdecl\fastcall? As i rember the default name conversation translate STD func name in export table as _func@argsize, so if it's really stdcall it's args size is 20 bytes, so what it is? I think it must have some pointer to scripts name's and there pointers and smth else, but it's quite hard to guess all this.

[6633eda995d36StaticZ]

OK I found some script sources here: http://www.whoopdedo.org/projects.php?scripts

Thow it seems they are more for thief it seems quiet simlar:

Code: [Select]

extern "C"
int __declspec(dllexport) __stdcall
ScriptModuleInit (const char* pszName,
                  IScriptMan* pScriptMan,
                  MPrintfProc pfnMPrintf,
                  IMalloc* pMalloc,
                  IScriptModule** pOutInterface)