Difference between revisions of "Cabal Common Library Doc Briefing"

From Elite Wiki
m (Created page with '== 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 ti…')
 
m (Retagged!)
 
(19 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
−
This is the main class for the briefing with its members.
+
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
 
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.
 
of the displayed model. Scripts can pass the data easily and everything else is performed within the briefing script.
  
−
{{CodeEx|codeex=worldScripts.Cabal_Common_Briefing.startBriefing(obj);}}
+
  worldScripts.Cabal_Common_Briefing.startBriefing(obj);
 +
 
  
 
A second approach is possible by instantiating a copy of the underlaying API, e.g.
 
A second approach is possible by instantiating a copy of the underlaying API, e.g.
−
{{CodeEx|codeex=this.helper = new Cabal_Common_ScreenFCB();}}
+
  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!
 
But scripts are then responsible to remove the framecallbacks on their own with the method provided by the API!
 +
 +
 +
Missionscreens invoked by <tt>Cabal_Common_Briefing.js</tt> are using the screenID {{AV|1.7.1}}
 +
{{CodeEx|codeex="Cabal_Common_Briefing"}}
  
  
 
== Functions ==
 
== Functions ==
 
=== startBriefing() ===
 
=== startBriefing() ===
−
{{CodeEx|codeex=this.startBriefing = function( obj )}}
+
{{CodeEx|codeex=worldScripts.Cabal_Common_Briefing.startBriefing = function( obj )}}
−
Calling this method starts the handling. The argument (obj) should hold a few parameters to define the actions.
+
Calling this method starts the handling. The passed obj must hold a few parameters to define the actions.
  
−
obj:
 
 
'''Parameters:'''
 
'''Parameters:'''
−
:;absolutePos:Array. Optional.
+
:;obj:Object.
 +
 
 +
'''Returns:'''
 +
:;nothing
 +
 
 +
 
 +
'''Properties of obj:'''
 +
:;absolutePos:Array. Optional. E.g. [10,12,540].
 
:;background:String. Optional. Filename with extension.
 
:;background:String. Optional. Filename with extension.
 
:;briefing:Array. Required. Action commands.
 
:;briefing:Array. Required. Action commands.
−
:;callback:String. Optional. Required. WorldScript identifier.
+
:;callback:String. Required. WorldScript identifier.
 
:;callbackc:String. Optional. Mission choice.
 
:;callbackc:String. Optional. Mission choice.
 
:;callbackf:String. Required. Callback function.
 
:;callbackf:String. Required. Callback function.
−
:;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. The current missionscreen is used.
−
:;cornerPos:Array. Optional. Movement to one corner.
+
:;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. {{AV|1.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.
 
:;music:String. Optional. Filename with extension.
−
:;ori:Array. Optional. Orientation.
+
:;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.
 +
:;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. {{AV|1.6.1}}
 
:;role:String.
 
:;role:String.
 
:;title:String. Optional. Defaults to "Briefing".
 
:;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()|fcbZoomBackground()]].
 +
*'''bind''' - Sticks two subents together. See [[#fcbSetBinding()|fcbSetBinding()]].
 +
*'''check''' - Useful for developers to see how many framecallbacks are invoked. See [[#fcbCheckAll()|fcbCheckAll()]].
 +
*'''clean''' - Clears all fcbs without stopping the briefing. See [[#fcbRemoveAll()|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()|fcbFace()]].
 +
*'''flightTo''' - Turn and accelerate model until target position is reached. See [[#fcbFlightTo()|fcbFlightTo()]].
 +
*'''kill''' - Stops briefing and clears all fcbs. See [[#fcbRemoveAll()|fcbRemoveAll()]].
 +
*'''mes''' - Add a message.
 +
*'''mSpeed''' - Velocity based on vectorForward. See [[#fcbModelSpeed()|fcbModelSpeed()]].
 +
*'''mVelo''' - Velocity vectorUp, Right and Forward. See [[#fcbModelVelo()|fcbModelVelo()]].
 +
*'''mVeloTo''' -  Set Velocities until target position is reached. See [[#fcbModelVeloTo()|fcbModelVeloTo()]].
 +
*'''prop''' - Set property, e.g. fuel. See [[#fcbSetProp()|fcbSetProp()]].
 +
*'''reback''' - Set background image. See [[#reBackground()|reBackground()]].
 +
*'''reori''' - Set orientation. See [[#reOrient()|reOrient()]].
 +
*'''reover''' - Set overlay image. See [[#reOverlay()|reOverlay()]].
 +
*'''repos''' - Set position. See [[#rePosition()|rePosition()]].
 +
*'''retex''' - Set materials/shaders. See [[#reTexture()|reTexture()]].
 +
*'''rot''' - Rotate X,Y,Z. See [[#fcbRotation()|fcbRotation()]].
 +
*'''stopSound''' - Stop briefing sound.
 +
*'''stopVelo''' - Stop velocity. See [[#stopVelo()|stopVelo()]].
 +
*'''turn''' - Rotate vectorUp, Right and Forward and velocity. See [[#fcbFlight()|fcbFlight()]].
 +
*'''walk''' - Subtract Z-position, biased Y. See [[#fcbWalk()|fcbWalk()]].
 +
*'''zoom''' - Multiplied position. See [[#fcbZoom()|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;
 +
 +
Current version is {{CodeEx|codeex={{CCL_Int}}}}
 +
 +
 +
=== Methods ===
 +
==== fcbCheckAll() ====
 +
{{CodeEx|codeex=this.helper.fcbCheckAll();}}
 +
Check invoked framecallbacks.
 +
 +
'''Parameters:'''
 +
:;none.
 +
 +
'''Returns:'''
 +
:;nothing.
 +
 +
 +
==== fcbFace() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=this.helper.fcbRemoveAll();}}
 +
Clear all framecallbacks.
 +
 +
'''Parameters:'''
 +
:;none.
 +
 +
'''Returns:'''
 +
:;nothing.
 +
 +
 +
==== fcbSetBinding() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=this.helper.reBackground(png);}}
 +
Set background image.
 +
 +
'''Parameters:'''
 +
:;png:Filename.
 +
 +
'''Returns:'''
 +
:;nothing.
 +
 +
 +
==== reOrient() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=this.helper.reOverlay(png);}}
 +
Set overlay image.
 +
 +
'''Parameters:'''
 +
:;png:Filename.
  
 
'''Returns:'''
 
'''Returns:'''
−
:;nothing
+
:;nothing.
 +
 
 +
 
 +
==== rePosition() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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() ====
 +
{{CodeEx|codeex=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].
  
−
Example:
+
'''Returns:'''
−
{{CodeEx|codeex=var obj = {
+
:;nothing.
−
  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);}}
 
  
−
Short overview about the Action commands:
 
−
:;"bgzoom":Zooms background image in and out.
 
−
:;"bind":Sticks two subents together.
 
−
:;"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.
 
−
:;"kill":Stops briefing.
 
−
:;"mes":Add a message.
 
−
:;"mSpeed":Velocity based on vectorForward.
 
−
:;"mVelo":Velocity vectorUp.Right and Forward.
 
−
:;"prop":Set property, e.g. fuel.
 
−
:;"reori":Set orientation.
 
−
:;"repos":Set position.
 
−
:;"rot":Rotate X,Y,Z.
 
−
:;"stopSound":Stop briefing sound.
 
−
:;"stopVelo":Stop velocity.
 
−
:;"turn":Rotate vectorUp,Right,Forward and velocity.
 
−
:;"walk":Subtract Z-position, biased Y.
 
−
:;"zoom":Multiplied position.
 
  
−
...more...
+
----
  
−
[[Category:OXPDoc]]
+
[[Category:OXP API's]]

Latest revision as of 14:13, 20 September 2023

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!


Missionscreens invoked by Cabal_Common_Briefing.js are using the screenID Added in v1.7.1

"Cabal_Common_Briefing"


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. The current missionscreen is used.
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. Added 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. Added 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;

Current version is

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.


Retrieved from "https://wiki.alioth.net/index.php?title=Cabal_Common_Library_Doc_Briefing&oldid=79872"