nis_pipeline
NIS Pipeline User’s Guide
\
The game has a built-in preview mode to enable the user to tweak the NIS using a number of special features. The NIS to preview is set using a pair of command line-switches:
/testNIS <nisFile>: specifies what NIS to test.
/testNISScript <scriptFile>: specifies script file to go with NIS.
/noLockout: enables the following keys even while playing the single-player game.
/nisCounter: display nis time index info by default.
\
Here is a quick reference of all the NIS testing keys:
\
-
Camera Release: Toggles between the NIS camera and the standard game camera. This is useful for watching the NIS from an ‘external’ perspective.
-
Pause: Toggles NIS playback pause on/off.
-
Info On/Off: Turns on a display of information such as current time/frame.
-
Start/End NIS: If there is no NIS currently playing, this key starts the test NIS using the position of the currently selected ship as its origin. If there is an NIS playing, this key will stop it.
-
Back 1s: Seeks backward 1 second.
-
Back 10s: Seeks backward 10 seconds.
-
Increase/Decrease speed: Pressing this key will increase playback speed by a factor of 2 (i.e. 2x, 4x, 8x…). Hitting CTRL+0 will decrease playback speed by a factor of 2 (i.e. .5x, .25x, .125x).
-
Normal Speed: Sets playback speed to 1x.
\
Not all the information for an animation can be defined in Lightwave. Some information, such as ships exploding and attacks must be defined in a text file. This script file can be created using any text editor such as SlickEdit.
\
The scripting format is fairly simple. Blocks of events are grouped by ship and by time. Nesting is not permitted. Single-line comments using the C-style // comment delimiter and the assembly-style ; delimiter are supported. Leading spaces are ignored permitting indentation to make the scripts look cleaner. There is no case sensitivity in these scripts. Following is a sample script file. This script has 3 events for 1 ship.
\
//test script file for a test NIS
\
with R2/AttackBomber
{
at frame 20
hide
at frame 25
show
at 2.6
attack R1\ProximitySensor (2)
}
\
Times can be identified by frame number or by the time, in seconds. Both can have fractional parts. A frame time is identified by the “frame” keyword in the “at” statement.
\
Ships are identified using a naming convention similar to Lightwave. That is, they have the name of the .LWO file they came from, plus an optional instance index. This instance index is not needed if the .lwo name is unique within the NIS. The race identifies the race of the ship, or it’s type if it is not a ship. The / and the \ between race and name are interchangeable for convenience. To determine what ship to use, simply run the NIS in testing mode and click on the ship you want to identify. If NIS info printing is on (numlock 6), the name of the ship in that format will be printed.
\
Following is a listing of all scripting commands and their syntax. Any syntax members in <angle brackets> are required. Any syntax in [square brackets] is required. All other text is literal.
with <object name>
Specify what objects to perform events on. Further events will be in . Not all events need an object context. The format of <object name> is as follows:
<type></|\><FileName> [(instance)]
This is similar to the name that would appear in Lightwave, except for the type at the beginning. The forward or back slash can be interchanged. The instance ID is only needed if there are two or more objects from the same <FileName>, is enclosed in parenthesis and is preceded by a space. The <type> will be one of the following:
-
R1,R2,P1,P2,P3,Traders: Standard ship type in on of the 6 standard races. Name will be a ship type. An exception to this is if the <FileName> is Missile. In this case, a missile will be animated instead of a ship.
-
Asteroids: Name will be one of the asteroid types.
-
DustClouds: Name will be one of the dust cloud types.
-
GasClouds, Nebulae: Same as dust clouds. Not likely to be used in an NIS.
-
Derelicts: Name will be the name of a derelict.
-
ETG: Animated effect. Name will be the name of an effect and the .LWS file will specify a dummy .LWO file with the same name as the effect. This type of object is hidden by default and showing will start the effect while ***hide’***ing it will turn the effect off.
-
Misc: For mesh objects not falling into any other categories. Internally, these are treated much like derelicts and hence are not really needed.
\
at [frame] <time>
Specify time of event. Not all events need a time context.
\
*** (braces)***
All events listed in braces will be with the object preceding the braces.
deathDamage
deathProjectile
deathBeam
Causes a ship to explode in one of 3 ways as defined in the ETG scripting files. A ship and a time context are needed.
attack <target>
haltAttack
Start and stop an attack on an object. Ships, derelicts and resources can all be attacked. A ship and a time context are needed.
\
fire
Fires a ship’s weapons once. Ship and time context required.
\
invincible
vincible
By default, NIS ships are invincible. If you want a ship to die due to damage it has received, you can make it “vincible”. Ship and time context required.
soundEvent <eventNum>
speechEvent <eventNum> <parameter> [actor <0..2>]
fleetSpeechEvent <eventNum> <parameter>
Start sound and speech events. The definitions for these events can be found in soundeventdefs.h and speechevent.h. The actor can optionally be explicitly specified. Ship and time context required.
\
startMusic <trackNumber>
stopMusic <fadeOutTime> [FRAMES]
Start and stop music tracks. Time context required.
hide
show
Hides and shows and object. For most object types, it is merely hidden and displayed. For effects, this starts and stops the effect. All objects are visible by default except for effects, which are off by default. Ship and time context required.
\
remainAtEnd
The object will persist after the NIS ends. Ship context required.
\
cameraFOV <degrees>
Adjust the FOV of the camera. Time context required.
\
swapRaces
Swaps the race (R1<->R2) of all ships in the NIS, provided they are one of these races.
\
cameraCut <time> [FRAMES]
Fast-forwards the camera a few frames to preventing visible glitches during sudden motion of the camera. Time context required.
\
fadeSet <fadeLevel>[%]
Instantly sets the fade level. A level of 0 is unfaded while 100% or 1.0 is totally black. Text cards will be displayed on top of a fade-out. Time context required.
\
fadeTo <fadeLevel>[%] <fadeDuration> [FRAMES]
Smoothly fades the scene from the current fade level to the level specified over a specified amount of time. Time context required.
\
centreShip
Specify the ship the NIS will be centred about. This is actually done from the KAS but there may be cases where there is ambiguity as to what ship is the centre ship. In those cases, this directive can resolve the ambiguity. Ship context is required.
\
colorScheme <0..7>
Sets the color scheme for the specified ship or derelict. The specified color scheme should have been enabled using the “AvailableColorSchemes” directive in the .mission file.
Cutting between the game and the NIS has a fairly complex flow that is best illustrated with a diagram. Here's a flow chart of how it all goes down. Time is zero at the top and increases downward.
\
So, the NIS begins when the camera cut begins. However, it will be paused at frame 0 until the end of the camera cut. The widescreen out will usually be at the end of the NIS but can be slightly before it. In any case, it should overlap with the end of the NIS. The game will resume once the widescreen is gone. Since the cut back to the game uses the conventional focus command, the length of this cut cannot be precisely known. The length of the other cuts can be precisely known.
\
Here is a list of the comands specific to these transitions.
cameraBlendIn*<n> [Frames]*
Starts at the beginning of the NIS and blends the camera from it's current position in the game to the camera position at the first frame of the NIS. The NIS will begin after this camera cut. No context required.
\
wideScreenIn*<n> [Frames]*
Starts the widescreen bars dropping and fading in. Begins at the same time as the camera cut. Ends after <n> [Frames]. No context required.
\
at [Frame] <n>
wideScreenOut*<m> [Frames]*
Starts the widescreen bars dropping out. [Frame] n + m [Frames] should exceed the length of the NIS. Time context required.
\
with <ship>
{
at [Frame] 0
focusAtEnd
....
\
Flag the ship to be focussed on at the end of the NIS. If none are specified, the camera will go back to where it was focussed before the NIS began. Multiple ships can be specified for the focus set. Ship and time context required.
\
at [Frame] <n>
**focus
\
Focus on ships flagged as focusAtEnd or on what was selected before the NIS began.
There is a number of functions for displaying text cards in the game. No ship context is required. For most of these events, no time context is required, but they effect text card events below them in the script file.
\
textFont <fontFileName>
Specify the font for upcoming text cards. No context required. Look in data\fonts\English for suitable names.
\
textColor <red>,<green>,<blue>
Specify the color of upcoming text cards. No context required.
\
textPosition <x>,<y>
Specify the location of the top-left corner of upcoming text cards. If multiple text cards are specified with a single textPosition directive, they will flow like a paragraph and wrap at the edge of the screen. Also, the usage of #n in the text string will act as a newline character. No context required.
\
textMargin <x>
Specify the text-wrapping margin of upcoming text cards. This will be used in strings long enough to wrap around at the edge of the screen or with newline characters. No context required.
\
textDuration <time> [FRAMES]
Specify how long upcoming text cards will last. No context required.
\
textScroll <distance> [FRAMES]
Causes all visible text to scroll a given distance vertically over a given amount of time. The distance respects sign so to scroll up, a negative distance will be required. Note that this scroll will effect the y coordinate of all current text cards and all future text cards. Time context required.
\
textFadeIn <time> [FRAMES]
textFadeIn <time> [FRAMES]
Causes the text to fade in and out smoothly. By default these values are 0, meaning no fade at all. No context required.
\
textCard <stringName>
Creates a text string. The string is a named string from the localization script files. The name of these strings is of the following format: n<NIS Number>Str<String number>. There are a number of strings pre-defined for each NIS already. For example, n01Str05 would be a string name. The actual strings cannot be specified in the NIS’s .sc file because they have to be localized.
Mesh animations are triggered from the .sc file rather than animated directly in the NIS.
\
meshAnimStart <animationName>
Start an animation. The name of the animation can be found in the scene file that defines the animations (usually the top LOD of that ship). Ship and time context required.
\
meshAnimStop
Stop any currently playing animation. Ship and time context required.
\
meshAnimPause
Pause/unpauses any currently playing animation. Ship and time context required.
\
meshAnimSeek time [FRAMES]
Fast-forwards the animation by a specified amount. Ship and time context required.
\
blendCameraToFocus
Modifies the last camera keyframe such that it will be positioned perfectly for a focus at the end of the NIS. This should be called when the ships to be focussed on are positioned where they will be at the end of the NIS and about 1 second before the last camera keyframe is reached. The last camera keyframe should be pointing in roughly the correct direction with this function merely doing some fine-tuning. The camera will only be moved; it will not be rotated. Time context required.
\
musicVolume <0..1>
Set the music volume. Volume will be reset at the end of the NIS. Time context required.
\
Set the speech volume. Volume will be reset at the end of the NIS. Time context required.
\
Set the sound effects volume. Volume will be reset at the end of the NIS. Time context required.
\
trailMove
Moves a ship’s trail(s) in preparation for a “position cheat” of that ship. The amount to move will be determined by 2 keyframes less than ¼ second apart immediately following the time of this event. The trail will only be translated as per these keyframes; it will not be rotated. Ship and time contexts required.
\
trailZero
Zeros out a ship’s engine trail(s). Ship and time context required.
\
pauseUniverseToggle
Toggle the pausing of everything in the universe that is not an NIS – animated object. Should always be used in pairs so that it is off at the end of the NIS. Time context required.
\
hideUniverseToggle
Toggle the visibility of non-NIS objects. Should always be used in pairs so that everything is visible at the end of an NIS. Time context required.
\
environment <EnvironmentName>
Load in a new background and lighting as per the name specified. Do not include the path or extension to the environment files and they must match names (such as BTG\Ez01.btg and hsf\ez01.HSF. Time context required.
\
midPointLookAt
For a 3-point camera blend in, this function determines what direction the camera will be looking at the midpoint of the camera zoom. Object context required.
\
Turn on or the SMPT timer simulation starting at a specified time, in a specified on-screen location, using an optional color and font. Time context required.
\
Turn off the SMPT timer simulation. Time context required.
\
staticOn <staticIndex, nLines, nLinesVariation, width, widthVariation, y, yVariation[, hue, hueVariation, lum, lumVariation, sat, satVariation, alpha, alphaVariation]>
Turn on static. There are many parameters, some of which are optional. The staticIndex is an index into an array of static structures. Time context required.
\
staticOff
Turn a specified static index off. Time context required.
\
hideDerelict <derelictType>
Hides all derelicts of a specified type. Time context required.
\
showDerelict <derelictType>
Shows all hidden derelicts of a specified type. Time context required.
\
newNIS <nisName>
Starts a new NIS. This can be used to connect several NIS’s together. Time context required.
\
attributes <attribs>
Sets the attributes member of a ship that will remainAtEnd. Ship and time context required.
\
nisAttackKasSelectionSet <selection>
Attack a KAS team of ships. This is the only way to get NIS ships to attack ships that are not part of the NIS. This is useful for ships that will remainAtEnd. Ship and time context required.
\
keepMovingAtEnd
By default, NIS objects will come to a cold, screeching halt at the end of an NIS. This function allows them to retain their velocity vector as the NIS ends. Useful for ships that will remainAtEnd. Ship context required.
\
numberLODs <n>
It is sometimes useful to lock the LOD of a ship to a particular level so as not to disturb the continuity of closeups and fly-bys. This is a way to do it. numberLODs 1 will lock it to the maximum LOD. Note that this will affect all ships of the specified type and it must be ‘manually” reset at the end of an NIS to the number of LOD’s in the .LOD file. This function should be used with caution. We’ve implemented LOD’s for a good reason – to keep frame rate reasonable. This function grants the power to undermine that work. Ship and time context required.
\
health <health[%]>
Set the health of a ship. This is related to the vincible command except that it does not restore the ship to full health; it sets it to a percentage of full health. This is useful to make ships look damaged in NIS’s. Note that if there are ships attacking during the NIS, this function can be dangerous. It is possible that the NIS ship would die of “natural causes” causing a crash. If the specified ship is to remainAtEnd, it’s health will be set to 100% at the end of the NIS. Ship and time context required.
\
NIS’s are built using the LWExport tool. This is the same tool as is used for exporting meshes, lights and .mex files. The syntax is: lwexport -+<.lws file> -=<.nis file>. The .nis extension is important. The extension determines what type of file to export. A proper makeNIS pipeline will come along soon. For now this should be sufficient with you trusty 4NT command shell.
\
\