Difference between revisions of "Cabal Common Library Doc Music"

From Elite Wiki
m
m (Retagged!)
 
(8 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.
Line 19: Line 19:
 
On startUp created set of handlers (Array) for Cabal_Common_Music.
 
On startUp created set of handlers (Array) for Cabal_Common_Music.
  
−
{{CodeEx|codeex=var a = worldScripts.Cabal_Common_Music.requestHandlerSet;
+
  var a = worldScripts.Cabal_Common_Music.requestHandlerSet;
−
a -> [ [aegis, enter, exit], [alert, red, ... ] ... ]}}
+
  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 don't pass non-writable, sealed or frozen objects.
+
Internally every entry gets a group ID, so make sure that the object is extensible and not sealed or frozen.
  
 
'''Properties:'''
 
'''Properties:'''
Line 38: Line 39:
 
:;launch:Object. Allowed members: ent, inter, goneNova, doNova, main, any.
 
:;launch:Object. Allowed members: ent, inter, goneNova, doNova, main, any.
 
:;planet:Object. Allowed members: ent<sup>3</sup>, enterMain<sup>3</sup>, enterSun<sup>3</sup>, exitMain<sup>3</sup>, exitSun<sup>3</sup>.
 
:;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: ent<sup>2</sup>.
+
:;scooped:Object. Allowed members: ent<sup>2</sup>, fuel<sup>4</sup> {{AV|1.6.1}}.
 
:;track:Object. Allowed members: byName.
 
:;track:Object. Allowed members: byName.
  
Line 45: Line 46:
  
 
<sup>1</sup> If other handlers have fired blocked for 10 seconds.<br>
 
<sup>1</sup> If other handlers have fired blocked for 10 seconds.<br>
−
<sup>2</sup> The handler is only fired for scripted pods.<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.
+
<sup>3</sup> Can collide, because aegis and planet vicinities can be close together.<br>
 +
<sup>4</sup> Blocked for 10 seconds when fired.
  
  
Line 54: Line 56:
  
 
=== removeMedia() ===
 
=== removeMedia() ===
−
{{CodeEx|codeex=removeMedia = function( who )}}
+
{{CodeEx|codeex=worldScripts.Cabal_Common_Music.removeMedia( who )}}
 +
{{CodeExTime|native=0.000040|extension=0.000012|js=0.000346}}
 
Removes all entries of a group from the stored list.
 
Removes all entries of a group from the stored list.
  
Line 65: Line 68:
  
 
=== changeStatus() ===
 
=== changeStatus() ===
−
{{CodeEx|codeex=changeStatus = function( who, status )}}
+
{{CodeEx|codeex=worldScripts.Cabal_Common_Music.changeStatus( who, status )}}
 +
{{CodeExTime|native=0.000040|extension=0.000017|js=0.000104}}
 
Changes the group state for a specific group.
 
Changes the group state for a specific group.
  
Line 78: Line 82:
 
== Structure ==
 
== Structure ==
 
A short overview about the expected structure:
 
A short overview about the expected structure:
−
{{CodeEx|codeex=var eventMusic = {
+
  var eventMusic = {
−
:who:this.name,<br>
+
    who:this.name,
−
:start:true,<br>
+
    start:true,
−
:aegis:{<br>
+
    aegis:{
−
::exit:[<br>
+
      exit:[
−
:::{prop:"myProperty",music:"myMusic.ogg"}<br>
+
        {prop:"myProperty",music:"myMusic.ogg"}
−
::]<br>
+
      ]
−
:}<br>
+
    }
−
};<br>
+
  };
−
worldScripts.Cabal_Common_Music.addMedia(eventMusic);}}
+
  worldScripts.Cabal_Common_Music.addMedia(eventMusic);
  
−
The objects that are holding the music itself have a set of available properties as well, but only '''music''' is required.
+
The objects that are holding the music itself have a set of available properties as well.
−
:;dist:Number. Min. distance to entity. Only available in '''track'''.
+
:;dist:Number. Min. distance to entity. Required in '''track.byName'''.
−
:;ent:String. Entity name. Available in '''destroyed''', '''launch''', '''planet''', '''scooped''' and '''track'''.
+
:;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. Sound as transition between musicfiles. If used must be 1 (will be expanded).
+
:;fadeQ:Number. Optional. Sound as transition between musicfiles. If used must be 1 (will be expanded).
−
:;music:String. Filename with fileextension.
+
:;music:String. Required. Filename with fileextension.
−
:;prop:String. Name of worldScript property to be checked.
+
:;prop:String. Optional. Name of worldScript property to be checked.
  
  
 
----
 
----
  
−
[[Category:OXPDoc]]
+
[[Category:OXP API's]]

Latest revision as of 15: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"