Difference between revisions of "Cabal Common Library Doc Briefing"
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 -> |
+ | 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. |
+ | :;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
Contents
- 1 Overview
- 2 Functions
- 3 Cabal_Common_ScreenFCB
- 3.1 Properties
- 3.2 Methods
- 3.2.1 fcbCheckAll()
- 3.2.2 fcbFace()
- 3.2.3 fcbFlight()
- 3.2.4 fcbModelSpeed()
- 3.2.5 fcbModelVelo()
- 3.2.6 fcbModelRotation()
- 3.2.7 fcbRemoveAll()
- 3.2.8 fcbSetBinding()
- 3.2.9 fcbSetProp()
- 3.2.10 fcbWalk()
- 3.2.11 fcbZoom()
- 3.2.12 fcbZoomBackground()
- 3.2.13 reOrient()
- 3.2.14 rePosition()
- 3.2.15 reTexture()
- 3.2.16 screenCornerPos()
- 3.2.17 stopVelo()
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 = {
}; |
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.