Difference between revisions of "BGS Doc"

Revision as of 11:44, 29 January 2013

Overview

BGS-M is the script for ambient sounds, music and image switches.

Cabal Common Library

BGS checks existance of Cabal Common Library and the internal version. If the requirement is not fullfilled the script gets completely disabled.

Autoconfiguration

Countdown

The timed countdowns are using single soundfiles for the countdown. BGS checks the keys in customsounds.plist ([galactic-hyperspace-countdown-begun] and [hyperspace-countdown-begun]) to see if another soundpack is using them. If so BGS disables its own countdown.

Additionally BGS checks the duration of the countdown (declared by OXPs via hyperspace_motor_spin_time for playerships) and adjusts it's own countdown.

Effects

On startUp BGS checks the shader support level. If it's switched off or no shader support is available all effects are disabled.

BGS-XMapping

The script ships functionality to display more infos on the LongRangeChart via overlay if the player has bought the Advanced Navigational Array. BGS-X will (when released) add the named regions and lanes from ClymAngus vector maps (see Oolite_planet_list).

BGS uses Cabal_Common_2DCollision() to check if the cursor is inside a specified polygon or on a specified line. Methods for inserting the datatsets are available (see addToLRCSpecial() and addToLRC()).

Properties

^OXPC - Marked properties can be configured via OXPConfig.

ambientSounds

Boolean. Switches ambientSounds on/off. This switch affects the crowd layer in stations and engine mumble inflight. Default is true.^OXPC

fxSounds

Boolean. Switches fxSounds on/off. This switch affects the screen based sounds in stations and engine up/down inflight. Default is true.^OXPC

logging

Boolean. Switches extended logging on/off. Default is false.^OXPC

stationMusic

Boolean. Switches music in stations on/off. Default is true.^OXPC

bgsCountOffset

Number. Switches the nextTime for the countdown timer to clock.absoluteSeconds+offset (0...0.3). This can help to ‘correct’ the countdown if the displayed messages are not in sync with the spoken countdown. Default 0.^OXPC

bgsDelay

Integer. Defines the delay in milliseconds between mission screens before BGS re-enables its features. Default 600.^OXPC

bgsDisableChatter

Boolean. Disables radio chatter when in station aegis. Default false.^OXPC

bgsDisableCrowd

Boolean. Disables crowd noise in stations. Default is false.^OXPC

bgsDisableJump

Boolean. Disables spoken jumpcountdown. Default false.^OXPC

bgsHyperFX

Boolean. Shader effect for hyperjumps. If no shader support available the script sets it to false. Default true.^OXPC

bgsHyperFXWormhole

Boolean. Wormhole exit point effect. Default true.^OXPC (New in v1.6)

bgsHyperMove

Number. Move the playership forward to get rid of the breakpattern rings. Set to 0 to disable it. Ignored if bgsHyperFX is false. Default 500.^OXPC Will be removed in v1.6.

bgsJitterRemove

Number. In case uers have problems with their Joystick deadzones for throttle (resulting in playing engine sounds even at full stop) a finetuning option is available. Default 0.^OXPC (New in v1.6)

bgsOff

Boolean. Disables some BGS functions (all when docked, chatter when inflight). It is primarily meant for mission OXPs and stations where no additional functions are available or if the features would interfere. Scripts are responsible to reset it when used, but BGS resets it on its own on shipWillLaunchFromStation, playerCancelledJumpCountdown, playerJumpFailed and playerStartedAutoPilot. Default false.

	`worldScripts["BGS-M"].bgsOff = true;`

bgsQPatch

Boolean. QMine monkeypatch. If true, implement sound for QMines. Only processed on startUp. Default false.^OXPC

Methods

addToLRCSpecial()

	`addToLRCSpecial( obj )`

Inserts a overlay for the special keys. Make sure that the object is extensible and not sealed or frozen.

Parameters:

obj

Object with the following properties

gal: Number. Required. Galaxy number in range 0...7.
ov: String. Required. Filename for the overlay with extension.
txt: String. Required. Text to be displayed.
check: String. Optional. worldScript name to be checked.

Returns:

bool: Boolean. True on success.

addToLRC()

	`addToLRC( obj )`

Inserts a overlay as route or region. 4 different types can be used (circle, rectangle, npoly and route). Make sure that the object is extensible and not sealed or frozen.

Parameters:

obj

Object.

type: Number. Required. Range 1...4.
gal: Number. Required. Galaxy number in range 0...7.
ov: String. Required. Filename for the overlay with extension.

Returns:

bool: Boolean. True on success.

Additional properties are required for the different types:

Type 1 (Circle):

posx: Number. Position of the center. X coordinate in LY.
posy: Number. Position of the center. Y coordinate in LY.
radi: Number. Radius.

Type 2 (Rectangle):

posx: Number. Position of the center. X coordinate in LY.
posy: Number. Position of the center. Y coordinate in LY.
w: Number. Width.
h: Number. Height.

Type 3 (nPoly):

nvert: Number. Number of points.
ax: Array. X coordinates in LY.
ay: Array. Y coordinates in LY.
con: Boolean. Optional. Concave shapes may need to set it.

Type 4 (Route):

pos: Array. Pairs of coordinates in LY in x,y format, e.g. [[8,34.6],[...]]

shipdata.plist

Additional keys for specific entities are available and can be specified via script_info dictionary.

Keys

bgs_chatter: String. Station - Chatter sound files for mainStation. Multiple files can be separated by “|”.
bgs_countonly: Boolean. Playership - spoken countdown only.
bgs_engine: String/Filename. Playership - engine mumble sound.
bgs_engineUp: String/Filename. Playership - engine acceleration sound.
bgs_engineDown: String/Filename. Playership - engine deceleration sound.
bgs_music: String/Filename. Station - music file for specific station.
bgs_nocrowd: Boolean. Station - disables the crowd sounds and switches images on F5.
bgs_nomusic: Boolean. Station - disables the music.

Examples:

Playership (with preloaded sounds):

	`script_info = {"bgs_engine" = "[vector_engine]"; "bgs_engineUp" = "[vector_engineUp]"; "bgs_engineDown" = "[vector_engineDown]";};`

Playership (without preloaded sounds):

	`script_info = {"bgs_engine" = "myEngine.ogg"; "bgs_engineUp" = "myEngineUp.ogg"; "bgs_engineDown" = "myEngineDown.ogg";};`

Station:

	`script_info = {"bgs_music" = "buoyRepair_music.ogg"; "bgs_nocrowd" = true;};`

missiontext.plist

Additional keys specially for other soundpacks are available.

Please note that these options will be removed in v1.6.