Difference between revisions of "Cabal Common Library Doc Music"

From Elite Wiki
(Started Doc for CCL_Music)
 
m (Retagged!)
 
(11 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
−
This is the main class for the event driven inflight music for missions.
+
This is the main class for the event driven inflight music for missions and part of the [[Cabal_Common_Library]].
  
 
The script handles incoming data from worldScripts to play music in specific situations.
 
The script handles incoming data from worldScripts to play music in specific situations.
 
OXPs can place or remove their sets fairly simple and a few parameters are handled.
 
OXPs can place or remove their sets fairly simple and a few parameters are handled.
 +
The inserted data is associated to the inserting worldScript by ID and the whole group
 +
of events can be easily de/activated at every time via [[#changeStatus()|.changeStatus()]].
 +
Additionally a property can be assigned to a specific event, means that different entries
 +
can be de/activated by using different properties.
 +
 +
'''Note:'''
 +
Length, volume and fadeIn/fadeOut in the audio itself are important factors for a smooth transition between
 +
musicfiles. For the volume it is adviced to use at least -9 db (peak) to avoid conflicts with spoken inflight messages
 +
and digital clipping.
  
  
 
== Properties ==
 
== Properties ==
 
=== requestHandlerSet ===
 
=== requestHandlerSet ===
−
On startUp created set of handlers for Cabal_Common_Music.
+
On startUp created set of handlers (Array) for Cabal_Common_Music.
  
−
'''TODO''' - Example.
+
  var a = worldScripts.Cabal_Common_Music.requestHandlerSet;
 +
  a -> [ [aegis, enter, exit], [alert, red, ... ] ... ]
  
  
 
== Functions ==
 
== Functions ==
 
=== addMedia() ===
 
=== addMedia() ===
−
{{CodeEx|codeex=addMedia = function( obj )}}
+
{{CodeEx|codeex=worldScripts.Cabal_Common_Music.addMedia( obj )}}
 +
{{CodeExTime|native=0.000097|extension=0.000032|js=0.000455}}
 
Adds incoming object to the list and associates the entries to the sending worldScript.
 
Adds incoming object to the list and associates the entries to the sending worldScript.
 +
Internally every entry gets a group ID, so make sure that the object is extensible and not sealed or frozen.
  
 
'''Properties:'''
 
'''Properties:'''
 
:;who:String. Required. Name of the sending worldScript.
 
:;who:String. Required. Name of the sending worldScript.
−
:;start:Boolean. Required. Starting state after insertion.
+
:;start:Boolean. Required. Starting state for the group after insertion.
−
:;aegis:Object. Allowed members: '''TODO'''
+
:;aegis:Object. Allowed members: enter<sup>3</sup>, exit<sup>3</sup>.
−
:;alert:Object. Allowed members: '''TODO'''
+
:;alert:Object. Allowed members: red, yellow<sup>1</sup>, green<sup>1</sup>.
−
:;destroyed:Object. Allowed members: '''TODO'''
+
:;destroyed:Object. Allowed members: ent.
−
:;exitWS:Object. Allowed members: '''TODO'''
+
:;exitWS:Object. Allowed members: inter, goneNova, doNova, standard, any.
−
:;launch:Object. Allowed members: '''TODO'''
+
:;launch:Object. Allowed members: ent, inter, goneNova, doNova, main, any.
−
:;planet:Object. Allowed members: '''TODO'''
+
:;planet:Object. Allowed members: ent<sup>3</sup>, enterMain<sup>3</sup>, enterSun<sup>3</sup>, exitMain<sup>3</sup>, exitSun<sup>3</sup>.
−
:;scooped:Object. Allowed members: '''TODO'''
+
:;scooped:Object. Allowed members: ent<sup>2</sup>, fuel<sup>4</sup> {{AV|1.6.1}}.
−
:;track:Object. Allowed members: '''TODO'''
+
:;track:Object. Allowed members: byName.
  
 
'''Returns'''
 
'''Returns'''
 
:;Boolean: True on success, false on failure.
 
:;Boolean: True on success, false on failure.
  
 +
<sup>1</sup> If other handlers have fired blocked for 10 seconds.<br>
 +
<sup>2</sup> The handler is only fired for scripted pods. (Changed in Oolite v1.77)<br>
 +
<sup>3</sup> Can collide, because aegis and planet vicinities can be close together.<br>
 +
<sup>4</sup> Blocked for 10 seconds when fired.
  
−
'''TODO''' - Infos about members.
+
 
 +
The above mentioned members are all of type Array and are holding the music related objects.
 +
See [[#Structure|Structure]] for a overview.
  
  
 
=== removeMedia() ===
 
=== removeMedia() ===
−
{{CodeEx|codeex=removeMedia = function( who )}}
+
{{CodeEx|codeex=worldScripts.Cabal_Common_Music.removeMedia( who )}}
−
Removes entries from the stored list.
+
{{CodeExTime|native=0.000040|extension=0.000012|js=0.000346}}
 +
Removes all entries of a group from the stored list.
  
 
'''Properties:'''
 
'''Properties:'''
Line 49: Line 68:
  
 
=== changeStatus() ===
 
=== changeStatus() ===
−
{{CodeEx|codeex=changeStatus = function( who, status )}}
+
{{CodeEx|codeex=worldScripts.Cabal_Common_Music.changeStatus( who, status )}}
−
Removes entries from the stored list.
+
{{CodeExTime|native=0.000040|extension=0.000017|js=0.000104}}
 +
Changes the group state for a specific group.
  
 
'''Properties:'''
 
'''Properties:'''
 
:;who:String. Name of the worldScript.
 
:;who:String. Name of the worldScript.
−
:;status:Boolean. Changes the active flag for all inserted files of a specific worldScript.
+
:;status:Boolean. Sets the group flag for all inserted files of a specific worldScript group.
  
 
'''Returns'''
 
'''Returns'''
Line 60: Line 80:
  
  
−
[[Category:OXPDoc]]
+
== Structure ==
 +
A short overview about the expected structure:
 +
  var eventMusic = {
 +
    who:this.name,
 +
    start:true,
 +
    aegis:{
 +
      exit:[
 +
        {prop:"myProperty",music:"myMusic.ogg"}
 +
      ]
 +
    }
 +
  };
 +
  worldScripts.Cabal_Common_Music.addMedia(eventMusic);
 +
 
 +
The objects that are holding the music itself have a set of available properties as well.
 +
:;dist:Number. Min. distance to entity. Required in '''track.byName'''.
 +
:;ent:String/Number. Either entity.name (String) or entity.radius (Number). Required in '''destroyed.ent''', '''launch.ent''', '''planet.ent''' (radius), '''scooped.ent''' and '''track.byName'''.
 +
:;fadeQ:Number. Optional. Sound as transition between musicfiles. If used must be 1 (will be expanded).
 +
:;music:String. Required. Filename with fileextension.
 +
:;prop:String. Optional. Name of worldScript property to be checked.
 +
 
 +
 
 +
----
 +
 
 +
[[Category:OXP API's]]

Latest revision as of 14:11, 20 September 2023

Overview

This is the main class for the event driven inflight music for missions and part of the Cabal_Common_Library.

The script handles incoming data from worldScripts to play music in specific situations. OXPs can place or remove their sets fairly simple and a few parameters are handled. The inserted data is associated to the inserting worldScript by ID and the whole group of events can be easily de/activated at every time via .changeStatus(). Additionally a property can be assigned to a specific event, means that different entries can be de/activated by using different properties.

Note: Length, volume and fadeIn/fadeOut in the audio itself are important factors for a smooth transition between musicfiles. For the volume it is adviced to use at least -9 db (peak) to avoid conflicts with spoken inflight messages and digital clipping.


Properties

requestHandlerSet

On startUp created set of handlers (Array) for Cabal_Common_Music. 

 var a = worldScripts.Cabal_Common_Music.requestHandlerSet;
 a -> [ [aegis, enter, exit], [alert, red, ... ] ... ]


Functions

addMedia()

worldScripts.Cabal_Common_Music.addMedia( obj )
Profiler
Native 0.000097s
Extension 0.000032s
JS 0.000455s

Adds incoming object to the list and associates the entries to the sending worldScript. Internally every entry gets a group ID, so make sure that the object is extensible and not sealed or frozen.

Properties:

who
String. Required. Name of the sending worldScript.
start
Boolean. Required. Starting state for the group after insertion.
aegis
Object. Allowed members: enter3, exit3.
alert
Object. Allowed members: red, yellow1, green1.
destroyed
Object. Allowed members: ent.
exitWS
Object. Allowed members: inter, goneNova, doNova, standard, any.
launch
Object. Allowed members: ent, inter, goneNova, doNova, main, any.
planet
Object. Allowed members: ent3, enterMain3, enterSun3, exitMain3, exitSun3.
scooped
Object. Allowed members: ent2, fuel4 Added in v1.6.1.
track
Object. Allowed members: byName.

Returns

Boolean
True on success, false on failure.

1 If other handlers have fired blocked for 10 seconds.
2 The handler is only fired for scripted pods. (Changed in Oolite v1.77)
3 Can collide, because aegis and planet vicinities can be close together.
4 Blocked for 10 seconds when fired.


The above mentioned members are all of type Array and are holding the music related objects. See Structure for a overview.


removeMedia()

worldScripts.Cabal_Common_Music.removeMedia( who )
Profiler
Native 0.000040s
Extension 0.000012s
JS 0.000346s

Removes all entries of a group from the stored list.

Properties:

who
String. Name of the worldScript.

Returns

Boolean
True on success, false on failure.


changeStatus()

worldScripts.Cabal_Common_Music.changeStatus( who, status )
Profiler
Native 0.000040s
Extension 0.000017s
JS 0.000104s

Changes the group state for a specific group.

Properties:

who
String. Name of the worldScript.
status
Boolean. Sets the group flag for all inserted files of a specific worldScript group.

Returns

Boolean
True on success, false on failure.


Structure

A short overview about the expected structure: 

 var eventMusic = {
   who:this.name,
   start:true,
   aegis:{
     exit:[
       {prop:"myProperty",music:"myMusic.ogg"}
     ]
   }
 };
 worldScripts.Cabal_Common_Music.addMedia(eventMusic);

The objects that are holding the music itself have a set of available properties as well.

dist
Number. Min. distance to entity. Required in track.byName.
ent
String/Number. Either entity.name (String) or entity.radius (Number). Required in destroyed.ent, launch.ent, planet.ent (radius), scooped.ent and track.byName.
fadeQ
Number. Optional. Sound as transition between musicfiles. If used must be 1 (will be expanded).
music
String. Required. Filename with fileextension.
prop
String. Optional. Name of worldScript property to be checked.


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