Difference between revisions of "Cabal Common Library Doc Briefing"

From Elite Wiki
m
m (v1.4.4 features added)
Line 34: Line 34:
 
:;capture:Boolean. If true only a new briefing, callback and callbackf gets established.
 
:;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]
 
:;cornerPos:Array. Optional. Movement to one corner. E.g. [0.33,1,1,1.3]
  +
:;getOri:String. Optional. script_info keyname that holds orientation, e.g. "1,0,0,0". (New in v1.4.4)
  +
:;getPos:String. Optional. script_info keyname that holds position, e.g. "0,0,300". (New in v1.4.4)
 
:;music:String. Optional. Filename with extension.
 
:;music:String. Optional. Filename with extension.
 
:;ori:Array. Optional. Orientation. E.g. [1,0,0,0].
 
:;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.
 
:;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. (New in v1.4.4)
  +
:;prepareOrientations:Array. Optional. Sets orientations for subentities. (New in v1.4.4)
  +
:;preparePositions:Array Optional. Sets positions for subentities. (New in v1.4.4)
  +
:;prepareProps:Object. Optional. Sets properties for model and all subentities, e.g. {energy:2000,fuel:0}. (New in v1.4.4)
 
:;role:String.
 
:;role:String.
 
:;title:String. Optional. Defaults to "Briefing".
 
:;title:String. Optional. Defaults to "Briefing".
Line 73: Line 79:
 
*'''reori''' - Set orientation. See [[#reOrient()|reOrient()]].
 
*'''reori''' - Set orientation. See [[#reOrient()|reOrient()]].
 
*'''repos''' - Set position. See [[#rePosition()|rePosition()]].
 
*'''repos''' - Set position. See [[#rePosition()|rePosition()]].
  +
*'''retex''' - Set materials/shaders. See [[#reTexture()|reTexture()]]. (New in v1.4.4)
 
*'''rot''' - Rotate X,Y,Z. See [[#fcbRotation()|fcbRotation()]].
 
*'''rot''' - Rotate X,Y,Z. See [[#fcbRotation()|fcbRotation()]].
 
*'''stopSound''' - Stop briefing sound.
 
*'''stopSound''' - Stop briefing sound.
Line 90: Line 97:
 
Number. Property to give OXPs a chance to check the required lib min. version easily. This number will be raised with every release.
 
Number. Property to give OXPs a chance to check the required lib min. version easily. This number will be raised with every release.
 
{{CodeEx|codeex=var a = this.helper.internalVersion;
 
{{CodeEx|codeex=var a = this.helper.internalVersion;
a -> 6}}
+
a -> 8}}
   
   
Line 207: Line 214:
   
 
==== fcbSetBinding() ====
 
==== fcbSetBinding() ====
{{CodeEx|codeex=this.helper.fcbSetBinding(ent,sub,last,tar,dist,inheritFE);}}
+
{{CodeEx|codeex=this.helper.fcbSetBinding(ent,sub,last,tar,dist,inheritFE,swap);}}
 
Bind subentities.
 
Bind subentities.
   
Line 215: Line 222:
 
:;last:Number. Duration for fcb.
 
:;last:Number. Duration for fcb.
 
:;tar:Entity. Target subEntity.
 
:;tar:Entity. Target subEntity.
:;dist:Boolean. Keep its distance. Currently nonsense .-)
+
:;dist:Boolean. Keep its distance. (New in v1.4.4)
 
:;inheritFE:Boolean. Bind fuel and energy too.
 
:;inheritFE:Boolean. Bind fuel and energy too.
  +
:;swap:Boolean. Flip orientation. (New in v1.4.4)
   
 
'''Returns:'''
 
'''Returns:'''
Line 312: Line 320:
 
:;sub:SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].
 
:;sub:SubEntity. If -1 main entity is used, otherwise ent.subEntities[sub].
 
:;pos:Array. Position in x,y,z.
 
:;pos:Array. Position in x,y,z.
  +
  +
'''Returns:'''
  +
:;nothing.
  +
  +
  +
==== reTexture() ====
  +
{{CodeEx|codeex=this.helper.rePosition(ent,sub,mat,sha);}}
  +
Set materials and shaders.
  +
(New in v1.4.4)
  +
  +
'''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:'''
 
'''Returns:'''

Revision as of 21:37, 19 July 2011

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]
getOri
String. Optional. script_info keyname that holds orientation, e.g. "1,0,0,0". (New in v1.4.4)
getPos
String. Optional. script_info keyname that holds position, e.g. "0,0,300". (New in v1.4.4)
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. (New in v1.4.4)
prepareOrientations
Array. Optional. Sets orientations for subentities. (New in v1.4.4)
preparePositions
Array Optional. Sets positions for subentities. (New in v1.4.4)
prepareProps
Object. Optional. Sets properties for model and all subentities, e.g. {energy:2000,fuel:0}. (New in v1.4.4)
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. Most actions will need additional parameter.

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().
  • continue - Enables checkpoints if specific points are reached.
  • face - Rotate entity to face another entity. See fcbFace().
  • 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().
  • prop - Set property, e.g. fuel. See fcbSetProp().
  • reori - Set orientation. See reOrient().
  • repos - Set position. See rePosition().
  • retex - Set materials/shaders. See reTexture(). (New in v1.4.4)
  • 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 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 -> 8


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.


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.


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. (New in v1.4.4)
inheritFE
Boolean. Bind fuel and energy too.
swap
Boolean. Flip orientation. (New in v1.4.4)

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.


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.


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. (New in v1.4.4)

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.