Cabal Common Library Doc Briefing

This article is a stub. You can help EliteWiki by expanding it.

Overview

This is the main class for the briefing with its members.

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 Cabal_Common_ScreenFCB();

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

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]

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.

role

String.

title

String. Optional. Defaults to "Briefing".

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. Most actions will need additional parameter.

Short overview about the actions:

• bgzoom - Zooms background image in and out.
• bind - Sticks two subents together. See fcbSetBinding().
• check - Useful for developers to see how many framecallbacks are invoked.
• continue - Enables checkpoints if specific points are reached.
• face - Rotate entity to face another entity. See fcbFace().
• kill - Stops briefing.
• mes - Add a message.
• mSpeed - Velocity based on vectorForward. See fcbModelSpeed().
• mVelo - Velocity vectorUp, Right and Forward. See fcbModelVelo().
• prop - Set property, e.g. fuel.
• reori - Set orientation.
• repos - Set position.
• rot - Rotate X,Y,Z. See fcbRotation().
• stopSound - Stop briefing sound.
• stopVelo - Stop velocity.
• turn - Rotate vectorUp, Right and Forward and velocity. See fcbFlight().
• walk - Subtract Z-position, biased Y.
• zoom - Multiplied position.

Cabal_Common_ScreenFCB

Scripts can instantiate a copy via

	this.helper = new 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 -> 6

Methods

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.

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.

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.

fcbSetBinding()

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

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. Currently nonsense .-)

inheritFE

Boolean. Bind fuel and energy too.

Returns:

nothing.

...more...