001package com.fs.starfarer.api;
002
003import com.fs.starfarer.api.combat.CombatEngineAPI;
004
005/**
006 * WARNING
007 * Do not store campaign data in data members of an implementation of this interface.
008 * There is only one instance of it per application session and references to campaign
009 * data will likely cause memory leaks.
010 * 
011 * If data storage is required, use SectorAPI.getMemory() or other such.
012 * 
013 */
014public interface MusicPlayerPlugin {
015
016        /**
017         * Called when free-flying in the campaign only, i.e. not in 
018         * any sort of interaction dialog.
019         * @return
020         */
021        Object getStateTokenForCampaignLocation();
022        
023        
024        /**
025         * Called for the following states:
026         * 
027         * MusicPlayerPluginImpl.MARKET
028         * MusicPlayerPluginImpl.ENCOUNTER
029         * MusicPlayerPluginImpl.PLANET_SURVEY
030         * MusicPlayerPluginImpl.CAMPAIGN_SYSTEM
031         * MusicPlayerPluginImpl.CAMPAIGN_HYPERSPACE
032         * 
033         * ... and any other states returned by getStateTokenForCampaignLocation()
034         * 
035         * 
036         * @param token
037         * @return
038         */
039        String getMusicSetIdForCampaignStateToken(Object token, Object param);
040
041
042        String getMusicSetIdForCombat(CombatEngineAPI engine);
043        String getMusicSetIdForTitle();
044
045}