001package com.fs.starfarer.api.campaign;
002
003import java.util.Map;
004
005import com.fs.starfarer.api.campaign.rules.MemoryAPI;
006import com.fs.starfarer.api.combat.EngagementResultAPI;
007
008/**
009 * You need to create a class that implements this interface to create your own dialogs.
010 * This can be a dialog shown before a fleet engagement, a custom GUI or anything else.
011 *
012 * To actually show the dialog, you can use Global.getSector().getCampaignUI().showInteractionDialog()
013 *
014 * If you want to replace the FleetInteractionDialog for a certain fleet encounter, you need to create
015 * a {@link com.fs.starfarer.api.campaign.BaseCampaignPlugin} and implement the logic in the pickInteractionDialogPlugin
016 * method.
017 *
018 * <p>Example
019 * <pre>
020 *  <code>
021 * // This is a simple dialog with some text, an image and an option.
022 * // Note: For simplicity sake, error handling and null-checking is omitted in this example
023 * class MyDialog implements InteractionDialogPlugin{
024 *   interface ExecutableOptionData{
025 *     void execute();
026 *   }
027 *   private InteractionDialogAPI dialog = null;
028 *   {@code @Override}
029 *   void init(InteractionDialogAPI dialog){
030 *     this.dialog = dialog;
031 *     dialog.getTextPanel().addParagraph("Some text")
032 *     dialog.getOptionPanel().addOption(
033 *       "OptionName",
034 *       new ExecutableOptionData(){
035 *         {@code @Override}
036 *         void execute(){
037 *           // implementation of what the option should do when clicked
038 *           // For instance, for a leave option:
039 *           dialog.dismiss();
040 *           // If your GUI e.g. moves to another stage after this, you should clear the options and
041 *           // create new options in here. It might also make sense to move this ExecutableOptionData
042 *           // to another file, if the implementation gets too long.
043 *         }
044 *       }
045 *     );
046 *     String spriteName = Global.getSettings().getSpriteName("spriteCategory", "mySpriteName");
047 *     dialog.getVisualPanel().showImageVisual(
048 *       spriteName,
049 *       Global.getSettings().getSprite(spriteName).width
050 *       Global.getSettings().getSprite(spriteName).height
051 *     );
052 *   }
053 *   {@code @Override}
054 *   void optionSelected(String optionText, Object optionData){
055 *     ExecutableOptionData option = (ExecutableOptionData)optionData;
056 *     if(option == null){ return; }
057 *     option.execute();
058 *   }
059 *
060 *   // Override the remaining methods (Ctrl+O in IntelliJ), but leave their implementation empty if their
061 *   // return type is void, or return null otherwise.
062 *
063 * }
064 *  </code>
065 *
066 * </pre>
067 *
068 */
069public interface InteractionDialogPlugin {
070  /**
071   * Initialize your GUI in here, by populating options, texts and images   *
072   *
073   * @param dialog entry point for interacting with the dialog. You should probably store this in a member variable
074   *
075   */
076  void init(InteractionDialogAPI dialog);
077
078  /**
079   * This gets called when the player clicks on an option. Execute the logic for the selected option in here
080   * @param optionText the name of the option, i.e. the first argument passed to addOption
081   * @param optionData the data/identifier of the selected option. Cast this to the correct type. Don't forget to
082   *                   null-check the result of the cast.
083   */
084  void optionSelected(String optionText, Object optionData);
085
086  /**
087   * Get's called when the player hovers over an option. Can usually be left empty.
088   * @param optionText
089   * @param optionData
090   */
091  void optionMousedOver(String optionText, Object optionData);
092
093  /**
094   * Get's called every frame. Can usually be left empty.
095   * @param amount
096   */
097  void advance(float amount);
098
099  /**
100   * Get's called after a fleet battle connected to this dialog ends. Can be left empty if the dialog
101   * you are implementing isn't related to a fleet battle.
102   *
103   * This documentation is incomplete.
104   *
105   * @param battleResult
106   */
107  void backFromEngagement(EngagementResultAPI battleResult);
108
109  /**
110   * Usually, simply returning null is fine
111   *
112   * @return the context, e.g. campaign entity or fleet or other thing that was interacted with to spawn this dialog   *
113   */
114  Object getContext();
115
116  /**
117   * Usually, simply returning null or an empty map is fine.
118   *
119   * @return a map that maps string keys to memory entries. Only relevant if you want to interact with rulescmd (I think)
120   */
121  Map<String, MemoryAPI> getMemoryMap();
122}