Cabal Common Library Doc Briefing

Overview

This is the main class for the briefing with its members and part of the Cabal_Common_Library.

The script handles incoming data from worldScripts to make missionscreens a bit more interesting with time based animations of the displayed model. Scripts can pass the data easily and everything else is performed within the briefing script.

	worldScripts.Cabal_Common_Briefing.startBriefing(obj);

A second approach is possible by instantiating a copy of the underlaying API, e.g.

	this.helper = new worldScripts.Cabal_Common_Functions.Cabal_Common_ScreenFCB();

But scripts are then responsible to remove the framecallbacks on their own with the method provided by the API!

Versions before v1.6 have used this.myHelper = new Cabal_Common_2DCollision();

Functions

startBriefing()

	worldScripts.Cabal_Common_Briefing.startBriefing = function( obj )

Calling this method starts the handling. The passed obj must hold a few parameters to define the actions.

Parameters:

obj

Object.

Returns:

nothing

Properties of obj:

absolutePos

Array. Optional. E.g. [10,12,540].

background

String. Optional. Filename with extension.

briefing

Array. Required. Action commands.

callback

String. Required. WorldScript identifier.

callbackc

String. Optional. Mission choice.

callbackf

String. Required. Callback function.

capture

Boolean. If true only a new briefing, callback and callbackf gets established.

cornerPos

Array. Optional. Movement to one corner. E.g. [0.33,1,1,1.3]

fadeIn

Boolean. Optional. If true overlay images will be used to simulate a fade in. (New in v1.6.1)

getOri

String. Optional. script_info keyname that holds orientation, e.g. "1,0,0,0".

getPos

String. Optional. script_info keyname that holds position, e.g. "0,0,300".

music

String. Optional. Filename with extension.

ori

Array. Optional. Orientation. E.g. [1,0,0,0].

overlay

String. Optional. Filename with extension. Defaults to "bgs-i_overlay_none.png" if BGS-A or BGS-I installed.

prepareBindings

Array. Optional. Sets bindings for subentities.

prepareOrientations

Array. Optional. Sets orientations for subentities.

preparePositions

Array Optional. Sets positions for subentities.

prepareProps

Object. Optional. Sets properties for model and all subentities, e.g. {energy:2000,fuel:0}.

repRelative

Boolean. Optional. If true relativePosition will be replaced by position in used shaders on setting up the briefing. (New in v1.6.1)

role

String.

title

String. Optional. Defaults to "Briefing".

A short example:

	var obj = { role:"trader", ori:[1,0,0,0], briefing:[ [3,"mVelo",[0,-1,3,-1.005,0,0,1,0,0.85]], [17,"stopVelo",[0,-1]] ], callback:this.name, callbackf:"choiceEval" }; worldScripts.Cabal_Common_Briefing.startBriefing(obj);

obj.briefing

The briefing array contains the timebased actions. A entry contains at least two elements:

Time

Number. Based on a interval of 0.25 sec.

Action

String. Specifier for the action.

ActionParameter

Array. See below.

Message

String. Via mission.addMessageText().

Sound

Filename.

SoundParameter

Number. repeatCount.

SoundStopTime

Number.

Short overview about the actions:

• bgzoom - Zooms background image in and out. See fcbZoomBackground().
• bind - Sticks two subents together. See fcbSetBinding().
• check - Useful for developers to see how many framecallbacks are invoked. See fcbCheckAll().
• clean - Clears all fcbs without stopping the briefing. See fcbRemoveAll().
• continue - Enables checkpoints if specific points are reached. If callback function returns number, this is used as goto command.
• face - Rotate entity to face another entity. See fcbFace().
• flightTo - Turn and accelerate model until target position is reached. See fcbFlightTo().
• kill - Stops briefing and clears all fcbs. See fcbRemoveAll().
• mes - Add a message.
• mSpeed - Velocity based on vectorForward. See fcbModelSpeed().
• mVelo - Velocity vectorUp, Right and Forward. See fcbModelVelo().
• mVeloTo - Set Velocities until target position is reached. See fcbModelVeloTo().
• prop - Set property, e.g. fuel. See fcbSetProp().
• reback - Set background image. See reBackground().
• reori - Set orientation. See reOrient().
• reover - Set overlay image. See reOverlay().
• repos - Set position. See rePosition().
• retex - Set materials/shaders. See reTexture().
• rot - Rotate X,Y,Z. See fcbRotation().
• stopSound - Stop briefing sound.
• stopVelo - Stop velocity. See stopVelo().
• turn - Rotate vectorUp, Right and Forward and velocity. See fcbFlight().
• walk - Subtract Z-position, biased Y. See fcbWalk().
• zoom - Multiplied position. See fcbZoom().

Cabal_Common_ScreenFCB

Scripts can instantiate a copy via

	this.helper = new worldScripts.Cabal_Common_Functions.Cabal_Common_ScreenFCB();

Properties

internalVersion

Number. Property to give OXPs a chance to check the required lib min. version easily. This number will be raised with every release.

	var a = this.helper.internalVersion; a -> 15

Methods

fcbCheckAll()

	this.helper.fcbCheckAll();

Check invoked framecallbacks.

Parameters:

none.

Returns:

nothing.

fcbFace()

	this.helper.fcbFace(ent,sub,last,tar,basez,dampa,dampb,away);

Rotate entity to face another entity.

Parameters:

ent

Entity. To be reoriented. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

tar

Entity. Target entity. If -1 player.ship is used.

basez

Boolean. If true Z position will be taken into account.

dampa

Number. Linear dampening duration for rotation start.

dampb

Number. Linear dampening duration for rotation end.

away

Number. Multiplier to head away from target. -1...1.

Returns:

nothing.

fcbFlight()

	this.helper.fcbFlight(ent,sub,last,rU,rR,rF,velo);

Turn and accelerate model.

Parameters:

ent

Entity. To be reoriented and/or accelerated. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

rU

Number. Rotate vectorUp by rU (radians).

rR

Number. Rotate vectorRight by rR (radians).

rF

Number. Rotate vectorForward by rF (radians).

velo

Number. Multiply vectorForward and set velocity. If -1 no velocity set.

Returns:

nothing.

fcbFlightTo()

	this.helper.fcbFlightTo(ent,tar,last,dampa,dampb,mul,velo,offset);

Turn and accelerate model until target position is reached.

Parameters:

ent

mission.displayModel.subentity. To be reoriented and/or accelerated.

tar

mission.displayModel.subentity. Target.position

last

Number. Duration for fcb.

dampa

Number. Linear dampening duration for rotation start.

dampb

Number. Linear dampening duration for rotation end.

mul

Number. Multiplier for rotation.

velo

Number. Multiply vectorForward and set velocity.

offset

Vector/Array. Offset position for target.

Returns:

nothing.

fcbModelSpeed()

	this.helper.fcbModelSpeed(ent,sub,last,velo,basez,dampa,dampb);

Accelerate model.

Parameters:

ent

Entity. To be accelerated. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

velo

Number. Multiply vectorForward and set velocity.

basez

Boolean. If true Z position will be taken into account.

dampa

Number. Linear dampening duration for velo start.

dampb

Number. Linear dampening duration for velo end.

Returns:

nothing.

fcbModelVelo()

	this.helper.fcbModelVelo(ent,sub,last,mU,mR,mF,basez,dampa,dampb);

Set Velocities.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

mU

Number. Multiplier vectorUp.

mR

Number. Multiplier vectorRight.

mF

Number. Multiplier vectorForward.

basez

Boolean. If true Z position will be taken into account.

dampa

Number. Linear dampening duration for start.

dampb

Number. Linear dampening duration for end.

Returns:

nothing.

fcbModelVeloTo()

	this.helper.fcbModelVeloTo(ent,sub,last,mU,mR,mF,basez,dampa,dampb,tar,offset);

Set Velocities until target position is reached.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

mU

Number. Multiplier vectorUp.

mR

Number. Multiplier vectorRight.

mF

Number. Multiplier vectorForward.

basez

Boolean. If true Z position will be taken into account.

dampa

Number. Linear dampening duration for start.

dampb

Number. Linear dampening duration for end.

tar

SubEntity.

offset

Vector/Array. Offset for target position.

Returns:

nothing.

fcbModelRotation()

	this.helper.fcbRotation(ent,sub,last,rX,rY,rZ,basez,dampa,dampb);

Set rotations.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

rX

Number. Radians X.

rY

Number. Radians Y.

rZ

Number. Radians Z.

basez

Boolean. If true Z position will be taken into account.

dampa

Number. Linear dampening duration for start.

dampb

Number. Linear dampening duration for end.

Returns:

nothing.

fcbRemoveAll()

	this.helper.fcbRemoveAll();

Clear all framecallbacks.

Parameters:

none.

Returns:

nothing.

fcbSetBinding()

	this.helper.fcbSetBinding(ent,sub,last,tar,dist,inheritFE,swap);

Bind subentities.

Parameters:

ent

Entity. To be reoriented. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

tar

Entity. Target subEntity.

dist

Boolean. Keep its distance.

inheritFE

Boolean. Bind fuel and energy too.

swap

Boolean. Flip orientation.

Returns:

nothing.

fcbSetProp()

	this.helper.fcbSetProp(ent,sub,prop,value,last,dampa,dampb);

Set property.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

prop

String. Property name.

value

Value for the property. If last specified current value added last times.

last

Number. Duration for fcb.

dampa

Number. Linear dampening duration for start.

dampb

Number. Linear dampening duration for end.

Returns:

nothing.

fcbWalk()

	this.helper.fcbWalk(ent,sub,last,steps,movez,friction,dampa,dampb);

Walk.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

steps

Number. Divider for duration.

movez

Number.

friction

Number. Modifier for Y movement

dampa

Number. Linear dampening duration for start.

dampb

Number. Linear dampening duration for end.

Returns:

nothing.

fcbZoom()

	this.helper.fcbZoom(ent,sub,last,amz,basez,dampa,dampb);

Zoom model.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

last

Number. Duration for fcb.

amz

Number. Multiplier for Z.

basez

Boolean. If true Z position will be taken into account.

dampa

Number. Linear dampening duration for start.

dampb

Number. Linear dampening duration for end.

Returns:

nothing.

fcbZoomBackground()

	this.helper.fcbZoomBackground(bg,last,w,h,factor,dampa,dampb);

Zoom background image.

Parameters:

bg

String. Filename with extension

last

Number. Duration for fcb.

w

Number. Dimension width.

h

Number. Dimension height.

factor

Number. Multiplier Z.

dampa

Number. Linear dampening duration for start.

dampb

Number. Linear dampening duration for end.

Returns:

nothing.

reBackground()

	this.helper.reBackground(png);

Set background image.

Parameters:

png

Filename.

Returns:

nothing.

reOrient()

	this.helper.reOrient(ent,sub,ori);

Set orientation.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

ori

Array. Orientation in w,x,y,z.

Returns:

nothing.

reOverlay()

	this.helper.reOverlay(png);

Set overlay image.

Parameters:

png

Filename.

Returns:

nothing.

rePosition()

	this.helper.rePosition(ent,sub,pos);

Set position.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

pos

Array. Position in x,y,z.

Returns:

nothing.

reTexture()

	this.helper.rePosition(ent,sub,mat,sha);

Set materials and shaders.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

mat

Object. Materials.

sha

Object. Shaders.

Returns:

nothing.

screenCornerPos()

	this.helper.screenCornerPos(level,signx,signy,further);

Missionscreen model corner positioning.

Parameters:

level

Number. Works best with values between 0 and 0.35.

signx

Number. Used as sign mantissa (-1...1) for X axis.

signy

Number. Used as sign mantissa (-1...1) for Y axis.

further

Number. Multiplier for Z axis. Defaults to 1.3.

Returns:

nothing.

stopVelo()

	this.helper.stopVelo(ent,sub);

Stops velocity.

Parameters:

ent

Entity. If not specified mission.displayModel.

sub

SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].

Returns:

nothing.

---