Difference between revisions of "Cabal Common Library Doc Briefing"
m |
m (formatting) |
||
(4 intermediate revisions by the same 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. |
||
− | + | 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. |
||
− | + | 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"}} |
||
Line 32: | Line 36: | ||
:;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. E.g. [0.33,1,1,1.3] |
:;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". |
:;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". |
:;getPos:String. Optional. script_info keyname that holds position, e.g. "0,0,300". |
||
Line 43: | Line 48: | ||
:;preparePositions:Array Optional. Sets positions 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}. |
:;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". |
||
Line 48: | Line 54: | ||
A short example: |
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); |
+ | worldScripts.Cabal_Common_Briefing.startBriefing(obj); |
− | |||
=== obj.briefing === |
=== obj.briefing === |
||
Line 99: | Line 105: | ||
== Cabal_Common_ScreenFCB == |
== Cabal_Common_ScreenFCB == |
||
Scripts can instantiate a copy via |
Scripts can instantiate a copy via |
||
− | + | this.helper = new worldScripts.Cabal_Common_Functions.Cabal_Common_ScreenFCB(); |
|
=== Properties === |
=== 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. |
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}}}} |
||
Latest revision as of 00:25, 16 September 2013
Contents
- 1 Overview
- 2 Functions
- 3 Cabal_Common_ScreenFCB
- 3.1 Properties
- 3.2 internalVersion
- 3.3 Methods
- 3.3.1 fcbCheckAll()
- 3.3.2 fcbFace()
- 3.3.3 fcbFlight()
- 3.3.4 fcbFlightTo()
- 3.3.5 fcbModelSpeed()
- 3.3.6 fcbModelVelo()
- 3.3.7 fcbModelVeloTo()
- 3.3.8 fcbModelRotation()
- 3.3.9 fcbRemoveAll()
- 3.3.10 fcbSetBinding()
- 3.3.11 fcbSetProp()
- 3.3.12 fcbWalk()
- 3.3.13 fcbZoom()
- 3.3.14 fcbZoomBackground()
- 3.3.15 reBackground()
- 3.3.16 reOrient()
- 3.3.17 reOverlay()
- 3.3.18 rePosition()
- 3.3.19 reTexture()
- 3.3.20 screenCornerPos()
- 3.3.21 stopVelo()
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.